docs/src/main/docbook/how-to-build.xml

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

    Copyright (c) 2010, 2021 Oracle and/or its affiliates. All rights reserved.

    This program and the accompanying materials are made available under the
    terms of the Eclipse Public License v. 2.0, which is available at
    http://www.eclipse.org/legal/epl-2.0.

    This Source Code may also be made available under the following Secondary
    Licenses when the conditions for such availability set forth in the
    Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
    version 2 with the GNU Classpath Exception, which is available at
    https://www.gnu.org/software/classpath/license.html.

    SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0

-->

<!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/eclipse-ee4j/jersey">https://github.com/eclipse-ee4j/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/eclipse-ee4j/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/eclipse-ee4j/jersey/tags">https://github.com/eclipse-ee4j/jersey/tags</link>.
        </para>
    </section>

    <section xml:id="building">
        <title>Building the Source</title>
        <para>
            Jersey source code requires Java SE 8 or higher. The build is based on Maven.
            Maven 3.6.3 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 -DskipTests</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 -pl :[modulename]</programlisting>
            where
            <literal>pattern</literal>
            may be a comma separated set of names matching tests classes or individual methods (like
            <literal>LinkTest#testDelimiters</literal>).
            And [modulename] is name of a module from which tests are called. If module does not contain those tests
            build failure (as no tests run) occurs.
        </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>