Level: Intermediate Tyler Anderson (tyleranderson5@yahoo.com), Freelance writer
17 Jan 2006 Many new and veteran developers are hopping onto the ever-growing Apache Geronimo bandwagon. Thus, the ability to build Geronimo is becoming increasingly important to developers who want to incorporate changes or full-custom modules. Unfortunately, building Geronimo is no trivial task. It requires learning new build scripts and companion build applications. Luckily, you can follow this step-by-step guide to understand exactly how to build the Apache Geronimo source code from scratch.
Introduction
Apache Geronimo is gaining steam as an open source solution, and with the new full version 1.0 release now available, Geronimo is more than ready for prime time. A great open source solution like Geronimo always brings along its own share of developers. Whether these developers become committers or private parties developing for internal or business use, they're going to need to know more about the structure of Geronimo to streamline the build process.
This article covers the topic of building Geronimo as follows:
- Find out how the download and installations of necessary build applications -- Apache Maven and Subversion (SVN) -- are used in the build process.
- Understand the relevant directories of Geronimo in both the source and binary standard distribution and how they relate to the whole of Geronimo.
- Build Geronimo from scratch, and log in to the Geronimo Console.
- Check out the latest version of Geronimo from svn.apache.org using SVN, and then test and run it by logging into the Geronimo Console.
Get started
This article uses version 1.0 of Geronimo and assumes you have no prior knowledge of Geronimo or the Geronimo build process. To use Geronimo, you need Java™ 1.4.2_08 (or later, but before 1.5). Download Java code from Sun Microsystems.
After you get the Java download, download Geronimo, Version 1.0. Select either the .zip (Microsoft® Windows® or Linux®) or the .tar.gz (Linux) file in both the Binaries and Source Code sections.
When the downloads complete, decompress the .zip or .tar.gz files in the same directory, then your Geronimo installation is ready.
Because Geronimo uses Apache Maven as the build tool, you also need to download Maven 1.1 Beta 2 from apache.org. Follow the simple installation instructions, and you're all set!
The last application you'll need to download is Subversion, which you'll use to check out the latest tree (HEAD) from the Apache Geronimo Subversion repository.
Also, make sure the following are added as environment variables:
- MAVEN_HOME should be the root install-dir of your Apache Maven installation.
- JAVA_HOME should be the root directory of your Java installation.
Finally, make sure the following directories are in your PATH variable:
- <maven-install-dir>/bin
- <geronimo-install-dir>/bin
- <java-install-dir>/bin
- <subversion-install-dir>/bin
See Resources for a link to information on adding to your PATH or creating new environment variables for both Windows and Linux users.
Geronimo and the initial build
There are several directories in the binary and source installations you've downloaded. The binary download includes the bare bones of Geronimo, which are necessary to run and use Geronimo. The source download includes all the Geronimo source, including Maven build scripts to build the entire tree. First, let's take a look at the binary distribution and then the source distribution.
Binary distribution
The binary has fewer files/directories; however, they're larger because they're in binary form. Here's the list of relevant directories:
- bin -- Most developers should be familiar with this directory. Here lie the executables.
- config-store -- Ever wondered where Geronimo's deployer places your application .war and other files? This is the place.
- doc -- Several plans or configurations for GBeans go here.
- repository -- This holds dependencies for building and running Geronimo.
- var -- Configuration and property files are stored here along with the built-in Derby database system.
That covers the binary distribution. Take a look at Resources for links to more information. Let's move to the source distribution.
Source distribution
There are several files/trees in this distribution, which is typical of source trees -- lots of fun code to look at! Here's the list of top-level directories:
- applications -- Holds the various standard applications that come with Geronimo. See Resources for links on how to demo each of them.
- modules -- Is several directories that contain all the Geronimo source code. Assembly is the main build directory; however, it's also possible to build each directory separately.
As a developer, you'll become most familiar with the subdirectories of the modules directory you have interest in modifying. Next you'll do the initial build on all of Geronimo.
Initial build
Performing an initial build of Geronimo is easy. Simply open a console, go to <geronimo-install-dir>, and type maven new. When making changes to the code, however, you should rebuild the tree. Do this by typing maven m:clean m:clean-repo new.
You can skip tests by adding "-Dmaven.test.skip=true -Dmaven.itest.skip=true" to the above command. I don't recommend skipping the tests after you've modified or added to the tree, but it's a good way to save time in some cases. Keep in mind that skipping the built-in tests can compromise the security and functionality of your system. After typing the above, the beginning of the build should appear as shown in Figure 1.
Figure 1. Building Geronimo
Throughout the build process, you'll notice Maven downloading various .jar files and other dependency files. I mention this because when I first built Geronimo, I got errors from Maven saying that it couldn't retrieve certain dependency files. It was a major hurdle that prevented me from debugging my code, using the Geronimo core as an aid. When I built Geronimo with Maven this time, I didn't receive any such errors. However, as backup, if you stumble across similar problems with Maven being unable to obtain certain dependencies, follow these instructions:
- Go to the <geronimo-install-dir>.
- Copy all the directories listed in the repository directory to the .maven/repository directory located in your HOME directory.
- Try building Geronimo again.
Maven should run this time without problems, because it'll have all the bulk of the necessary dependency files from the Geronimo installation. And if Maven needs more it should be able to find them.
A successful build is shown in Figure 2.
Figure 2. Successful build
When the build completes, the new build doesn't get saved where you might think, in the ./bin directory, because the ./bin directory isn't part of the source distribution. Thus, building Geronimo doesn't, in any way, affect the out-of-box build of Geronimo, nor does it affect any other builds you choose to replace the out-of-box build with.
Lets move on and test the build.
Test the initial build
To run the newly built server, go to this directory: <geronimo-install-dir>\assemblies\j2ee-tomcat-server\target\geronimo-1.0.
Open a console and type java -jar bin/server.jar.
The server should now start, as shown in Figure 3.
Figure 3. Starting Apache Geronimo
Now that Geronimo is started, open a browser and point it to http://localhost:8080/console.
You should now see the Geronimo Console, shown in Figure 4.
Figure 4. The Geronimo Console
Feel free to browse around. Note that the default username is system, and the password is manager.
Now, being a developer, or an ambitious debugger that likes to muck around in source code, you want to have the latest and greatest code, which brings us to using SVN to check out the entire tree.
Check out the latest Geronimo source tree using SVN
Being on the cutting edge is important to developers building leading technology. With something like Geronimo, every release is going to have highly important updates. Daily, or even weekly, expect a good share of new bug fixes and features coming in like the morning paper. Using SVN to check out and build the entire source tree allows you to do just that. You can take advantage of all the new features that the Geronimo developers have been working on.
Checking out the latest Geronimo build with SVN is easy. You installed SVN earlier. To check out the latest and greatest, go to a directory to which you want to check out the latest Geronimo source code tree, and type svn checkout http://svn.apache.org/repos/asf/geronimo/trunk geronimo.
The Geronimo tree is downloaded, or checked out, to your computer, as shown in Figure 5.
Figure 5. Checking out the latest Geronimo source tree
You can get further updates by typing the following in the ./geronimo directory (the directory you just checked Geronimo into from svn.apache.org): svn update.
Next you're going to clean and build the distribution. Change to the new Geronimo directory you just checked out from svn.apache.org, and type maven m:clean m:clean-repo new -Dmaven.test.skip=true -Dmaven.itest.skip=true.
Notice that this time Maven even downloads new dependency files, so you can tell that the Geronimo developers have been up to something! The tree builds as before, but you now have the absolute latest version of Geronimo.
Next you test your new build.
Test the latest build
You test the build similar to how you tested the initial build of the source download from Apache Geronimo, except this time you test the latest source retrieved via SVN. Type the following in a new console to start Geronimo:
java -jar <svncheckout-geronimo-dir>/assemblies
/j2ee-installer/target/geronimo-1.0-SNAPSHOT/bin/server.jar
Great! The server is up and running. Now go into the Geronimo Console. Open a browser, and point it to the Geronimo Console, as you did before (http://localhost:8080/console). See Figure 6.
Figure 6. Viewing the Geronimo Console in the latest version of Geronimo
The default username and password are still system and manager, respectively.
You now have the latest version of the Geronimo application server installed and running on your machine.
Conclusion
You're an accomplished Geronimo source tree builder now. You can build Geronimo no matter what or how many boulders are thrown in your path. You've also checked out the latest Geronimo source tree from svn.apache.org using SVN, and successfully built and run the server. If you plan to develop Geronimo code and/or modify and add to the Geronimo source tree, there are several folks over on the Geronimo developer mailing lists that would really appreciate the effort. See Resources for a link to the Geronimo mailing lists.
Resources Learn
- Find out what all the buzz is at The Geronimo renegade, a column featuring two of Geronimo's top committers.
- Learn more about Geronimo straight from Jeremy Boynes in this interview conducted here on developerWorks (May 2005).
- Read "Understand Geronimo's deployment architecture" (developerWorks, August 2005) for a peek into the concepts behind the Geronimo configuration and deployment model.
- Check out "Create, deploy, and debug Apache Geronimo applications" (developerWorks, May 2005) to learn how to use the Eclipse tools to help streamline your application development.
- Browse the Apache Geronimo Java API.
- Read about the power of GBeans, and learn what all the rave is about.
- Check out another GBeans article from the good folks at apache.org.
- Take advantage of this useful link on apache.org for more advanced methods of building Geronimo.
- Learn about modifying or creating your
PATH in Linux and Windows.
- Get information on creating new environment variables in both Linux and Windows.
- Learn more on getting the Geronimo source code using Subversion.
- Find helpful resources for beginners and experienced users at the Get started now with Apache Geronimo section of developerWorks.
- Join the Apache Geronimo mailing list.
- For more great pieces on Geronimo, check out the following content:
- Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
- Check out the developerWorks Apache Geronimo project area for articles, tutorials, and other resources to help you get started developing with Geronimo today.
- Browse all the Apache articles and free Apache tutorials available in the developerWorks Open source zone.
Get products and technologies
Discuss
About the author  | | | Tyler Anderson recieved both his B.S. in Computer Science in 2004 and his M.S. in Electrical and Computer Engineering in 2005 from Brigham Young University. Tyler has written and coded numerous articles and tutorials for IBM developerWorks and DevX. |
Rate this page
| 
