<?xml version="1.0"?>
<!--

    DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

    Copyright (c) 2010-2013 Oracle and/or its affiliates. All rights reserved.

    The contents of this file are subject to the terms of either the GNU
    General Public License Version 2 only ("GPL") or the Common Development
    and Distribution License("CDDL") (collectively, the "License").  You
    may not use this file except in compliance with the License.  You can
    obtain a copy of the License at
    http://glassfish.java.net/public/CDDL+GPL_1_1.html
    or packager/legal/LICENSE.txt.  See the License for the specific
    language governing permissions and limitations under the License.

    When distributing the software, include this License Header Notice in each
    file and include the License file at packager/legal/LICENSE.txt.

    GPL Classpath Exception:
    Oracle designates this particular file as subject to the "Classpath"
    exception as provided by Oracle in the GPL Version 2 section of the License
    file that accompanied this code.

    Modifications:
    If applicable, add the following below the License Header, with the fields
    enclosed by brackets [] replaced by your own identifying information:
    "Portions Copyright [year] [name of copyright owner]"

    Contributor(s):
    If you wish your version of this file to be governed by only the CDDL or
    only the GPL Version 2, indicate your decision by adding "[Contributor]
    elects to include this software in this distribution under the [CDDL or GPL
    Version 2] license."  If you don't indicate a single choice of license, a
    recipient has the option to distribute your version of this file under
    either the CDDL, the GPL Version 2 or to extend the choice of license to
    its licensees as provided above.  However, if you add GPL Version 2 code
    and therefore, elected the GPL Version 2 license, then the option applies
    only if the new code is made subject to such option by the copyright
    holder.

-->
<!DOCTYPE chapter [<!ENTITY % ents SYSTEM "jersey.ent" > %ents; ]>
<chapter xmlns="http://docbook.org/ns/docbook"
         version="5.0"
         xml:lang="en"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd
                             http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
         xml:id="how-to-build">
    <title>Building and Testing Jersey</title>

    <section xml:id="checkout">
        <title>Checking Out the Source</title>
        <para>
            Jersey source code is available on GitHub. You can browse the sources at
            <link xlink:href="https://github.com/jersey/jersey">https://github.com/jersey/jersey</link>.
        </para>
        <para>
            In case you are not familiar with Git, we recommend reading some of the many "Getting Started with Git" articles
            you can find on the web. For example this
            <link xlink:href="http://refcardz.dzone.com/refcardz/getting-started-git">DZone RefCard</link>.
        </para>
        <!--<para>-->
            <!--Before you can clone Jersey repository you have to sign up for a-->
            <!--<link xlink:href="http://java.net">java.net</link>-->
            <!--account. Once you are registered, you have to add an SSH key to your java.net profile - see this article on how-->
            <!--to do that:-->
            <!--<link xlink:href="http://java.net/projects/help/pages/ProfileSettings#SSH_Keys_Tab">http://java.net/projects/help/pages/ProfileSettings#SSH_Keys_Tab</link>-->
        <!--</para>-->
        <para>
            To clone the Jersey repository you can execute the following command on the command-line
            (provided you have a command-line Git client installed on your machine):
            <programlisting language="bash" linenumbering="unnumbered">git clone git://github.com/jersey/jersey.git</programlisting>
            This creates read-only copy of Jersey workspace. If you want to contribute, please use "pull request":
            <link xlink:href="https://help.github.com/articles/creating-a-pull-request">https://help.github.com/articles/creating-a-pull-request</link>.
        </para>
        <para>
            Milestones and releases of Jersey are tagged. You can list the tags by executing the standard Git command in the repository directory:
            <programlisting language="bash" linenumbering="unnumbered">git tag -l</programlisting> or by visiting
            <link xlink:href="https://github.com/jersey/jersey/tags">https://github.com/jersey/jersey/tags</link>.
        </para>
    </section>

    <section xml:id="building">
        <title>Building the Source</title>
        <para>
            Jersey source code requires Java SE 7 or higher. The build is based on Maven.
            Maven 3.1 or higher is highly recommended. Also it is recommended you use the following
            Maven options when building the workspace (can be set in <literal>MAVEN_OPTS</literal> environment
            variable):
            <programlisting language="bash" linenumbering="unnumbered">-Xmx1048m -XX:PermSize=64M -XX:MaxPermSize=128M</programlisting>
        </para>
        <para>
            It is recommended to build all of Jersey after you cloned the source code repository.
            To do that execute the following commands in the directory where jersey source repository
            was cloned (typically the directory named "jersey"):
            <programlisting language="bash" linenumbering="unnumbered">mvn -Dmaven.test.skip=true clean install</programlisting>
            This command will build Jersey, but skip the test execution.
            If you don't want to skip the tests, execute the following instead:
            <programlisting language="bash" linenumbering="unnumbered">mvn clean install</programlisting>
            Building the whole Jersey project including tests could take significant amount of time.
        </para>
    </section>

    <section xml:id="testing">
        <title>Testing</title>
        <para>
            Jersey contains many tests. Unit tests are in the individual Jersey modules,
            integration and end-to-end tests are in <literal>jersey/tests/e2e</literal> directory.
            You can run tests related to a particular area using the following command:
            <programlisting language="bash" linenumbering="unnumbered">mvn -Dtest=&lt;pattern&gt; test</programlisting>
            where
            <literal>pattern</literal>
            may be a comma separated set of names matching tests classes or individual methods (like
            <literal>LinkTest#testDelimiters</literal>).
        </para>
    </section>
    <section xml:id="netbeans-build">
        <title>Using NetBeans</title>
        <para>
            <link xlink:href="http://netbeans.org">NetBeans IDE</link>
            has excellent maven support. The Jersey maven
            modules can be loaded, built and tested in NetBeans without any additional
            NetBeans-specific project files.
        </para>
    </section>

</chapter>
