-*- outline -*-

This file attempts to describe the rules to use when hacking Octave.
Don't put this file into the distribution.

* Working from the repository

These notes intend to help people working on the checked-out sources.
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:

  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 source 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 that directory to the bootstrap
script using the

  --gnulib-srcdir=DIRNAME

option (all options passed to autogen.sh are forwarded to the
bootstrap script).  This way, 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.

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