HACKING

                         Hacking on GSL

The GSL hacker needs some stuff that the end users don't:

   Autoconf >= 2.60
   Automake >= 1.10
   Libtool  >= 1.5.24
   Texinfo  >= 4.0

Once you have this stuff, you can get the repository and start
working from your own machine.  

GSL development is hosted at http://savannah.gnu.org/projects/gsl

# ANONYMOUS CHECKOUT

To do the initial checkout of the repository try:

   bzr branch bzr://bzr.sv.gnu.org/

[from now on you can just do "bzr pull" in the gsl directory]

To generate the initial build scripts, run autoreconf -i -v or ./autogen.sh

# PEOPLE WITH SAVANNAH SSH WRITE ACCESS:

  bzr branch bzr+ssh://bzr.savannah.gnu.org/gsl/trunk/

  # editing and committing
  <edit file1>
  bzr add file2
  bzr rm file3
  bzr diff  # see changes
  bzr commit -m 'commit message' file1 file2 file3
  
  # push to repository
  bzr push

# PEOPLE WHO JUST WANT A WORKING VERSION
grab the latest bundled release at
  ftp://ftp.gnu.org/pub/gnu/gsl/

Please send a message to help-gsl@gnu.org if any of these steps don't
work.

---------- submitting patches

The best way to send us a patch is to compile from an anonymous bzr
checkout and to use a nice diff option, like 

  bzr diff -p1

Note: Please test your patch before sending it, by applying it to a
clean set of files and running 'make'.

If your patch contains lines longer than 80 characters please check
that your mailer does not break these lines.  If in doubt, send the
patch as a mime attachment or uuencoded file.

Before submitting a patch you may want to search the mailing list
archives for related information. There is a search facility for the
mailing list available at,

  http://lists.gnu.org/archive/html/bug-gsl/

---------- useful scripts

There are some useful perl scripts in the scripts/ directory:

  mkheaders.pl -- updates header files for different types from 
                  the "float" version

  mkdefuns.pl  -- creates a texinfo fragment from the function 
                  prototypes in a header file

---------- some special targets

To check for ansi compliance define a bash alias "makestrict",

    makestrict () { make $* CFLAGS="-ansi -pedantic -Werror -W -Wall -Wtraditional -Wconversion -Wshadow -Wpointer-arith -Wcast-qual -Wcast-align -Wwrite-strings -Wstrict-prototypes -fshort-enums -fno-common -Wmissing-prototypes -Wnested-externs -Dinline= -g -O4" } ;

which lets you type things like

    makestrict check

Note that total compliance to makestrict is not necessary, but it is a
useful way to locate possible problems. If you can compile your code
with

    makestrict
    makestrict CC=c++ 

then that's a good test for portability.

Also do a compilation in c89 and c99 mode explicitly

     ./configure CC=c89
     make

     ./configure CC=c99
     make

---------- warning about picking up old header files

When compiling the library it's important to use the local copies of
the header files, and not ones that have been installed previously in
/usr/local/include.

There can be confusing errors if the installed and local copies of the
headers get mixed up!  (In particular, some of them only show up when
doing 'make distcheck')

To put the local copies on your include path you need, in your Makefile.am,

INCLUDES = -I$(srcdir)/..

srcdir is always your working dir, and so $(srcdir)/.. is the
top-level dir where gsl_math.h and gsl_complex.h are located.

---------- fixing Makefile.am

The SUBDIRS and SUBLIBS variables have to be updated manually.

----------- Pre-release checks

* Make all internal functions static, and have all exported functions
& variables prefixed with gsl_ or GSL_. Useful command for checking this: 

 nm -A -g -P .libs/*.a  | perl -a -n -e 'print if $F[1] !~ /gsl_/ && $F[2] ne "U"'

* Make sure config.h is used consistently. This is especially relevant
for HAVE_INLINE use in installed headers.  

 grep config.h gsl/*.h    --- shouldn't match anything
 grep -L config.h */*.c | grep -v _source  --- gives files not using config.h

* Make a master gsl header file of cat gsl/*.h > tmp.c and try
compiling it to test all possible conflicts

* Check that the library passes "make check" with -O3 and -mfpmath=sse -msse2, 
also check with -funsigned-char (to simulate Power/ARM)
and -std=c89 -ansi -pedantic, now that GCC uses c99 by default 
instead of c89.

* Make sure the library passes "make check" with export
GSL_TEST_VERBOSE=1 (it is possible to get segfaults in the verbose
test output functions if they are called with the wrong format string,
and these don't show up otherwise).

* Do make distcheck with /usr/bin/install and install-sh

make distcheck
make distcheck INSTALL=/home/bjg/gsl/gsl-1.13/install-sh  # absolute location of install-sh

----------- Notes on making a release

* Edit the version numbers in configure.ac:
  AC_INIT     (remove the + for a release and add it back after the release)
  dnl gsl-X.Y (follow the comments in this section)
  GSL_CURRENT
  GSL_REVISION
  GSL_AGE

* Adjust the libtool version numbers according to the procedure in the
  Libtool manual (Updating library version information).  Use 'nm' to
  check what functions have been added and removed.

* run:
  > autoreconf -W all
  to check any obsolete directives in configure.ac, as well
  as the Makefile.am's

* Update the NEWS file.

* Update the BUGS file using scripts/BUGS.pl

* Regenerate everything. make dist, unpack somewhere and then
configure, make, make check.  Try running make check under ulimit -v
65536 to be sure that excessive memory is not required to do the
compilation.

* Test with bounds checking version of GCC and valgrind (belt and braces)
Note that you can run all the test under valgrind with the TESTS_ENVIRONMENT
variable

  $ TESTS_ENVIRONMENT="valgrind --tool=memcheck" make check

Note that this only works if configure was run with --disable-shared,
because otherwise the shared library libtool scripts themselves are
run under valgrind giving misleading results.

* Tag release with: bzr tag release-X-Y

* Upload to ftp-upload.gnu.org with GPG signatures (see http://www.gnu.org/prep/maintain/maintain.html)
  /incoming/ftp for official releases
  /incoming/alpha for test releases

  3 files to upload:
  * gsl-X.Y.tar.gz
  * gsl-X.Y.tar.gz.sig           (generate with gpg -b gsl-X.Y.tar.gz)
  * gsl-X.Y.tar.gz.directive.asc (generate with gpg --clearsign gsl-X.Y.tar.gz.directive)

  Ensure that the directive file contains a symlink for gsl-latest.tar.gz

* Submit updated entry to GNU Free Software Directory.

* Update webpages, including the link to the NEWS file (see below)

* Announce on the mailing lists info-gsl@gnu.org,
gsl-announce@sourceware.org, info-gnu@gnu.org.  It is best to announce
on the smaller lists first before announcing on info-gnu@gnu.org to
catch any errors. Remember to check the version number is updated in
all announcements!

* Later you can post an announcement on the na-digest list
na.digest@na-net.ornl.gov or freshmeat.net

----------- Notes on updating documentation

* edit doc/gsl-ref.texi and make sure copyright years are current

* Make html docs using texi2html, 

    cd doc ; mkdir html ; cd html
    ../texi2html -verbose -split_chapter -expandinfo ../gsl-ref.texi

* Make complete GNU docs using Gendocs.sh

    $ cd doc
    $ wget "http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs.sh"
    $ wget "http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs_template"
    $ sh gendocs.sh --html --ifinfo gsl-ref "GNU Scientific Library -- Reference"
    # The --html --ifinfo flags above ensure that the @ifinfo sections are expanded in the HTML versions,
    # otherwise the equations won't show up properly
    # $ sh gendocs.sh gsl-ref "GNU Scientific Library -- Reference"

    # PDF might fail in above step due to eps files, execute these commands for PDF/PS generation
    $ make ps ; ps2pdf gsl-ref.ps gsl-ref.pdf
    $ gzip gsl-ref.ps
    $ cp gsl-ref.ps.gz gsl-ref.pdf manual/

    # Edit manual/index.html and manually add entry for gsl-ref.ps.gz and update size info for gsl-ref.pdf

    # NOTE DON'T TRY TO IMPORT - it doesn't work as .GZ files tend to be ignored
    # JUST COPY THE FILES INTO A CHECKED OUT AREA AND CVS ADD/REMOVE AND COMMIT THEM

    # Edit the checked out gsl.html and update version numbers

* Tag with "cvs tag release-X-Y" for version X.Y

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

Notes for Volunteers
====================

1) Study the GSL Design Document at http://www.gnu.org/software/gsl/
It contains the project coding standards and other useful information.

2) Make sure you are allowed to release code under the GPL. It may be
necessary to get a written disclaimer from your employer to confirm
it.  You don't need to assign copyright to us, but you need to check
that you are allowed to release GPL software -- otherwise the work
will be wasted.

3) Tell Brian Gough (bjg@network-theory.co.uk) what you plan to do
(I'll make sure nobody else starts on it).  Subscribe to the
gsl-discuss@sourceware.org mailing list (a digest version is
available to avoid too many messages)

4) Literature search (this is discussed in the Design document).

5) Post on gsl-discuss@sourceware.org periodically to keep us
updated of your progress.  Make patches available somewhere for people
to try out.  Code goes into GSL when it is stable and well-tested, and
has documentation.

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

Savannah Information
========================

Developer Access via SSH.

Only project developers can access the Bzr tree via this method. SSH2
must be installed on your client machine.  Put the following 
in your ~/.ssh/config file:

  Host subversions.gnu.org
     Protocol 2
     ForwardX11 no

In the example below substitute 'USER' with your account username.
Your savannah web password is not used for Bzr --- you have to
register an SSH Shared key in the Account Maintenance page.

Source tree:

  bzr checkout bzr+ssh://USER@bzr.savannah.gnu.org/gsl/trunk/

HTML tree:

  export CVS_RSH=ssh
  cvs -z3 -d:ext:USER@cvs.savannah.gnu.org:/web/gsl co gsl