Compilation, deployment, installation

This section describes how to build new releases of Lhogho sources, how to install a release, how to compile Lhogho and rebuild its documentation.

Note:

To build Lhogho you need the following tools: GCC (for the Lhogho compiler), DOXYGEN (for the Lhogho documentation), GZIP and TAR (for packaging and unpackaging releases).

In all code examples below ?.?.??? stands for the full release number (e.g. 0.0.005 )

• Preparing a Developer's Release
• Installing a release
• Compiling Lhogho and its documentation
• Compiling only Lhogho
• Compiling only Lhogho documentation
• Cleanup
• Installing documentation
• Compile defines
• Compile debug defines
• Testing Lhogho

Preparing a Developer's Release

A developer's release is a package containing all Lhogho sources (including the compiler and the documentation). The Developer's release does not include Lhogho binary or the HTML version of the documentation.

To prepare a new release first set the release version in file src/version. Then from the src folder execute:

make release

As a result three new files should appear in the folder:

lhogho.?.?.???.src.tar.gz
lhogho.?.?.???.doc.tar.gz
lhogho.?.?.???.bin.tar.gz

The names of the files start with lhogho followed by the complete release number - a sequence of X.Y.ZZZ, where X is the major version number, Y is the minor version number and ZZZ is the build number.

The file lhogho.?.?.???.src.tar.gz is the Developer's release. It contains compiler and documentation sources needed to recompile Lhogho and regenerate its documentation.

The file lhogho.?.?.???.doc.tar.gz contains the Developer's Documentation in preprocessed HTML format. It is needed only if the documentation sources cannot be rebuilt with Doxygen. The Developer's Documentation in this package is platform independent.

The file lhogho.?.?.???.bin.tar.gz contains the binary (executable) of the Lhogho compiler along with one simple test source file. The binary file is strictly platform dependable. It is highly suggested to recompile Lhogho rather than to use a prebuilt binary.

Installing a release

Releases are deployed in the form of GZIPed TARred files. Provided that you have downloaded lhogho.?.?.???.src.tar.gz in an empty folder and this folder is your current folder, installation completes in this way:

gzip -d lhogho.?.?.???.src.tar.gz
tar -xf lhogho.?.?.???.src.tar

The commands above create a folder src containing all sources of the release. For a large number of operating systems it is possible to directly unpack the *.TAR.GZ file from the user interface.

Compiling Lhogho and its documentation

To compile Lhogho and generate its documentation (you need GCC and DOXYGEN) enter the source directory and execute make:

cd src
make clean all

As a result the executable lhogho.exe (for Windows/Cygwin) or lhogho (for Linux) is created in src/core/ and the HTML documentation is generated in doc/ folder.

Compiling only Lhogho

To compile only Lhogho (you need GCC) enter Lhogho's source directory and rebuild:

cd src/core
make clean all

As a result the executable lhogho.exe (for Windows/Cygwin) or lhogho (for Linux) is created in src/core/.

Compiling only Lhogho documentation

To compile only Lhogho documentation (you need DOXYGEN) enter Lhogho's documentation source directory and execute make:

cd src/doc
make

As a result the HTML documentation is generated in doc/ folder.

Cleanup

To clean all files which can be regenerated (Lhogho binary and/or HTML documentation) execute:

make clean

from the appropriate directory.

Installing documentation

In case it is neede to install preprocessed documentation, download the Developer's Documentation file lhogho.?.?.???.doc.tar.gz and unpack it similarily to how the Developer's Release is unpacked.

Compile defines

This section describes define symbols in the compiler's source which determine what functionality to include in the compiler. These defines are defined in globals.h file.

• UNICODE_CHARS - if defined Lhogho maintains internal representation of strings as UTF-16 Little Endian. Reading text files recognizes ASCII, UTF-8 and UTF-16LE file formats. Writing text files creates UTF-16LE files.
• SAFEMODE - if defined Lhogho includes various checks during memory allocation, passing parameters, atom management, etc.
• ADVANCED - if defined Lhogho gathers statistical informaiton about atom allocation and deallocation and includes features needed in its development and debug. An example of such feature is the ability to dump structure of variables. End-user Lhogho should not need this define. All Z options are available only in the ADVANCED mode.

Compile debug defines

The globals.h file contains a set of define symbols which control what parts of the source code to compile. These defines are used for debugging purposes only. By default most of the defines are switched off. To use any of them remove the prefix no from the name.

• noDEBUG_ATOM - if defined it will include code to trace all atom operations
• noDEBUG_VAR - if defined it will include code to trace all var operations
• noDEBUG_HEAP - if defined it will include code to trace all heap operations
• noDEBUG_POOL - if defined it will include code to trace all pool operations
• noDEBUG_TOKENS - if defined it will include code to trace generation of tokens via the microprogram cell automata
• noDEBUG_LIST_FLAGS - if defined dump_atom will output the flags of each list node encoded in this way:
  • New - if FLAG_NEWLINE is set
  • Asp - if FLAG_AFTER_SPACE is set
  • Bsp - if FLAG_BEFORE_SPACE is set
• noDEBUG_LIST_TOKEN_FLAGS - if defined dump_atom will output the token-related flags of each list node encoded in this way:
  • ' - if the data node is parsed as data
  • ! - if the data node is parsed as commands
• noDEBUG_TOKENIZATION - if defined it will include code to trace generation of list from tokens
• noDEBUG_TOKENS - if defined it will include code to trace converting a tokenized list
• noDEBUG_PARENTHESES - if defined it will include code to trace generation of subexpressions
• noDEBUG_PARSE - if defined it will include code to trace parsing, i.e. generation of syntax trees (lisp notation)
• noDEBUG_COMPILE - if defined it will include code to trace compilation
• noDEBUG_FIND_VAR - if defined it will include code to trace var searching
• noDEBUG_RUNTIME_ATOMS - similar to noDEBUG_ATOM, but shows debug information about atoms (allocation, freeing, using and deusing) only during the execution of the compiled program. Atom management during compilation is not shown.
• DEBUG_CLEAR_FREED_MEM - if defined all atoms which are returned to the pool are cleared with 0xFF. This can be used while looking for bugs where deallocated atom is still in use. In such cases the atom would be filled with 0xFF's and in most cases some assert() testing the ID will fail, because 0xFF is not an ID of any atom type.
• noDEBUG_MEMORY_LEAKS - if defined all unreleased atoms and their contents is printed on the screen.

Testing Lhogho

To compile only lhogho tester application (you need GCC) enter Lhogho's test directory and rebuild:

cd src/test
make clean all

As a result the executable lTester.exe (for Windows/Cygwin) or lTester (for Linux) is created in src/test/ folder.