Skip to content

Home

Jump to bottom
nyeholt edited this page Jan 12, 2011 · 18 revisions

SilverStripe Australia Build Environment

This build environment makes use of Phing to provide management in a few key areas

  • Required module management
  • Module version management
  • Module dependency management
  • Patch management for externally maintained packages
  • Various packaging options - Full developer environment, deployment packages for new site installations, update packages containing module + mysite updates, individual module packaging
  • Server deployment over SSH (See the Deployment page for more information about setting this up)
  • Tweaked testing structure to allow for better integration with Hudson (and other CI tools)

Some of the important phing targets that can be executed

  • build - Retrieves all dependent modules (or updates them if they already exist), applies any relevant patches, and runs dev/build
  • add_module - Adds a module to the local environment (note that this does NOT update the project's build/dependent-modules file)
  • test - Executes all unit tests. You can run tests just for a single module by passing a module name, ie phing test -Dmodule=mysite. You can also optionally pass a single test case to run, eg phing test -Dmodule=mysite -Dtestcase=MyTest
  • phing-package - Creates a complete copy of this development environment repository that can be passed to another person, retaining all SVN and Git information
  • update-package - Creates a package that excludes several diretories that can be used for extracting over the top of existing installs
  • backup - Takes a database dump of the site before packaging

After cloning the repository, you should

  • Delete the .git directory! You'll eventually add this project to a new location, meaning it is unnecessary to keep the existing git info(1).
  • Edit the build.xml file and change the project name from rename-me to something more accurate
  • Copy the build/build.properties.sample file to build/build.properties
  • Edit that file and make any necessary adjustments. In particular, change the rewrite.base variable to match your webroot
  • Edit the build/dependent-modules.default and add in any additional modules you may need (see the section below on module management).
  • Run phing, which will fetch all needed modules and run a dev/build for the first time
  • Visit http://localhost/pathname/dev/build to ensure all caches are built correctly for the web

(1)If you're wanting to get any future updates to the build environment, you can add the silverstripe-base project as a separate git "remote" and cherry-pick relevant commits.

Module management

The build environment attempts to handle both the list of modules your project relies on, as well as the order they are installed to ensure dependencies are met.

The format for a module entry is as follows

[subpath/]modulename[:revision] gitUrl|svnUrl [true]

The first part here is the name of the module as it will appear in your project root; it is safe to use a path in this case so you can extract, for example, themes from a separate repository. This is useful to ensure that certain modules are in the correct directory path as required by the module

Following the modulename, the ":revision" can refer either to a specific SVN revision (if the svnUrl isn't a tag) to check out, or a specific git branch, tag or commit id. This allows you to ensure that every time the project is checked out by a user (or build system), the exact same repository versions of 3rdparty modules are being used. Note that for git, the format of the ':revision' must be ':branch:commit|tag', which will first ensure the module is on the correct branch before setting it to the appropriate commit or tag.

gitUrl|svnUrl is the git URL (git://xx, git@xx, etc) or SVN url used to checkout the module you are interested in.

The final optional 'true' indicates whether to run explicity run dev/build after adding this module to the system. This is useful if you need to run dev/build after adding a particular module to ensure adding a module later succeeds (given that some module dependencies won't be able to find code otherwise). By default, the system will just run a single dev/build after all the modules have been downloaded.

Some examples

\# Adds the trunk of the sqlite3 module
sqlite3 http://svn.silverstripe.com/open/modules/sqlite3/trunk

\# Uses revision 107809 of the legacydatetimefields module
legacydatetimefields:107809 http://svn.silverstripe.com/open/modules/legacydatetimefields/trunk

\# Uses tag 0.1.0 of the memberprofiles module
memberprofiles:master:0.1.0 git://github.com/ajshort/silverstripe-memberprofiles.git

Patch management

In some cases you will want to provide custom patches to dependent modules. As these can't be committed back to this project's repository, a mechanism exists to include just the .patch diffs. Create a diff from the root directory of your project. Drop any diffs into build/patches, and these will be applied during the build target.

For example

svn diff sapphire/ > build/patches/sapphire.patch)
Clone this wiki locally