== Development Environments
One of the most important aspects of an open source project is how easy it is for developers to contribute.  
Of course hosting the project on github goes a long way toward making that as simple as possible (from the 
perspective of source code management).  However, a sometimes overlooked aspect of encouraging developer 
contributions is how easy it is to create a working development environment.  This means getting the project 
and all its dependencies running, either standalone or (better) in debug mode within an IDE.  The 
s-ramp-dev-server project aims to make running Artificer and its components extremely easy.

=== Artificer Development Server
The Artificer Development Server (s-ramp-dev-server) does the following:

* Runs Jetty 9.x
* Deploys "artificer-server" (the Artificer repository backend)
* Deploys "artificer-ui" (the Artificer browser web application)

==== Getting Started from Maven
If you're just looking to get started quickly and aren't too concerned about debugging and in-place editing 
of Java classes and web resources, you can simply run everything from Maven:

----
mvn -Prun clean package
----

In this scenario, the Artificer Development Server will download all relevant dependencies, including the 
artificer-server WAR and the artificer-ui WAR.  It will then unpack necessary files into s-ramp-dev-server/target 
and launch Jetty, deploying using the unpacked files in target.

If everything starts up cleanly, you can go here:  http://localhost:8080/artificer-ui/index.html

When running in this way, the Java code and other resources are not editable in-place.  However, it will 
provide a *very* quick runtime environment for testing out Artificer.

==== Developing in Eclipse
Once you're ready to do some coding, follow these steps to get everything imported into Eclipse and running 
like clockwork (detailed instructions follow the overview):

. Download and install Eclipse (obviously)
. Clone the relevant Artificer repositories
.. Artificer
.. Artificer Browser UI
.. Overlord Commons
.. Artificer Development Server
. Build all projects from Maven (command line)
. Import all projects into Eclipse
. Launch "Artificer Dev Server" via Debug or Run menu
. (Optional) launch artificer-ui as a GWT "Web Application"

===== 1. Download and Install Eclipse
You probably know how to do this:  http://www.eclipse.org

You'll also want to install the m2e and egit plugins (from the Eclipse Marketplace).  These are pretty 
much essential since all the projects we'll be dealing with are maven projects hosted in github.

In addition, you may want to install the Google Web Toolkit Eclipse plugin (from the Eclipse Marketplace) if
you are planning on contributing UI code.

Lastly, another helpful Eclipse plugin is JRebel.  It's optional, but it can make life a little bit easier.
Later in this guide we have some instructions on how to configure it.

===== 2. Clone Relevant Repositories
You can clone all or only some of the repositories, depending on what aspect of Artificer you are contributing 
to.

----
mkdir ~/git
cd ~/git
git clone git://github.com/Governance/artificer.git
git clone git://github.com/Governance/artificer-ui.git
git clone git://github.com/Governance/overlord-commons.git
git clone git://github.com/EricWittmann/s-ramp-dev-server.git
----

===== 3. Build Using Maven
Ok, really you only need to build the Artificer project, because there is a code generation step in that project
that should be accomplished prior to importing it into Eclipse.  This ensures that the proper code has been
generated and the codegen target directory has been created.

----
cd artificer
mvn clean package
----

===== 4. Import Projects Into Eclipse
Next, all you need to do is import all of the projects into Eclipse.  To do this:

. Choose *File->Import* from the main menu
. From the resulting dialog choose *"Maven/Existing maven projects"*
. Click *Next*
. For *Root Directory* choose wherever you cloned all the repos (e.g. ~/git)
. Eclipse will scan for all Maven projects at that location.  Choose them all and Import them.

The result should be a fairly large number of top level Eclipse projects now available in your Project
Explorer (or Navigator or Package Explorer, etc).  Hopefully they all even compile/build without error.

===== 5. Launch "Artificer Dev Server"
The s-ramp-dev-server project comes with a file named *Artificer Dev Server.launch* which can be found in
the "launches" directory.  Eclipse should have automatically found that file and added it to your available
launches.  To run it simply choose it from either the Debug or Run toolbar menus.

This launch will execute the *org.artificer.devsvr.JettyDevServer* class with some default parameters.
The JettyDevServer application should automatically detect that it is being run from an IDE such as Eclipse
and therefore it should launch Jetty against the local web application directories.  In other words, if
artificer-ui is imported into Eclipse, then the Dev Server will launch Jetty with the following as the
webapp location for Artificer browser static files:

----
artificer-ui/src/main/webapp
----

That will allow you to change files in Eclipse and have those changes automatically picked up on the next
browser refresh.  Also note that because you are running the Artificer Dev Server from Eclipse, you can simply
modify Java code in Eclipse and expect that your changes will take effect next time you launch the server.

TIP: See the section about running with JRebel for an even *faster* way to see your code changes in action!

===== 6. (Optional) Launch Artificer Browser in GWT Hosted Mode
(To be written)

==== (Advanced) Running with JRebel
If you're looking to be more productive, you may want to give JRebel a try.  JRebel can be used for both
the server-side components (the Artificer Development Server) and the client-side (GWT) components.  In both
cases you obviously need to install the JRebel Eclipse plugin from the Marketplace.

===== Server Side JRebel
In order to enable JRebel for the server-side components, follow these steps:

. Add the JRebel Nature to *artificer-dev-server*
.. Right-click on *artificer-dev-server*
.. Choose *JRebel->Add JRebel Nature*
. Generate a *rebel.xml* file
.. Right-click on *artificer-dev-server*
.. Choose *JRebel->Advanced Properties*
.. Uncheck *Generate on build*
.. Click the *Generate Now!* button
.. Click the *Open rebel.xml* button
.. Click *OK*
. Modify the *rebel.xml* file to include all Artificer target/classes paths
.. Many (but not all) of the Artificer projects should be included
.. See below for an example rebel.xml (just change the paths):

----
<?xml version="1.0" encoding="UTF-8"?>
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xmlns="http://www.zeroturnaround.com" 
      xsi:schemaLocation="http://www.zeroturnaround.com http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
    <classpath>
        <!-- Artificer -->
        <dir name="/home/sholmes/git/s-ramp/s-ramp-api/target/classes"></dir>
        <dir name="/home/sholmes/git/s-ramp/s-ramp-atom/target/classes"></dir>
        <dir name="/home/sholmes/git/s-ramp/s-ramp-client/target/classes"></dir>
        <dir name="/home/sholmes/git/s-ramp/s-ramp-common/target/classes"></dir>
        <dir name="/home/sholmes/git/s-ramp/s-ramp-repository/target/classes"></dir>
        <dir name="/home/sholmes/git/s-ramp/s-ramp-repository-jcr/target/classes"></dir>
        <dir name="/home/sholmes/git/s-ramp/s-ramp-repository-jcr/modeshape/target/classes"></dir>
        <dir name="/home/sholmes/git/s-ramp/artificer-server/target/classes"></dir>
        <!-- Artificer UI -->
        <dir name="/home/sholmes/git/artificer-ui/artificer-ui/src/main/webapp/WEB-INF/classes"></dir>
    </classpath>
</application>

----

===== Client Side JRebel
It is, of course, very similar to set up JRebel for your GWT Web Application launch.  Simply do the following:

. Add the JRebel Nature to *artificer-ui*
.. Right-click on *artificer-ui*
.. Choose *JRebel->Add JRebel Nature*
. Generate a *rebel.xml* file
.. Right-click on *artificer-ui*
.. Choose *JRebel->Advanced Properties*
.. Uncheck *Generate on build*
.. Click the *Generate Now!* button
.. Click the *Open rebel.xml* button
.. Click *OK*
. Modify the *rebel.xml* file to include the Artificer UI classpaths 
.. Include artificer-ui
.. See below for an example rebel.xml (just change the paths):

----
<?xml version="1.0" encoding="UTF-8"?>
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xmlns="http://www.zeroturnaround.com" 
      xsi:schemaLocation="http://www.zeroturnaround.com http://www.zeroturnaround.com/alderaan/rebel-2_0.xsd">
    <classpath>
        <dir name="/home/sholmes/git/artificer-ui/artificer-ui/src/main/webapp/WEB-INF/classes"></dir>
    </classpath>
</application>
----