$Id: README-CVS,v 1.25 2007/03/12 04:54:24 jhs Exp $


HOW TO BUILD PIKE FROM CVS

If you like to live at the bleeding edge you can download Pike from
CVS with all the latest additions from the developers.  There are two
major branches in the archive, the latest stable branch and latest
development branch.  Stable versions have an even minor version
number, i.e. 7.0.x, 7.2.x, 7.4.x, whereas the development branches
have an odd minor version.

Keep in mind that the CVS versions are under heavy development and
have not been tested nearly as well as the offcial releases.  You use
the code AT YOUR OWN RISK.


DEPENDENCIES

Building from CVS requires the same tools as building from a source
distribution (gnu m4, bison and a C compiler, suggested also GNU make
and libz), and then some.  In addition to thosee requirements, you
need a working Pike, autoconf and gcc (to generate the dependency
files; another compiler can be used to do the actual compilation).

Not all autoconf versions meet Pike's requirements.  Autoconf version
2.13 and 2.52 are known to work.  Versions 2.53 through at least 2.57
are known to not work.


CHECKING OUT PIKE FROM CVS

1. Get a recent version of cvs.

2. Login to the CVS server:

         cvs -d :pserver:anon@cvs.roxen.com:/cvs login

   Just hit enter on the password prompt.

3. Check out the source:

         cvs -z3 -d :pserver:anon@cvs.roxen.com:/cvs co Pike/7.7

   substitute 7.7 for whatever version you want to get.

The top-level makefile (in this directory, not the src directory) has
all the magic you need to build Pike directly from CVS.  Just type
'make'.  It is preferable to build from the toplevel since it avoids
contaminating the source tree with object files and other generated
files.

Other interesting make targets are:

install             Compile and install in default location.
install_interactive Interactive install.
tinstall            Test install, i.e. install in build directory.
verify              Do a test install and run the testsuite with the
                    installed Pike.
just_verify         Run the testsuite directly with the Pike binary in
                    the build tree.
run_hilfe           Run hilfe without installing Pike.
pike                Build only the Pike core, do not recurse into the
                    module directories.
documentation       Build the reference documentation from the
                    source.  See the refdoc subdirectory.
depend              Build the files that tracks dependencies between
                    the source files.  This is necessary to ensure
                    correct rebuilding if some of the source files
                    change, but not if you only intend to use the
                    build tree once.  It's not run by default.
source              Prepare the source tree for compilation without
                    the need for a preexisting installed Pike.
force_autoconfig    Force a build of the configure scripts.  This is
                    useful e.g. if a new module directory is added in
                    the CVS.
force_configure     Force configure to be run (recursively).  If
                    you've installed a new library and want Pike to
                    detect it, then the simplest way is to remove
                    config.cache in the build directory (or perhaps
                    just delete the relevant variables in it) and then
                    use this target.
dump_modules        Dump the Pike modules directly in the build tree.
                    That makes Pike load faster if it's run directly
                    from there, e.g. through the bin/pike script (see
                    below).  These dumped modules are not used for
                    anything else.  After this has been run once, any
                    changed Pike modules will be redumped
                    automatically by the main build targets.
undump_modules      Remove any modules dumped by dump_modules, and
                    remove the redump step described above.
force_dump_modules  Force all Pike modules to be redumped, not just
                    those whose source files have changed.
snapshot            Create a snapshot export tarball.
export              Create a source dist and bump up the build number
                    (if you have cvs write access).  Please do not
                    check in the generated files.
clean               Remove all the built binary files.
cvsclean            Remove all files that are generated automatically,
                    i.e. bring the tree back to the state as if it
                    was checked out from the CVS.


CONFIGURE OPTIONS AND BUILD VARIABLES

If you want to pass arguments to the configure script (see below), the
simplest way is to use the CONFIGUREARGS variable, like this:

    make CONFIGUREARGS="--prefix=/usr/local/my-pike --with-security"

The arguments passed through CONFIGUREARGS are remembered in the build
tree and reused if CONFIGUREARGS is undefined or the empty string.
You therefore don't need to repeat them every time, but you can still
change them later if you like.  There's a special case for the --help
argument: If CONFIGUREARGS is set to '--help' then the help text from
the configure script is shown and nothing else is done, and the stored
CONFIGUREARGS setting isn't affected.

The build targets also creates a script 'pike' in the bin subdirectory
which runs the built Pike directly without installing it first.  If
you want to use Pike this way (which is mainly useful if you update
from CVS often), you should consider doing 'make dump_modules' to make
it start faster.


Some options for the configure script are:

--prefix=/foo/bar         if you want to install Pike in /foo/bar,
                          default is /usr/local.
--without-gdbm            compile without gdbm support
--without-bignums         disable support for large integers
--without-gmp             compile without gmp support (implies
                          --without-bignums)
--with-rtldebug           compile with runtime debug checks
--without-cdebug          compile without debug symbols (-g)
--with-debug              same as --with-rtldebug --with-cdebug
--without-debug           same as --without-rtldebug --without-cdebug
--without-copt            compile without -O2
--without-threads         compile without threads support (see
                          also the section 'If It Doesn't Work' below)
--without-zlib            compile without gzip compression libary
                          support
--without-dynamic-modules compile statically, no dynamic loading
                          used (makes the binary larger)
--without-mysql           compile without mysql support
--with-profiling          enables profiling Pike code but slows
                          down interpreter a little
--with-poll               use poll instead of select
--with-dmalloc            compile with memory tracking, makes Pike
                          very slow, use for debugging only.
--with-security           enable internal object security system


You might also want to set the following environment variables:

CFLAGS     Put extra flags for your C compiler here.
CPPFLAGS   Put extra flags for your C preprocessor here
           (such as -I/usr/gnu/include)
LDFLAGS    Put extra flags to your linker here, such as
           -L/usr/gnu/lib and -R/usr/gnu/lib


MANUAL BUILDING

Instructions if you want to do the build more manually:

1. cd src ; ./run_autoconfig
   This creates configure files and Makefile.in files.

2. Create a build directory an cd to it.  Do NOT build in the source
   dir, doing so will make it impossible to do 'make export' later.

3. Run the newly created configure file located in the src dir from
   the build dir.  Make sure to use an absolute path! This creates the
   Makefiles you need, e.g. Makefile from Makefile.in and machine.h
   from machine.h.in.  If you don't use an absolute path the debug
   information will be all warped...

4. If needed, edit config.h and Makefile to suit your purposes.  We
   have tried to make it so that you don't have to change config.h or
   Makefile at all.  If you need to do what you consider 'unnecessary
   changes' then mail us and we'll try to fit it into configure.  If
   possible, use gnu make, gcc, gnu sed and bison.

5. Run 'make'
   This builds Pike.

6. Optionally, run 'make verify' to check that the compiled driver
   works as it should (might be a good idea).  This will take a little
   time and use quite a lot of memory, because the test program is
   quite large.  If everything works out fine no extra messages are
   written.

7) If you want to install Pike, write 'make install'.  This will put
   your Pike in <prefix>/pike/<version>/. This way, you can install
   many Pike versions in parallell on the system if you want to.  To
   put it below <prefix> directly, as other packages usually do, run
   'make INSTALLARGS="--traditional" install' instead.

After doing this, DO NOT commit the generated files.  They are placed
in .cvsignore files so you shouldn't have to bother with them.


IF IT DOESN'T WORK

 o Try again.

 o Try running 'make depend'.

 o Your sh might be too buggy to run ./configure (this is the case on
   A/UX).  Try using bash, zsh or possibly ksh.  To use bash, first
   run /bin/sh and type:

   $ CONFIG_SHELL=full_path_for_bash
   $ export CONFIG_SHELL
   $ $CONFIG_SHELL ./configure

 o If you are not using GNU make, compile in the source dir rather
   than using a separate build dir.

 o ./configure relies heavily on sed, if you have several sed in your
   path try another sed (preferably gnu sed).

 o configure might have done something wrong, check machine.h and
   report any errors back to us.

 o Your gmp/gdbm libraries might not be working or incorrectly
   installed; start over by running configure with the appropriate
   --without-xxx arguments.  Also note that threads might give
   problems with I/O and signals.  If so you need to run configure
   --without-threads.

 o Try a different compiler, malloc, compiler-compiler and/or make
   (if you have any other).


BUGS

If you find a bug in the interpreter, typically if Pike dumps core,
the first thing to do is to make sure it is compiled with the
--with-rtldebug configure flag.  If not, reconfigure and recompile
with that and see if you get another error.  When you've done this,
please report the bug to us at http://community.roxen.com/crunch/ and
include as much as you can muster of the following:

  o The Pike version.  (Try pike --version or look in src/version.h)
  o What kind of system hardware/software you use (OS, compiler, etc.)
  o The piece of code that crashes or bugs, preferably in a very
    small Pike-script with the bug isolated.  Please send a complete
    running example of something that causes the bug.
  o A description of what it is that bugs and when.
  o If you know how, then also give us a backtrace and dump of vital
    variables at the point of crash.
  o Or, if you found the error and corrected it, just send us the
    bugfix along with a description of what you did and why.
