This wiki page is intended to present the project, thinking on a developer that continues the work done so far. Thus, this manual is a reference for new developers who join the project with the consequent lack of knowledge of the system.

First of all, if you do not know anything about maven, please, read a bit.

What Maven is -> http://maven.apache.org/what-is-maven.html

Maven in 5 minutes -> http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html

To understand what Maven is and how works is quite important because all project is build using Maven. For example, we use maven to perform tests, to get dependencies, to generated a site with info about the project (metrics, test results, etc.) and to deploy new versions of the project in Maven Central repositories.

Once you have understood this, install the following software in you computer:

To develop this project, we have used JDK6 because JDK7 had some problems when we tried to perform release with maven. Maybe this problem has been solved in recent versions, but we have not checked. Anyway, ensure that you JAVA_HOME system variable is properly configured. The method to define this variable depends of the operating systems. If you do not know how to do it, search in Google. ;)

1. Download the last version of Maven in zip format from the official Maven page. http://maven.apache.org/
2. Unzip it in the location where you want to have it installed.
3. Modify the path by adding the location of the bin directory located inside the unzipped folder. For example: C:\Program Files\apache-maven-3.0.3\bin
4. Test Maven runs correctly by writing ’mvn’ in the console.

Note: We have used maven 3.0.3 but any newer version should work without problems.

Download and install Eclipse Classic. We are using 4.2.2. "Juno".

Note: To install the following plugins, I recommend you to execute Eclipse as root/administrator. Some permissions are required and if you execute Eclipse as a regular user, some plugins cannot be installed.

A Github repository is used as control version and as issue management systems. The eclipse plugins used to integrate git commands with the eclipse IDE is egit (http://eclipse.github.com/).

Furthermore, Github Mylyn connector (see the link above) is used to get all project issues in eclipse IDE or comment any progress in a specific task.

Useful advice: you can close an issue in a commit message. See this https://help.github.com/articles/closing-issues-via-commit-messages

To sign your packages when you perform a release and you want to deploy your project in the maven central repositories, you must install GnuPG (or GPG) http://www.gnupg.org/

You can follow the next tutorial to understand the maven release process: https://docs.sonatype.org/display/Repository/How+To+Generate+PGP+Signatures+With+Maven

To execute such as mvn deploy or mvn release:prepare, you need to install git in console mode.

First of all, be sure that your git client is configured with the correct "user.email" and "user.name" variables and the system has access to these variables. In other words, check the git configuration using "git config --system --list" command.

Note: I had some problems with these. In the end, I configured my user.email and my user.name in my git project configuration (git config user.name), git global configuration (git config --global user.name) and git system configuration (git config --system user.name).

We have used the Maven plugin for eclipse m2eclipse (http://www.eclipse.org/m2e/), which let as saving some time and efforts. It allows us the automation of running test, building the javadoc and the .jar file, and the most important, include other dependencies to the building process, obtaining great information of our project without any effort. One example of these dependencies is Cobertura, which checks the testing level of our system and indicates the lines of code that have never been tested. It warns as well about the number of TODO’s and FIXME’s in the code. For this functionality tests must be written in src/test/java.

To configure all maven issues can be a headache. So for this reason, a few advices are offered here.

When you execute "mvn release:perform", maven launches a lot of console instances by itself. To ensure that these instances has rights to access the required directories, be sure that you execute that command with administrador rights (or sudo, as you like). If no rights are given, gpg plugin will not be able to sign the packages to release a new version in the maven central repositories. Furthermore, you need to configure your gpg profile in your settings.xml.

<profiles>
	<profile>
		<id>release-sign-artifacts</id>
		<activation>
			<property>
				<name>performRelease</name>
				<value>true</value>
			</property>
		</activation>
		<properties>
			<gpg.secretKeyring>your path</gpg.secretKeyring>
			<gpg.publicKeyring>your path</gpg.publicKeyring>
			<gpg.passphrase>your passphrase</gpg.passphrase>
		</properties>
		<build>
			<plugins>
				<plugin>
					<groupId>org.apache.maven.plugins</groupId>
					<artifactId>maven-gpg-plugin</artifactId>
					<version>1.4</version>
					<executions>
						<execution>
							<id>sign-artifacts</id>
							<phase>verify</phase>
							<goals>
								<goal>sign</goal>
							</goals>
						</execution>
					</executions>
				</plugin>
			</plugins>
		</build>
	</profile>
</profiles>

Finally, check that your local settings.xml file contains all required information of all servers (usernames, passwords and configurations).

For example, to deploy a new version of the site generated by maven (mvn site site:deploy), you must configure the github credentials and specify the branch (gh-pages).

<servers>
	<server>
		<id>site-github-web</id>
		<username>your username</username>
		<password>your password</password>
		<configuration>
			<scmVersionType>branch</scmVersionType>
			<scmVersion>gh-pages</scmVersion>
		</configuration>
	</server>
</servers>

But take care about to use different configurations for scm developer connections. In this case, it should be:

<servers>	
	<server>
		<id>github.com</id>
		<username>your username</username>
		<password>your password</password>
	</server>
</servers>

And to deploy releases and snapshots:

<servers>
	<server>
		<id>sonatype-nexus-staging</id>
		<username>your username</username>
		<password>your password</password>
	</server>
	<server>
		<id>sonatype-nexus-snapshots</id>
		<username>your username</username>
		<password>your password</password>
	</server>
</servers>

If you use the same configuration, all files will be stored in the same branch (master brach if you use the second option or gh-pages if you use the first one).

To use these notes, please check the pom.xml file in the project root folder.

1. Download BEAST-Tool project from github using "Git repositories" view in eclipse. You can automatically import any project in the repository to the workspace checking the option in the wizard windows that appears. https://github.com/gsi-upm/BeastTool
2. Execute Maven Install over the whole project of BEAST-Tool. Right-click in the project -> Run as -> Maven install. To execute mvn install or mvn tests you can use the m2eclipse plugin (i.e. execute these commands from the eclipse GUI). But to execute complex maven commands, I recommend you to launch them from console because many problems occurs with access right since eclipse is an application. For example, gpg need administration access to sign packages.

Sometimes we have to work with dependencies that are not stored in maven central repositories (or any other repositories). Then, you must install them in your local repository with the following command:

$ mvn install:install-file -DgroupId=com.tilab -DartifactId=jade -Dversion=4.0 -Dpackaging=jar -Dfile=/path/to/jarfile

Of course, you have to change "/path/to/jarfile" for the real path and the rest of the parameters for the proper ones.

Note: In Windows, sometimes Maven take dots (".") as separators... So if you get a message saying things like ".blabla.blublu" is an unknown phase of the lifecycle... You have to write all parameters between "". For example: -DgroupId="com.tilab"

To ensure that you have all configured in your computer, please execute some maven commads as ADMINISTRATOR/ROOTin the following order:

$ mvn install
$ mvn compile
$ mvn test
$ mvn site
$ mvn site:deploy
$ mvn clean
$ mvn release:clean
$ mvn release:prepare
$ mvn release:perform

Notice:

• mvn site:deploy will deploy a new site in gh-pages branch in github repository
• mvn release:prepare will deploy a new tag in github repository
• mvn release:perform performs a lot of tasks. The most important are that it deploys a new version of the software in the maven repositories and it uses gpg to sign the packages. Furthermore, it deploys a new version of the maven site in gh-pages branch of github repository

If no error appears, congratulations!! :) All works.

If you don't want to release a new version of the project when you are performing these tests, you must follow these steps:

1. Go to http://oss.sonatype.org, log in and go to "Staging repositories". Then, drop the new one created by "mvn release:perform" command.
2. Delete the last tag created by "mvn release:prepare" in github repository. Check this link -> http://nathanhoad.net/how-to-delete-a-remote-git-tag
3. Return to the previous version in pom.xml. For example if you were working in version 0.1.1-SNAPSHOT, after you perform the release, the new version will be 0.1.2-SNAPSHOT. Then, you should change that for the correct version and commit&push the correct version of pom.xml file.

This is an important point of this developer manual. To perform a new release, you only need to execute this command:

$ mvn release:clean release:prepare release:perform

or execute every command alone to ensure that the command was successfully executed before you launch the next one:

$ mvn release:clean
$ mvn release:prepare
$ mvn release:perform

Once these commands were executed successfully,

1. Go to http://oss.sonatype.org, log in and go to "Staging repositories".
2. Select the repository that contains the release and click "Close" option. Leave a comment about why you are closing this repository (you can leave it in blank). Note: Many other repositories could appears, but don't worry. They are only backups performed by Sonatype.
3. Once the repository is closed, select again the repository and click in "Release" option and leave a comment if you like.
4. That's all! Check that the release is available in the central repository searching it.

Important Note: I have found problems in Ubuntu 14.04 and Maven 3.0.5 with the maven-release-plugin. I don't know why an snapshot is deployed to the Sonatype Snapshot Repository instead of the prepared released in the Sonatype Release Repository. The solution found is to sign and upload the release jars externally, i.e., without release:perform command. Once you have generated, with "mvn release:prepare" the following files:

beast-tool-1.2.pom
beast-tool-1.2.jar
beast-tool-1.2-javadoc.jar
beast-tool-1.2-sources.jar

(of course, with different version...), you can deploy this artifacts to the Sonatype Release Repository using the "mvn gpg:sign-and-deploy-file" as follows:

$ mvn gpg:sign-and-deploy-file -Durl=https://oss.sonatype.org/service/local/staging/deploy/maven2/ -DrepositoryId=sonatype-nexus-staging -DpomFile=beast-tool-1.2.pom -Dfile=beast-tool-1.2.jar
$ mvn gpg:sign-and-deploy-file -Durl=https://oss.sonatype.org/service/local/staging/deploy/maven2/ -DrepositoryId=sonatype-nexus-staging -DpomFile=beast-tool-1.2.pom -Dfile=beast-tool-1.2-sources.jar -Dclassifier=sources
$ mvn gpg:sign-and-deploy-file -Durl=https://oss.sonatype.org/service/local/staging/deploy/maven2/ -DrepositoryId=sonatype-nexus-staging -DpomFile=beast-tool-1.2.pom -Dfile=beast-tool-1.2-javadoc.jar -Dclassifier=javadoc

Take into account that the pom.xml after the execution of "mvn release:prepare" does not generate the beast-tool-1.2.pom. You must change the version properly removing the SNAPSHOT label before you execute these commands. This should not be required and "release:perform" goal should work fine... Maybe, it is a configuration issue or a bug in any of the maven plugins... No idea, but this is the solution I found... :)

I recommend you to read the paper published in ITMAS2012 workshop to understand the scope of the project. It can be found in: http://scholar.google.es/citations?view_op=view_citation&hl=es&user=mT3KgXUAAAAJ&citation_for_view=mT3KgXUAAAAJ:Tyk-4Ss8FVUC

The source code has the following structure:

es.upm.dit.gsi.beast
	mock
		common
		jade
		jadex
	platform
		jade
		jadex
	reader
		mas
		system
	story
		logging

Package mock contains mock agents already developed in BeastTool. Some JADEX2.0 and JADE4.0 mock agents have been developed.

Packege platform contains key classes to connect BeastTool with a multi-agent platform (Connector, Messenger and AgentIntrospector). If you want to connect BeastTool with a new agent platform, you must implement these classes for that specific platform. JADEX2.0 and JADE4.0 are already integrated.

Package reader contains classes to parse the User Stories and the Agent Stories.

Packege story containts the BeastTestCase model that connects with the Platform connectors from platform package.