Skip to content

Commit

Permalink
[docs] Update the SRE launching documentation.
Browse files Browse the repository at this point in the history 
close #513

Signed-off-by: Stéphane Galland <galland@arakhne.org>
  • Loading branch information
@gallandarakhneorg
gallandarakhneorg committed Nov 14, 2016
1 parent 8b76575 commit d1dc228
Show file tree
Hide file tree
Showing 12 changed files with 214 additions and 144 deletions.
46 changes: 24 additions & 22 deletions docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/gettingstarted/CreateFirstProject.spec
View file
Expand Up @@ -186,20 +186,17 @@ describe "Create First Project" {
"%sarlmavenrepository%" should beURL "!file"
}

/* For executing your SARL program, you must select a
/* For executing your SARL program, you must use a
* [runtime environment](%website%/runtime/index.html).
*
* <p>The runtime environment that is recommended by the developers of SARL
* is [Janus](http://www.janusproject.io).
*
* <p>If you want to embed the runtime environment inside the Jar files
* of your SARL application, it is recommended to put it in the
* Maven dependencies.
* <p>In several specific cases, you may want to include the runtime environment into the Maven dependencies
* of your project. In this case, you could replace the Maven dependency to the SARL sdk (as defined in
* the previous section) by a Maven dependency to the runtime environment.
* The
*
* <note>You could remove the dependencies to the
* SARL artifacts in the previous Maven configuration. Indeed, the Janus platform depends
* already on. You will obtain the SARL artifacts by transitivity.</note>
*
* <p>Replace the version number (`%janusversion%`) of the [Janus platform](http://www.janusproject.io)
* with the one you want to use. You could search on the
* [Maven Central Repository](http://search.maven.org) for
Expand All @@ -215,24 +212,30 @@ describe "Create First Project" {
* <janus.version>%janusversion%</janus.version>
* </properties>
* ...
* <build>
* <plugins>
* ...
* <plugin>
* <groupId>io.sarl.maven</groupId>
* <artifactId>sarl-maven-plugin</artifactId>
* <version>${sarl.version}</version>
* <extensions>true</extensions>
* <configuration>
* <source>%compilerlevel%</source>
* <target>%compilerlevel%</target>
* <encoding>%encoding%</encoding>
* </configuration>
* </plugin>
* </plugins>
* </build>
* ...
* <dependencies>
* ...
* <dependency>
* <groupId>io.janusproject</groupId>
* <artifactId>io.janusproject.kernel</artifactId>
* <version>${janus.version}</version>
* </dependency>
* <dependency>
* <groupId>io.sarl.maven</groupId>
* <artifactId>io.sarl.maven.sdk</artifactId>
* <version>${sarl.version}</version>
* <exclusions>
* <exclusion>
* <groupId>com.google.guava</groupId>
* <artifactId>guava</artifactId>
* </exclusion>
* </exclusions>
* </dependency>
* ...
* </dependencies>
* ...
Expand All @@ -242,9 +245,8 @@ describe "Create First Project" {
* `io.sarl.maven.sdk` and `io.janusproject.kernel` in your
* POM file, you must be sure that the imported version
* of the Google Guava library is the one provided by the Janus
* platform. For ensuring this, you must exclude the Guava
* library from the transitive dependencies of
* `io.sarl.maven.sdk`</important>
* platform. For ensuring this, you must specify the version of the Guava
* library by defining it in the "dependencyManagement" section of your pom file.</important>
*
* @filter(.*)
*/
Expand Down
254 changes: 158 additions & 96 deletions docs/io.sarl.docs.suite/src/test/java/io/sarl/docs/gettingstarted/RunSARLAgentCLI.spec
View file
Expand Up @@ -23,135 +23,197 @@ package io.sarl.docs.gettingstarted
import com.google.inject.Inject
import io.sarl.docs.utils.SARLParser
import io.sarl.docs.utils.SARLSpecCreator
import io.sarl.lang.sarl.SarlAgent
import org.jnario.runner.CreateWith

import static extension io.sarl.docs.utils.SpecificationTools.*
import static extension org.junit.Assume.assumeFalse

/* @outline
*
* <p>For running an agent, you must launch this agent on the runtime
* environment.
* This document explains how to launch an agent on
* the [Janus platform](http://www.janusproject.io) from the command line.
*
* <p>Three methods could be used for launching an agent with Janus: <ul>
* <li>[Using the provided janus command-line tool](#Use_the_janus_command-line_tool);</li>
* <li>[Using the standard java method](#Use_the_standard_java_method);</li>
* <li>[Using Maven execution plugin](#Use_maven_execution_plugin).</li>
* <li></li>
* </ul>
*/
@CreateWith(SARLSpecCreator)
describe "Run SARL Agent from the Command Line" {

@Inject extension SARLParser

/* The Janus platform provides a `Boot` class.
* For launching the platform, you must execute this
* boot class in a Java Virtual Machine.
*
* <p>The typical command line is:
*
* java -cp app.jar io.janusproject.Boot
*
*
* <p>The option `-cp` specifies the Jar file that contains
* the compiled classes. The given `app.jar`
* file is a Jar file that is containing the Janus
* platform, the SARL libraries, and the application classes.
* The last argument is the fully qualified name of
* the booting class of Janus: `io.janusproject.Boot`
*
* @filter(.*)
/* The SARL project provides a command-line tool for launching agents on the
* Janus runtime environment.
*/
fact "Boot of Janus" {
true
}
describe "Use the janus command-line tool" {

/* The example given in the previous section causes an error.
* Indeed, it is mandatory to specify the fully qualified name
* of the agent to launch:
*
* java -cp app.jar io.janusproject.Boot myapp.MyAgent
*
*
* <veryimportant>The Janus
* platform allows to start only one agent from the command line.
* If you want to start a collection of agents, you must select
* one of the following approaches:
*
* * launch a separate Janus platform for each agent, or
* * launch an agent that is spawning the other agents.
* </veryimportant>
*
* @filter(.*)
*/
fact "Specify the Agent to Launch" {
true
}
/*
* You could download this command line tool, named "janus" on the [downloading page of SARL](%website%/download.html).
*
* @filter(.*)
*/
fact "Download the janus command-line tool" {
// The checks are valid only if the macro replacements were done.
// The replacements are done by Maven.
// So, Eclipse Junit tools do not make the replacements.
System.getProperty("sun.java.command", "").startsWith("org.eclipse.jdt.internal.junit.").assumeFalse
//
"%website%" should beURL "!file"
}

/*
* For launching an agent, you must launch the command-line tool with the fully-qualified
* name of the agent as parameter (`myapp.MyAgent` in the following example).
*
* janus myapp.MyAgent
*
* <p>The janus command-line tool provides options that will enable you to tune the launching
* configuration:
*
* janus --help
*
* @filter(.*)
*/
fact "Launching the agent" {
true
}

}

/* It is possible to give arguments to the launched agent.
* Indeed, all the arguments given on the command line
* are put in the `parameters` attribute of the `Initialize` event.
* This event is fired when the launched agent is started.
/*
*/
describe "Command Line Parameters" {
describe "Use the standard java method" {

/* The following example gives the values `FirstParam` and
* `SecondParam` to the launched agent:
/* The Janus platform provides a `Boot` class.
* For launching the platform, you must execute this
* boot class in a Java Virtual Machine.
*
* <p>The typical command line is:
*
* java -cp app.jar io.janusproject.Boot
*
*
* <p>The option `-cp` specifies the Jar file that contains
* the compiled classes. The given `app.jar`
* file is a Jar file that is containing the Janus
* platform, the SARL libraries, and the application classes.
* The last argument is the fully qualified name of
* the booting class of Janus: `io.janusproject.Boot`
*
* java -cp app.jar io.janusproject.Boot myapp.MyAgent FirstParam SecondParam
* @filter(.*)
*/
fact "Boot of Janus" {
true
}

/* The example given in the previous section causes an error.
* Indeed, it is mandatory to specify the fully qualified name
* of the agent to launch:
*
* java -cp app.jar io.janusproject.Boot myapp.MyAgent
*
*
* <veryimportant>The Janus
* platform allows to start only one agent from the command line.
* If you want to start a collection of agents, you must select
* one of the following approaches:<ul>
* <li>launch a separate Janus platform instance for each agent, or</li>
* <li>launch an agent that is spawning the other agents.</li>
* </ul></veryimportant>
*
* @filter(.*)
*/
fact "Specify the Agent to Launch" {
true
}

/* In the previous section, we assume that all the application binary files are
* contained into the `app.jar` file.
*
* <p>You may replace the `app.jar` in the previous command lines by the classpath
* that is containing all the jar files required for running your application, including
* the Janus jar file(s):
*
* java -cp /path/to/myapplication.jar:/path/to/io.janusproject.kernel-<version>-with-dependencies.jar io.janusproject.Boot myapp.MyAgent
*
* <p>The `io.janusproject.kernel-<version>-with-dependencies.jar` file may be dowloaded from the [Janus website](http://www.janusproject.io/)
*
* <p>You may also create the `app.jar` file with Maven by using the assembly plugin for creating a jar file with all the dependencies inside.
*
* @filter(.*)
*/
fact "What is app.jar?" {
"http://www.janusproject.io/" should beURL _
}

/* The Janus platform provides a collection of command line options.
* For obtaining the list of these options, you should type:
*
* java -cp app.jar io.janusproject.Boot --help
*
*
* @filter(.*)
*/
fact "Give Parameters to the Agent" {
fact "Janus Command Line Options" {
true
}

/* For retrieving the values passed on the command line,
* you must handle the `Initialize` event, as illustrated
* by the following example:

}

/*
*/
describe "Use Maven ExecutionPlugin" {

/* Maven provides a plugin for launching an application after automatically building
* the application's classpath. This plugin may be used for launching an agent.
*
* <p>Based on the fact that the Janus platform provides a `Boot` class for launching itself,
* you may use the Maven execution plugin for classing this booting class.
*
* <p>The typical command line is:
*
* mvn exec:java -Dexec.mainClass="io.janusproject.Boot"
*
*
* @filter(.* = '''|'''|.parseSuccessfully.*)
* <p>The option `-Dexec.mainClass` specifies the fully qualified name of
* the booting class of Janus: `io.janusproject.Boot`
*
* @filter(.*)
*/
fact "Retrieve the Command Line Parameters in the Agent" {
val model = '''
agent MyAgent {
uses Logging
on Initialize {
println("Command line parameters: "
+occurrence.parameters)
}
}
'''.parseSuccessfully(
"package io.sarl.docs.gettingstarted.runsarlagent
import io.sarl.core.Logging
import io.sarl.core.Initialize",
// TEXT
""
)

model => [
it should havePackage "io.sarl.docs.gettingstarted.runsarlagent"
it should haveNbImports 2
it should importClass "io.sarl.core.Logging"
it should importClass "io.sarl.core.Initialize"
it should haveNbElements 1
]

model.xtendTypes.get(0) => [
it should beAgent "MyAgent"
it should extend _
it should haveNbElements 2
(it as SarlAgent).members.get(0) => [
it should beCapacityUse "io.sarl.core.Logging"
]
(it as SarlAgent).members.get(1) => [
it should beBehaviorUnit "io.sarl.core.Initialize"
it should beGuardedWith _
]
]
}
fact "Boot of Janus" {
true
}

/* The example given in the previous section causes an error.
* Indeed, it is mandatory to specify the fully qualified name
* of the agent to launch:
*
* mvn exec:java -Dexec.mainClass="io.janusproject.Boot" -Dexec.args=myapp.MyAgent
*
*
* <veryimportant>The Janus
* platform allows to start only one agent from the command line.
* If you want to start a collection of agents, you must select
* one of the following approaches:<ul>
* <li>launch a separate Janus platform instance for each agent, or</li>
* <li>launch an agent that is spawning the other agents.</li>
* </ul></veryimportant>
*
* @filter(.*)
*/
fact "Specify the Agent to Launch" {
true
}

/* The Janus platform provides a collection of command line options.
* For obtaining the list of these options, you should type:
*
* java -cp app.jar io.janusproject.Boot --help
* mvn exec:java -Dexec.mainClass="io.janusproject.Boot" -Dexec.args=--help
*
*
* @filter(.*)
Expand All @@ -161,7 +223,7 @@ describe "Run SARL Agent from the Command Line" {
}

}

/*
* In the next section, we will learn how to launch your SARL project from
* a Java program.
Expand Down

0 comments on commit d1dc228

Please sign in to comment.