From scm-return-47063-apmail-geronimo-scm-archive=geronimo.apache.org@geronimo.apache.org Wed Aug 10 02:31:28 2011 Return-Path: X-Original-To: apmail-geronimo-scm-archive@www.apache.org Delivered-To: apmail-geronimo-scm-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id E58578C94 for ; Wed, 10 Aug 2011 02:31:28 +0000 (UTC) Received: (qmail 15374 invoked by uid 500); 10 Aug 2011 02:31:28 -0000 Delivered-To: apmail-geronimo-scm-archive@geronimo.apache.org Received: (qmail 15258 invoked by uid 500); 10 Aug 2011 02:31:27 -0000 Mailing-List: contact scm-help@geronimo.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: dev@geronimo.apache.org List-Id: Delivered-To: mailing list scm@geronimo.apache.org Received: (qmail 15251 invoked by uid 99); 10 Aug 2011 02:31:27 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 10 Aug 2011 02:31:27 +0000 X-ASF-Spam-Status: No, hits=-1993.0 required=5.0 tests=ALL_TRUSTED,HTML_MESSAGE,MIME_HTML_ONLY,URI_HEX X-Spam-Check-By: apache.org Received: from [140.211.11.22] (HELO thor.apache.org) (140.211.11.22) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 10 Aug 2011 02:31:22 +0000 Received: from thor (localhost [127.0.0.1]) by thor.apache.org (8.13.8+Sun/8.13.8) with ESMTP id p7A2V0jq015662 for ; Wed, 10 Aug 2011 02:31:00 GMT Date: Tue, 9 Aug 2011 22:31:00 -0400 (EDT) From: confluence@apache.org To: scm@geronimo.apache.org Message-ID: <15486122.12159.1312943460166.JavaMail.confluence@thor> Subject: [CONF] Apache Geronimo Development > Building Apache Geronimo MIME-Version: 1.0 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Auto-Submitted: auto-generated X-Virus-Checked: Checked by ClamAV on apache.org

Building Apache Geronimo

Page edited by Runhua Chi


Changes (2)

=20 =20
=20 =20
...
You will need to figure out w= hich repository the artifact is available from. Look in the {{BUILD_ROOT/po= m.xml}} file within the {{<repositories>}} tag to see the primary rep= ositories utilized. You can also review the build output to see where maven= attempted to download the artifact from.

h3. Overriding libraries provided by JVM in build time
In some ca= ses, Java EE 6 requires newer library versions then what is provided by Jav= a SE 6. For example, EE 6 requires annotations 1.1 api but SE 6 provides an= notation 1.0 api. So it is necessary that during a build we override the JV= M provided libraries with newer versions.

You can use {{geronimo-property-plugin}} in the pom.xml file of artif= acts to set __bootClassPath__ property which is used by {{maven-compiler-pl= ugin}} and {{maven-surefire-plugin}} as followed:
{code:xml|title=3Dpom= .xml}
...
<plugin>
<groupI= d>org.apache.geronimo.buildsupport</groupId>
&= lt;artifactId>geronimo-property-plugin</artifactId>
= <configuration>
<propertyName>boo= tClassPath</propertyName>
<propertyValuePr= efix>-Xbootclasspath/p:</propertyValuePrefix>
= <classpath>
<dependency>
= <groupId>org.apache.geronimo.specs</grou= pId>
<artifactId>geronimo-annotati= on_1.1_spec</artifactId>
<version&= gt;1.0.1</version>
</dependency> <dependency>
= <groupId>org.apache.geronimo.specs</groupId>
= <artifactId>geronimo-jaxws_2.2_spec</artifactId>= ;
<version>${geronimojaxws.version}&l= t;/version>
</dependency>
= </classpath>
</configuration> <= br> </plugin>
<plugin>
= <groupId>org.apache.maven.plugins</groupId>
= <artifactId>maven-compiler-plugin</artifactId>
= <configuration>
<compilerArgum= ent>${bootClassPath}</compilerArgument>
</c= onfiguration>
</plugin>
<plugin= >
<groupId>org.apache.maven.plugins</groupI= d>
<artifactId>maven-surefire-plugin</artif= actId>
<configuration>
= <argLine>${bootClassPath}</argLine>
</c= onfiguration>
</plugin>
...
{code}
Meanwhile, you can use _listFiles_ options so that the *set* property of = {geronimo-property-plugins}} could contain files or directories. For exampl= e, if you want the geronimo-property-plugin to set "-Djava.endorsed.di= rs" property configure the plugin with:
{code:xml}
<propert= yValuePrefix>-Djava.endorsed.dirs=3D</propertyValuePrefix>
<= ;listFiles>false</listFiles>
{code}
If you want the plugin= to set "-Xbootclasspath/p:" property configure the plugin with: =
{code:xml}
<propertyValuePrefix>-Xbootclasspath/p:</proper= tyValuePrefix>
<listFiles>true</listFiles>
{code}

*{+}Apache Geronimo 2.0{+}* <= br>If you're building the 2.0 branch and the build fails because it can= 't find an xbean jar (for example org.apache.xbean:xbean-naming:jar:3.2= -r579367), then add the
...

Full Content

Overview

This documents how to build the Apache Geronimo Server project.

This guide is intended to cover how to build the latest server/trunk= , though other newer branches should also follow similar instructions.= Server trees that use the same basic build tooling include:

    =09
  • server/trunk
  • =09
  • server/branches/2.2
  • =09
  • server/branches/2.1
  • =09
  • server/branches/2.0
  • =09
  • server/branches/1.2 (not tested recently)

nightly built snapshots from trunk
If you are only interested in obtaining a compiled binary of what is most r= ecent in trunk, this is already made available. Geronimo server/trunk is built from the repository on a nightly basis, and the resulting comp= iled binaries are available as snapshots on Apache's Snapshot Repository. Particularly you will want the Apache Geronimo a= ssemblies which is what is published when Geronimo is released as a maj= or revision.

Typically one would compile Geronimo when testing code modifications, ot= herwise the snapshots the Geronimo community provides is sufficient for tes= ting the latest code from the repository. And when submitting a bug, the co= mmunity appreciates if these latest Geronimo assemblies can be tested for t= he bug to make sure we haven't already fixed it. 

other relevant documentation
The Geronimo community also maintains build documentation specific to each = Geronimo version. While the community attempts to keep all these related do= cs in sync with each other, you may find some varying information among the= m.

Prerequisites

Build Machine

It is recommended that a dedicated computer used to build server/tru= nk have a minimum of 2GB of real memory. The computer will also need a= connection to the Internet to download artifact dependencies.

Build Time
The first-time-build will download all artifact dependencies into your loca= l maven repository, so the build time will partly depend on the speed of yo= ur internet connection. The builds that are executed after the first comple= te build will be faster because the artifact dependencies are already downl= oaded during the first build. As Geronimo trunk is being developed as SNAPS= HOT (e.g. Geronimo 3.0-SNAPSHOT), it also depends on 3rd-party artifacts th= at are being released as SNAPSHOTs. As a result, new artifacts will be down= loaded as snapshots are released, which is a daily occurrence.

As of June 2011 the following build time results were recorded:

    =09
  • 90 minutes - one 2.4GHz dual-core CPU; 2GB of real memory; 2Mb Inter= net connection; empty local maven repository (first build)
  • =09
  • 13+ hours - two 2.0GHz dual-core CPUs; 1GB of real memory; 2Mb Inter= net connection; populated maven repository; (not first build)

The available real memory makes a big difference. During the build proce= ss, maven self-loads the artifacts it builds. Having enough real memory all= ows the build process to quickly start up the dependencies that are built. = Without enough memory, your real memory must be swapped so the dependencies= can be started, and then swapped again to go back to the build process.

Build Tips
Refer to the Build = Options section below for more options that can speed up your build tim= e.

Java D= eveloper Kit (JDK)

You will need a JDK 6.0+ (Java SE 1.6.0+ SDK) or compatible JDK to b= uild Apache Geronimo from trunk. It is recommended you use SUN's implement= ation, or something compatible like Apples implementation. Other JDK vendo= rs implementations may work, but use at your own risk.

Apache Geronimo 2.2
JDK 5.0+ (J2SE 1.5.0+) or compatible JDK.
The Java SE (JDK) 6.0 works with Geronimo 2.2.

Apache Geronimo 2.1 and earlier
JDK 5.0+ (J2SE 1.5.0+) or compatible JDK.

Windows Tip
Windows users should = not double-quote JAVA_HOME (or MAVEN_HOME for the same reason), according t= o MAVEN-666.
Setting:
set JAVA_HOME=3D"C:\Program Files\Java\jdk1.6.0_20"
doesn't work, but this does:
set JAVA_HOME=3DC:\Program Files\Java\jdk1.6.0_20

Apache Maven 2

To execute the build process you need to have Apache Maven version= 2.2.1 (or newer) installed to build Apache Geronimo from trunk. M= aven 3.0 can also be used to build trunk.

To check if your installation is working and you have the required minim= um version run:

mvn -version

And it should produce something like:

Maven version: 2.2.1

If you have an incompatible version the server build will probably fail = with a message complaining 3D""

Apache Geronimo 2.2
Apache Maven version 2.0.10 (or newer)

maven repository
When building Ge= ronimo 2.2. Add the following to your settings.xml for maven so th= at you can avoid the redirect (and hence avoid the bogus poms/jars) and get= beyond compilation failure problem to build Geronimo using maven. See this message for more details.
excerpt of setting= .xml for maven
...
   <mirrors>
       <mirror>
           <id>java.net</id>
           <name>Mirror of https://ma=
ven-repository.dev.java.net/nonav/repository/</=
name>
           <url>http://download.java.=
net/maven/2/</url>
           <mirrorOf>java.net</mirrorOf>
       </mirror>
   </mirrors>
...

Subversion

To fetch the source code for the server, you will need to have a Subversion client version 1.5 (or newer, 1.5 is recommended) installed= .

Windows Tip
Windows users are = strongly encouraged to change the M2 local repository (the place where = dependencies are downloaded) to a shorter path with no spaces, e.g. C:\= .m2.
Using a longer path may cause the build (and Geronimo itself) to behave ver= y strangely when it hits the 260 char limit for filenames on Windows.

In order to change the m2 local repository go to %USERPROFILE%\.m2 and edit or create settings.xml file to contain the following = content:

<?xml version=3D"1.0=
"?>
<settings>
    <localRepository>C:\.m2</localRepository>
</settings>

Checkout Geroni= mo

svn co https://svn.apache.org/repos/asf/geronimo/server/trunk server
Tip
If you are using Chinese syst= em, please change your locale to en_US. Otherwise, the maven 2.0.7(or below= ) can't parse Chinese characters.
<= /tr>
Windows Tip
Windows users are = strongly encouraged to checkout Geronimo into c:\g.
Using a longer path may cause the build (and Geronimo itself) to behave ver= y strangely when it hits the 260 char limit for filenames on Windows.

You can also use Git mirrors to checkout Geronimo source code, and make = sure you have a Git client installed before using the following command:

git clone git://git.apache.org/geronimo server

= Preparing to Build for the First Time

Chances are you will need to increase the heap size for Maven. Add the = following lines to ~/.mavenrc:

3D""The following snips only set MAVEN_O= PTS if its not already set, so that you can override these values on t= he command line if needed.
# Increase the heap size Maven
if [ "x$MAVEN_OPTS" =3D "x" ]; then
    MAVEN_OPTS=3D-Xmx512m
fi

If you are using the SUN JDK (or a JDK with compatible flags, like the A= pple JDK), you should also increase the maximum permanent size as well as t= he heap:

# Increase the heap and max permanent size for Maven
if [ "x$MAVEN_OPTS" =3D "x" ]; then
    MAVEN_OPTS=3D"-Xmx1024m -XX:PermSize=3D256m -XX:MaxPermSize=3D1024m -XX=
:ReservedCodeCacheSize=3D64m"
fi

For Apache Geronimo 2.2, use at least:

if [ "x$MAVEN_OPTS" =3D "x" ]; then
    MAVEN_OPTS=3D"-Xmx512m -XX:MaxPermSize=3D128m -XX:ReservedCodeCacheSize=
=3D64m"
fi
Windows Tip
Windows users should = create mavenrc_pre.bat under c:\documents and settings\<use= rname>\mavenrc_pre.bat or c:\mavenrc_pre.bat depending on = how the %HOME% property is set on your system.

Variables will need to use the batch set syntax:

set <VARIABLE>=3D<VALUE>

Building

To build all changes incrementally:

mvn install

To perform clean builds, which are sometimes needed after some changes t= o the source tree:

mvn clean install

Building Stages

In some cases you may need to build Geronimo in stages, such as when you= have changed the geronimo version. Most users will not need to do this, b= ut its documented here for clarity.

To build modules, testsupport and maven-plugins:

mvn install -Dstage=3Dbootstrap

To build apps, configs and assemblies:

mvn install -Dstage=3Dassemble

As mentioned, most users will not need to build Geronimo in stages. But= in some cases, when bootstrapping new versions (when no artifacts are depl= oyed into remote repositories for the current version), then you must build the stages separately for the first build and then for all= builds afterwards, the staged build is not necessary.

3D""Using Sonatype nexus can help make large= maven builds faster and more reliable. However you have to configure all = the repositories specified in the geronimo poms in your nexus instance.

Build Options

HeapDumpOnOutOfMemoryError
Add the HeapDumpOnOutOfMemoryError flag to MAVEN_OPTS to get a dump on OutO= fMemory errors

-XX:+HeapDumpOnOutOfMemoryError

Skip tests
Use -DskipTests=3Dtrue to turn off tests during server build. You can u= se this flag if you are simply running a build to save a little more time. = However, you should not use this flag if you are making code changes, as yo= u should want to build with the tests to make sure your changes do not brea= k anything. Testing the build is necessary if you are submitting a patch or= code change recommendations.

mvn clean install -DskipTests=3Dtrue

Build offline
You can also build in an offline mode. Use -o to avoid searching remote= repositories to save more time. However, you have to complete one full onl= ine build before this will work so that all dependencies will be downloaded= into your local maven repository. After the first complete build, using th= e -o flag will cause maven to only use what you have locally and not se= arch remote repositories.

mvn -o clean install

More error and debug information
To get Maven to provide you with more error details, use -e to get stac= k traces on errors, and use -X to produce execution debug output.

mvn -X clean install
mvn -e clean install

Restricting a build to only one assembly
If your only interested in either the tomcat or jetty assemblies, you can s= ave build time by indicating which of these assembly types should be built.= There are two profiles in the geronimo/server/trunk/assemblies/pom.xml= named tomcat and jetty. To only build the tomcat as= semblies and not the jetty ones, you would indicate it like this:

mvn clean install -Ptomcat

You should be able to do this with built-in maven stuff, see maven tips and tricks= advanced reactor options.
Example: This should build everything needed for the named assembly includi= ng the assembly:

mvn clean install -pl :geronimo-tomcat7-javaee6 -am

Geronimo Assemblies Resulting from the Build

After a complete build has successfully finished, the resulting assembli= es are located in associated target subdirectories of each assembly. These = are the same as what are provided from the nightly Apache Geronimo Snapshot= s.

BUILD_ROOT/assemblies/geronimo-jetty8-javaee6/target/geronimo-jetty8-j=
avaee6-3.0-SNAPSHOT-bin(.tar.gz|.zip)
BUILD_ROOT/assemblies/geronimo-jetty8-javaee6-web/target/geronimo-jetty8-ja=
vaee6-web-3.0-SNAPSHOT-bin(.tar.gz|.zip)
BUILD_ROOT/assemblies/geronimo-tomcat7-minimal/target/geronimo-tomcat7-mini=
mal-3.0-SNAPSHOT-bin(.tar.gz|.zip)
BUILD_ROOT/assemblies/geronimo-tomcat7-javaee6/target/geronimo-tomcat7-java=
ee6-3.0-SNAPSHOT-bin(.tar.gz|.zip)
BUILD_ROOT/assemblies/geronimo-tomcat7-javaee6-web/target/geronimo-tomcat7-=
javaee6-web-3.0-SNAPSHOT-bin(.tar.gz|.zip)
BUILD_ROOT/assemblies/geronimo-jetty8-minimal/target/geronimo-jetty8-minima=
l-3.0-SNAPSHOT-bin(.tar.gz|.zip)
BUILD_ROOT/plugins/clustering/geronimo-plugin-farm-node/target/geronimo-plu=
gin-farm-node-3.0-SNAPSHOT-bin(.tar.gz|.zip)
BUILD_ROOT/framework/assemblies/geronimo-framework/target/geronimo-framewor=
k-3.0-SNAPSHOT-bin(.tar.gz|.zip)
BUILD_ROOT/framework/modules/geronimo-plugin/target/test-resources/Archiver=
GBeanTest/server1/bar-1.0-bin(.tar.gz|.zip)

Testing the A= ssembly

usin= g the geronimo-maven-plugin

Once you have build the server fully, which will produce a number of zip and tar.gz archives from the assembly modules, you can u= se the geronimo-maven-plugin to start the server. From the projec= t root directory run:

mvn -Ptools geronimo:start
Windows Tip
Windows users may nee= d to specify an alternative installDirectory to avoid long path pr= oblems:
mvn -Ptools geronimo:start -DinstallDirectory=3Dc:\g

And to stop, either CTRL-C or from a separate terminal, from th= e project root directory run:

mvn -Ptools geronimo:stop

or by hand

cd assemblies/geronimo/jetty6-javaee5/target
tar xzf geronimo-jetty6-javaee5-<version>-bin.tar.gz
./geronimo-jetty-javaee5-<version>/bin/gsh geronimo/start-server

IDE Setup

The server project does not have any IDE files checked in since major ID= Es have better support for maven than maven for them.

Intellij IDEA

For the IDEA 8.1 and later:
The project is too large to easily open at once in IDEA. Generally the fram= ework project and individual plugins are a good size to work with. In the m= aven projects tab, check the it profile to get more of the maven projects.<= /p>

Eclipse

Use the maven2 eclipse:eclipse plugin. See Developing Geronimo in Eclipse for detailed instructions. As f= or IDEA, opening framework or individual plugins is more likely to work tha= n trying to open the whole project.

Troubleshooting<= /h2>

If for some reason maven is unable to download and install an artifact, = and the build stops with an error complaining of such, you will need to man= ually download the archive and install it in your local maven repository. Y= ou can do that with a maven command similar to this:

mvn install:install-file
    -DgroupId=3Dorg.apache.geronimo.framework
    -DartifactId=3Dgeronimo-kernel
    -Dversion=3Djar
    -Dpackaging=3D3.0-20110608.081951-139
    -Dfile=3D/path/to/file-artifact.jar

Maven can download and install dependencies for you:

mvn dependency:get
    -DrepoUrl=3Dhttps://repository.apache.org/content/groups/snapshots/
    -Dartifact=3D"org.apache.geronimo.framework:geronimo-kernel:jar:3.0-201=
10608.081951-139"

You will need to figure out which repository the artifact is available f= rom. Look in the BUILD_ROOT/pom.xml file within the <reposi= tories> tag to see the primary repositories utilized. You can also = review the build output to see where maven attempted to download the artifa= ct from.

Overriding libraries provided by JVM in build time

In some cases, Java EE 6 requires newer library versions then what is pr= ovided by Java SE 6. For example, EE 6 requires annotations 1.1 api but SE = 6 provides annotation 1.0 api. So it is necessary that during a build we ov= erride the JVM provided libraries with newer versions.

You can use geronimo-property-plugin in the pom.xml file of art= ifacts to set _bootClassPath_ property which is used by maven-= compiler-plugin and maven-surefire-plugin as followed:

pom.xml
<= div class=3D"codeContent panelContent">
...
            <plugin>
                <groupId>org.apache.g=
eronimo.buildsupport</groupId>
                <artifactId>geronimo-=
property-plugin</artifactId>
                <configuration>
                    <propertyName>boo=
tClassPath</propertyName>
                    <propertyValuePrefix>-Xbootclasspath/p:</propertyValuePrefix>=

                    <classpath>
                        <dependency>
                            <groupId>=
org.apache.geronimo.specs</groupId>
                            <artifactId>geronimo-annotation_1.1_spec</artifactId>=

                            <version>=
1.0.1</version>
                        </dependency>
                        <dependency>
                            <groupId>=
org.apache.geronimo.specs</groupId>
                            <artifactId>geronimo-jaxws_2.2_spec</artifactId>
                            <version>=
${geronimojaxws.version}</version>
                        </dependency>
                    </classpath>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.m=
aven.plugins</groupId>
                <artifactId>maven-com=
piler-plugin</artifactId>
                <configuration>
                    <compilerArgument>${bootClassPath}</compilerArgument>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.m=
aven.plugins</groupId>
                <artifactId>maven-sur=
efire-plugin</artifactId>
                <configuration>
                    <argLine>${bootCl=
assPath}</argLine>
                </configuration>
            </plugin>
...

Meanwhile, you can use listFiles options so that the set= property of {geronimo-property-plugins}} could contain files or directorie= s. For example, if you want the geronimo-property-plugin to set "-Djava.end= orsed.dirs" property configure the plugin with:

<propertyValuePrefix>-Djava.endorsed.=
dirs=3D</propertyValuePrefix>
<listFiles>false</listFiles>

If you want the plugin to set "-Xbootclasspath/p:" property configure th= e plugin with:

<propertyValuePrefix>-Xbootclasspath/=
p:</propertyValuePrefix>
<listFiles>true</listFiles>

Apache Geronimo 2.0
If you're building the 2.0 branch and the build fails because it can't find= an xbean jar (for example org.apache.xbean:xbean-naming:jar:3.2-r579367), = then add the

http://svn.apache.org/repos/asf/openejb/repo/

repository to the pom.xml file in the root of the source tree. = See this message for more details.