Fetching latest commit…
Cannot retrieve the latest commit at this time
|Failed to load latest commit information.|
====================================================================== SPRING ROO - DEVELOPER INSTRUCTIONS ====================================================================== Thanks for checkout out Spring Roo from Git. These instructions detail how to get started with your freshly checked-out source tree. These instructions are aimed at experienced developers looking to develop Spring Roo itself. If you are new to Spring Roo or would simply like to try a release that has already been built, tested and distributed by the core development team, we recommend that you visit the Spring Roo home page and download an official release: http://www.springsource.org/roo ====================================================================== 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 <firstname.lastname@example.org> uid Ben Alex <email@example.com> uid Ben Alex <firstname.lastname@example.org> 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. ====================================================================== DEVELOPING WITHIN ECLIPSE ====================================================================== The Spring Roo team use SpringSource Tool Suite to develop Roo, which is our free IDE. While you can use any IDE at all, these instructions assume you're using STS. The main difference to be aware of is STS has setup the M2_REPO variable correctly, and thus the Maven paths work out of the box. You can setup M2_REPO manually within a normal Eclipse if you wish; just use Window > Preferences > Java > Build Path > Classpath Variables and set M2_REPO to the ~/.m2/repository directory. First of all change into the directory where you checked out Roo. Now you need to instruct Maven to produce .classpath and .project files for Eclipse: mvn clean eclipse:clean eclipse:eclipse If this fails, please review the "OSGi Wrapping JARs" section above. You should now be able to import the projects into STS/Eclipse. Click File > Import > Existing Projects into Workspace, and select the same directory as where you ran the "mvn" command from. Several dozen Spring Roo projects will be listed and can be imported. At this stage you're free to open any class and edit it as normal. ====================================================================== RUNNING THE COMMAND LINE TOOL ====================================================================== Roo uses OSGi and OSGi requires compiled JARs. Therefore as you make changes in Roo, you'd normally need to "mvn package" the relevant project(s), then copy the resulting JAR files to the OSGi container. To simplify development and OSGi-related procedures, Roo's Maven POMs have been carefully configured to emit manifests, SCR descriptors and dependencies. These are mostly emitted when you use "mvn package". To try Roo out, you should type the following: mvn install (from the root Roo checkout location) cd ~/some-directory roo-dev It's important that you run roo-dev from a directory that you'd like to eventually contain a Roo-created project. Don't try to run roo-dev unless your current working directory is empty or contains a previously-created Roo project. If this fails, please review the "OSGi Wrapping JARs" section above. Notice we used "mvn install" rather than "mvn package". This is simply for convenience, as it will allow you to change into any Roo module subdirectory and "mvn install". If you never "mvn install", you will need to "mvn install" from the root directory so internal build dependencies are preserved. You can use "mvn package" from the root if you prefer. "mvn install" just gives you more flexibility. Roo ships with a command line tool called "roo-dev". This is only maintained for *nix. It copies all relevant JARs from the Roo directories into ~/roo/bootstrap/target/osgi. This directory represents a configured Roo OSGi instance. "roo-dev" also launches the OSGi container, which is currently Apache Felix. Be aware that Felix will cache the bundles you have installed each run (in /roo/bootstrap/target/osgi/cache). It's therefore more common that instead of using "roo-dev", you will type a command like: rm -rf ~/roo/bootstrap/target/osgi; roo-dev The above guarantees your Felix instance is fully cleaned. The "roo-dev" command line tool doesn't do this for you, as you might wish to test the operation of other bundles with Roo core. ====================================================================== DEBUGGING VIA ECLIPSE ====================================================================== **** Note as of ROO-728 this section is out of date **** Most of the time we just use the roo-dev command line tool directly from the command line. This we have found is the fastest approach and also lets us see exactly what a user would see, including the TAB completion features. Still, sometimes you have a tricky issue you'd prefer to work through via the STS/Eclipse debugger. When you do this you need to be aware that you lose the full capabilities of the shell, as the JLine library (used for command line parsing) is unable to fully hook into your operating system's keyboard and ANSI services. Anyhow, for some issues a debugger is worth the minor price of losing your full keyboard and colour services! :-) To setup debugging, open org.springframework.roo.bootstrap.Main. Note it has a Java "main" method. Execute the class using Run As > Java Application. Note the "Console" tab in Eclipse/STS will open. Type "quit" then hit enter. Now select Run > Debug Configurations. Select the Java Application > Main entry. Click on Arguments and then add the following VM Arguments: *nix machines: -Djline.terminal=org.springframework.roo.shell.jline.EclipseTerminal Windows machines: -Djline.WindowsTerminal.directConsole=false -Djline.terminal=jline.UnsupportedTerminal Finally, set the working directory to "Other" and a location on your disk where you'd like the Roo shell to be loaded. This is usually a project you're intending to test with. ====================================================================== SHELL DIAGNOSTIC FEATURES ====================================================================== The Roo shell includes several commands especially for Roo developers. Firstly, any exception thrown by Roo or one of its add-ons is always caught by the shell infrastructure and a simplified message displayed to the user. This is generally what is desired, as it allows you to simply throw exceptions whenever something is in an incorrect state. However, full exceptions can be displayed by typing this command: development mode There is also a "development mode -enabled false" to deactivate. There are also several metadata-related commands: metadata summary metadata trace -level x metadata for type -type com.foo.bar.TypeName metadata for id -metadataId MID:com.metadata.Class#theIdentifier The most practical command is "metadata for type", which shows you how Roo internally sees a particular Java type. It will also show you all of the downstream dependencies of a particular type, complete with the various metadata identifiers (strings starting with "MID:"). You can present those strings to the "metadata for id" command and see extra information about how Roo internally understands that metadata. The "metadata trace -level 1" command is useful for seeing how changes to metadata are notified to downstream dependencies, including any nested notifications that are taking place. You can also use level 2 if you would like even more verbose details, or level 0 to switch off the metadata tracing. An example of a condensed level 1 log follows: roo> add field string -fieldName test Managed SRC_MAIN_JAVA/com/hello/Foo.java 00000008 MID:xxx.PhysicalTypeIdentifier#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.BeanInfoMetadata#SRC_MAIN_JAVA?com.hello.Foo 00000009 MID:xxx.BeanInfoMetadata#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.FinderMetadata#SRC_MAIN_JAVA?com.hello.Foo 00000009 MID:xxx.BeanInfoMetadata#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.ToStringMetadata#SRC_MAIN_JAVA?com.hello.Foo 00000008 MID:xxx.PhysicalTypeIdentifier#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.PluralMetadata#SRC_MAIN_JAVA?com.hello.Foo 0000000c MID:xxx.PluralMetadata#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.EntityMetadata#SRC_MAIN_JAVA?com.hello.Foo 0000000d MID:xxx.EntityMetadata#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.BeanInfoMetadata#SRC_MAIN_JAVA?com.hello.Foo 0000000e MID:xxx.BeanInfoMetadata#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.FinderMetadata#SRC_MAIN_JAVA?com.hello.Foo 0000000e MID:xxx.BeanInfoMetadata#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.ToStringMetadata#SRC_MAIN_JAVA?com.hello.Foo 0000000d MID:xxx.EntityMetadata#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.FinderMetadata#SRC_MAIN_JAVA?com.hello.Foo 00000008 MID:xxx.PhysicalTypeIdentifier#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.ConfigurableMetadata#SRC_MAIN_JAVA?com.hello.Foo 00000008 MID:xxx.PhysicalTypeIdentifier#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.FinderMetadata#SRC_MAIN_JAVA?com.hello.Foo 00000008 MID:xxx.PhysicalTypeIdentifier#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.ToStringMetadata#SRC_MAIN_JAVA?com.hello.Foo 00000008 MID:xxx.PhysicalTypeIdentifier#SRC_MAIN_JAVA?com.hello.Foo -> MID:xxx.JavaBeanMetadata#SRC_MAIN_JAVA?com.hello.Foo Created SRC_MAIN_JAVA/com/hello/Foo_Roo_JavaBean.aj The numbers in the very first column are in hex format and increment by one for each metadata notification. There are then one or more spaces, with the spaces being used to denote nested notifications. The metadata identification (MID) on the left hand side of the "->" token is the "upstream" dependency which is notifying of a change, and the metadata identification (MID) on the right hand side of the "->" token is the downstream dependency that is receiving the notification. This continues until all notifications have been delivered. Circular loops are automatically avoided by the system, and string-based MID keys are used to ensure metadata remains immutable, cachable and memory efficient even in a large project. ====================================================================== GIT POLICIES ====================================================================== When checking into Git, you must provide a commit message which begins with the relevant Roo Jira issue tracking number. The message should be in the form "ROO-xxx: Title of the Jira Issue". For example: ROO-1234: Name of the task as stated in Jira You are free to place whatever text you like under this prefix. The prefix ensures FishEye is able to correlate the commit with Jira. You should not commit any IDE or Maven-generated files into Git. Try to avoid "git pull", as it creates lots of commit messages like "Merge branch 'master' of git.springsource.org:roo/roo". You can avoid this with "git pull --rebase". See the "Git Tips" below for advice. ====================================================================== GIT TIPS ====================================================================== Setup Git correctly before you do anything else: git config --global user.name "Kanga Roo" git config --global user.email email@example.com Perform the initial checkout with this: git clone firstname.lastname@example.org:roo/roo.git Let's take the simple case where you just want to make a minor change against master. You don't want a new branch etc, and you only want a single commit to eventually show up in "git log". The easiest way is to start your editing session with this: git pull That will give you the latest code. Go and edit files. Determine the changes with: git status You can use "gwt add -A" if you just want to add everything you see. Next you need to make a commit. Do this via: git commit -e The -e will cause an editor to load, allowing you to edit the message. Every commit message should reflect the "Git Policies" above. Now if nobody else has made any changes since your original "git pull", you can simply type this: git push origin If the result is '[ok]', you're done. If the result is '[rejected]', someone else beat you to it. The simplest way to workaround this is: git pull --rebase The --rebase option will essentially do a 'git pull', but then it will reapply your commits again as if they happened after the 'git pull'. This avoids verbose logs like "Merge branch 'master'". If you're doing something non-trivial, it's best to create a branch. Learn more about this at http://sysmonblog.co.uk/misc/git_by_example/. ====================================================================== RELEASING ====================================================================== Roo is released on a regular basis by the Roo project team. To release you should edit your ~/.m2/settings.xml so it includes: <settings> <servers> <server> <id>spring-roo-repository</id> <username>the_amazon_s3_main_account_access_id</username> <passphrase>the_amazon_s3_main_account_secret_key</passphrase> </server> </servers> </settings> The following command is used from the root checkout location: mvn clean package site assembly:assembly deploy site:deploy This will create a ZIP in the "target" directory. The org.springframework.roo.annotations JAR should be uploaded to repository.springsource.com/maven/bundles/release/org/springframework/ roo/org.springframework.roo/org.sfw.roo.annotations/<version>. Ensure SHA1/MD5 files, plus the POM and JAR is uploaded. Set public read ACL. Use the mvn-hash.sh if required to create the SHA1/MD5 files. The target/spring-roo-<version>.zip should be uploaded to /dist.springframework.org/milestone/ROO/. Also upload an SHA1 file. The following S3 properties must be set on the upload release ZIP: x-amz-meta-bundle.version:1.1.0.M1 x-amz-meta-release.type:milestone x-amz-meta-package.file.name:spring-roo-1.1.0.M1.zip x-amz-meta-project.name:Spring Roo If performing a GA release (ie *.RELEASE) upload the ZIP to /dist.springframework.org/release/ROO/ and change the S3 props to: x-amz-meta-release.type:release In addition, a Git tag should be created in the form w.x.y.zzzz (note there is no prefix or suffix to the Git tag). ====================================================================== HELP ====================================================================== There are no developer-specific forums or mailing lists for Roo. If you have any questions, please use the community support forum at http://forum.springsource.org/forumdisplay.php?f=67. Thanks for your interest in Spring Roo!