<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ 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.
  -->
<document xmlns="http://maven.apache.org/XDOC/2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
    <properties>
        <title>Developing Apache Axis2</title>
    </properties>
    <body>
        <section name="Introduction">
            <p>
                This document provides information on how to use SVN to get an
                SVN checkout/update, make commits to the repository, etc., in the
                process of contributing to Apache projects (specifically Axis2).
                Instructions on configuring IDEs for development and using Maven to
                build the project is also included here.
            </p>
        </section>
        <section name="Working with Subversion (SVN)">
            <p>
                The Axis2 development team uses Subversion (SVN) for source
                control. Subversion is a compelling replacement for CVS, developed
                under the auspices of the Tigris community and licensed under an
                Apache compatible license. To learn more about Subversion or to
                download the latest distribution, visit the <a href=
                "http:///subversion.tigris.org">Subversion project
                site</a>. If you are looking for guidance on setting up and
                installing Subversion, please read the ASF <a href=
                "http://www.apache.org/dev/version-control.html">Source
                Code Repositories page</a>.
            </p>
        </section>
        <section name="Checkout Axis2 from Subversion">
            <p>
                To check out the latest version of Axis2 from the Foundation's
                Subversion repository, you must use one of the following URLs
                depending on your level of access to the Axis2 source code:
            </p>
            <ul>
                <li><b>If you are not a committer:</b> <a href=
                "http://svn.apache.org/repos/asf/axis/axis2/java/core/trunk/">http://svn.apache.org/repos/asf/axis/axis2/java/core/trunk/</a></li>
                <li><b>If you are a committer:</b> <a href=
                "https://svn.apache.org/repos/asf/axis/axis2/java/core/trunk/">https://svn.apache.org/repos/asf/axis/axis2/java/core/trunk/</a></li>
            </ul>
            <p>
                If you are a committer, make sure that you have selected an
                svnpasswd. To do this, you must log into svn.apache.org. For more
                information, please read the ASF <a href=
                "http://www.apache.org/dev/version-control.html">Source Code Repositories page</a>.
            </p>
            <p>
                Once you have successfully installed Subversion, you can check
                out Axis2 trunk by following these steps:
            </p>
            <ol type="1">
                <li>Run <strong>svn co &lt;repository URL&gt; axis2</strong> where
                the repository URL is one of the URLs from the previous list.</li>
                <li>This step will check out the latest version of the Axis2 Java
                codebase to a directory named "axis2". The second parameter to the
                <strong>svn co</strong> selects a directory to create on your local
                machine. If you want to checkout Axis2 to a different directory,
                feel free to change axis2 to any other directory name.</li>
                <li>To update your working copy to the latest version from the
                repository, execute the <strong>svn update</strong> command.</li>
                <li>If you would like to submit a patch, you can execute
                <strong>svn diff</strong> to create a unified diff for submission
                to the Axis2 JIRA issue tracker.</li>
            </ol>
        </section>
        <section name="Installing Maven 2">
            <p>
                Axis2's build is based on Maven 2. Maven is a build system that
                allows for the reuse of common build projects across multiple
                projects. For information about obtaining, installing, and
                configuring Maven 2, please see the <a href=
                "http://maven.apache.org">Maven project page</a>.
                To use Maven to build the Axis2 project, Please install
                <a href="http://maven.apache.org/download.html">Maven2</a> and
                follow instructions here -  <a href="maven-help.html">Quick Guide to Maven for Axis 2.0</a>.
            </p>
        </section>
        <section name="Configuring your IDE">
            <p>
                The Axis2 development team uses a variety of development tools
                from vi to emacs to Eclipse to Intellij/IDEA. The following section
                is not an endorsement of a specific set of tools, it is simply
                meant as a pointer to ease the process of getting started with
                Axis2 development.
            </p>
            <subsection name="Intellij IDEA">
                <p>
                    Type <strong>mvn idea:idea</strong>. Generates the necessary IDEA .ipr, .iml
                    and .iws project files.
                </p>
            </subsection>
            <subsection name="Eclipse">
                <p>
                    We recommend using <a href="http://maven.apache.org/plugins/maven-eclipse-plugin/">maven-eclipse-plugin</a>
                    to import the Axis2 sources into Eclipse. This works best with the following
                    combinations of versions and settings:
                </p>
                <ul>
                    <li>
                        Early versions of Maven 2 have issues with non standard packagings
                        (<tt>bundle</tt>, <tt>aar</tt> and <tt>mar</tt> in the case of Axis2)
                        in multi-module builds. While this has no impact on the normal Maven
                        build, it prevents the Maven Eclipse plugin from identifying modules
                        with these packagings as Java projects. Therefore it is recommended
                        to use Maven 2.2.x or 3.0.x to execute the Maven Eclipse plugin.
                    </li>
                    <li>
                        By default, the Maven Eclipse plugin only imports generated sources
                        and resources created during the <tt>generate-sources</tt> and
                        <tt>generate-resources</tt> phases, but fails to locate them if they
                        are generated during the <tt>generate-test-sources</tt> and
                        <tt>generate-test-resources</tt> phases. This is due to a limitation in Maven 2 (see
                        <a href="http://jira.codehaus.org/browse/MECLIPSE-37">MECLIPSE-37</a>
                        for more information). Executing the <tt>eclipse:eclipse</tt> goal after
                        the <tt>process-test-resources</tt> phase is also not enough because of
                        <a href="http://jira.codehaus.org/browse/MDEP-259">MDEP-259</a>. The
                        best is to execute it after the <tt>install</tt> phase. The <tt>skipTests</tt>
                        property can be used to skip the execution of the unit tests (<tt>maven.test.skip</tt>
                        is not appropriate here because it also skips some of the goals configured
                        in the <tt>generate-test-sources</tt> and <tt>generate-test-resources</tt> phases).
                    </li>
                </ul>
                <p>
                    To summarize, use the following command to prepare the Axis2 sources for
                    import into Eclipse:
                </p>
                <pre>mvn -DskipTests=true install eclipse:eclipse</pre>
                <p>
                    As usual, before importing the projects into Eclipse, check that a Classpath Variable
                    for <tt>M2_REPO</tt> is configured in Eclipse. Then select File &gt; Import &gt; Existing Projects
                    into Workspace &gt; Select root directory. Selecting the root of
                    the Axis source discovers all the modules and allows them to be
                    imported as individual projects at once.
                </p>
            </subsection>
        </section>
    </body>
</document>