Tools
From XABSL source documents, four types of documents can be generated:
- An Intermediate Code which is executed by the XabslEngine.
Thus no additional parser is needed as on many embedded computing platforms
e.g. XML parsers are not available due to resource and portability constraints.
- An extensive HTML-documentation containing SVG-charts for each agent,
option and state which helps the developers to understand what their
behaviors do. See the start page for examples.
- Debug Symbols containing the names for all options, states,
basic behaviors, and symbols can be helpful to implement platform
and application dependent debugging tools for monitoring option and
state activations as well as input and output symbols.
- A keyword list for instance for using editors with syntax highlighting.
The graph above shows how these documents are generated. Documentation and debug symbols are generated from an intermediate XML representation using an XSLT processor. The XML representation also allows to generate different content from XABSL sources using custom XSLT style sheets. The files are automatically generated using a Makefile, which is desribed in the next section. A Ruby interpreter is required to run the XABSL compiler.
Adopting the Makefile
As there are very many input files and XSLT style sheets, it is recommended to use a Makefile instead of executing the XABSL compiler and the XSLT processor directly. There is a common XABSL Makefile. This file has to be included into a custom Makefile which should be located inside the directory of the source files. The custom Makefile must contain the following variables:
| AGENTS_FILE | The root source file agents.xabsl which defines the behavior agents and links to all other source files. |
| SOURCES | A list of all XABSL source files |
| XABSL_OUTPUT_DIR | Directory where the intermediate code and the debug symbols shall be generated. |
| XABSL_TEMP_DIR | Directory where temporary files generated during compilation can be stored. |
| INTERMEDIATE_CODE | The path of the intermediate code to be generated. |
| DEBUG_SYMBOLS | Path of the debug symbols to be generated. |
| XML_OUTPUT_DIR | Directory where the XML representation shall be generated. |
| XABSL_COMPILER_DIR | Directory where the XABSL compiler (the file xabsl.rb) can be found. |
| XABSL_COMPILER_OPTIONS | Additional options to the XABSL compiler. See below for a description of possible compiler options. |
| DOC_OUTPUT_DIR | Directory for the documentation output. |
| XSLT | An XSLT processor that can process XInclude statements (with necessary parameters). We recommend LibXSLT (http://xmlsoft.org/XSLT/). |
| DOT | Path to the dot tool. (http://www.research.att.com/sw/tools/graphviz/). This is needed for the charts in the HTML documentation. |
| DOTML_DIR | Directory that contains the DotML Schemas and XSLT stylesheets (http://www.martin-loetzsch.de/DOTML/). DotML is needed to generate the charts in the HTML documentation. |
| XABSL_XSL_DIR | Directory of the XABSL Schemas and XSLT Stylesheets relative to the source files and the custom Makefile. |
At last, the common Makefile must be included into the Makefile:
include $(XABSL_DIR)/XabslMakefile
Using the Makefile
make all
generates intermediate code and XML representation from XABSL sources. Then documentation and debug symbols are generated.
make DOC
generates the documentation. Note that single HTML pages can also be generated seperately by typing
make file_path_and_name_of_the_HTML_page.html
Some shortcuts:
make IC
Intermediate code only.
make DS
Debug symbols only.
Using the XABSL compiler
The XABSL compiler is invoked by executing the Ruby script xabsl.rb. The following options can be specified at the command line when running the XABSL compiler:
| -q, --quiet | Suppress almost any output. |
| -v, --verbose | Run verbosely. |
| -x, --xml path | Generated xml at path. |
| -i, --intermediate-code filename | Generate intermediate code in filename. |
| -a, --api-file filename | Create .api file filename and copy it to scite/Microsoft Visual Studio locations. |
| -m, --vcproj filename | Create partial .vcproj file containing a files list for a Microsoft Visual Studio project. |
| -I, --incremental directory | Incremental compiling, put dumpfiles to given directory. |
| -C, --comments | Insert additional comments into generated files. |
| -V, --vs-error-message-style | Produce Microsoft Visual Studio compliant error messages. |
| -f, --force-output | Will force output even if errors occured. |