Clava is a C/C++/CUDA/OpenCL source-to-source compiler. It applies analysis and transformations written in JavaScript scripts, and can be installed in under a minute.
If you have used Clava, please consider filling the Clava User Experience Feedback form (it's short, really!)
Clava also supports LARA files (.lara), but the LARA DSL is now considered legacy, please use JavaScript instead.
Currently Clava requires Java 17
Although Clava is mainly a Java program, which should run on any compatible Java runtime, it also uses compiled binaries. These have operating system restrictions. Currently Clava is supported in Windows 10, Ubuntu 20.04, CentOS 7 and MacOS 11 (Big Sur).
Clava Web-based Tutorial - 2022 - Tutorial on how to use Clava, based on the online demo version.
Language Specification - List of all join points, attributes and actions available in Clava.
API Documentation - List of LARA APIs available in Clava.
API Slides - Introduction to Clava and the LARA Framework APIs.
For a sample of Clava examples, please check the Unit Tests.
When adding new join points and attributes, besides the weaver generator (Java side), it is also necessary to run the join point generator (TS side). To do this, execute npm run build-interfaces on Clava-JS folder.
A ZIP file with the last compiled JAR for Clava can be downloaded from here (previous releases).
There is an installation script for Linux that can be run locally and that will install the Clava binary in the script path (sudo is required for CMake module installation).
For an online demo version of Clava, please click here.
To call Clava from within CMake, please click here.
To build Clava, please check the ClavaWeaver project folder.
Clava can be run from CMake, using a GUI, or as a command-line tool.
Instructions for the Clava CMake plugin can be found here.
Run the JAR with passing parameters, e.g.:
java -jar Clava.jar
A video demonstrating the GUI can be found here.
There are two main modes in command line, either passing all arguments (LARA file, parameters, etc...), or passing a configuration file that was built with the graphical user interface.
java -jar Clava.jar <aspect.lara> -p <source_folder>
where <aspect.lara> is the LARA aspect you want to execute, and <source_folder> is the folder where the source code is.
There are more command-line options available, which can be consulted by running:
java -jar Clava.jar --help
To pass a configuration file, use the flag -c:
java -jar Clava.jar -c <config.clava>
where <config.clava> is the configuration file created with the GUI.
For short executions, most of the execution time is related to starting a JVM.
There is an experimental feature where you can call Clava in server mode. In this mode, Clava can run in the background and will wait for requests. Then you can use a compiled program that performs requests to the server.
To start Clava in server mode, use the flag -server:
java -jar Clava.jar -server
The Linux instalation script provides the clavaw program, which sends a request to a Clava server:
clavaw <Clava flags>
- Only absolute paths are supported in this mode, since the server will use its own folder as the working folder. However, files defined in config files should be handled automatically, they are converted to absolute paths, using the folder of the config file as the base folder. Additionally, if inside a Lara script you need to use files, you can use
Clava.getData().getContextFolder()(import clava.Clava;) to return the folder of the config file. - The output of the program will appear on the terminal of the server, not where
clavawruns-
Check if you have at least Java 11 installed, this is the minimum version.
On Fedora >28 systems this can be solved by installing the package ncurses-compat-libs
Install libz package (e.g., in Ubuntu sudo apt-get install libz-dev)
If you want to reference Clava in your work, please use the following publication:
João Bispo, and João MP Cardoso. Clava: C/C++ source-to-source compilation using LARA. SoftwareX, Volume 12, 2020, Article 100565. [ScienceDirect] [bibtex]
This work has been partially funded by the ANTAREX project through the EU H2020 FET-HPC program under grant no. 671623. João Bispo acknowledges the support provided by Fundação para a Ciência e a Tecnologia, Portugal, under Post-Doctoral grant SFRH/BPD/118211/2016.