Skip to content

Latest commit

 

History

History
181 lines (121 loc) · 6.27 KB

building.rst

File metadata and controls

181 lines (121 loc) · 6.27 KB

Building Libadalang

First, note that if you have access to a pre-built Libadalang package, which generally come with GNAT Pro and GNAT Community, then you do not need to go through the following steps: just follow the instructions in the README file that comes with this pre-built package.

Setup

To generate and build the library itself, you'll need to go through the following steps:

  • Make sure you have a working Python3 installation (version 3.7 or newer).

  • Install the GNAT tools and compiler. You can find Community Editions on AdaCore's website.

  • Build and install the GNATcoll library (core, plus Iconv and GMP bindings). You can find its source release on AdaCore's website or directly on GitHub's repositories for gnatcoll-core and gnatcoll-bindings.

  • Install every Python dependency. We recommend creating a virtual environment and installing them inside of it, this way:

    $ python -mvenv env
$ source env/bin/activate
$ pip install -r REQUIREMENTS.dev

  • Install Langkit, build and install Langkit_Support. Get Langkit's sources on GitHub, making sure you use the same branch in both repositories. For instance, if you use Libadalang's master branch, you should use Langkit's master branch as well. Then, from the checkout root directory, run:

    # Install the Langkit python package
$ pip install .

# Build the "langkit_support.gpr" project
$ python manage.py build-langkit-support --library-types=static,static-pic,relocatable

# Install it. Replace $PREFIX below with the directory where you want to
# install the langkit_support.gpr project.
$ python manage.py install-langkit-support --library-types=static,static-pic,relocatable $PREFIX

To develop comfortably:

  • If you want interactive debugging when code is generated, install IPython.
  • If you want to compute code coverage for the code generator, install coverage.py (see REQUIREMENTS.dev).
  • If you want to check memory issues, the testsuite has an option to track them using Valgrind.

Regarding the version of these dependencies: Libadalang's development branch (master branch on the Git repository) is built and tested using the development version of Langkit, of GNATcoll, and of GNATcoll's own dependencies, and their release cycles are synchronized. This means that in order to build Libdalang's branch X, you need to install Langkit using the branch of the same name, and likewise for GNATcoll and its dependencies.

Building the library

First, let's generate code for Libadalang itself. In the top-level directory, run:

$ python manage.py generate

This generates Ada, C and Python source code for Libadalang in the build directory. In order to build this source code into a shared library, run:

$ python manage.py build --library-types=static,static-pic,relocatable

Assuming you satisfied all the above dependencies, both commands should successfuly run to completion.

While developing Libadalang you might be happy to use the following command:

$ python manage.py make --library-types=static,static-pic,relocatable

It will wrap the two previous commands in one, generating the code and building it in one step.

If you are interested in shared (relocatable) libraries only, you can omit the --library-types argument.

Install

Once you built Libadalang, you can install the library in any place you want:

$ python manage.py install $INSTALL_DIR --library-types=static,static-pic,relocatable

Then, depending on your operating system and your system configuration, you may need to update environment variables so that programs can load dynamic libraries:

# On most Unix systems:
export LD_LIBRARY_PATH=$INSTALL_DIR/lib:$LD_LIBRARY_PATH

# On Windows, either:
export PATH=$INSTALL_DIR/bin:$PATH
# ... or:
set PATH "$INSTALL_DIR\bin;$PATH"

In addition, if GPRbuild is not installed in $INSTALL_DIR, you need to add $INSTALL_DIR/share/gpr to the GPR_PROJECT_PATH environment variable in order for GPRbuild to locate the installed project files, such as libadalang.gpr.

Using Libadalang without installing it

During development, it can be useful to update environment variables so that Libadalang can be used directly after a build, without performing a bona fide installation. The setenv command enables one to do that. Assuming a Bourne-compatible shell, run:

$ eval `python manage.py setenv`

After this, you can both build programs that depend on Libadalang using GPRbuild and run Python interpreter to import the libadalang module.

Building the documentation

Libadalang itself is required to build this Sphinx documentation: this allows to automatically generate the Ada API reference from the corresponding Ada source code (conversely for Python). As a consequence, you need either to have Libadalang installed (and in particular its Python bindings) or to update your environment without installing it: see the corresponding section above.

In addition, you need to install the laldoc Python project, which contains documentation extraction helpers:

$ pip install contrib/laldoc

From there, building this documentation as a set of static HTML pages is as easy as running the following command from the user_manual directory:

$ make html

Assuming successful completion, the documentation is then available in the user_manual/_build/html directory: you can start reading it from the index.html page.

Note that on Mac OS X, security features require you to explicitly pass the LD_LIBRARY_PATH environment variable:

$ make html LD_LIBRARY_PATH="$LD_LIBRARY_PATH"