Build Scripts
=============

The build scripts in this directory makes possible to compile and install LLVM, GNUstep and Etoile very easily (or a subset of these modules).

For Ubuntu, it can install the required dependencies too.
Feel free to send us dependency install scripts for other systems :-)

Finally these build scripts can be used to drive test builds and report any build failure by mail (including the logs in attachment). 

The main script is build.sh, this script accepts some options in argument. See 'build.sh --help' for details. 

Check build.config to know more about the default build.

**Note: Any element enclosed in bracket is optional in the examples.**


Normal Builds
-------------

For a non-test build, don't forget to provide the right installation prefix, otherwise build modules go into the build directory. You should usually do:

./build.sh --prefix=/ --update-bash-rc=yes

If you are not on Ubuntu, the `DEPENDENCY_SCRIPT` in build.config must be updated to match your system or disabled. In the latter case, you must install all the dependencies manually before running the build script.

Don't forget the build script might ask for a password several times, because sudo is invoked to install each built module.


Build Profiles
--------------

To maintain and test various build combinations independently, build.sh supports build profiles to control which module versions and is built and how. To miminize the build time, the build script tries to reuse downloaded modules accross invocations.

You can edit build profile to disable some modules in the build. For example:

	export ETOILE_VERSION=

For the Etoile module, the same can be achieved by passing the right option to the build script:

	./build.sh --etoile-version=

**Note: Any build.sh option takes priority over the value bound to the same option in the build profile.**


If you run:

	./build.sh

A 'build' directory will be created in the current directory and 'build.config' will be used as the build profile, and the compilation result is installed inside the 'build' directory.

You can create a custom build profile and pass it to build.sh:

	./build.sh --profile=./testbuild-clang31-gsreleases-etoiletrunk.profile

For a single build directory, build.sh can accept various build profiles. However in case some build profiles use the same module version but pass different options to the compiler, the output binaries could be incompatible. For example, although it is not supported currently, the same GNUstep Base version could be compiled into two incompatible binaries depending on the fragile or non-fragile ABI option (see -disable-mixedabi).

So to prevent such issue to arise, if you are not sure, use a distinct build directory per build profile:

	./build.sh --profile=./testbuild-clang31-gsreleases-etoiletrunk.profile --build-dir=./build-clang31-gsreleases-etoiletrunk


Test Builds
-----------

A test build is a normal build, plus some steps:

- run test suites (not yet implemented)
- report build failure by mail

And the following adjustments:

- the dependency script is skipped if `SUDO` is empty in the build profile ('sudo' might prevent the build to happen in background without user feedback)
- bash.rc is never updated (even when --update-bash-rc is 'yes')

You can request a test build as shown below:

	./build.sh [--profile=./someprofile.config] --test-build=yes


Mail Reporting
--------------

The test build support gives you the possibility to report build failures by sending a mail. If the same build fails repeatedly for the same error, a mail is sent only once. In other words, a test build can be invoked every hour without getting flooded with the same build failure mail over and over (if the failure isn't quickly fixed).

To set up the mail reporting, install the 'sendemail' program, edit the MAIL_TO variable (for the mail recipient) in the build profile and edit mail.config. Once it is done, source both the build profile and mail.config in your shell, and try send a mail:

	. ./build.config
	. ./mail.config
	sendemail -f $MAIL_TO -t $MAIL_FROM -s $MAIL_SMTP_SEVER [-xu $MAIL_SMTP_USERNAME -xp $MAIL_SMTP_PASSWORD] -s "build.sh is my subject'

If the mail is sent properly, you are ready to run test builds that report failures through the given mail config.

**Note**: The Ubuntu dependency script will install 'sendemail' on the first build too.


Debugging Builds
----------------

To track build failures, it's convenient to speed up the build time. You can do so by narrowing the build scope, just pass --skip--llvm-build=yes or --skip-gnustep-build=yes to prevent rebuilding modules such as LLVM and GNUstep.

If a build fails, it's possible to edit and compile the source code retrieved by build.sh without using it.
  
The build script generates some special scripts such as llvm-LLVM_VERSION.sh and PREFIX_DIR/System/Library/Makefiles/GNUstep.sh (LLVM_VERSION and PREFIX_DIR values are based on the build profile and options). You can source these scripts in your shell to hack the built modules inside the build directory:

	# Change current directory to the build directory
	cd build

	# LLVM_VERSION is trunk here (for LLVM 3.1, the script would be named llvm-3.1.sh)
	. ./llvm-trunk.sh

	# GNUstep.sh and GNUstep-reset.sh locations depend on PREFIX_DIR and --prefix-dir 
	# Here the build directory is used as the prefix (this is the default).

	# Don't source GNUstep-reset.sh if there is a prior FHS-based GNUstep install in use.
	# FHS install means GNUstep tools and libraries are installed in /usr/bin, /usr/lib 
	# or /usr/local/bin, /usr/local/lib.
	[. ./System/Library/Makefiles/GNUstep-reset.sh]

	. ./System/Library/Makefiles/GNUstep.sh

Now you can move into modules directories, edit the source code and use **make** and **[sudo -E] make install** to test your changes.

For being able to commit from the built modules (supposing you have commit access the related repositories), before running the build for the first time, SVN_ACCESS (for GNUstep) and LLVM_SVN_ACCESS (for LLVM) variables must be customized in the build profile.