Build
Overview
Fantom comes bundled with its own standard build engine to promote consistency and make sharing code easy. Build scripts are normal Fantom scripts which subclass from build::BuildScript
. Characteristics of build scripts:
BuildScript
base class handles common functions like command line parsing, environment setup, and logging- Subclasses define targets which are things the build script can do such as "compile", "clean", or "test"
- Targets are implemented as normal Fantom methods which can execute any procedural code needed using the APIs installed
- The
build
pod provides libraries of tasks which are designed to provide common chunks of functionality which can be composed to define targets - The
build
pod provides a library of predefinedBuildScript
classes to handle common scripts - one you will use all the time isBuildPod
used to build Fantom pods.
The build toolkit is designed to provide a consistent way to organize build scripts - it doesn't provide a comprehensive library of everything you might need to perform a build. But by predefining common scripts such as BuildPod
it reduces most scripts down to purely declarative information. When you do need the power of custom code, you can implement it cleanly as normal Fantom code.
Example
Let's create a build script called "buildtest.fan":
using build class Build : BuildScript { @target="Compile everything" Void compile() { log.info("Compile away!") } @target="Clean it all up" Void clean() { log.info("Clean away!") } }
The script above defines two targets: compile and clean. The targets are annotated with the @target
facet - the value is a string description. To print the usage of this script use "-?":
C:\dev\fan\src>buildtest -? usage: build [options] <target>* options: -? -help print usage summary -v verbose debug logging targets: dumpEnv Dump env details to help build debugging compile* Compile everything clean Clean it all up
Note that the "compile" target is marked with an asterisk indicating it is the default target because it is the first one declared. You can also explicitly override defaultTarget
. If we invoke the script with no arguments the "compile" target is executed:
C:\dev\fan\src>buildtest Compile away! BUILD SUCCESS [3ms]!
Or we can pass one or more targets as arguments:
C:\dev\fan\src>buildtest clean Clean away! BUILD SUCCESS [2ms]! C:\dev\fan\src>buildtest clean compile Clean away! Compile away! BUILD SUCCESS [2ms]!
Note: see Setup to configure your environment to run scripts using just the script filename.
BuildScript
The BuildScript
is the base class for all build scripts. It provides many useful slots you will find handy:
log
: standardized loggingscriptFile
: the file of the script itselfscriptDir
: the directory containing the scriptbinDir
: bin directory of your development environment for the current operating system
Lifecycle
A build script lifecycle is composed of these steps:
- Constructor is run and will immediately setup the environment variables such as
log
andscriptFile
. - The
setup
callback is invoked to give the script a chance to initialize itself - The
makeTargets
callback is invoked to get the list of targets - most often you will let the default implementation build this list by searching for methods which implement the@target
facet. Once initialized the list of targets is available via thetargets
field. - Command line parsed to find all the specified targets, if no targets specified then we use
defaultTarget
. - Each target method is invoked in the order specified
- If an exception is raised, the script fails and returns -1, otherwise 0 is returned.
Problems during the script should be reported via the BuildScript.log
. If an error is encountered which should terminate the script, then throw a FatalBuildErr
via this pattern:
throw fatal("I just can't go on!")
BuildPod
BuildPod
is the base class for build scripts which build a Fantom pod. The BuildPod
script defines a bunch of fields to be filled in. Plus it predefines several targets ready to use:
compile
: recompiles Fantom code into a pod file along with all associated natives (JavaScript, Java, .NET)clean
: deletes all the intermediate and derived target filesdoc
: compile fandoc to HTMLtest
: runs all tests declared by the podfull
: clean, compile, test
By convention pod source directories are organized as follows:
foo/ build.fan pod.fan fan/ ClassAlpha.fan ClassBeta.fan java/ ClassAlphaPeer.java js/ ClassAlphaPeer.js dotnet/ ClassAlphaPeer.cs test/ TestClassAlpha.fan TestClassBeta.fan res/ icon.png resource-file.txt
If you don't have tests or native code, then those directories aren't included. The build script and pod file for our directory structure above would look like:
// build.fan using build class Build : BuildPod { override Void setup() { podName = "foo" } } // pod.fan ** ** Description of foo pod. Foo is good. ** @podDepends = [Depend("sys 1.0+"), Depend("bar 1.1+")] @podSrcDirs = [`fan/`, `test/`] @podJavaDirs = [`java/`] @podJsDirs = [`js/`] @podDotnetDirs = [`dotnet/`] @podResDirs = [`res/`] @js pod foo {}
Note that all the directories are specified as Uris relative to the script directory. If you don't have native code, you can omit the podJavaDirs
, podDotnetDirs
, and podJsDirs
facets. If you don't have resource files you can omit podResDirs
. See HelloWorld for a simpler example.
Typically the pod's version is set by the build script's version
field. By default this is set to the config property buildVersion
configured in "etc/build/config.props".