
$Id: README.CVS,v 1.29 2012/11/16 03:22:40 we7u Exp $


CVS Instructions:
-----------------
     For those who think CVS might be a bit too complicated to deal with,
     here are (I think) the minimal commands.  See the "SUDO" section
     below though for ideas on how to make updating Xastir even simpler.

     Initial CVS Checkout:
     ---------------------
     1) Create a ".cvsrc" file in your home directory containing the
        following lines.  Use whatever Unix-type editor you're
        comfortable with.  Choices might be pico, vi, emacs, others:

         ##cvs -z3
         update -P -d
         status -v
         diff -u

        These are just some of the CVS options that I prefer, and make some
        things easier.  They are not required.

        The "cvs -z3" option isn't accepted by SourceForge currently.  Comment
        it out by adding a couple of '#' marks in front of the line.  You can
        test it at a later date by removing the '#' marks and trying a cvs
        command.

     2) Start up a shell window of some type, perhaps an xterm or an rxvt.
        Type the following commands into this one shell.  You'll be setting
        an environment variable which will then allow you check out the full
        sources for the first time.  After that, the environment variable
        won't be needed anymore and all shells you use will be able to
        work with the remote CVS repository.  The checked-out sources contain
        administration info which the CVS commands use to know which remote
        server to talk to, and which account/encrypted password to use from
        your ~/.cvspass file.

     3) Follow the instructions listed under "Anonymous CVS Access".  Go to:
        <http://sourceforge.net/projects/xastir/>, then click on "CVS" to
        find the instructions.

        For those that are Internet-challenged, here are the two commands,
        customized for the Xastir project:

          cvs -d:pserver:anonymous@xastir.cvs.sourceforge.net:/cvsroot/xastir login

        Press the <ENTER> key when it asks you for a password.  That creates
        a ".cvspass" file in your home directory with the anonymous login
        information inside it.

          cvs -d:pserver:anonymous@xastir.cvs.sourceforge.net:/cvsroot/xastir co xastir

        That creates a subdirectory called "xastir" that has all the latest
        sources in it.

     You may want to use this instead, to get the sources corresponding to the
     latest release:

       cvs -d:pserver:anonymous@xastir.cvs.sourceforge.net:/cvsroot/xastir co -r RELEASE xastir

     or use this line to get the latest version deemed "stable" by the developers
     (generally newer than the RELEASE version):

       cvs -d:pserver:anonymous@xastir.cvs.sourceforge.net:/cvsroot/xastir co -r STABLE xastir

     All done!  You now have the latest development sources on your computer.
     Now you can forget about all of the previous instructions unless you
     delete the entire tree and want to start over from scratch.

     Note that if you choose the "RELEASE" or "STABLE" tags, those tags will
     become sticky, so that "cvs update" commands will update to the latest
     versions of files containing those tags.  If you wish to remove this
     sticky option so that you can synchronize to a different tag or the latest
     developer's CVS, see the "cvs update -A" command below.


     CVS Commands for Maintaining the Current Development Sources:
     -------------------------------------------------------------
     Once all this is in place, just cd into the "xastir" directory at any
     time, type "cvs update", then type "make install" and you'll have the
     latest development stuff installed on your system.

     Here are the commands to do if you want a clean build of the latest
     sources, and want configure to recheck all the libraries and header
     files that Xastir needs:

         cd xastir
         cvs update (snag all the latest changes)
         ./bootstrap.sh
         ./configure
         (make clean;make -j3 2>&1) | tee make.log
         su
         make install (make install-strip can be used after the first time,
                       it removes debugging info from executable)
         chmod 4555 /usr/local/bin/xastir (only needed if using kernel AX.25)
         exit (from root)
         xastir

     Note that you'll need autoconf 2.53 or newer and automake 1.6.3 or newer
     in order to run the "./bootstrap.sh" script.

     For the "cvs update" line, you can also choose which version to update to,
     just like the "cvs co" lines shown above:

       cvs update -r RELEASE
     or
       cvs update -r STABLE

     Once you specify a revision tag (RELEASE or STABLE), that option becomes
     "sticky" for future checkouts and updates.  That means you only need to
     type "cvs update" in order to update your code to the latest sources
     containing that tag.

       cvs update -A

     will make the cvs update command track to the most recently submitted
     versions again (will make the RELEASE or STABLE options un-sticky).  To
     review:

       cvs update -A            # To get to developers sources.
       cvs update -r STABLE     # To get to latest stable sources.
       cvs update -r RELEASE    # To get to latest released sources.


     Even more CVS commands (most people won't need these):
     ------------------------------------------------------
     I use these aliases the most (defined in my bash shell startup files):

       alias cvsdiff='cvs diff -w -r HEAD'
       alias cvsstat2='cvs -n -q update'
       alias cvsstat3='(cvs status 2>&1) | grep -E "Status: | Examining" | grep -v Up-to-date | grep -v Makefile.in'

     to see if anything has changed.  cvsstat3 is the most useful one
     for me as a developer.  If anything has, I can use this alias to
     see the details on a particular file:

         alias cvsdiff='cvs diff -w -r HEAD'

     As in:

         cvsdiff main.c

         -or- (not using the alias)

         cvs diff -w -r HEAD main.c

     Then perhaps do an update on that file alone:

         cvs update main.c


    Checking out a branch (for anonymous-CVS users):
    ------------------------------------------------

        Go to a new directory structure (not CVS controlled) and type this:

            export CVS_RSH=ssh
            mkdir <branchname>
            cd <branchname>
            cvs -d:pserver:anonymous@xastir.cvs.sourceforge.net:/cvsroot/xastir login

        Press the <ENTER> key when it asks for your password, then:

            cvs -d:pserver:anonymous@xastir.cvs.sourceforge.net:/cvsroot/xastir co -r BRANCH_<branchname> xastir

        The above command will create a directory "xastir" in the <branchname>
        directory containing the latest sources from that branch.

        A complete example (Using an imaginary branch "xastir99"):

            export CVS_RSH=ssh
            cd ~/src
            mkdir xastir99
            cd xastir99
            cvs -d:pserver:anonymous@xastir.cvs.sourceforge.net:/cvsroot/xastir login
            Hit <ENTER> when asked for passwd.
            cvs -d:pserver:anonymous@xastir.cvs.sourceforge.net:/cvsroot/xastir co -r BRANCH_xastir99 xastir

        will fetch the BRANCH_xastir99 code branch and deposit it into:

            /home/<user>/src/xastir99/xastir/


    There are many more CVS commands and options.  Many of them are more of
    use to the developers.  Some of those are listed below.  The above should
    be enough for most people to keep their copies in sync with the latest CVS
    development sources.


SUDO Instructions:
------------------

    "sudo" is a command that can make your life much simpler.  After you set
    it up that is!  By adding a couple of lines to your /etc/sudoers file
    (using the "visudo" command to edit this file), you'll be able to run a few
    commands as root without having to type the root password each time.
    Another thing you can do at that point is automate the entire
    "cvs update;./configure;su;make install" process via a script.  Here's how
    to set all of this up:

    Type "su" to become the root user, then type "visudo".  This will bring up
    the "vi" editor on the /etc/sudoers file.  If you'd like to learn more
    about what I'm going to describe, type "man sudoers" in another window and
    read about this file.  Another man-page that is useful here is the "man
    sudo" page.

    Back to the editing:  There's a section in there for user alias.  Mine is
    labeled "# User alias specification".  Add a line there that reads like
    this:

        User_Alias XASTIR = username1, username2, username3

    where username1, etc, are valid usernames that you wish to be able to do
    Xastir installs.  For instance you might have:

        User_Alias XASTIR = mikey

    Next, add a line near the bottom that reads like this:

        XASTIR ALL = NOPASSWD: /bin/chmod, /usr/bin/make

    Now write out and close the file.  At this point the "mikey" user will have
    root permissions when he/she runs the commands "/bin/chmod" or
    "/usr/bin/make".  Make sure the paths to those programs are correct for
    your system.

    Exit from "su" so that you're a regular (non-root) user again.

    Now, in the "xastir" source directory (mine is in "~/src/xastir"), create a
    script that reads like this.  I named my script  "update-xastir" but nearly
    any name for the script will do:
 
    -----------------cut here--------------------
        #! /bin/sh

        cvs update
        ./bootstrap.sh
        ./configure
        sudo make clean
        sudo make install
        sudo chmod 4755 /usr/local/bin/xastir
    -----------------cut here--------------------

    Now type "chmod u+rwx update-xastir" to make that script executable.

    Actually, we've just created a script for Xastir that implements the above
    and called it "update-xastir".  Do a "cvs update" to get it.

    Try out the script.  Type:

        ./update-xastir

    It should run through the entire update/configure/make/install process for
    Xastir.  Remember to either change to the proper xastir directory before
    running it, or add a "cd" command at the beginning of the script so that it
    will run in the proper directory in all cases.  If you add the proper "cd"
    command you can copy the script to /usr/local/bin and then run it as
    "update-xastir" from anywhere.

    Windows users:  You may need to remove the "sudo" keyword on each line to
    have it work properly for you.

    A note from Gerry Creager as to another way to set up the sudoers file:

      "I now consider it a good idea to add the "gifted" users to the 'wheel'
      group and then solely enable wheel in /etc/sudoers; I've seen a recent
      article also supporting this."


Developer's CVS Instructions:
-----------------------------

    Read this doc first.  Why did they have to put spaces in the URL???:

        http://sourceforge.net/apps/trac/sourceforge/wiki/CVS%20client%20instructions

    For branching/merging, read these as well:

        http://www.drdobbs.com/programmers-toolchest/184404280  # Recommended by Tom Russo
        http://ioctl.org/unix/cvs/branches/
        http://www.astro.princeton.edu/~rhl/cvs-branches.html
        http://users.csc.calpoly.edu/~jdalbey/205/Resources/cvsBranchMerge.html


    A suggested organization (directory names), to keep branches separate from trunk:

        /home/<user>/src/xastir/head/           # Trunk (or HEAD), mainline development
        /home/<user>/src/xastir/branchname1/    # branchname1 development
        /home/<user>/src/xastir/branchname2/    # branchname2 development


    Checking out HEAD (Also known as "trunk", default, or main branch):
    -------------------------------------------------------------------

    These commands will create a directory "xastir" in your current directory which
    contains the latest Xastir sources from the "trunk" branch.  Replace "<devel>"
    with your Sourceforge developer's login name.  To keep the trunk code from
    getting confused with any branches, consider putting it into a subdirectory
    labeled "trunk" or "head", something like "/home/<user>/src/xastir/head/".
    These commands will create just such a directory and populate it with the
    latest development sources (HEAD branch):

        export CVS_RSH=ssh
        cd ~src/xastir
        mkdir head
        cd head
        cvs -z3 -d:ext:<devel>@xastir.cvs.sourceforge.net:/cvsroot/xastir co xastir


    Checking out a branch:
    ----------------------

    To check out a branch to a fresh directory:

        cd ~/src/xastir
        mkdir <my_branchdir>  # /home/<user>/src/xastir/<my_branchdir>/
        cd <my_branchdir>
        cvs -z3 -d:ext:<devel>@xastir.cvs.sourceforge.net:/cvsroot/xastir co -r BRANCH_<branchname> xastir

    Replace "<devel>" above with your Sourceforge developer's login name, and
    "<branchname>" with the name of the branch you wish to check out.  "my_branchdir" can
    be any directory name you like, but naming it the same as <branchname> may be less
    confusing.

    The above command will create a directory "xastir" under <my_branchdir> containing
    the sources from the branch you specified.  The selected branch will remain "sticky"
    in your checked-out working directory unless/until you override it via additional CVS
    commands.  Any cvs commits done there will commit to the new branch instead of the
    trunk.  Commits done to a working copy of "trunk" won't appear on your new branch.
    Pay attention to your directory structure from that point on, whether you're working
    on a checked-out copy of a branch or a checked-out copy of the trunk, and commit
    responsibly.

    With the fictitional "xastir99" branch we used before, example commands would be:

        cd ~/src/xastir
        mkdir xastir99  # /home/<user>/src/xastir/xastir99/
        cd xastir99
        cvs -z3 -d:ext:<devel>@xastir.cvs.sourceforge.net:/cvsroot/xastir co -r BRANCH_xastir99 xastir

    NOTE:  The trunk has version numbers like "dd.dd", while branches have version numbers
    like "dd.dd.dd.dd".

    You can run the "cvs status <filename>" command and look at the "Sticky Tag" near the
    top of the listing to see which branch you're working with:

        cvs status README.CVS | head -15


    Creating a branch:
    ------------------

    NOTE:  This is a special operation.  Do _not_ attempt unless you are familiar with
    CVS tagging, branches, and merging.  We plan to do development on the trunk for
    the mainline (trunk) code and use branches only for a few special development bits:
    Experimental code that we're not sure will make it to production, or porting to
    a new widget set for instance...  Something that might lead to a dead-end, a major
    refactor, or any code that might not see the light of day for some time.

    NOTE:  We've adopted the convention that all branch tags begin with
    "TAG_BRANCH_" and all branches begin with "BRANCH_".  This makes it easy
    to see where branches diverge or merge back with "trunk" and to determine
    which tags are related to branching/merging.

    In a checked-out CVS copy of Xastir, make sure your working copy is up-to-date
    ("cvs -nq update") if you wish all current development changes to this point to
    make it to the new branch you're creating:
    
        cvs update

    Then:

        # Create a tag called "TAG_BRANCH_<branchname>"
        cvs rtag TAG_BRANCH_<branchname> xastir

        # Create branch "BRANCH_<branchname>" starting at the tag you created above
        cvs rtag -b -r TAG_BRANCH_<branchname> BRANCH_<branchname> xastir

    Replace "branchname" with a name of your choosing.  For instance to create
    a branch called "xastir99":

        cvs rtag TAG_BRANCH_xastir99 xastir
        cvs rtag -b -r TAG_BRANCH_xastir99 BRANCH_xastir99 xastir

    Follow the "Checking out a branch" section above to create a NEW directory area to
    work on the new branch.  It's important to keep your directories separate, because
    commits made on a branch will apply only to that branch;  Commits made to trunk
    will apply only to the trunk.


    Listing the tags on a file:
    ---------------------------
    
        cvs log -t README.CVS


    Merging between trunk and a branch:
    -----------------------------------
    TBD.

    A note from Tom regarding merges:  Use the "-kk" option on all merges, otherwise every
    file that has "$Revision: 1.29 $" or "$Date: 2012/11/16 03:22:40 $" in it will get
    flagged as a change -- possibly even a conflict -- even if that's the only difference
    between branch and head.  "-kk" on a cvs update doesn't do substitution on those tags,
    and so only files with real changes will get updated.



  ------------------------------------------------------------------------
Copyright (C) 1999 Frank Giannandrea
Copyright (C) 2000-2012 The Xastir Group

