mirror of
https://github.com/AdaCore/langkit.git
synced 2026-02-12 12:28:12 -08:00
133 lines
4.6 KiB
Markdown
133 lines
4.6 KiB
Markdown
Langkit
|
|
=======
|
|
|
|
Langkit (nickname for language kit) is a tool whose purpose is to make it easy
|
|
to create syntactic and semantic analysis engines. Write a language
|
|
specification in our Python DSL and Langkit will generate for you an Ada
|
|
library with bindings for the C and Python programming languages.
|
|
|
|
The generated library is meant to provide a basis to write tooling, including
|
|
tools working on potentially changing and incorrect code, such as IDEs.
|
|
|
|
The currently main Langkit user is
|
|
[Libadalang](https://github.com/AdaCore/libadalang), a high performance
|
|
semantic engine for the Ada programming language.
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
To use Langkit, you will need:
|
|
|
|
* A Python 3.11 interpreter (or more recent). Python2 is no longer supported.
|
|
* Some Python libraries, including the Mako template system for Python (see
|
|
`requirements-pypi.txt` and `requirements-github.txt` for the full list).
|
|
* A recent version of the GNAT Ada compiler, either from your OS's packages, or
|
|
use [Alire](https://alire.ada.dev/docs/#toolchain-management) to get one.
|
|
* The [gnatcoll-core](https://github.com/AdaCore/gnatcoll-core) library.
|
|
* Ada bindings for GMP and Libiconv, from
|
|
[gnatcoll-bindings](https://github.com/AdaCore/gnatcoll-bindings).
|
|
* The [VSS](https://github.com/AdaCore/VSS) library.
|
|
* The [Prettier-Ada](https://github.com/AdaCore/prettier-ada) library.
|
|
* The [AdaSAT](https://github.com/AdaCore/adasat) library.
|
|
|
|
For all Ada libraries (GNATcoll, VSS, Prettier-Ada, AdaSAT), make sure to
|
|
install the version that corresponds to the version of Langkit that is built.
|
|
For instance, build all `24.1` branches, or all `master` branches. Mixing
|
|
versions is not supported.
|
|
|
|
Install
|
|
-------
|
|
|
|
We assume below that all the Ada dependencies are installed under the
|
|
`$PREFIX` directory, and that the environment is properly set up to use it:
|
|
|
|
* GPRbuild has access to project files (`$PREFIX/share/gpr` is in
|
|
`GPR_PROJECT_PATH`, for example).
|
|
|
|
* The dynamic linker has access to shared libraries (`$PREFIX/lib` is in
|
|
`LD_LIBRARY_PATH`, for exmaple).
|
|
|
|
First, clone the `adasat` repository in the `langkit` subdirectory of the
|
|
`langkit` repository:
|
|
|
|
$ (cd langkit; git clone https://github.com/AdaCore/adasat)
|
|
|
|
Then, install the Langkit Python package itself:
|
|
|
|
$ pip install .
|
|
|
|
Build the Liblktlang support library:
|
|
|
|
$ python manage.py make --no-mypy --library-types=static,static-pic,relocatable
|
|
|
|
Install the `Langkit_Support` library:
|
|
|
|
$ python manage.py install-langkit-support $PREFIX --library-types=static,static-pic,relocatable
|
|
|
|
Install the Liblktlang support library:
|
|
|
|
$ python -m langkit.scripts.lkm install -c lkt/langkit.yaml $PREFIX --library-types=static,static-pic,relocatable --disable-all-mains
|
|
$ pip install lkt/build/python
|
|
|
|
If you are interested in shared (`relocatable`) libraries only, you can omit
|
|
the `--library-types` arguments.
|
|
|
|
Testing
|
|
-------
|
|
|
|
In order to run the testsuite, launch the following command from the top-level
|
|
directory:
|
|
|
|
$ python manage.py test
|
|
|
|
This is just a wrapper passing convenient options to the real testsuite
|
|
driver that is in `testsuite/testsuite.py`.
|
|
|
|
Note that even though the testsuite framework requires Python 3.11, it is
|
|
possible to run the tests themselves using a different Python interpreter. For
|
|
instance, to run them using Python 3.7, run:
|
|
|
|
$ python manage.py test --with-python=python3.7
|
|
|
|
If you want to learn more about this test driver's options (for instance to run
|
|
tests under Valgrind), add a `-h` flag.
|
|
|
|
Documentation
|
|
-------------
|
|
|
|
The developer and user's documentation for Langkit is in `langkit/doc`. You can
|
|
consult it as a text files or you can build it. For instance, to generate HTML
|
|
documents, run from the top directory:
|
|
|
|
$ make -C doc html
|
|
|
|
And then open the following file in your favorite browser:
|
|
|
|
doc/_build/html/index.html
|
|
|
|
Bootstrapping a new language engine
|
|
-----------------------------------
|
|
|
|
Nothing is more simple than getting an initial project skeleton to work on a
|
|
new language engine. Imagine you want to create an engine for the Foo language,
|
|
run from the top-level directory:
|
|
|
|
$ python -m langkit.scripts.create_project Foo
|
|
|
|
This creates a `langkit.yaml` configuration file in the current directory as
|
|
well as a `foo` directory with Lkt sources for a minimal lexer and parser, that
|
|
you can build with:
|
|
|
|
$ python -m langkit.scripts.lkm make
|
|
|
|
Here you are!
|
|
|
|
Developer tools
|
|
---------------
|
|
|
|
Langkit uses mako templates generating Ada, C and Python code. This can be hard
|
|
to read. To ease development, Vim syntax files are available under the `utils`
|
|
directory (see `makoada.vim`, `makocpp.vim`). Install them in your
|
|
`$HOME/.vim/syntax` directory to get automatic highlighting of the template
|
|
files.
|