Download, Configure, and Build

Download Free Electron

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

If you want the latest development code, in whatever state, you can grab it with Mercurial:

hg clone
hg clone
hg clone

If you don't want to type the username and password every time, you can add a section to the .hgrc file in your home directory, using your particular password. It is generally good practice to adjust this file to not be readable by anyone but yourself.

base.prefix =
base.username = USERNAME
base.password = PASSWORD

Repository Content

The base repo contains a copy of the fundamental Free Electron source code, required for simple plugin support.

The extensions repo contains a copy of the Free Electron extension modules.

The media repo contains a copy of the Free Electron test files, like models and scenes. Currently, these media files are only needed to run the unit tests.

Install OS Software



For a quick colorama install:

curl -o
pip install colorama

Install Supporting Code

Additional technologies should be installed before compiling. You can choose which whichever ones you want. The Free Electron build should ignore modules for technology you don't have installed. A full list of installation notes can be found on a separate page.

Prerequisite Libraries

Quick Build

(currently Linux only)

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

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

cd <install path>/base

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

No environment variables are required, but CODEGEN can be used to change the build type, usually debug or optimize.

A full list of environment variables can be found on a separate page.

Environment Variables



cd <install path>/base
python bin/ here

Shell aliases are recommended. For example,

export JOB_COUNT=`/bin/grep -c \^processor /proc/cpuinfo`
alias b='python ${FE_ROOT}/bin/ -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.


Open a "Native Tools Command Prompt", either x86 or x64, depending on which kind of code you want to generate.

cd <install path>/base
python bin/ 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.


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 options. 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 completed its execution, 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, then you will always get a build failure during this step. Those modules will simply be removed from the list of things 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 neccessarily contain the same content. The string 'auto' indicates that the module participates in the "autoload" mechanism that can determine the source of requested components at run time and automatically load the required dynamic libraries just as they are needed. Some strings start with "-" to indicate some feature of that module 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,

cd <install path>/base
python bin/ 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.

cd <install path>/base
rm test/log.txt