SARL Agent Programming Language

SARL is a general-purpose agent-oriented language, www.sarl.io.

SARL aims at providing the fundamental abstractions for dealing with concurrency, distribution, interaction, decentralization, reactivity, autonomy and dynamic reconfiguration. These high-level features are now considered as the major requirements for an easy and practical implementation of modern complex software applications. We are convinced that the agent-oriented paradigm holds the keys to effectively meet this challenge.

Considering the variety of existing approaches and meta-models in the field of agent-oriented engineering and more generally multi-agent systems, our approach remains as generic as possible and highly extensible to easily integrate new concepts and features. The language is platform- and architecture-independent.

However, we provide a first set of tools to support its execution based on the new version 2.0 of the Janus (see www.janusproject.io) platform, but it can be linked with other existing agent platforms and frameworks.

Build Status
Linux and OSX
Windows

Table of Contents

1. Requirements
2. Using SARL
3. P2 Repository
4. Issues
5. Contributions
6. Authors and Contributors
7. License of SARL
8. Success Stories

1. Requirements

Java Development Toolkit (JDK) 1.8 or higher.

2. Using SARL

2.1. Recommendations

For making your experience with SARL the best, we recommend you:

to enable the assertions at development time (with the -ea command line option).

2.2. Use the stable version with Maven

The lastest stable version of SARL is available on Maven Central. Consequently, you could directly include the SARL module into the Maven dependencies of your project:

	...
	<dependency>
	  <groupId>io.sarl.maven</groupId>
	  <artifactId>io.sarl.maven.sdk</artifactId>
	  <version>0.4.2</version>
	</dependency>
	...

Please, replace Version 0.4.2 in the previous snipset by the number of the version you want to use.

2.3. Use of the development version with Maven

New features, enhancements and bug fixes are available in the SNAPSHOT (development) version of SARL. For using this version, you must add the Maven Repository Server of SARL in your pom file:

	...
	<dependencies>
	  <dependency>
	    <groupId>io.sarl.maven</groupId>
	    <artifactId>io.sarl.maven.sdk</artifactId>
	    <version>0.5.0-SNAPSHOT</version>
	  </dependency>
	<dependencies>
	...
	<repositories>
	  <repository>
	    <id>io.sarl-maven</id>
	    <name>SARL Snapshots</name>
	    <url>http://maven.sarl.io/</url>
	  </repository>
	</repositories>
	<pluginRepositories>
    	  <pluginRepository>
	    <id>io.sarl-maven</id>
	    <name>SARL Snapshots</name>
	    <url>http://maven.sarl.io/</url>
	    <snapshots>
	      <enabled>true</enabled>
	    </snapshots>
	  </pluginRepository>
	</pluginRepositories>
	...

2.4. Compile SARL code with Maven

For compiling SARL source files with Maven, you should use the provided plugin: sarl-maven-plugin. It invokes the SARL and Java compilers with a simpler interface than the standard Xtext maven plugin. For using the sarl-maven-plugin, you should add in your pom file:

	...
	<build>
	  <plugins>
	    <plugin>
	      <groupId>io.sarl.maven</groupId>
	      <artifactId>sarl-maven-plugin</artifactId>
	      <version>0.4.2</version>
	      <extensions>true</extensions>
	      <configuration>
	        <source>1.8</source>
	        <target>1.8</target>
	        <encoding>UTF-8</encoding>
	      </configuration>
	    </plugin>
	    ...
	  </plugins>
	  ...
	</build>
	...

Please, replace Version 0.4.2 in the previous snipset by the number of the version you want to use.

Caution

Do not forget to set the extensions flag to true.

2.5. Syntax highlighting with other tools

Several style specifications are provided for syntax highlighting in third party tools. Style specifications are provided for:

3. P2 Repository

A P2 repository is set up and accesible at the address: updates.sarl.io.

4. Issues

Issues related to SARL are tracked on GitHub You must use this issue tracker to report and follow your issues.

5. Contributions

Any contribution to the SARL is welcome. For setting up the development environment of SARL, please follow our recommendations in the following sections.

5.1. Obtaining the SARL Source Code

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. 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 from Github to your local harddisk:

git clone https://github.com/<your_github_login>/sarl

We recommend to use the git tool on command-line until you’re becoming expert with the git tools that is embedded in Eclipse.

5.2. First Compilation the SARL Source Code

Maven is the standard tool for compiling SARL.

We recommended to launch the Maven compilation process on the command line before importing the code in the Eclipse environment. The command line to use (see below) compiles the SARL project and install the Maven modules into your local .m2 repository. This step is mandatory for compiling the embedded SARL run-time environment (Janus). Indeed, it needs the current SARL tools to be installed for being compiled.

The command line is:

mvn clean install -Dmaven.test.skip=true -Dcheckstyle.skip=true

5.3. Installing the Eclipse Development Environment

For setting up the development environment, 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 the Xtext tools.
Launch the Eclipse IDE for Java and DSL Developers, and configure it (look&feel, etc.)
Import the Eclipse preferences for SARL developers, which are stored into the dev-tools folder.
Import the SARL project: Menu File > Import > Maven > Existing Maven Project
- Select the folder in which you have cloned the SARL project (see Section 5.1);
- 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 io.sarl.lang.targetplatform.target in the project io.sarl.lang.targetplatform;
- 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 Platform at 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.xml files. After displaying the popup window of the error, click on Discover m2e connector and follow the instructions.
The Checkstyle plugin may need to install specific connectors. Do an action that is similar as the one in the previous step.
Clean and compile the project: Menu Project > Clean.

5.4. Compilation of SARL before Contributing

Prior to any sending of your contribution (see Section 5.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.

Type on the command-line:

mvn clean install

This command line will launch the compilation, checkstyle and unit tests. It must be successfull.

5.5. Sending the Contribution

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. This process is supported by Travis-CI for linux and OSX platforms, and AppVeyor for Windows platforms.
You must sign the Contributor License Agreement on GitHub. It is supported by cla-assistant.
Your PR should be reviewed by one or more of the main contributors for ensure 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 Travis-CI or AppVeyor 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.

6. Authors and Contributors

Mohamed Ezzat, code cleaning and optimization.
James Foster, documentation contributor.
Stéphane GALLAND, founder, original and active author.
Nicolas GAUD, founder, original and active author.
Jeremie JOST, documentation contributor.
Sebastian RODRIGUEZ, founder, original and active author.

7. License of SARL

SARL is distributed under the Apache v2 license, and is copyrigthed to the original authors and the other authors, as expressed in the NOTICE.

8. Success Stories

The following projects have sucessfully used SARL:

vimukthiperera / sarl Goto Github PK

sarl's Introduction