-*- 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 cloned 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-cloned
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/>
  - 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 clone

If you are reading these notes, you may have already managed to clone
this package from the repository.  For the record, you will find all the
relevant information on downloading sources at:

  http://www.octave.org/download.html

After cloning Octave, you will need to run the bootstrap script:

  $ ./bootstrap

This script will examine the source tree and generate some Makefile
fragments, then run autotools scripts to generate Makefile.in files from
Makefile.am files and create the configure script.  The bootstrap script
comes from gnulib, but is kept in the Octave source archive.  It should
be updated from the gnulib sources as necessary.

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.  Since 2011, the gnulib sources are a Mercurial
subrepository, so they will be automatically updated to the
corresponding Mercurial revision if you update the working directory to
a past revision not too far in the past.

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

Once the bootstrap script completes successfully, you may configure and
build Octave.  We recommend that you build Octave in a separate
directory tree from the sources.  For example, if you have just finished
running the bootstrap script in the top-level source directory, run the
following commands to create a build tree, configure, and build Octave:

  $ mkdir .build
  $ cd .build
  $ ../configure
  $ make
  $ make check

At this point, there should be no difference between your working tree
and the currently visited hg revision:

  $ hg diff

should output no difference.

** Coding style

The most important advice is to follow any conventions you detect in the
file being edited.  In addition, Octave maintainers have written a lot
on the subject.  See "Appendix C: Tips and Standards" and
"Appendix D: Contributing Guidelines" in the PDF documentation.

* Bugs and patches

See the file BUGS in this directory for more guidance on reporting bugs
and preparing patches.

* Code layout

An overview of the directory layout of Octave's source files:

  doc           -- Texinfo documentation for Octave


  examples      -- some example files


  gnulib-hg     -- gnulib subrepo.  This is a clone of the gnulib source
                   tree maintained by the Octave project.  The default
                   branch is identical to the upstream gnulib sources.
                   There is also an "octave-stable" branch that may
                   contain changes as needed for the "stable" branch in
                   the Octave archive.  We usually don't want to update
                   gnulib sources when going from one stable point
                   release to the next, but we occasionally need to
                   include small updates.


  libgnu        -- gnulib sources that we use.  The files here are
                   copied here from the gnulib directory by the
                   bootstrap script.


  liboctave     -- C++ interfaces to the numerical libraries, Fortran
                   numerical libraries, various OS facilities, and utility
                   functions

    array       the base Array, NDArray, Matrix, and Sparse classes

    cruft       various numerical libraries (mostly Fortran)

      amos             bessel functions

      blas-xtra        wrappers for blas functions used in Octave

      daspk            large scale differential algebraic equation solver

      dasrt            differential algebraic equation solver with root finding

      dassl            differential-algebraic system solver

      fftpack          subroutines for fast fourier transforms

      lapack-xtra      wrappers for lapack functions used in Octave

      misc             miscellaneous utilities

      odepack          ordinary differential equation solver

      ordered-qz       code for ordering eigenvalues for QZ factorization

      quadpack         subroutines for numerical integration

      ranlib           random number generators

      slatec-err       slatec error handling library

      slatec-fn        various special function subroutines

    numeric     C++ numerical algorithms and interfaces to the Fortran
                algorithms

    operators   code for operators that act on base classes such as Array

    system      OS-related functions
 
    util        utility and miscellaneous functions

  libinterp     -- The interpreter itself plus lots of infrastructure
                   around it.  Octave's extensive octave_value class
                   hierarchy for polymorphically handling all Octave
                   types is defined here.  The built-in functions are
                   also defined here.

    octave-value     The octave_value class hierarchy.  These are the
                     container classes that hold various Octave data
                     types like struct numerical arrays, structure
                     arrays, and cell arrays.

    parse-tree       Classes that define the parse tree for the
                     interpreter.

    interp-core      Core utilities for the interpreter.  There are no
                     DEFUN functions (callable from the scripting
                     language) defined here.

    interpfcn        Functions closely related to the interpreter.
                     Includes DEFUN functions (callable from the
                     scripting language).  Also may export C++ functions
                     that are used in other parts of the interpreter.

    corefcn          Statically linked DEFUN functions (callable from
                     the scripting langauge).  No C++ functions exported
                     for use in other parts of the interpreter.

    dldfcn           Dynamically linked DEFUN functions (callable
                     from the scripting language).  If you see "help
                     foo" telling you that foo is defined in foo.oct,
                     then foo.cc will be found here and contain the
                     source code.

    operators        Definitions and template instantiations for
                     operators for all possible Octave type
                     combinations.

    template-inst    Some C++ template instantiations.


  libgui        -- the graphical user interface of GNU Octave

    src              source files.

      m-editor       source files for the m-file editor.

      octave-adapter souce files for the octave layer for threadsafe
                     communication with the octave interpreter.
      qtinfo         source files for the Qt texinfo browser.

      icons          icon files that will be compiled into the
                     executable via a resource file.

    qterminal        Qt terminal widget

    languages        translation files and list of translators.

    kb-layouts       various files need by the qterminal widget that has
                     been derived from Konsole.
      

  scripts       -- functions written in the Octave language

    audio            play and record sound files (system dependent)

    deprecated       older deprecated functions

    elfun            elementary mathematical functions

    @ftp             ftp object class

    general          utility functions

    geometry         geometry algorithms

    help             help subsystem functions

    image            image processing

    io               input/output functions

    linear-algebra   linear algebra stuff

    miscellaneous    stuff that doesn't fit anywhere else

    optimization     zero finders and minimizers

    path             functions for path manipulation

    pkg              the package manager

    plot             plotting functions

    polynomial       polynomial manipulation

    prefs            user-defined preferences

    set              set manipulation

    signal           signal processing

    sparse           sparse matrix support

    specfun          special mathematical functions

    special-matrix   functions for generating special types of matrices

    startup          initialization functions

    statistics       statistical functions, distributions, and tests

    strings          character string manipulation

    testfun          unit testing

    time             time and date functions


  test          -- tests for the interpreter

    test_ .m         fixed tests for the interpreter

    fntests.m        script to run function tests embedded in C++ and .m
                     files

----
John W. Eaton
jwe@octave.org


Last updated: Thu, 10 Jan 2013 10:46:41 EST


################################################################################

Copyright (C) 2009-2012 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/>.