- Copy stable/9 to releng/9.2 as part of the 9.2-RELEASE cycle.

[FreeBSD/releng/9.2.git] / contrib / cvs / INSTALL

-------------------------------------------------------------------------------

CVS is Copyright (C) 1986-2006 The Free Software Foundation, Inc.

CVS is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

-------------------------------------------------------------------------------

Now back to our regularly scheduled program:

Please read the README file before reading this INSTALL file.  Then, to
install CVS:


First you need to obtain and install the CVS executables.  If you got
a distribution which contains executables, consult the installation
instructions for that distribution.  If you got source code, do not
panic.  On many platforms building CVS from source code is a
straightforward process requiring no programming knowledge.  See the
section BUILDING FROM SOURCE CODE at the end of this file, which
includes a list of platforms which have been tested.

-------------------------------------------------------------------------------

1) Take a look at the CVS documentation, if desired.  For most
   purposes you want doc/cvs.texinfo, also known as _Version Management
   with CVS_ by Per Cederqvist et al.  Looking at it might be as simple
   as "info cvs" but this will depend on your installation; see README
   for more details.

   See what CVS can do for you, and if it fits your environment (or can
   possibly be made to fit your environment).  If things look good,
   continue on.  Alternately, just give CVS a try first then figure out
   what it is good for.

2) Set the CVSROOT environment variable to where you want to put your
   source repository.  See the "Setting up the repository" section of
   the Cederqvist manual for details, but the quick summary is just to
   pick some directory.  We'll use /src/master as an example.  For
   users of a POSIX shell (sh/bash/ksh) on unix, the following
   commands can be placed in user's ~/.profile, ~/.bash_profile file;
   or in the site-wide /etc/profile:

       CVSROOT=/src/master; export CVSROOT

   For C shell users on unix place the following commands in the
   user's ~/.cshrc, ~/.login, or /etc/chsrc file:

       setenv CVSROOT /src/master

   For Windows users, supposing the repository will be in
   d:\src\master, place the following line in c:\autoexec.bat.  On
   Windows 95, autoexec.bat might not already exist.  In that case,
   just create a new file containing the following line.

       set CVSROOT=:local:d:\src\master

   If these environment variables are not already set in your current
   shell, set them now by typing the above line at the command prompt
   (or source the login script you just edited).
   The instructions for the remaining steps assume that you have set
   the CVSROOT environment variable.

3) Create the master source repository.  Again, the details are in
   the "Setting up the repository" section of cvs.texinfo; the
   one-line summary is:

       $ cvs init

   In this and subsequent examples we use "$" to indicate the command
   prompt; do not type the "$".

4) It might be a good idea to jump right in and put some sources or
   documents directly under CVS control.  From within the top-level
   directory of your source tree, run the following commands:

       $ cvs import -m "test distribution" ccvs CVS_DIST CVS-TEST

   (Those last three items are, respectively, a repository location, a
   "vendor tag", and a "release tag".  You don't need to understand
   them yet, but read the section "Starting new projects" in the
   Cederqvist manual for details).

5) Having done step 4, one should be able to checkout a fresh copy of the
   sources you just imported and hack away at the sources with the
   following command:

      $ cd
      $ cvs checkout ccvs

   This will make the directory "ccvs" in your current directory and
   populate it with the appropriate files and directories.

6) You may wish to customize the various administrative files, in particular
   modules.  See the Cederqvist manual for details.

7) Read the NEWS file to see what's new.

8) Hack away.

-------------------------------------------------------------------------------

BUILDING FROM SOURCE CODE

Tested platforms

CVS has been tested on the following platforms.  The most recent
version of CVS reported to have been tested is indicated, but more
recent versions of CVS probably will work too.  Please send updates to
this list to bug-cvs@nongnu.org (doing so in the form of a diff
to this file, or at least exact suggested text, is encouraged).
"tested" means, at a minimum, that CVS compiles and appears to work on
simple (manual) testing.  In many cases it also means "make check"
and/or "make remotecheck" passes, but we don't try to list the
platforms for which that is true.

Alpha:
        DEC Alpha running OSF/1 version 1.3 using cc (about 1.4A2)
        DEC Alpha running OSF/1 version 2.0 (1.8)
        DEC Alpha running OSF/1 version 2.1 (about 1.4A2)
        DEC Alpha running OSF/1 version 3.0 (1.5.95) (footnote 7)
        DEC Alpha running OSF/1 version 3.2 (1.9)
        Alpha running alpha-dec-osf4.0 (1.10)
        DEC Alpha running Digital UNIX v4.0C using gcc 2.7.2.2 (1.9.14)
        DEC Alpha running VMS 6.2 (1.8.85 client-only)
        Alpha running NetBSD 1.2E (1.10)
Cray:
        J90 (CVS 970215 snapshot)
        T3E (CVS 970215 snapshot)
HPPA:
        HP 9000/710 running HP-UX 8.07A using gcc (about 1.4A2)
        HPPA running HP-UX 9 (1.8)
        HPPA 1.1 running HP-UX A.09.03 (1.5.95) (footnote 8)
        HPPA 1.1 running HP-UX A.09.04 (1.7.1)
        HPPA running HP-UX 9.05 (1.9)
        HPPA running HP-UX 10.01 (1.7)
        HPPA running HP-UX 10.20 (1.10.7)
        HPPA running HP-UX 11.11 (1.11.13) (footnote 12)
        HPPA 2.0 running HP-UX 10.20 (1.10.9) (footnote 13)
        NextSTEP 3.3 (1.7)
i386 family:
        Solaris 2.4 using gcc (about 1.4A2)
        Solaris 2.6 (1.9)
        UnixWare v1.1.1 using gcc (about 1.4A2)
        Unixware 2.1 (1.8.86)
        Unixware 7 (1.9.29)
        ISC 4.0.1 (1.8.87)
        Linux (kernel 1.2.x) (1.8.86)
        Linux (kernel 2.0.x, RedHat 4.2) (1.10)
        Linux (kernel 2.0.x, RedHat 5.x) (1.10)
        Linux (kernel 2.2.x, RedHat 6.x) (1.10.8)
        Linux (kernel 2.2.x, RedHat 7.x) (1.11)
        BSDI 4.0 (1.10.7)
        FreeBSD 2.1.5-stable (1.8.87)
        NextSTEP 3.3 (1.7)
        SCO Unix 3.2.4.2, gcc 2.7.2 (1.8.87) (footnote 4)
        SCO OpenServer 5.0.5 (1.10.2)
        Sequent DYNIX/ptx4.0 (1.10 or so) (remove -linet)
        Sequent Dynix/PTX 4.1.4 (1.9.20 or so + patches)
        Lynx 2.3.0 080695 (1.6.86) (footnote 9)
        Windows NT 3.51 (1.8.86 client; 1.8.3 local)
        Windows NT 3.51 service pack 4 (1.9)
        Windows NT 3.51 service pack 5 (1.9) -- DOES NOT WORK (footnote 11)
        Windows NT 4.0 (1.9 client and local)
        Windows NT 4.0 (1.11 client and local - build & test, but no test suite)
        Windows 95 (1.9 client and local)
        QNX (1.9.1 + patches for strippath() and va_list)
        OS/2 Version 3 using IBM C/C++ Tools 2.01 (1.8.86 + patches, client)
        OS/2 Version 3 using EMX 0.9c (1.9.22, client)
        OS/2 Version 3 using Watcom version ? (? - has this been tested?)
m68k:
        Sun 3 running SunOS 4.1.1_U1 w/ bundled K&R /usr/5bin/cc (1.8.86+)
        NextSTEP 3.3p1 (1.8.87)
        Lynx 2.3.0 062695 (1.6.86) (footnote 9)
        NetBSD/mac68k (1.9.28)
m88k:
        Data General AViiON running dgux 5.4R2.10 (1.5)
        Data General AViiON running dgux 5.4R3.10 (1.7.1)
        Harris Nighthawk 5800 running CX/UX 7.1 (1.5) (footnote 6)
MIPS:
        DECstation running Ultrix 4.2a (1.4.90)
        DECstation running Ultrix 4.3 (1.10)
        SGI running Irix 4.0.5H using gcc and cc (about 1.4A2) (footnote 2)
        SGI running Irix 5.3 (1.10)
        SGI running Irix 6.2 using SGI MIPSpro 6.2 and beta 7.2 compilers (1.9)
        SGI running Irix-6.2 (1.9.8)
        SGI running IRIX 6.4 (1.10)
        SGI running IRIX 6.5 (1.10.7)
        Siemens-Nixdorf RM600 running SINIX-Y (1.6)
PowerPC or RS/6000:
        IBM RS/6000 running AIX 3.1 using gcc and cc (1.6.86)
        IBM RS/6000 running AIX 3.2.5 (1.8)
        IBM RS/6000 running AIX 4.1 (1.9)
        IBM RS/6000 running AIX 4.3 (1.10.7)
        Lynx 2.3.1 120495 (1.6.86) (footnote 9)
        Lynx 2.5 (1.9) (footnote 10)
        Linux DR3 GENERIC #6 (1.10.5.1) (presumably LinuxPPC too)
        Mac OS X ALL (footnote 14)
        Mac OS X Darwin 6.6 Darwin Kernel Version 6.6 (1.11.1p1)
        Mac OS X Darwin 5.5 Darwin Kernel Version 5.5 (1.11.6) (footnote 12)
        Mac OS X Darwin 5.5 Darwin Kernel Version 5.5 (1.12.1) (footnote 12)
SPARC:
        Sun SPARC running SunOS 4.1.x (1.10)
        Sun SPARCstation 10 running Solaris 2.3 using gcc and cc (about 1.4A2)
        Sun SPARCstation running Solaris 2.4 using gcc and cc (about 1.5.91)
        Sun SPARC running Solaris 2.5 (1.8.87)
        Sun SPARC running Solaris 2.5.1 using gcc 2.7.2.2 (1.9.14)
        Sun SPARC running Solaris 2.6 (1.10.7)
        Sun UltraSPARC running Solaris 2.6 using gcc 2.8.1 (1.10)
        NextSTEP 3.3 (1.7)
        Sun SPARC running Linux 2.0.17, gcc 2.7.2 (1.8.87)
        Sun UltraSPARC running Solaris 2.8 using gcc 2.95.3
VAX:
        VAX running VMS 6.2 (1.9+patches, client-only)
          (see README.VMS for information on necessary hacks).

(footnote 2)
        Some Irix 4.0 systems may core dump in malloc while running
        CVS.  We believe this is a bug in the Irix malloc.  You can
        workaround this bug by linking with "-lmalloc" if necessary.
        (about 1.4A2).

(footnote 4) Comment out the include of sys/time.h in src/server.c. (1.4.93)
        You also may have to make sure TIME_WITH_SYS_TIME is undef'ed.

(footnote 6) Build in ucb universe with COFF compiler tools.  Put
        /usr/local/bin first in PATH while doing a configure, make
        and install of GNU diffutils-2.7, rcs-5.7, then cvs-1.5.

(footnote 7) Manoj Srivastava <srivasta@pilgrim.umass.edu> reports
        success with this configure command:
  CC=cc CFLAGS='-O2 -Olimit 2000 -std1' ./configure --verbose alpha-dec-osf

(footnote 8) Manoj Srivastava <srivasta@pilgrim.umass.edu> reports
        success with this configure command:
  CC=cc CFLAGS='+O2 -Aa -D_HPUX_SOURCE' ./configure --verbose hppa1.1-hp-hpux

(footnote 9) 
    Had to configure with ./configure --host=<arch>-lynx.

    In src/cvs.h, protected the waitpid prototype with ifdef _POSIX_SOURCE.
    (I might try building with gcc -mposix -D_POSIX_SOURCE.)

    LynxOS has <dirent.h>, but you don't want to use it.
    You want to use <sys/dir.h> instead.
    So after running configure I had to undef HAVE_DIRENT_H and
    define HAVE_SYS_DIR_H.

(footnote 10)
    Had to compile with "make LIBS=-lbsd" (to get gethostbyname
    and getservbyname).

(footnote 11)
    when I do a `cvs init' I get this message:
      ci: 'RCS/loginfo,v' is not a regular file
      ci:  RCS/loginfo,v: Invalid argument
      cvs [init aborted]: failed to checkin n:/safe/CVSROOT/loginfo

(footnote 12)
    Need to `configure --without-gssapi' unless you have installed Kerberos 5
    libraries on the system yourself.  For some reason Apple ships OS X with
    the Kerberos 5 headers installed and not the libraries, which confuses the
    current configure script.  Some HP, BSD, & Sun boxes have similar problems.

(footnote 13)
    A build under HP PA-RISC 2.0 will probably not run under PA-RISC 1.1
    unless "+DAportable" is added to the HP ANSI cc compiler flags.

(footnote 14)
    Because of the case-insensitive file system on Mac OS X, you cannot build
    CVS directly from a checkout from CVS.  The name of the built executable,
    `cvs', conflicts with name of the CVS administration directory, `CVS'.
    The work-around is to build the executable from a build directory separate
    from the source directory.  i.e.:

        cvs co ccvs; cd ccvs
        mkdir build; cd build
        ../configure && make

-------------------------------------------------------------------------------

Building from source code under Unix:

1)  Run "configure":

        $ ./configure

    You can specify an alternate destination to override the default with
    the --prefix option:

        $ ./configure --prefix=/usr/local/gnu

    or some path that is more appropriate for your site.  The default prefix
    value is "/usr/local", with binaries in sub-directory "bin", manual
    pages in sub-directory "man", and libraries in sub-directory "lib".

    A normal build of CVS will create an executable which supports
    local, server, or client CVS (if you don't know the difference,
    it is described in the Repository chapter of doc/cvs.texinfo).  If
    you do not intend to use client or server CVS, you may want to
    prevent these features from being included in the executable you
    build. You can do this with the --disable-client and
    --disable-server options:

        $ ./configure --disable-client --disable-server

    Typically this can reduce the size of the executable by around 30%.

    If you are building CVS with the server enabled, you can disable
    server flow control using the --disable-server-flow-control
    If you are working with a large remote repository and a 'cvs
    checkout' is swamping your network and memory, enable flow control.
    You will end up with even less probability of a consistent checkout
    (see Concurrency in cvs.texinfo), but CVS doesn't try to guarantee
    that anyway.  The master server process will monitor how far it is
    getting behind, if it reaches the high water mark, it will signal
    the child process to stop generating data when convenient (ie: no
    locks are held, currently at the beginning of a new directory).
    Once the buffer has drained sufficiently to reach the low water
    mark, it will be signalled to start again.  You may override the
    default hi/low watermarks here too by passing
    '<lowwater>,<highwater>', in bytes, as an argument to
    --enable-server-flow-control.  The low water mark defaults to one
    megabyte and the high water mark defaults to two megabytes.

        $ ./configure --enable-server-flow-control=1M,2M

    The --with-tmpdir argument to configure may be used to set a
    specific directory for use as a default temporary directory.  If not
    set, configure will pick the first directory it finds which it has
    read, write, and execute permissions to from $TMPDIR, $TMP, $TEMP,
    /tmp, and /var/tmp, in that order.  Failing that, it will use /tmp.

    The --with-umask argument to configure can be used to change
    the default umask used by the CVS server executable.

    Unlike previous versions of CVS, you do not need to install RCS
    or GNU diff.  

    If you are using gcc and are planning to modify CVS, you may want to
    configure with -Wall; see the file HACKING for details.

    If you have Kerberos 4 installed, you can specify the location of
    the header files and libraries using the --with-krb4=DIR option.
    DIR should be a directory with subdirectories include and lib
    holding the Kerberos 4 header files and libraries, respectively.
    The default value is /usr/kerberos.

    If you want to enable support for encryption over Kerberos, use
    the --enable-encryption option.  This option is disabled by
    default.

    If you want to disable automatic dependency tracking in the makefiles,
    use the '--disable-dependency-tracking' option:

        $ ./configure --disable-dependency-tracking

    This avoids problems on some platforms.  See the note at the end of this
    file on BSD.

    Try './configure --help' for further information on its usage.

    NOTE ON CVS's USE OF NDBM:

        By default, CVS uses some built-in ndbm emulation code to allow
        CVS to work in a heterogeneous environment.  However, if you have
        a very large modules database, this may not work well.  You will
        need to supply the --disable-cvs-ndbm option to configure to
        accomplish this.  If you do this, the following comments apply.  If
        not, you may safely skip these comments.

        If you configure CVS to use the real ndbm(3) libraries and
        you do not have them installed in a "normal" place, you will
        probably want to get the GNU version of ndbm (gdbm) and install
        that before running the CVS configure script.  Be aware that the
        GDBM 1.5 release does NOT install the <ndbm.h> header file included
        with the release automatically.  You may have to install it by hand.

        If you configure CVS to use the ndbm(3) libraries, you cannot
        compile CVS with GNU cc (gcc) on Sun-4 SPARC systems.  However, gcc
        2.0 may have fixed this limitation if -fpcc-struct-return is
        defined.  When using gcc on other systems to compile CVS, you *may*
        need to specify the -fpcc-struct-return option to gcc (you will
        *know* you have to if "cvs checkout" core dumps in some ndbm
        function).  You can do this as follows:

            $ CC='gcc -fpcc-struct-return' ./configure

        for sh, bash, and ksh users and:

            % setenv CC 'gcc -fpcc-struct-return'
            % ./configure

        for csh and tcsh users.

    END OF NOTE FOR NDBM GUNK.

2)  Try to build it:

        $ make

    This will (hopefully) make the needed CVS binaries within the
    "src" directory.  If something fails for your system, and you want
    to submit a bug report, you may wish to include your
    "config.status" file, your host type, operating system and
    compiler information, make output, and anything else you think
    will be helpful.

3)  Run the regression tests (optional).

    You may also wish to validate the correctness of the new binary by
    running the regression tests.  If they succeed, that is nice to
    know.  However, if they fail, it doesn't tell you much.  Often it
    will just be a problem with running the tests on your machine,
    rather than a problem with CVS.  Unless you will have the time to
    determine which of the two it is in case of failure, you might
    want to save yourself the time and just not run the tests.

    If you want to run the tests, see the file TESTS for more information.

4)  Install the binaries/documentation:

        $ make install

    Depending on your installation's configuration, you may need to be
    root to do this.

-------------------------------------------------------------------------------

Detailed information about your interaction with "configure":

The "configure" script and its interaction with its options and the
environment is described here.  For more detailed documentation about
"configure", please run `./configure --help' or refer to the GNU Autoconf
documentation.

Supported options are:

        --srcdir=DIR            Useful for compiling on many different
                                machines sharing one source tree.
        --prefix=DIR            The root of where to install the
                                various pieces of CVS (/usr/local).
        --exec_prefix=DIR       If you want executables in a
                                host-dependent place and shared
                                things in a host-independent place.

The following environment variables override configure's default
behaviour:

        CC                      If not set, tries to use gcc first,
                                then cc.  Also tries to use "-g -O"
                                as options, backing down to -g
                                alone if that doesn't work.
        INSTALL                 If not set, tries to use "install", then
                                "./install-sh" as a final choice.
        RANLIB                  If not set, tries to determine if "ranlib"
                                is available, choosing "echo" if it doesn't
                                appear to be.
        YACC                    If not set, tries to determine if "bison"
                                is available, choosing "yacc" if it doesn't
                                appear to be.

-------------------------------------------------------------------------------

Building from source code under Windows NT/95/98/2000:

You may find interesting information in windows-NT/README.

* Using Microsoft Visual C++ 5.x (this is currently broken - someone with
  MVC++ 5.x needs to regenerate the project files, but the builds using `nmake'
  below will work).

1) Using Microsoft Visual C++ 5.x, open the project `cvsnt.dsw',
   in the top directory of the CVS distribution.  If you have an older
   version of Visual C++, take a look at windows-NT/README.
2) Choose "Build cvs.exe" from the "Project" menu.
3) MSVC will place the executable file cvs.exe in WinRel, or whatever
   your target directory is.

* From the top level directory, with MSVC++ 6.0 installed, something like the
following also works:

        C:\> vcvars32
        C:\> nmake /f cvsnt.mak CFG="cvsnt - Win32 Debug"

* Using the Cygwin development environment <http://cygwin.com>, Windows clients
  and servers can be built using the instructions for building on UNIX.  For
  deploying the CVS server on Windows NT, see the `cygrunsrv' executable that
  comes with Cygwin.

* You might also try <http://wincvs.org> & <http://www.cvsnt.org>.

-------------------------------------------------------------------------------

Building from source code under other platforms:

For OS/2, see os2/README and emx/README.

For VMS, see README.VMS

Mac OS X: Builds fine, just like UNIX.

For older versions of Mac OS, you might try <http://wincvs.org>.

For a Java client, see jCVS (which is a separate package from CVS
itself, but which might be preferable to the Macintosh port mentioned
above, for example).

-------------------------------------------------------------------------------