Prequisites before building Apache Shindig

In order to build Apache Shindig, you must have the following:

• Java (JDK/JRE) 1.5 or later installed on your system and the JAVA_HOME environment variable set.
  • See: http://java.sun.com/ for installation instructions.
• A Subversion client installed in order to checkout the code.
  • Instructions for downloading and installing Subversion can be found here: http://subversion.tigris.org/
• Apache Maven installed to perform the build.
  • Instructions for downloading and installing Maven can be found here: http://maven.apache.org/download.html

Getting the code

Create a subdirectory and checkout the Apache Shindig code from its Subversion repository

1. mkdir ~/src/shindig (or wherever you'd like to put it)
2. cd ~/src/shindig
3. svn co http://svn.apache.org/repos/asf/incubator/shindig/trunk/ .

Building and running the code with Maven

To build a Web Archive (WAR) file for the Gadget server and run tests, perform the following:

1. Make sure you have the prerequisites installed first.
2. cd ~/src/shindig/
3. mvn
4. Once the build successfully completes, you can install the built WAR files located in the /target subdirectory onto your JEE server.

To run the code and start a Jetty server that will run on at localhost:8080:

• mvn -Prun
• Open in you browser http://localhost:8080/gadgets/ifr?url=http://www.labpixies.com/campaigns/todo/todo.xml

To run the Jetty server on a different port, use:

• cd java/server
• mvn clean install jetty:run -DrunType=<full|gadgets|social> -Djetty.port=<port>

Once you've either installed the WAR file on your JEE server, or are running locally using the Jetty server, you can test the Gadget server using:

• http://localhost:<port>/gadgets/ifr?url=http://www.labpixies.com/campaigns/todo/todo.xml

Setting up an Eclipse project to build Apache Shindig

These steps, after completing the previous section, will allow you to build from within Eclipse using the Maven2 plugin. You should first install the Maven plugin, then create the new Java project.

• Create ~/.m2/settings.xml consisting solely of

 <settings> </settings>

• Install the Maven2 plugin
  1. Help -> Software Updates -> Find and Install
  2. Search for new features to install
  3. Create a new remote update site for the Maven 2 plugin
     • Name: Maven2 - Sonatype
     • URL: http://m2eclipse.sonatype.org/update/
  4. Select the site and click "Finish"
  5. There are optional dependencies on mylyn and subclipse. If you don't have these plugins, you can get them here. Otherwise, select only the Maven Integration plug-in.
  6. Complete the installation

• Setup new workspace and project
  Creating a new workspace eliminates the performance cost from existing projects and makes it easier to manage the code.
  1. File -> Switch Workspace -> Other...
  2. Select directory to store workspace
     • Do not select a parent directory of the Apache Shindig source (e.g. ~/src/shindig) as Eclipse won't allow you to create the Java project.
     • Something like ~/eclipse/workspaces/shindig would work fine
  3. File -> New -> Java Project
     1. Name the project. The instructions below will assume "SHINDIG".
     2. Select 'Create project from existing source' and navigate to .../src/shindig/java
     3. Click Finish
     4. If you see a dialog for "Open Associated Perspective", click Ok. Don't worry about the errors after loading as they will be fixed in the next step.
  4. Right-click the project, select Maven : Enable Dependency Management
  5. Right-click the project, select Maven : Update Source Folders
  6. Optionally, if you would like to be able to browse or step into the code of your dependent jars when debugging, you need the source jars. Right-click the project, select Maven : Download Sources and Eclipse will automatically know about these sources when debugging. You can browse them under Maven Dependencies in your project.
  7. If you'll be using AllTests to run tests or generate code coverage stats, adjust the project's output folders.
     1. Project -> Properties -> Java Build Path -> Source
     2. Locate and open SHINDIG/gadgets/src/test/java
     3. Select Output Folder: (Default Output Folder) and click Edit...
     4. Select Specific Output Folder
     5. Enter target/test-classes and click OK.
     6. Repeat for SHINDIG/social-api/src/test/java

Generating Code Coverage in Eclipse

To generate code coverage statistics inside of Eclipse, install the EclEmma plugin. Then

• Open org.apache.shindig.gadgets.AllTests
• Right-click in the class, and select Coverage as -> JUnit Test

Running inside Eclipse

To debug the server in Eclipse, follow the last two steps here (takes a few minutes to set up):

• "Using eclipse external tools"
• "Attaching to the server running in debug mode, using eclipse"

Note: You must have set up Eclipse to build the code or do mvn package yourself after making changes, but you won't need to restart Jetty to see your changes.

Running with Caja

Caja is an important part of OpenSocial that greatly enhances JavaScript security. Caja is managed in a separate open source project hosted by Google code projects. For more information on Caja, see: http://code.google.com/p/google-caja/wiki/CajaEasyIntro

1. Load this page: http://localhost:8080/gadgets/files/samplecontainer/samplecontainer.html
2. Point it to this gadget: http://localhost:8080/gadgets/files/samplecontainer/examples/SocialHelloWorld.xml

To see the cajoled code (Firefox only), right-click inside the iframe and do "This Frame -> View Frame Source"

Additional reading

Read java/README for original instructions on how to start up any of the java shindig servers.

Read javascript/README for instructions for using the Apache Shindig Gadget Container JavaScript to enable your page to render Gadgets using gmodules.com or a server started up as described above.