diff doc/interpreter/contrib.txi @ 14150:87f06b9990bb stable

doc: improve documentation for building Octave * install.txi, contrib.txi: Improve documentation for building Octave, including listing dependencies.
author John W. Eaton <jwe@octave.org>
date Thu, 05 Jan 2012 17:34:30 -0500
parents 72c96de7a403
children 72b8b39e12be c49d891eb263
line wrap: on
line diff
--- a/doc/interpreter/contrib.txi
+++ b/doc/interpreter/contrib.txi
@@ -1,3 +1,4 @@
+@c Copyright (C) 2012 John W. Eaton
 @c Copyright (C) 2008-2012 Jaroslav Hajek
 @c
 @c This file is part of Octave.
@@ -25,6 +26,8 @@
 
 @menu
 * How to Contribute::
+* Building the Development Sources::
+* Basics of Generating a Changeset::
 * General Guidelines::
 * Octave Sources (m-files)::
 * C++ Sources::
@@ -41,6 +44,86 @@
 (@url{http://octave.sf.net}).  Note that the Octave project is
 inherently more conservative and follows narrower rules.
 
+@node Building the Development Sources
+@section Building the Development Sources
+
+In addition to all the tools (both optional and required) that are
+listed in @ref{Build Dependencies} you will need:
+
+@table @asis
+@item Mercurial
+Distributed version control system (@url{http://mercurial.selenic.com}).
+Octave's sources are stored in a Mercurial archive.
+
+@item Git
+Distributed version control system (@url{http://git-scm.com}).  The
+gnulib sources that Octave depends on are stored in a Git archive.
+@end table
+
+Once you have the required tools installed, you can build Octave by
+doing
+
+@itemize @bullet
+@item
+Check out a copy of the Octave sources:
+@example
+hg clone http://hg.savannah.gnu.org/hgweb/octave
+@end example
+
+@item
+Change to the top-level directory of the newly checked out sources:
+@example
+cd octave
+@end example
+
+@item
+Generate the necessary configuration files:
+@example
+./autogen.sh
+@end example
+
+@item
+Create a build directory and change to it:
+@example
+mkdir build
+cd build
+@end example
+By using a separate build directory, you will keep the source directory
+clean and it will be easy to completely remove all files generated by
+the build.  You can also have parallel build trees for different
+purposes that all share the same sources.  For example, one build tree
+may be configured to disable compiler optimization in order to allow for
+easier debugging while another may be configured to test building with
+other specialized compiler flags.
+
+@item
+Run Octave's configure script from the build directory:
+@example
+../configure
+@end example
+
+@item
+Run make in the build directory:
+@example
+make
+@end example
+@end itemize
+
+Once the build is finished, you will see a message like the following:
+
+@example
+@group
+Octave successfully built.  Now choose from the following:
+
+   ./run-octave    - to run in place to test before installing
+   make check      - to run the tests
+   make install    - to install (PREFIX=...)
+@end group
+@end example
+
+@node Basics of Generating a Changeset
+@section Basics of Generating a Changeset
+
 The preferable form of contribution is creating a Mercurial changeset
 and sending it via e-mail to the octave-maintainers mailing list.
 Mercurial is the source code management system currently used to develop