The Stubbles build system

To ease the development with Stubbles, we provide a build-system, that takes care of commonly needed tasks. To make use of this build system, you will have to install Phing. If you need help installing this requirement, please take a look at installing Phing.

Setting up your project

After you downloaded the Stubbles release and extracted the archive, you are ready to setup your project:

$ cd /path/to/stubbles
$ stubbles setup-project

After running this command, you will be asked several questions:

project name

The build process will ask you for the name of your project. This is only needed for the Phing build file, it can easily be changed afterwards. If your project name contains ampersands please make sure that you mask them as & by yourself instead of just typing &. Not masking the ampersand results in a broken generated build file.

permissions for cache folder

The build process will automatically set the permissions for all folders, that will contain cache files. Please make sure, that the cache permissions allow the webserver to write in these folders.

Enabling JSON-RPC functionality

If you want to build an AJAX powered site, please answer this questions with Y to copy all required files.

directory for generated clients

If you enabled the JSON-RPC functionality, you will need to specify a directory, in which Stubbles will copy the Javascript proxy classes generated during the build process. If you need to change this at a later point, this can be done in the build.properties file.

enabling JSON-RPC examples

If you have never worked with the AJAX features of Stubbles, you may want to enable the JSON-RPC examples. If you do, please answer this question with Y.

usage of the remote YUI version

If you enabled the JSON-RPC example, Stubbles will try and detect, whether you have a local copy of the YAHOO! User Interface Library installed. If not, it will ask you, whether a remote version should be used.

enable logging

If you answer this question with Y, Stubbles will copy all configuration files required by the logging features to the expected location.

enable variant manager

If you want to use variants in your website, answer this question with Y to copy the required configuration files.

All available commands

The stubbles build script provides various commands that help you with common tasks. To run a command, just execute the following line in your shell:

$ stubbles [commandname]

Besides setup-project the stubbles script provides the following commands:

setup-examples

This command will make sure that the included examples work on your server or provides information, why the examples are not working.

clean-dist

This command will remove all left over dist files from your installation. By default, all configuration files are named [config]-dist.xml, so you do not accidentally overwrite your own config files. If you have finished your configuration, execute this command to delete all obsolete files.

clean-config

The setup-project command will create a build.properties file, that contains your choices during setup. If you want to delete the choices you made and re-setup your project, run the clean-config command followed by setup-project.

clean-examples

This command will remove all examples from the distribution. It is recommended to remove them before going into production mode.

clear-cache

This will remove all cache files from your installation. Make sure, that the user who runs this command has the permissions to delete files written by the webserver.

Starting the build

After you finished the project setup and adjusted all configuration options, you are ready to start the build. All, that is needed for this is running Phing:

$ phing
Buildfile: path/to/stubbles/build.xml

MyProject > main:

...

BUILD FINISHED

Total time: 1.2271 second

The output of the build process depends on the selections you made during project setup and the Stubbles version and components you are using.

Adjusting the build process

The build process is completely managed by Phing and can easily be adjusted. After the project setup has been finished, the root folder of your project will contain to build files:

• build.xml
• build-stubbles.xml

Feel free to modify the build.xml file to make additions to the build process. All tasks provided by Stubbles are defined in the build-stubbles.xml file, which must not be changed manually, as new versions will provide improved build scripts.