-*- outline -*-

This file attempts to describe the rules to use when hacking Octave.
DO NOT put this file into the distribution.

* Working from the repository

These notes are intended to help people working on sources checked-out from
the savannah source code repository.
These requirements do not apply when building from a distribution
tarball.

** Requirements

We've opted to keep only the highest-level sources in the repository.
This eases our maintenance burden, (fewer merges, etc.), but imposes
more requirements on anyone wishing to build from the just-checked-out
sources.  For example, you have to use the latest stable versions of
the maintainer tools we depend upon, including:

  - Autoconf <http://www.gnu.org/software/autoconf/>
  - Automake <http://www.gnu.org/software/automake/>
  - Bison <http://www.gnu.org/software/bison/>
  - Flex <http://www.gnu.org/software/flex/>
  - Git <http://git-scm.com/>
  - Gnulib <http://www.gnu.org/software/gnulib/>
  - GNU Make <http://www.gnu.org/software/make/>
  - Gzip <http://www.gnu.org/software/gzip/>
  - Libtool <http://www.gnu.org/software/libtool/>
  - Mercurial <http://mercurial.selenic.com/>
  - Perl <http://www.cpan.org/>
  - Rsync <http://samba.anu.edu.au/rsync/>
  - Tar <http://www.gnu.org/software/tar/>

Only building the initial full source tree will be a bit painful.
Later, after synchronizing from the repository, a plain `make' should
be sufficient.

** First checkout

Obviously, if you are reading these notes, you did manage to check out
this package from the repository.  For the record, you will find all the
relevant information on downloading sources at:

  http://savannah.gnu.org/hg/?group=octave

After checking out Octave, you will need to run the autogen.sh script:

  $ ./autogen.sh

This script will examine the source tree and generate some Makefile
fragments and then runs the bootstrap script.  The bootstrap script comes
from gnulib, but is kept in the Octave source archive.  It should be
updated from the gnulib sources as necssary.  The bootstrap script takes
care of checking out a copy of gnulib, running the autotools, and
generating the configure script.

If you have a copy of gnulib in some directory apart from the Octave
source tree, then pass the name of the directory containing gnulib-tool
to the bootstrap script using the option: 

  --gnulib-srcdir=DIRNAME

If you have downloaded gnulib directly, DIRNAME will be the directory where
gnulib was unpacked.  If you have installed gnulib using a package 
manager, DIRNAME is likely to be /usr/bin or /usr/local/bin(where the
gnulib-tool script resides).

By using an external gnulib directory, you can share a single gnulib source
tree among several projects.  Regardless of the location of the gnulib
sources, the bootstrap script will try to update them if it appears
that they are checked out using git.  Otherwise, it is your
responsibility to keep the gnulib sources up to date.  They change
frequently, so the best way to stay current is probably to use git to
do the job.

Additional options besides --gnulib-srcdir can be passed to autogen.sh and
they will be forwarded without modification to the bootstrap script.

Once the autogen.sh and bootstrap scripts complete successfully, you may
run

  $ ./configure
  $ make
  $ make check

At this point, there should be no difference between your local copy,
and the master copy:

  $ hg diff

should output no difference.

Additional information about coding style 

This file will eventually be extended to explain more about updating
Octave, preparing patches, and making releases.

Enjoy!

-----

Copyright (C) 2009 John W. Eaton

This file is part of Octave.

Octave 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 3 of the License, or (at
your option) any later version.

Octave 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.

You should have received a copy of the GNU General Public License
along with Octave; see the file COPYING.  If not, see
<http://www.gnu.org/licenses/>.


This file was adapted for Octave from the HACKING file that is part of
GNU Bison, which contained the following Copyright notice:

  Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009
  Free Software Foundation, Inc.

  This file is part of GNU Bison.

  This program 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 3 of the License, 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.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.