Building Shale

This page describes the process for downloading and building Shale from the Apache Subversion repository and then the wrinkles in building it for various IDEs

The Basics

Pulling Shale from SVN

Assuming that you already have a Subversion client installed such as TortoiseSVN. You need to checkout from the following repository URL http://svn.apache.org/repos/asf/struts/shale/trunk/, or from the command line use svn checkout with that same URL

Dependencies

Shale needs the following libraries, if you are building without an IDE you'll need to have these available. If you are using an IDE to inspect and build the Shale code, then some of these libraries may already be available for you. (See below)

You will also need Ant installed.

Building From The Command Line

To build the core Shale libraries follow these steps.

1. svn checkout the shale trunk from the url above
2. Copy build.properties.sample to build.properties
3. Edit the build.properties to point to the various libraries as above
4. Execute ant download-dependencies which will retrieve the required libraries
5. Execute ant dist to build core-library, test-framework, clay-plugin, and use-cases
   

Building Shale with Maven

• Instructions (updated 20050901) http://wiki.wsmoak.net/cgi-bin/wiki.pl?ShaleMavenBuild
• Check out http://blogs.sun.com/roller/page/wilfred/20050829 if you want to build Shale using Maven.
  
• Maven 2 build files (experimental): http://wiki.wsmoak.net/cgi-bin/wiki.pl?ShaleMaven2
  

IDEs

JDeveloper 10.1.3

To get the Ant compile to run successfully in JDeveloper a some extra settings have to be added to the build.properties to override locations defined in the build.xml if you want to use the JSF RI as shipped with JDeveloper and the OC4J servlet API JARs rather than downloading a separate JSF RI and Tomcat.

This assumes the use of JDeveloper 10.1.3 developer preview (J2EE edition).

Note the versions of the various Jakarta Commons libraries shipped in the JDeveloper install are lower than those needed for Shale, so you should separately download beanutils, chain, digester and logging and update your build.properties with the appropriate locations.

General JDeveloper Setup

Set up JDeveloper to exclude the .svn sub-directories from the source view in the navigator. to do this:

1. From the menu Tools > Properties
2. Choose Global Ignore List in the properties tree
3. Go to the New Filter field and add **/.svn
4. Press Add, then OK.
   

Next, if you want to compile Shale through the normal workspace make/compile rather than Ant, create user libraries to point at the updated versions of the various commons libraries mentioned above. Use the Tools > Manage Libraries menu option. It's probably worth doing this in any case, even if you intend to use Ant for building, just so that code insight and so on will work correctly if you want to change the source.

Creating a Base Project for Shale

JDeveloper 10.1.3 does not come with an SVN plugin yet so you'll have to pull the source tree from the command line or from a tool like TortoiseSVN.
Once you've done this, go ahead and do the following to create a project with the Shale core source.

1. Create a new workspace. Call this something like Shale and put it in the root shale directory created by the svn checkout.
2. Create a new project from source (call the project something like core-library) and point it at /core-library/src/java for the source tree. Store the project file in the core-library subdirectory for convenience, although both it and the workspace (jws) file can live outside of the Shale directory structure if you want to keep the source directories cleaner.
3. Once the project is created, open the project properties and select the Project Content node. Set the Output Directory field to the core-library/target/classes directory rather than the default /classes this will ensure that both the Ant compile target and a JDeveloper compile with both write to the same place and you'll not end up with two sets of class files.
4. Also in the project properties be sure to add the various libraries required for Shale if you might want to edit the code and need code assistance.
   • Servlet Runtime
   • JSF
   • Commons Logging 1.0.4
   • Commons Chain 1.0
   • Commons Digester 1.6
   • Commons Beanutils 1.7.0
     1.#5 Finally copy the build.properties.sample file to build.properties and make the changes outlined in the next section.
     

build.properties Settings

• The JSF RI jars are in %JDEV_HOME%/jsf-ri
• The servet and JSP API jars are in %JDEV_HOME%/j2ee/home/lib and have different names from the Tomcat jars
• The correct version of JUnit is available in %JDEV_HOME%/jdev/extensions/oracle.jdeveloper.junit.10.1.3/junit3.8.1

Also add these extra values to your build.properties file to force the use of OC4J and the shipped JSF RI. Substitute the physical location of the JDeveloper Home for %JDEV_HOME%

Building Shale in JDeveloper

To build you can simply use the defined Ant targets. Select the build.xml and in the structure pane you'll see the various targets. Either choose run on the build.xml as a whole to run the default library target or right mouse click on the required target inside the structure pane and choose run.

Eclipse 3.0.1

General Eclipse Setup

To make the checkout from the Struts subversion repository simpler it's worth installing the Eclipse Subversion plug-in [Subclipse http://subclipse.tigris.org/\] if you don't already have it.

1. Choose Help > Software Updates > Find and Install
2. Choose Search for new features to install in the Install wizard dialog.
3. Hit the New Remote Site button
4. In the pop up, set the name to Subclipse Update Site and the URL to *http://subclipse.tigris.org/update*
5. Install the Subclipse plug-in

Download the following libraries:

• JSF Reference implementation from Sun
• Tomcat 5.0.28
• Commons Logging 1.0.4
• Commons Chain 1.0
• Commons Digester 1.6
• Commons Beanutils 1.7.0
  

Creating a Base Project for Shale

Follow these steps:

1. Switch to the SVN repository exploring perspective
2. Right mouse click on the Repository navigator and choose New > Repository Location or click the Add SVN Repository button
3. In the Add SVN Repository dialog use _http://svn.apache.org/repos/asf/struts/shale/trunk/_ as the URL and _http://svn.apache.org_ as the root URL. (Leave username/password blank.) Click the 'Finish' button.
4. Expand the node in the navigator and choose the core-library node
5. Right mouse click and choose Check Out As then Java Project
6. Go to the project properties and select the Java Build Path node.
7. Add core-library/src/java as the source folder and remove the existing source folder of Eclipse does not do it for you.
8. In the same dialog set Default output folder to core-library/target/classes
9. Also in the properties dialog, with the Java Build Path node selected, click on the libraries tab and define libraries for the various packages as defined above.

10. [Describe best way to get the build.properties.sample file from the trunk into the core-library project – the only way I could figure out how do it was by creating a build.properies file manually, opening build.properties.sample from svn, then manually copying and pasting the test into the new file. -mlk]

11. Finally copy the build.properties.sample file to build.properties and make the changes outlined in the next section.
    

build.properties settings

Update the build.properties to point at the homes of the various packages downloaded as above. The one exception is JUnit which is shipped in the Eclipse Install:

Building Shale in Eclipse

To build carry out the following steps.

1. Use Window > Show View > Ant
2. In the Ant Window right mouse click or use the icon to add a build file. Select build.xml
3. Run the default Ant task from the Ant window, or expand the node and choose a specific task and run that.