Any contribution to the SARL is welcome. For setting up the development environment of SARL, please follow our recommendations in the following sections.
Issues related to SARL are tracked on GitHub. You must use this issue tracker to report and follow your issues.
In the issue description, provide the following information:
-
Your operating system and its version;
-
The version of SARL you are using;
-
Your language and/or locale (e.g. "en-US");
-
Clear steps to reproduce the bug (including a reduced-case user script, if applicable);
-
Any error messages seen in the Error Console;
-
A description of what you expected to happen;
-
A description of what actually happened.
Note: You can use the wizard in the SARL product for submitting an issue with the technical information already filled up.
The menu is accessible by selecting the menu SARL > Submit issue to SARL tracker.
This wizard required to have a valid Github account. It will query you to enter your password (this password is neither stored nor transmited outside the SARL product except to the Github authentification service).
This section describes how to set up the Eclipse development environment for contributing to SARL.
The main SARL developpers are using the following development environment:
-
Java Development Kit (JDK) 21 from OpenJDK or Oracle.
-
Maven 3.9.11 (for shell command-line actions) from Apache.
-
Eclipse 2025-09, version "for Java and DSL Developers", and version "for RCP and RAP Developers".
We recommend to fork the SARL project into your own Github account, in order to make easier the pull request that is needed for sending your contribution to the master version of SARL.
Forking the SARL project must be done through the Github web interface: click on the Fork button on the SARL project page.
For obtaining the code of SARL, you must clone your fork repository from Github to your local harddisk:
git clone https://github.com/<your_github_login>/sarlWe recommend to use the git tool on command-line until you’re becoming expert with the git tools that is embedded in Eclipse.
SARL project may include third-party extensions in separated Git repositories that are linked from the main SARL Git repository. To download the code for the extensions, it is necessary to refresh the Git submodules of the SARL project:
git submodule updateThe SARL project is splitted into different sub-projects that may be compiled independently. Each project is dedicated to a specific set of features and tools. These sub-projects are listed below in the order they should be compiled:
-
sarl-bom: Provide the Build-of-Material, i.e., a shared list of Maven dependency, for all the SARL sub-projects;
-
sarl-baseutils: Set of Maven artifacts that are independent of SARL but needed to build the SARL artifacts;
-
sarl-lang: Provides the language definition, the associated compiler (including the Maven plugin) and code formatting styles for different text editors;
-
sarl-sdk: Set of Maven artifacts that constitute the SDK for all the SARL developers;
-
sarl-apputils: Shared projects for building applications that are using a SARL compiler;
-
sarl-sre: SARL runtime environment (or SARL virtual machine);
-
sarl-docs: Tools and Doclet for the generation of the documentation, including the API documentation pages;
-
sarl-cli: Set of command-line tools (sarlc, sarldoc, janus…);
-
sarl-eclipse: Eclipse-based editor for SARL;
-
sarl-officialdoc: Markdown files of the official documentation of SARL.
Maven is the standard tool for compiling SARL.
We recommended to launch the Maven compilation process on the shell command line before importing the code in the Eclipse environment. Indeed, Maven generates several Java code files, and updates resource files with the correct configuration values.
The command line to use (see below) compiles the SARL project and install the Maven modules into your local .m2 repository.
There is two major ways for compiling the SARL components: compile all the subprojects, and compile a single subproject.
If you want to compile all the subprojects of SARL, you could use one of the shell scripts that are located in the root folder of the SARL project.
-
Linux or MacOS Operating Systems: on a command-line shell, run the Python script (with or without tests):
$> ./build-all.py
$> ./build-all.py --notest-
Windows Operating System: on a command-line shell, run the Python script (with or without tests):
C:\> python build-all.py
C:\> python build-all.py --notestIf you want to compile only one of the subprojects of SARL, you could go inside the subproject folder and use Maven.
-
Linux or MacOS Operating Systems: on a command-line shell, run the Python script:
$> ./clean-all.py-
Windows Operating System: on a command-line shell, run the Python script:
C:\> python clean-all.pyThree different types of contributions could be associated to the SARL project:
-
DSL Contribution: Contributions to the SARL tool chain (compiler, etc), excluding Eclipse-based tools and tools written in SARL (see below);
-
RCP Contribution: Contributions to the Eclipse tools: they are the plugins inside Eclipse and the Eclipse IDE; and
-
SARL Contribution: Contributions to the tools written in SARL (SDK/API, Janus SRE).
The following table gives you the best contribution approach according to the SARL subproject. The last column indicates if you could use Maven from the Shell command-line interface.
| SARL Subproject | DSL Contribution | RCP Contribution | SARL Contribution | CLI |
|---|---|---|---|---|
|
X |
X |
||
|
X |
X |
||
|
X |
|||
|
X |
X |
||
|
X |
X |
||
|
X |
X |
||
|
X |
X |
||
|
X |
X |
||
|
X |
X |
||
|
X |
X |
For setting up the development environment for contributing to the SARL tools, which are neither the Eclipse-based tools nor the tools written in SARL (API and Janus SRE), you should follow the steps:
-
Download the Eclipse IDE for Java and DSL Developers from eclipse.org/downloads/eclipse-packages/. This version of Eclipse includes the Java tools and all the tools for compiling a language grammar.
-
Launch the Eclipse IDE for Java and DSL Developers, and configure it (look&feel, etc.)
-
Import the SARL project:
Menu File > Import > Maven > Existing Maven Project-
CAUTION: We do not recommend to import
sarl-bomin Eclipse because of its specific static in the compilation process. -
Select the folder in which you have cloned the SARL project (see Section 2.2);
-
Click on
Finish.
-
-
Sometimes, the Maven Eclipse Plugin (a.k.a. m2e) does not have its connector installed by default. In this case, errors should appears in the
pom.xmlfiles. After displaying the popup window of the error, click onDiscover m2e connectorand follow the instructions. -
Clean and compile the project:
Menu Project > Clean.
For setting up the development environment for contributing to the Eclipse-based tools, you should follow the steps:
-
Download the Eclipse IDE for RCP and RAP Developers from eclipse.org/downloads/eclipse-packages/. This version of Eclipse includes the Java tools and the tools for developping Eclipse plugins and applications.
-
Launch the Eclipse IDE for RCP and RAP Developers, and configure it (look&feel, etc.)
-
Import the SARL project:
Menu File > Import > Maven > Existing Maven Project-
CAUTION: We do not recommend to import
sarl-bomin Eclipse because of its specific static in the compilation process. -
Select the folder in which you have cloned the SARL project (see Section 2.2);
-
Click on
Finish.
-
-
Set the Eclipse target platform, i.e. the definition of the Eclipse plugins to be imported by the project.
-
Open the target platform file
sarl-target-platform.targetin the projectsarl-eclipse; -
Wait for all the entries in the target file to be refreshed, i.e each location must contains the list of the features to be imported;
-
Click on
Set as Target PlatformorReload Target Platformat the upper right corner of the file editor.
-
-
Sometimes, the Maven Eclipse Plugin (a.k.a. m2e) does not have its connector installed by default. In this case, errors should appears in the
pom.xmlfiles. After displaying the popup window of the error, click onDiscover m2e connectorand follow the instructions. -
Clean and compile the project:
Menu Project > Clean.
For setting up the development environment for contributing to the tools written in SARL, you should follow the steps:
-
Download or compile (see point b, above) one of the SARL Eclipse products: the general IDE
io.sarl.eclipse.products.ideor, preferably, the IDE for contributorsio.sarl.eclipse.products.dev. -
Launch the SARL product, and configure it (look&feel, etc.)
-
Import the project written in SARL:
Menu File > Import > Maven > Existing Maven Project-
CAUTION: We do not recommend to import
sarl-bomin Eclipse because of its specific static in the compilation process. -
Select the folder in which you have cloned the SARL project (see Section 2.2);
-
Click on
Finish.
-
-
Clean and compile the project:
Menu Project > Clean.
To create the initial version of the launch configuration, open the product overview and click in the top right corner on the "Launch an eclipse application" Button. This will automatically create a first launch configuration.
Then,the "Run Configuration" to manage the detail of your launch config, switch to the "Plug-ins" tab, and check the "Include required Features and Plug-ins automatically while launching" checkbox, and run it.
Prior to any sending of your contribution (see Section 2.5), you must ensure that your local copy of SARL compiles without error.
The best and "sure" way to proceed is to use Maven on the command line, because it is the tool used by our compilation server for validating your contribution. Here, we recommend to not desactivate the runs of the tests.
Type on the command-line:
mvn clean installThis command line will launch the compilation, checkstyle and unit tests. It must be successfull.
For sending your contribution to the SARL master repository, you must request a pull (PR) to the GitHub repository.
For being merged, your must ensure the following points:
-
Your PR must be compilable with Maven.
-
Your PR must pass the compilation process successfully, including the code compilation, unit tests, and code style checking.
-
You must sign the Contributor License Agreement on GitHub. It is supported by cla-assistant (CLA text).
-
Your PR should be reviewed by one or more of the main contributors for ensuring it is following the development rules and philosophy related to SARL.
The page of your PR on Github is displaying the status of your PR. If one point is failing, please follows the steps:
-
Go on the CI console for obtaining the cause of the failure.
-
Fix the code of your PR on your local copy.
-
Commit on your local repository, compile, and test until you have fixed the issue.
-
Push the changes on the same PR with
git push -f, i.e. the same Git repository as the one used for the PR. Do not create a new PR for the fix. -
The GitHub platform will relaunch the CI process automatically.
It may be interesting to include third-party tools in the SARL tools, and more specifically the SARL Eclipse IDE. In this case, the SARL project is structured in a way that it is possible to include these external contributions.
The contraints to follow for being integrated are:
-
Having a specific Git repository with public access. In fact, the extension will be included as a Git submodule when building the SARL tools.
-
In the root folder of the Git repository, a tool must be provided for building the extension code. The supported tools are:
-
A file
pom.xmlthat will automatically starts the Maven compilation tool; -
A python script
build-all.pythat will be used for building your code; -
A Shell script
build-all.shthat will be used for building your code; or -
A PowerShell script
build-all.ps1that will be used for building your code.
-
-
The extension project must depends on the current version of SARL in which it is supposed to be included.
The extension will be compiled after all the SARL compiler modules, but before the SARL IDE modules.
The extension will be included if it is passing the compilation process and its unit tests that are considered as mandatory for avoiding regressions of the extension modules.
For integrating the extension module in the SARL tools, the following steps could be applied:
Git submodules provide a mechanism for integrating external repositories as nested components within a parent Git repository, enabling hierarchical version control. A submodule operates as a reference to a specific commit within an external repository, recorded in the parent repository’s .gitmodules file. This reference is stored as a gitlink—a special entry in the parent’s tree object that points to the submodule’s commit hash rather than a traditional file or directory. The parent repository tracks the submodule’s state (i.e., its commit hash) but does not store its contents directly, thereby maintaining separation between the two codebases.
The following command-line shell commands could be applied to create the submodule of the extension in the SARL project; where:
-
<path_to_sarl_root_folder>is the path to the root folder of the SARL project. -
<extension_git_url>>is the URL of the public Git repository of the extension project; for example, for BSPL extension, it isgithub.com/sarl/sarl-protocols; -
<name_of_extension>is the basename of the subfolder in the SARL project root folder that must contains the extension code; for example, for BSPL extension, it issarl-bspl.
$> cd <path_to_sarl_root_folder>
$> git submodule add <extension_git_url> <name_of_extension>
$> git submodule init
$> git submodule updateThe four commands are the following:
-
git submodule addadds an the existing Git repository of the extension project as a submodule of the SARL project repository. -
git submodule initinitializes the local configuration file after adding the submodule. -
git submodule updatefetches all the data from the extension project and check out the appropriate commit in SARL project.
|
Caution
|
Changes in the extension project and SARL project are managed separately. Therefore, commit and push actions are limited to the submodule or the SARL project, but not both at the same time. |
The developper tools are Python scripts that are reading a central module definition stored in the modules.json file.
Each extension project that must be included in the compilation, generation or release process of the SARL project must be specified in this JSON file.
For adding an extension project in the modules.json file, add an entry in the extensions array. Below, there is an example for the BSPL extension:
...
"extensions": [
{
"module": "sarl-bspl",
"name": "BSPL implementation for SARL",
"build": true,
"clean": true,
"apidoc": false,
"upgrade-mvn-plugins": true,
"in-maven-central": true,
"releasable": true
"git-submodule": true
}
],
...The attributes to be set are:
| Attribute | Explanation | Using Script |
|---|---|---|
|
Indicates if the extension project is included in the generation of the API documentation |
|
|
Indicates if the extension project is included in the building process of SARL |
|
|
Indicates if the extension project is included in the cleaning process of SARL |
|
|
Specifies that the extension is included in the SARL project with a Git Submodule. |
|
|
Indicates if the extension project must be included in the bundles to be uploaded to Maven Central server |
|
|
The name of the extension project in the SARL root folder. It must be the same as the one specified in the |
all |
|
The name of the extension project that will appear on the console |
all |
|
Indicates if the extension project must be including when releasing the SARL project on the remote Maven servers |
|
|
Is an associative array that contains the configuration properties for releasing the module. See below for the subproperties |
|
|
Indicates if the |
|
|
Indicates if the declaration of the versions for the Maven plugins must be upgraded in extension project |
|
|
Specifies the relative path to an Eclipse Target Plaform file to be considered when upgrading the versions numbers of the plugins. This property must be an array of the elements of the path. For example, the file |
|
|
Specifies the relative path to an additional Maven pom file to be considered when upgrading the versions numbers of the plugins. This property must be an array of the elements of the path. For example, the file |
|
For including the Eclipse bundles from the extension project in the SARL Eclipse IDE, that SARL target platform must be updated.
The modules io.sarl.apputils:eclipseextensions and io.sarl.apputils:uiextensions provides an API for integrating the extension contributions in the SARL Eclipse product.