The BlackBox Build Engine

The BlackBox build engine is an automated process for building BlackBox releases. It is running under Linux Debian 7 and uses wine for executing Windows programs such as BlackBox itself or InnoSetup.

The build engine is invoked periodically and builds for all branches that have new commits and that have the file appbuild/AppVersion.txt in the repository. A one line summary message is added to http://blackboxframework.org/dev/buildlog.html for every build performed.

In case of building a final release, the build engine puts the resulting files into http://blackboxframework.org/stable.

In case of building an unstable (intermediate) release such as an alpha or a beta version, the build engine puts the resulting files into a subdirectory of http://blackboxframework.org/dev which is named after the branch the build has been performed for.

In case of a successful build, the following three output files are created where XXX stands for the version information:

• an installable blackbox-XXX-setup.exe file

• a blackbox-XXX.zip file that can be installed simply by unzipping it

• a build log file in html format named blackbox-XXX-buildlog.html

In case of an unsuccessful build, only the log file will be produced. If a build is aborted and no version information is available, the log file logFile.html is created in http://blackboxframework.org/dev.

Internals of the build engine

The build engine is implemented as a Python 2.7 script and uses the scripting tool 'bbscript.exe' (BlackBox Scripting) built on top of BlackBox in order to compile BlackBox modules and and link the BlackBox.exe file with BlackBox itself.

The source code of the scripting tool can be found under the subsystem 'Script'. It essentially consists of a special 'Config' file that interprets the /PAR command line option as the file name of a BlackBox script. In order to successfully execute bbscript.exe, the BlackBox resource files must be available either from the startup directory or via the /USE command line option. Executing bbscript.exe under Linux requires (1) wine, the Windows API emulator available under Linux, and (2) for headless operation it needs Xvfb, the X-Windows virtual frame buffer that allows one to run graphical applications without any physical display device.

Two forms of scripts exist:

• BlackBox text documents stored in a .odc file: all commanders of such a file are executed from top to bottom.

• plain ASCII scripts stored in a .txt file: all qualified identifiers are executed as commands from top to bottom. Commands end at the end of the line and lines starting with # are comments.

For rebuilding BlackBox itself the script Dev/Docu/Build-Tool.odc is executed. Therefore, when adding new modules to the BlackBox distribution, this script must be adapted by inserting or appending the new module at the right position according to the compile order. It is the only place where a new module must be listed.

For rebuilding the scripting engine incrementally, i.e. BlackBox has been built before in the same directory, the script appbuild/newbbscript.txt must be executed. It compiles the new and adapted modules and links an exe file named newbbscript.exe. The involved subsystem 'Script' and bbscript.exe are not part of the generated BlackBox distribution.

There are no principal limitations for the executed scripts except that they must not wait for a user input. The build engine is thereby ready for automated unit tests.

The requirement that a script must not wait for user input is violated when creating a Sym or Code directory during BlackBox comilation. In order to avoid this problem, a customized module is used for HostFiles (see ScriptHostFiles).

In order to get access to compile time errors produced by DevCompiler.CompileThis, which is used for building BlackBox, an adapted module DevCPM (see ScriptDevCPM) is used. It simply writes the first error to the StdLog output and then generates a TRAP. The TRAP is recognized in the build process and stops it.

Note: For the future, it should be regarded as the ultimate goal to get rid of all the adapted standard modules in order to avoid maintenance problems. Also the scripting engine itself, i.e. the functionality provided by the Config file could be made available as a standard module such as DevScript because it is of general use for example for installing additional subsystems that are distributed in source form and that need a sequence of commands to be executed for proper installation.

An alternative scripting mechanism

For historical reasons there is another scripting mechanism available in the subsystems 'Cons' and 'Interp'. It is named dev0.exe and can be created by executing the script appbuild/newdev0.txt. The involved subsystems and dev0.exe are not part of the generated BlackBox distribution.

The main difference to bbscript is that dev0 does not require Xvfb but on the other side it does not allow one to run all BlackBox commands and to process (compile) all BlackBox files without modifications. It also does not allow one to run scripts stored in .odc files and it requires adaptations in much more files than bbscript does.