Title: Building Apache Directory Studio
Notice: Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    .
    http://www.apache.org/licenses/LICENSE-2.0
    .
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

# Building Apache Directory Studio

All projects use Maven as default build tool, we use [Maven 3](http://maven.apache.org) on JDK 1.6.


## Checkout Sources from SVN Repository

First you have to download the source code from the repository. Subversion is used for version control, so you can use the subversion client to download up to date source code. Here are the steps to have a running Apache Directory Studio from scratch:

To check out the active development branch of Apache Directory Studio and all co-projects run the following command (use https instead of http for committers):

    svn co http://svn.apache.org/repos/asf/directory/studio/trunk studio


## Build Apache Directory Studio

Now, change to studio:

    cd studio

Run the following command to build all the Apache Directory Studio Eclipse plugins and RCP application:

    mvn clean install

> **Memory settings:**
>
> If the build hangs or you get an out of memory exception please increase the heap space:
>
> * For Linux:
>
>         MAVEN_OPTS="-Xmx256m" mvn clean install
>
> * For Windows:
>
>         SET MAVEN_OPTS="-Xmx256m"
>         mvn clean install
>
> **Distribution settings:**
>
> By default a distribution for your current working OS is built. You can add additional distributions by adding the corresponding profile of it:
>
> | OS | os.family | os.arch | Profile to use |
> |---|:-:|:-:|---|
> | Mac OS X 32 Bit (Cocoa) | mac | i386 | -Pmacosx-x86 |
> | Mac OS X 64 Bit (Cocoa) | mac | x86_64 | -Pmacosx-x86_64 |
> | Windows 32 Bit | windows | x86 | -Pwin32-x86 |
> | Windows 64 Bit | windows | x86_64 or amd64 | -Pwin32-x86_64 |
> | Linux 32 Bit (GTK 2) | unix | i386 | -Plinux-x86 |
> | Linux 64 Bit (GTK 2) | unix | x86_64 or amd64 | -Plinux-x86_64 |
> | All | - | - | -Pinstallers |
> | Updatesite | - | - | -Pupdatesite |
>
> After the command ends running successfully you'll have all the projects compiled and the distribution(s) of Apache Directory Studio application generated in the directory **applications/application-<your platform>/target**.
>
> To run the application, double-click on it or launch it from command line.


## Run Integration Tests

Before running integration test you need a local installation of Eclipse 3.5. It is recommended to use a _dedicated_ and _small_ distribution, e.g. the "Eclipse IDE for Java Developers" package. Further you need to declare a Maven property **eclipse-home** that points to the Eclipse installation. Create or edit the **<home>/.m2/settings.xml** file and add the following content, please adapt the path to your local eclipse installation:

    <settings>
      <profiles>
        <profile>
          <id>eclipse-home</id>
          <properties>
            <eclipse-home>/opt/eclipse-3.5-for-integration-test/eclipse</eclipse-home>
          </properties>
        </profile>
      </profiles>
      <activeProfiles>
        <activeProfile>eclipse-home</activeProfile>
      </activeProfiles>
    </settings>

Run the following command to execute the integration tests:

    mvn -Pintegration-core,integration-ui test


### Background Info for Integration Tests

The integration tests start up a full eclipse environment.

* The 'core' test only start up a headless eclipse, without GUI.
* The 'ui' test starts up the eclipse GUI and plays some scenarios. We use [SWTBot](http://www.eclipse.org/swtbot).

The complete eclipse distribution, the studio plugins and the SWTBot plugins are copied into a test sandbox under test-integration-\[core|ui]/target/test-sandbox.

The test results are written to test-integration-\[core|ui]/target/test-sandbox/workspace/results.xml.

If errors occur please check test-integration-\[core|ui]/target/test-sandbox/workspace/.log and test-integration-\[core|ui]/target/test-sandbox/configuration/*.log.


## Build User Documentation

To build the user documentation in HTML and PDF, run the following command:

    mvn install -Puserguides
    
> **Note:**
> Generating PDF requires much memory. If you get an out of memory exception please increase the heap memory:
>
> * For Linux:
>
>         MAVEN_OPTS="-Xmx256M" mvn install -Puserguides
> 
> * For Windows:
>
>         SET MAVEN_OPTS="-Xmx256M"
>         mvn install -Puserguides
> 
> After the command ends running successfully you'll have all the user documentation generated in the directory **target/userguides**.


## Cleanup

To clean the project's directory, run the following command:

    mvn clean


## Misc

If you have problems building the projects please try to clean your local maven2 repository:

* For Linux:

        rm -rf ~/.m2/repository

* For Windows:

    Delete the folder C:\Documents and Settings\<your username>\.m2\repository


**Note:** Each sub-project can also be built separately. To do so, enter the project directory and run the **mvn install** command. This will compile and generate the plugin in the **target** directory

**Note 2:** Apache Directory Studio can be built on Linux, Mac OS X and Windows. It has been run successfully on Linux Ubuntu, Gentoo Linux (i386/amd64), Mac OS X Tiger, Leopard, Snow Leopard, Lion & Mountain Lion and Windows XP, Vista & 7.