Updated Docs for Spring Roo


  • Want updated Roo Documentation?
  • Want information on creating and publishing Roo Add-Ons?


1. Get the dev build of Spring Roo from: http://git.springsource.org/roo

I am assuming here that you have created a /roo-dev directory.

To build Roo, you should read the /roo-dev/roo/readme.txt file. Below is a snippet from that file.

** Note: You will need a GPG key!


=====================
ONE-TIME SETUP INSTRUCTIONS
=====================

We’ll assume you typed the following to checkout Roo (if not, adjust the paths in the following instructions accordingly):

cd ~
git clone git://git.springsource.org/roo/roo.git

Next double-check you meet the installation requirements:

* A *nix machine (Windows users should be OK if they write a .bat)
* A proper installation of Java 5 or above
* Maven 2.0.9+ properly installed and working with your Java 5+
* Internet access so that Maven can download required dependencies

Next you need to setup an environment variable called MAVEN_OPTS. If you already have a MAVEN_OPTS, just check it has the memory sizes shown below (or greater). If you’re following our checkout instructions above and are on a *nix machine, you can just type:

echo export MAVEN_OPTS=\”-Xmx1024m -XX:MaxPermSize=512m\” >> ~/.bashrc
source ~/.bashrc
echo $MAVEN_OPTS
(example result: MAVEN_OPTS=-Xmx1024m -XX:MaxPermSize=512m)

You’re almost finished. You just need to wrap up with a symbolic link:

sudo ln -s ~/roo/bootstrap/roo-dev /usr/bin/roo-dev
sudo chmod +x /usr/bin/roo-dev

Note: You do not need a ROO_CLASSPATH_FILE environment variable. This was only required for the Roo 1.0.x development series.

=====================
GPG (PGP) SETUP
=====================
Roo now uses GPG to automatically sign build outputs. If you haven’t installed GPG, download and install it:

* Main site: http://www.gnupg.org/download/
* Apple Mac option: http://macgpg.sourceforge.net/

Ensure you have a valid signature. Use “gpg –list-secret-keys”. You should see some output like this:

$ gpg –list-secret-keys
/home/balex/.gnupg/secring.gpg
——————————
sec 1024D/00B5050F 2009-03-28
uid Ben Alex
uid Ben Alex
uid Ben Alex
ssb 4096g/2DB6833B 2009-03-28

If you don’t see the output, it means you first need to create a key. It’s very easy to do this. Just use “gpg –gen-key”. Then verify your newly-created key was indeed created: “gpg –list-secret-keys”.

Next you need to publish your key to a public keyserver. Take a note of the “sec” key ID shown from the –list-secret-keys. In my case it’s key ID “00B5050F”. Push your public key to a keyserver via the command
“gpg –keyserver hkp://pgp.mit.edu –send-keys 00B5050F” (of course changing the key ID at the end). Most public key servers share keys, so you don’t need to send your public key to multiple key servers.

Finally, every time you build you will be prompted for the password of your key. You have three options:

* Type the password in every time
* Include a -Dgpg.passphrase=thephrase argument when calling “mvn”
* Edit ~/.bashrc and add -Dgpg.passphrase=thephrase to MAVEN_OPTS

Of course the most secure option is to type the password every time. However, if you’re doing a lot of builds you might prefer automation.

One final note if you’re new to GPG: don’t lose your private key! Backup the secring.gpg file, as you’ll need it to ever revoke your key or sign a replacement key (the public key servers offer no way to revoke a key unless you can sign the recovation request).

=====================
OSGI WRAPPING JARS
=====================

Some Roo modules require JARs that are not already in OSGi form. That is, they don’t have an OSGi-aware manifest. Roo has a special project called “wrapper” that can convert normal JARs into OSGi JARs.

You’ll need to run the wrapper before trying to do anything with Roo. If you don’t do this, you’ll see errors which state Maven cannot find “org.springframework.roo.wrapping.some_module”.

To create the wrapped JARs, from the root Roo checkout location type:

cd wrapping
mvn clean install
cd ..

You need not do this too often. If you get an error about a missing wrapper JAR (org.springframework.roo.wrapping.some_module), simply repeat the above commands and you should be fine.


2. Generating the Documentation

Use the following commands to build Spring Roo, the mvn site command will generate the HTML & PDF files.

  cd /roo-dev/roo
  mvn clean install
  mvn site

NOTE: As per the readme.txt file, the “wrapping” directory must be built once.

  cd /roo-dev/roo/wrapping
  mvn clean install

Then you can build from the project root directory

  cd /roo-dev/roo/wrapping
  mvn clean install site

3. Locate the PDF File

There are 2 PDF files, and I believe they are identical.

  /roo-dev/roo/target/docbkx/pdf/index.pdf
  /roo-dev/roo/target/site/reference/pdf/spring-roo-docs.pdf 

Further Reading

About Gordon

Technology enthusiast primarily focused on Java and Open Source projects. Spring Certified Professional and Trainer. http://twitter.com/gdickens http://linkedin.com/in/gordondickens http://github.com/gordonad
This entry was posted in felix, Git, LogBack, OSGi, Roo, Spring, Spring Framework, Spring Roo and tagged , , , , , , , . Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *


*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>