Tero's blog

Installing prerequisites

You of course need Ada compiler. FSF GNAT 4.6 or GNAT GPL 20xx is good enough. For the documentation you need Python and packages called sphinx and sphinxcontrib-adadomain. To build the system using comfignat.mk, you need GNU Make. Other Make tools, for example from BSD systems, do not work.

If your Linux distribution does not provide python-sphinx and sphinxcontrib-adadomain packages, it is best to install python-virtualenv package and create virtual environment where to install the other packages.

mkdir -p $HOME/python-virtual/ahven
virtualenv $HOME/python-virtual/ahven
. $HOME/python-virtual/ahven/bin/activate
pip install sphinx
pip install sphinxcontrib-adadomain

Build steps

The top level Makefile contains multiple targets: base, check, check_xml, html, install.

From these, base and check are the most useful ones when developing Ahven itself. Target base will compile the library and check will compile the tests and run them also. Variation of this is check_xml, which will run the tests and output the results in XML format. Various continuous integration systems, like Jenkins, know how to interpret this XML format and produce nice statistics and graphs.

Target html will generate the documentation using sphinx. For this, you need to have sphinx and sphinxcontrib-adadomain packages installed and necessary sphinx binaries available in PATH.

Finally, install will install the library and GNAT project files to the system so all users can use them. Usually, only distribution packagers want to use this.

The default action for the main Makefile is to compile the library and the documentation (default = base + html).

Known issues

comfignat.mk supports gprbuild and gnatmake build tools. gprbuild is more recent and I think that is what Adacore recommends. However, for example, on Ubuntu 14.04 gprbuild does not produce working executables (when used for Ahven). This is why gnatmake is the default.

If you want to use gprbuild, you can change GNAT_BUILDER variable in Makefile to gprbuild. Another word of caution: if you plan to use gprbuild on Fedora, make sure that you have locale settings configured to value "C". Otherwise, gprbuild might fail to build the library.

Example command could be something like this:

LANG=C make OPTS="GNAT_BUILDER=gprbuild"

or:

cd gnat && LANG=C make GNAT_BUILDER=gprbuild

The second command will enter gnat directory first and then run make from there. The main level Makefile will do that automatically, so you don't need to do that usually.

Windows

So far, all of above has applied to Linux and BSD systems with GNAT installed. comfignat.mk should work on Windows also, but you need to have GNU Make, and probably some other Linux tools installed also. These usually can be found via mingw or cygwin projects.

However, I also provide "old style" project file which can be used directly:

gnatmake -p -P gnat/ahven_lib

It only builds the library itself, but usually that should be enough.

I do not get it!

If this still sounds too complicated, you can also compile all of the source code as-is with plain gnatmake and run the resulting tester executable:

gnatmake -aIsrc -aIsrc/unix -aItest tester
./tester

Other compilers

Currently, I provide build scripts only for GNAT and Janus/Ada. In addition to those two compilers, I also regularly test the code with ICCAda, but ICCAda build tools are so easy to use that I haven't bothered to create separate build scripts for it.

For Janus/Ada the compilation process is following:

janusada\prepare.bat
janusada\update.bat
janusada\compile.bat

The first command prepares the Janus/Ada project files and you need to run it only once. The second command scans the source code for changes and determines which source files need to be compiled again. First time you of course need to compile all of the code. The third command then actually compiles the code.

You can combine the second and the third command using build.bat:

janusada\build.bat

Later, when you change some source file and want to recompile the project, you need to run only update.bat and compile.bat or build.bat only. Of course, if you want to do full clean build, then you can run prepare.bat first.

ICCAda users will find the build process very similar:

icm new
icm scan src\*.ad? src\windows\*.ad? test\*.ad?
icm make tester

The first command creates the necessary project files. The second command scans the source code for changes and finally the third command compiles the source code.

Documentation

The documentation is written in reStructuredText format. It is basically plain text with some simple formatting instruction sprinkled here and there. It originates from Python project.

A tool which which converts reStructuredText to HTML is called sphinx. To make sphinx work better with Ada documentation, I have written separate adadomain plugin.

The documentation lives in doc/manual/en/source directory. If you make changes to it, you can run make html which rebuilds the changed parts and places the output to gnat/obj/sphinx/html directory. for sphinx.

Final words

The new comfignat.mk based build system is still somewhat experimental. If you find bugs, please report them to me, so I can fix them before next release (which happens at some point later this year).

If you want to see what a full build of Ahven using some of my compilers looks, you can check it from build.ada-language.com.

The comfignat.mk build system is contributed by Björn Persson. Big thanks to him!