HOWTO: Using build.pl for fun and profit, or efficient multiproject building.
by Zachary T Welch <zw@superlucidity.net>
Last Updated: April 16, 2006

The build.pl script helps automate the process for building the various
dependencies for minisip.  It builds them under the main repository tree,
in separate trees, then installs them in a common root.

===========
Quick Start
-----------

If the repository is stable, the following step (when run from the base
of your local working copy) will bootstrap, build, and install minisip and 
its dependencies (as the current user):

	./build.pl run minisip

This command encapsulates many different individual steps, which are
described in the rest of this document and others.

------------------------
Rebuilding After Updates
........................

If you have previously tried to build in your working copy, you will
need to run a more thorough command to ensure everything is re-built:

	./built.pl bootstrap+configure+compile+install+run

This "combined action" can be understood by reading the 'actions.txt' file
(in the build documentation directory).


=============
Configuration
-------------

Before using the build script for the first time, it will be useful to
familiarize yourself with the build configuration file.  Used to establish
the package dependencies and configure options, the 'build.conf' file 
contains a few perl definitions that should be easy to understand and change.

Instead of modifying the 'build.conf' file directly, you should locate 
the file named 'build.local' and make the relevant changes there.  This
file is loaded immediately after the global build.conf file.

The 'build.pl' will create a 'build.local' if one does not exist.

----------
Batch Mode
..........

By default (without '-S'), the script will only apply actions to the 
targets explicitly specified on the command line.  With '-S', the script 
will also include dependencies of the targets specified on the command line.

The '$toggle_batch' option allows you to swap these behaviors.  When set to
a non-zero value in 'build.local', the script will include dependencies by 
default and '-S' will be required to restricts actions to single projects.

The following instructions assume that you have set $toggle_batch = 1,
which is set by the default 'build.local' file.

-------------------
Default Directories
...................

The 'build.pl' script stores its own configuration files in the 'build.d'
directory by default.  This can be overridden by a command line option,
but this is not generally recommended unless you know what you are doing.

By default, the build script will create two local directories called
'build' and 'install'.  All stages (after 'bootstrap') are performed in an
"object" directory located under 'build'.  The 'install' directory is used 
as the '--prefix' to each project's configure script.

As a result, the build or install state can be cleaned simply by removing 
the appropriate directory.  This setup also makes it possible to build for 
more than one target, such as x86 and arm, at the same time (but with 
different "object directories").

You can change the location of the 'build' and 'install' directories through
the command line options or your 'build.local' file (see "Configuration").


==================
Usage Instructions
------------------

The basic command usage form is:

	./build.pl [<options>] <action(s)> <targets>

The options, actions, and targets can be discovered using the following 
help options that are built into the 'build.pl' script:

	./build.pl --help
	./build.pl --list-actions
	./build.pl --list-targets

------------------
Basic Instructions
..................

To build the entire set of projects and install them in a temporary install
directory for testing, simply issue the following command:

	./build.pl install minisip

If you have a fresh copy of the repository, this will run 'bootstrap', 
'configure', 'make', and 'make install' for each of the projects in turn.
It will pass the correct options to configure, based on the definitions
in 'build.conf' and 'build.local'. 

To clean up everything (including the bootstrap files), you can run use
the build script as well:

	./build.pl mclean minisip

At this point, the repository should contain no extra files, unless you 
have added them during the process of development.

------------------------
Building Single Projects
........................

The above examples work on all local projects required by minisip, which is
pretty much all of them.  If you want to work on a single project, you can
turn off the automatic dependency resolution.  To build only libmsip,
you can use the following sequence of commands:

	./build.pl -S compile libmsip

For that to succeed, you must have previously installed 'libmutil' and
'libmnetutil', perhaps with something like the following command:

	./build.pl -S install libmutil libmnetutil

Since 'libmnetutil' depends on 'libmutil', it would have been faster to
use the equivalent command with dependency resolution:

	./build.pl install libmnetutil


Additional options may be passed to the script that alter the build process;
run './build.pl --help' for a description of all options.


=====================
Advanced Instructions
---------------------

cat build.pl | grok --enable-wetware --ignore-pets --allow-caffeine

--------------------
For More Information
....................

Additional documentation files can be found in the following directory:

	/Documentation/build/

You are also encouraged to discuss this script in the #minisip channel,
on irc.freenode.net.