Development guide Basic information for developing LSim
The main goal of this document is to guide any individual interested on developing LSim through the process of setting up the development environment until being able to execute a test application.
Development environment minimum requirements
- JDK 6 or higher
- Subversion (eclipse plugin, shell client, TortoiseSVN or other)
- Eclipse (indigo or higher recommended)
- Apache maven 3.0 and m2eclipse plugin
Installing apache maven
Once you downloaded the binary zip, extract to your desired folder and add this folder to PATH environment variable.
Setting up code repositories
LSim is organized in multiple projects. The root repository is available on svn://dpcs.uoc.edu/LSim.
Checking out this repository you will get:
- docs: this folder contains LSim related documentation
- lsim-applications: Here you will found applications that use LSim. There is a tutorial on how to use LSim to develop and test an application. It runs on LSim v1.0.
- lsim-library: the core of LSim along with lsim-framework. It contains the classes to automate the execution and coordination of applications and harvest the results of experiments. The are multiple branches that contains different versions of the library.
- lsim-framework: contains the tools to automate the deployment on the resources that will execute the tests. It's organized on five modules:
- lsim-commons: contains shared classes that are used on the library and the framework.
- lsim-launcher: setup the run environment from the specification of the experiment. Is the responsible for getting the resources and deploying the applications to that resources.
- lsim-dispatcher: manages the execution of applications on his own environment.
- localCodes: doesn't belong to LSim but is needed to locate the resources that will run the experiments.
- test-app: an application for testing when developing LSim. In this document we will learn how to run this application. It's a simple application that contains two kinds of workers: application and server, a coordinator and an evaluator.LSim will run a server and two applications that will send a number to the server. The server then will sum this numbers and will send the result to the evaluator that will assert that this number is the same than the expected. See the tutorialLSim for more information about this application.
Building LSim
You can run applications using eclipse but before that it is necessary to build the framework and library using maven.
First, you will need to modify the file (~/.m2/settings.xml) to add a repository that contains artifacts that aren't on the maven central repository. Open this file and add the next fragment:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
...
<profiles>
<profile>
<id>default</id>
<repositories>
<repository>
<id>lsim</id>
<name>LSim repository</name>
<url>http://sd2.uoc.edu:8080/maven/</url>
</repository>
</repositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>default</activeProfile>
</activeProfiles>
</settings>
Building a project with maven is as simple as getting with the command line to the root of the project (where the file pom.xml is located) and introducing this command on the shell:
> mvn clean install
You will need to build the LSim projects in this order:
1. LocalCodes
2. lsim-commons
3. lsim-library
4. lsim-dispatcher
5. lsim-launcher
6. test-app
Maven will generate a jar for each project that will be available on {project}/target and also automatically copied to ~/.m2/repository.
Setting up run environment
This step will require to create some folders and modify files to obtain an execution environment were the applications will run.
1. Import the projects from the repository to Eclipse.
2. Create a folder where LSim will copy the code that will be executed (e.g. c:\lsim\applications)
3. Create a folder that will contain the code to be executed (e.g c:\lsim\elements). Here you will need to create 4 folder more. One for each component of the test-app. These are server, application, coordinator and evaluator.
4. Copy the scripts and files located on test-app/src/scripts to corresponding folder on elements folder (e.g test-app/src/scripts/application copied to c:\lsim\elements\application). This files are needed to run each component.
5. Modify the script deployApp.bat of test-app project. %DESTINATION% variable must point to the parent folder of elements (e.g c:\lsim) without the trailing slash.
This script will copy all the jars needed to run the application.
6. Modify test-app.xml of lsim-launcher project. This file contains the specification of the experiment. Change the path on codeRef entries to point the lsim\elements\\{lsim-component} folder. If you are using windows OS, use double slash (\\) to separate folders. (e.g c:\\lsim\\elements\\coordinator). For more information on this file, you can read Esteve Verdura final project report or tutorial documentation.
7. Modify configDispRun.properties file of lsim-dispatcher project (the one in project root directory). Change folder property to point to applications folder (e.g c:\lsim\applications).
On this point you will be ready to run the application. The best way to do this is setting eclipse Run Configurations:
1. On LocalCodes project, run the main class localCodesPack.LocalCodesTest with left button->run As->Java Application.
2. The same for dispatcher.test.runenvironment.DispatcherRunTest on lsim-dispatcher project.
3. Finally, launch the experiment executing in the same way the class launcher.test.tutorialLSim.TutorialLSimLauncher on lsim-launcher.
If everything is ok, the running applications will be copied to applications folder and will be executed. You can take a view of the logs of the different components in theirs folders. Five folders need to be created: one for coordinator which name ends with C0, one for server that ends with Wserver0, two for applications ending with Wapplication10 and 20, and one for the evaluator, C0Eval0.
The folder of the evaluator will contain a file named result.txt with the results of the evaluation.
And that's all. Now you can modify the library to change its behavior and modify the test-app to test that new behavior.
Just remember the building order when building with maven and that you don't need to build all the projects, just the modified and the test-app.
Then remember to run the script deployApp to copy modified jars to execution location.