FreeElectron
Download, Configure, and Build

Download Free Electron

http://www.freeelectron.org/release

Untar the bzip2 file where ever you please. Remember that path for your FE_ROOT environment variable.

Install OS Software

Debian/Ubuntu: apt-get install csh mercurial python

Windows: http://www.activestate.com/Products/ActivePython/

Install Supporting Code

Additional technologies should be installed before compiling. A full list of installation notes can be found on a separate page.

Prerequisite Libraries

Quick Build

For a simple build, the makefile found at the root of the installation should suffice.

First edit the local.py file in the base directory. This describes what you want built and what external libraries you want to use.

cd <install path>/base
<edit> local.py
make

A developer may wish to build with more control. The easy build above uses the same procedure as shown below, but the makefile hides the details.

Setup Your Environment

At a minimum, two environment variables need to be set.

export FE_ROOT=<install path>/base
export CODEGEN=optimize (validate, debug, profile, or optimize)

For more control, a full list of environment variables can be found on a separate page.

Environment Variables

Compile

Linux

cd $FE_ROOT
python $FE_ROOT/bin/forge.py here

Shell aliases are recommended. For example,

export JOB_COUNT=`/bin/grep -c \^processor /proc/cpuinfo`
alias b='python ${FE_ROOT}/bin/forge.py -j ${JOB_COUNT}'
alias ba='b here'
alias bc='b clean here'
alias bt='b unit'

meaning build, build all, build clean, and build/run tests.

Win32

cd %FE_ROOT%
python %FE_ROOT%/bin/forge.py here

See the files ba.bat, bc.bat, and bt.bat included in the bin directory.

Watching the Build

As long as you don't set the environment variable PRETTY to 0, you should get a neatly formatted colorful output during the code compilation.

A full build proceeds through several distinct steps. It may be help to recognize what to expect during the build.

Auto-Configuring

The first step is to determine the fundamental build environment, such as the compiler and its settings, ccache and distcc availablilty, and python version.

Module Filtering

After general configuring, each of modules in each module set is configured individually. The first message during this step may involve custom configuration similar to the previous step, such as alternate compilers.

After the configuration messages for each module set, a count of modules for that set is announced and outstanding dependency issues hindering any of those modules may be listed. This is followed by a long single line that lists all the requested modules for that module set, along with some configuration data, such as versions and option. If there were problems, small strings can show up here, like "fail:build", which means that a minimal build-and-run test for that module could not be compiled, perhaps due to missing headers or libraries. If that minimal test compiled, but threw an uncaught exception, you may get "fail:exception". If the minimal test runs successfully, but returned a non-zero exit code, you may get "fail:run".

If a module is otherwise confident that it can be built and lists another module as a prerequisite, then if that prerequisite module could not be built, the first module will show the string "removed" and not remain on the list to be built. This determination can propogate.

The setups for each module are allowed to insert arbtrary strings, so you may get other short messages.

A module failure during this step is not generally a fatal issue. Some failures may be expected. For example, if you do not have Houdini and Maya installed on your machine, but you do have the 'houdini' and 'maya' modules active in your local.py, then you will always get a build failure during this step. Those modules will simply be removed from the list to be compiled.

There are some common non-error messages in concatenated module list. Aside from version numbers, the string 'dl' indicates that a dynamic library will be built, and 'lib' indicates that a static library will be built. If both are built, they do not neceessarily contain the same content. The string 'auto' indicates that the module participates in the "autoload" mechanism that can find the source of requested components and automatically load the required dynamic libraries just as they are needed. Some strings that start with "-" to indicate some feature of that module that has been deactivated, often giving the name of another module.

Scanning Dependencies

The dependency scan may only print two lines, one to start and a summary after it is done. However, if there are issues, like an include loop, warnings will follow.

Compiling and Linking

Once the build plan has been determined, the actual compilation commences. If all goes perfectly, each object, library, or executable file that is generated will show up in the output as one short line.

If there are any warnings or errors, they will be sent to the terminal once that generation of the relevant file is completed or terminated. The warning level is set to be quite verbose, so many of the third party headers can present unpleasant streams of warning messages.

Time Reporting

After all the files have been built (or have failed to build), a list is presented of how many seconds each module took to build.

After this, a total elapsed time should be the last message of the build.

Run Unit Tests

Many modules contain unit tests. To run the unit tests for all the active modules (selected with FE_EXT or local.py),

python ${FE_ROOT}/bin/forge.py unit

If the tests have already been run since the last build, they generally don't build again. You can force the tests by removing the current log of the results before running the tests again. This log is automatically removed when the source is rebuilt.

rm ${FE_ROOT}/test/log.txt