 -----
 Development setup
 -----
 Geoffrey De Smet
 -----

Development setup

    This section describes how to setup the project and start developing it.

Installation

    Download and install the following technologies:

    * Sun JDK 1.4+ from {{http://java.sun.com}} (or from a Linux repository)

        * Set the <<<JAVA_HOME>>> environment variable. Both Maven and JBoss need it.

        On Linux open <<</etc/profile>>> or <<<~/.bash_profile>>> and add
        <<<export JAVAHOME=...>>>. The JDK might be under <<</usr/lib/sun-jdk-1.x.x>>>.
        On Windows open <Control Panel/System/Advanced/Environment Variables>.
        The JDK will probably be under <<<C:\Program Files\java\jdk1.x.x>>>.

    * Maven 2+ from {{http://maven.apache.org}}

        * Set the <<<M2_HOME>>> environment variable.

        * Adjust the <<<PATH>>> environment variable to add <<<;$M2_HOME/bin>>> (Linux)
        or <<<;%M2_HOME%\bin>>> (Windows)

        * On Windows, the use of cygwin (with OpenSSH and Subversion) from {{http://www.cygwin.com}}
        to run maven is required for very advanced functionality (ssh repository deploy, ...)

    * One Java IDE (see below for configuration) with Subversion support

        * Eclipse 3.1+ from {{http://www.eclipse.org}}

            * Install one Subversion team support plugin:

                * Subversive plugin from {{http://www.polarion.org}}

                * Subclipse plugin from {{http://subclipse.tigris.org}}

            * Install Web Tools from {{http://www.eclipse.org}} for XML support (or MyEclipse)

        * NetBeans 5+ from {{http://www.netbeans.org}}

            * Subversion support is not that good yet, use a separate subversion client

        * IntelliJ IDEA 5.1+ from {{http://www.jetbains.com}}

            * Subversion is fully supported since IDEA 5

    * One separate Subversion client (optional if already supported in the IDE)
    It's possible and even handy to combine multiple Subversion clients.

        * Subversion (shell client) from {{http://subversion.tigris.org}}

        * Tortoise for Windows explorer from {{http://tortoisesvn.tigris.org}}

        * Any Subversion client referenced in <Links> on {{http://subversion.tigris.org}}

Getting the sources

    See {{{../source-repository.html}the source repository}}.

Building

* Main build command

    Open your command line (CygWin, bash, DOS, ...) and run in the project root:

+--
mvn install
+--

    This builds the project and installs it into your local repository.

    NOTE: The first time you run maven it will download all dependencies
    and cache them in your local repository in <<<~/.m2/repository>>>,
    so it may take some time.

* Other build commands

+--
mvn clean           Deletes all the generated files
mvn compile         Compiles the code
mvn test            Tests the code
mvn package         Generates the jar
mvn install         Copies the jar to your local repo
mvn site            Generates the website
mvn ant:ant         Generates a build.xml
+--

* Build result of "mvn install site"

    Take a look in the <<<target>>> directory in the project root and every module.
    You 'll find the module jar there, test reports and the website if you've generated it.

Configuring your favorite IDE

    Maven can do this for you.

* Eclipse

    There are 2 choices:

** Use the Eclipse plugin for Maven to generate .project, ... (recommended for the moment)

    [[1]] Ensure that you've followed the directions above and the execution
    of <<<mvn install>>> completed properly.

    [[2]] Run in the root of the project <<<mvn eclipse:eclipse>>>.
    This command automatically makes use of the <eclipse plugin in Maven 2>.  It
    generates all the files necessary to define the projects for eclipse.
    If you also want the sources of the dependencies, do
    <<<mvn -Declipse.downloadSources=true eclipse:eclipse>>> instead.

    [[3]] Install the Subclipse plugin if you haven't done so already.

    [[4]] Import the existing project found under the root of the project.  Open
    the import wizard and select <Import existing projects into workspace>.
    Choose the root directory of the project and you should see the project
    displayed.

    All the dependent libraries, source directories, etc. have already been
    configured.

    [[5]] Set the M2_REPO variable. This is required because the .classpath files
    generated by <<<mvn eclipse:eclipse>>> reference the M2_REPO variable in the
    classpath entries.

        Open the window <Window>\><Preferences>.\
        open the item <Java>\><Build Path>\><Classpath variables>.\
        Add the new variable <<<M2_REPO>>> with the value of the folder
        <<<USER_HOME/.m2/repository>>>, for example
        <<<C:/Documents and Settings/ge0ffrey/.m2/repository>>>.

    [[6]] Enable Subversion (if you haven't checked out with Subclipse):
    Right-click on each project and open <Team>\><Share...>.  This may not
    be necessary since recent versions of eclipse will automatically enable
    subversion during the project import.

    [[7]] Until the Maven plugin for Eclipse works properly, you will probably want
    to configure some external tools to perform maven operations from within
    eclipse (like you do with ant projects).

        Open <External Tools...>\
        Add a new <Program> configuration\
        On the <Main> tab, set the Location to <<<M2_HOME\bin\mvn.bat>>> for
        example <<<D:\Tools\maven-2.0.2\bin\mvn.bat>>>\
        Set the Working directory to the project root directory.\
        Set the arguments as needed for the command you want to run.\
        If you don't have an M2_HOME environment variable setup, then you need to
        add it on the <Environment> tab.
    []

** Using the plugin for Eclipse

    Install the <maven 2 plugin for Eclipse> referenced on {{http://maven.apache.org}}.

    Warning: Do not install a mevenide for maven 1 plugin, they do not work for Maven 2.

* NetBeans

    Install the <maven 2 plugin for NetBeans> referenced on {{http://maven.apache.org}}.

* IntelliJ IDEA

    Run in the root of the project <<<mvn idea:idea>>>.
    This command automatically makes use of the <idea plugin in Maven 2>.

    Open the <<<ipr>>> generated in the root of the project.
    All the dependend libraries, source directories, ... will be configured.

    Enable Subversion (if you haven't checked out with IntelliJ):
    Open <File>\><Settings>\><Project>\><Version Control>.
    Select <<<Subversion>>> as version control.

Maven 2 versus your favorite IDE

    After your IDE is configured with maven 2, you 'll use Maven 2 less frequently.

    You 'll use your IDE to:

    * Compile and run an application or a specific testcase

    * SCM update or commit

    []

    However, Continuum will use Maven 2 every night to:

    * SCM update and clean

    * Compile and run every single testcase

    * Build and deploy snapshots

    * Generate and deploy the site

    []

Running testcases

    Either configure them in your IDE or do:

+--
mvn test
+--
Website

* Generate the website

    To generate the website simply do:

+--
mvn site
+--

    Then take a look at <<<target/site/index.html>>>.

    To change the site content, take a look at <<<src/site/apt>>>.

* Deploy the website

    Create the file <<<USER_HOME/.m2/setting.xml>>> and add the following content:

+--
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <mirrors>
        <!-- ... -->
    </mirrors>
    <servers>
        <server>
            <id>shell.sourceforge.net</id>
            <username>xxx</username>
            <password>xxx</password>
            <filePermissions>775</filePermissions>
            <directoryPermissions>775</directoryPermissions>
        </server>
    </servers>
    <profiles>
        <!-- ... -->
    </profiles>
</settings>
+--

    It's important to set <<<filePermissions>>> and <<<directoryPermissions>>> correctly,
    otherwise you 'll make it impossible for other project-members to deploy the site.

    Note: this configuration will also be reused when deploying artifacts to our remove maven repository.

    Now run:

+--
mvn site-deploy
+--
