Download, Build and Deploy Project Wonderland v0.5 Modules

This page describes how to download, build and deploy the optional add-on modules for Project Wonderland from the source code. The add-on modules contain additional functionality not found in the core workspace. Some of these add-on modules are compiled into the binary distributions of Project Wonderland.

The Project Wonderland team is also working on a "warehouse" where you will be able to download add-on modules in binary form. Details of this "warehouse" will be posted when it is available.

Requirements

Before downloading, compiling, and installing the optional add-on modules, you should have first downloaded and compiled the Project Wonderland v0.5 source. You can find instructions here:

• Download, Configure, Build and Run from the Wonderland v0.5 Source

Download the Project Wonderland modules workspace

The wonderland-modules workspace contains all of the source code for the Project Wonderland modules and is available via svn. Note that this subversion workspace includes both the 0.4 modules and the 0.5 modules; the 0.5 module source is located under the 0.5/ directory and is broken up into two categories: stable and unstable. (Although "stable" is a relative term, since Project Wonderland itself is experimental software). For example, the "stable" modules currently include the SVG whiteboard and the audio recorder. The "unstable" modules are either examples or experimental modules: there is no guarantee they will work at any point in time.

The build system of Project Wonderland is designed so that you may compile and deploy each module individually. It is also designed so that if you place your wonderland-modules workspace alongside your wonderland workspace, the "stable" modules will also be compiled and certain ones appearing on a "white list" will also be deployed to the server when it is started.

This tutorial assumes you will place the modules workspace under a base directory named ~/src, although you are free to place it anywhere. It also assumes you have further placed the core Project Wonderland workspace under the 0.5-preview2/ subdirectory (for User Preview 2) or under the trunk/ subdirectory (for the latest source code).

Below, you will place the wonderland-modules workspace as a sibling of the core wonderland workspace (that is, both directories have the same parent directory in the file system).

User Preview 2 module source code

To download the source from our most recent stable release (User Preview 2), inside a terminal window from your home directory, after you have created the ~/src/0.5-preview2/ subdirectory:

% cd ~/src/0.5-preview2
% svn checkout https://wonderland-modules.dev.java.net/svn/wonderland-modules/branches/0.5-preview2 wonderland-modules --username <username>

where you should replace <username> with your java.net user name.

Latest module source code

To download the latest module source (trunk), inside a terminal window from your home directory, after you have created the ~/src/trunk/ subdirectory:

% cd ~/src/trunk
% svn checkout https://wonderland-modules.dev.java.net/svn/wonderland-modules/trunk/0.5 wonderland-modules --username <username>

where you should replace <username> with your java.net user name.

Building the Project Wonderland modules

Build the "stable" modules

You can build the Project Wonderland "stable" modules, assuming you have placed the workspace as a sibling of the core Wonderland workspace, by running the ant command from the core Wonderland workspace. For User Preview 2:

% cd ~/src/0.5-preview2/wonderland
% ant

and for the latest source code (trunk):

% cd ~/src/trunk/wonderland
% ant

Note: This ant command is not run from the wonderland-modules workspace, but rather from the wonderland workspace.

You may also build each "stable" module individually by executing the ant command within each "stable" module directory.

Build the "unstable" modules

You can build the Project Wonderland "unstable" modules by executing the ant command for each module individually. This tutorial uses the shape-module-tutorial "unstable" module for User Preview 2 as an example, but the instructions apply to any module beneath the unstable directory.

1. Change directories to ~/src/0.5-preview2/wonderland-modules/unstable/shape-module-tutorial.
2. Edit the my.module.properties file to make sure that the wonderland.dir property points to your installation of the core wonderland workspace. If you have arranged your wonderland-modules workspace as a sibling of the wonderland workspace as shown above, the proper value of wonderland.dir should be ../../../wonderland.
3. Run the ant command from the shape-module-tutorial directory.

Deploying the Project Wonderland modules

Deploy the "stable" modules that appear in the "white list"

By default, a certain set of "stable" modules are automatically deployed (i.e. installed) to Wonderland when you run the server (using ant run-server in the wonderland workspace), assuming you have placed the workspace as a sibling of the core Wonderland workspace.

The set of "stable" modules that are automatically deployed are found in the wonderland-modules/stable/build.xml file, within the <target name="-modules-stable-dist-copy-selected">...</target> tags (see example below). If you wish to add a "stable" module to the "white list", then add a new <file name="..."/> line following the examples already present.

    <!--
         copy only the selected modules to the dist directory.  This is the
         default action, unless the modules.include.all property is set
    -->
    <target name="-modules-stable-dist-copy-selected" unless="modules.include.all">
        <copy todir="dist">
            <filelist dir=".">
                <file name="orientationworld/dist/orientationworld.jar"/>
                <file name="pdfviewer/dist/pdfviewer.jar"/>
                <file name="telepointer/dist/telepointer.jar"/>
                <file name="whiteboard/dist/whiteboard.jar"/>
                <file name="image-viewer/dist/imageviewer.jar"/>
                <file name="audiorecorder-module/dist/audiorecorder.jar"/>
                <file name="stickynote/dist/stickynote.jar"/>
            </filelist>
            <mapper type="flatten"/>
        </copy>
    </target>

Deploy the non-"white list" "stable" modules and "unstable" modules

You can deploy each "stable" module that does not appear in the "white list" and all of the "unstable" modules individually. (Note that you may also manually (re)deploy the "stable" modules that appear in the "white list" too using these instructions.)

Note that when you deploy a module, it will restart the Wonderland server. If you have changed any code in your module that runs inside of the Project Wonderland server, the transient world state is typically erased. If you wish to persist the world state, you must take a snapshot of your world state first. For more information, please visit the Wonderland Web-Based Administration Guide.

To deploy a module, first make sure your Wonderland server is running, and then within the module directory:

% ant deploy

If you wish to uninstall the module later on, you may do so via the Wonderland Web-Based Administration Tool.

Some additional comments

Really, you can checkout any individual module to any directory you wish. The instructions above simply point out the "best practices" followed by the core Wonderland development team. So long as the wonderland.dir property in the my.module.properties file points to your core wonderland workspace, you should be able to compile and deploy the module.