$Id$

C-U Wireless Developer's Guide
--- -------- ----------- -----

This is draft 0 of a document that tells you how to get started as
a developer for C-U Wireless.

User Account
---- -------

    You are eligible for a user account if it will help you to meet
    C-U Wireless development goals and if you are somebody who the core
    developers trust to use your account responsibly. Ordinarily it is
    a requirement that you have a particular project in mind, and also
    that one of the core developers has met you in person.

    Right now the system administrator is David Young
    (dyoung@ojctech.com). Contact him to get an account.

    You need to belong to groups `users' and `cuw' to get started
    with development. You can check the groups you belong to using the
    groups(1) command.

    We prefer that you use a secure-shell key to login to our server,
    and we may mandate that in the future.  Keep your password secret,
    choose a good password, and please use a different password on our
    system than you use on other systems. Please observe good key hygiene:
    choose a good passphrase for your key, and if you use a key-agent,
    do not forward your agent to hosts that you cannot trust.

Subversion
----------

    The C-U Wireless Project uses Subversion as its source control system.

    There are a few things you need to do before you start to use
    Subversion.

    We need for Subversion to use umask 002 to manipulate its database,
    or else we are going to be stepping on each others' toes.  Please copy
    the wrappers `svn' and `svnserve' from ~dyoung/bin/ to your ~/bin/
    directory, and then put $HOME/bin/ at the front of your path so that
    you use the wrappers instead of directly running the Subversion
    binaries.  (Note that the scripts can be linked together.) The
    wrappers set the umask to 002 before they invoke svn.

    Check out the Subversion repository into your home directory using
    this command,

        svn co file:///var/svn/cuw

    The main branch is cuw/trunk/, there are miscellaneous tags in tags/.
    In branches/ I have made myself a private branch. You may want to
    do this, also.

    (Sorry the repository is so huge; I added the pkg/ directory in haste,
    it's *really* gotta go.)

    Most of your favorite CVS commands (and their abbreviations)
    are in Subversion, too: `svn update', `svn commit', `svn diff',
    `svn add', `svn remove'. There are also svn mv (renaming, yay!) and
    svn cp (for making branches/tags).  Branch merges are done with
    `svn merge'.  To find out more about Subversion, read the docs at
    http://svnbook.red-bean.com/.

    The build scripts for the station software are in
    trunk/src/boot-image/.  Assorted documentation is in trunk/doc/. In
    trunk/src/hsls/ and trunk/src/spf/, I did a couple of hours'
    work on HSLS and a shortest-path first library many months ago. In
    trunk/src/ssrv/, I also did a couple hours' work on a socket-server
    library. In trunk/src/pkg-rewrite/ is some code a NetBSDer sent me. He
    had started to re-write some utilities for pkgsrc, which is like
    FreeBSD's `ports' system. (See `NetBSD Packages Collection', below.)

NetBSD Kernel & Userland Sources
------ ------ - -------- -------

    There are read-only NetBSD-current sources in /usr/src/. The -current
    sources are the sources currently under development.  They come from
    NetBSD's CVS server. C-U Wireless uses -current sources because they
    contain the most up-to-date wireless support. Every now and then,
    I will check out more up-to-date -current sources.

    In /usr/src/sys are the kernel sources, and in /usr/src/bin/,
    /usr/src/usr.bin/, etc., are the sources for the NetBSD userland.

    The very best way to build the NetBSD userland & kernel is to use the
    `build.sh' script.

    The development environment for C-U Wireless requires NetBSD,
    so it will not hurt to understand how to use build.sh. Here is
    an introduction.

    Anybody can check out the -current sources by following the
    instructions at
    <http://www.netbsd.org/Documentation/current/#using-anoncvs>, or
    else by following my instructions---if you do not use tcsh, things
    will be slightly different:

        % cd $HOME
        % mkdir nbsd
        % cd nbsd
        % setenv CVSROOT :pserver:anoncvs@anoncvs.NetBSD.org:/cvsroot
        % cvs login      # password anoncvs
        % cvs co -P src

    To build, prepare some directories to hold the build outputs,

        % cd $HOME/nbsd
        % mkdir D       # destination directory: binaries and such go here
        % mkdir O       # .o's go here
        % mkdir T       # tools for the build go here
        % mkdir R       # a release---the whole system in .tgz's---goes here

    and create a build script that uses those directories.

        % cd ~/nbsd/src
        % cat > ./mybuild <<EOF
        #!/bin/sh
        NBSD=~/nbsd
        ./build.sh -D $NBSD/D -O $NBSD/O -T $NBSD/T -R $NBSD/R -U "$@"
        EOF

    Next, build the tools,

        % ./mybuild tools

    and build a distribution---all the system files except for a kernel:

        % ./mybuild distribution

    You can go take a break, because that will take a while.

    Now, build a "release" consisting of the kernels and archives of
    all of the system files.  The -u option avoids re-building the
    `distribution' target!

        % ./mybuild -u release

    To build a kernel using a custom kernel-configuration file,

        % ./mybuild kernel=your_kernel_configuration_file

    To build the kernel and drop it into your release directory
    ($HOME/nbsd/R), do this:

        % ./mybuild kernel=your_krnl_cfg_file releasekernel=your_krnl_cfg_file

    To re-build the kernel after a "minor" source modification,
    I recommend option -o ("don't create obj directories"), which
    keeps the build script from re-creating the subdirectories under
    ~/nbsd/O. Using -u ("update") keeps the build script from throwing
    away all the .o's that were built the last time.

        % ./mybuild -u -o kernel=your_krnl_cfg_file

    build.sh is very powerful, letting you cross-build NetBSD for many
    architectures on NetBSD hosts and also non-NetBSD hosts such as Linux.
    You can read more about build.sh in /usr/src/BUILDING.

NetBSD Packages Collection
------ -------- ----------

    There are read-only sources for the NetBSD Package Collection in
    /usr/pkgsrc/. The NetBSD Package Collection contains all that you
    need to build 3rd-party programs on NetBSD, including package
    dependencies, source URLs, and patches.  C-U Wireless uses the
    Zebra/Quagga sources from pkgsrc. To find out more about pkgsrc, read
    /usr/pkgsrc/{RAEDME,Packages.txt} and the manual page packages(7). See
    my script ~dyoung/bin/pkgmake to see how I build packages from the
    package sources using the read-only sources.

$Id$