Difference between revisions of "The BlackBox Build Engine"

From BlackBox Framework Wiki
Jump to navigation Jump to search
(Created page with "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 Black...")
 
Line 16: Line 16:
In case of a successful build, the following three output files are created where XXX stands for the version information:
In case of a successful build, the following three output files are created where XXX stands for the version information:


1. an installable '''blackbox-XXX-setup.exe''' file
* an installable '''blackbox-XXX-setup.exe''' file


2. a '''blackbox-XXX.zip''' file that can be installed simply by unzipping it
* a '''blackbox-XXX.zip''' file that can be installed simply by unzipping it


3. a build log file in html format named '''blackbox-XXX-buildlog.html'''
* a build log file in html format named '''blackbox-XXX-buildlog.html'''


In case of an unsuccessful build, only the build log file will be produced.
In case of an unsuccessful build, only the build log file will be produced.
----
'''Internals of the build engine'''
The build engine is implemented as a Python 2.7 script and uses a scripting mechanism
built on top of BlackBox in order to compile and Link BlackBox modules and the BlackBox.exe file
with BlackBox itself.
The scripting engine 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.
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.
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).

Revision as of 12:10, 18 August 2014

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 build log file will be produced.


Internals of the build engine

The build engine is implemented as a Python 2.7 script and uses a scripting mechanism built on top of BlackBox in order to compile and Link BlackBox modules and the BlackBox.exe file with BlackBox itself.

The scripting engine 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.

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.

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).