blob: db1595930a67e977c66dc28cf33c9b671893f0f0 [file] [log] [blame]
<?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>