Home

Marcus edited this page Mar 17, 2015 · 15 revisions
Clone this wiki locally

SilverStripe Australia Build Environment (Ozzy)

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

Creating a new project using Ozzy

You can create a new project using Ozzy as a basis by using composer as follows

composer create-project -s dev silverstripe/ozzy {your_project_name}

This will create the project ready for development, with the

  • 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 the composer.json and/or 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/

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 project uses two methods for doing this: composer (SilverStripe 3.0 and later) and a custom dependent-modules definition format.

For composer based modules, enter entries in the composer.json file; the phing build script will take care of running composer for you.

For non-composer modules, use the build/dependent-modules file, with the following format

The format for a module entry is as follows

[subpath/]modulename[:revision] gitUrl|svnUrl [execute_dev_build=false] [local=false]

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)

Git creates patches slightly differently - in this case, you need to create the patch from the module folder, and you'll need to explicitly tell it the module name when creating

git diff --no-prefix modulename > ../build/patches/modulename.patch

which will prefix things appropriately for when the patch is created.

Testing options

An example test config that allows for executing tests a little faster

Create ssautesting/testing.conf.php with something like

'''php

"ss_tmpdb_silverstripe_testing", "reporter" => "CliTestReporter", "logfile" => "ssautesting/logs/testsuite.xml", 'type' => 'SQLite3Database', 'path' => ASSETS_PATH . '/.sqlitedb/', 'key' => 'SQLite3DatabaseKey', 'memory' => false ); ''' To run completely in memory, change the 'memory' option to 'true'. Instead of running in memory, you can also pass build=0 as a URL parameter (or on the command line) to skip rebuilding the database. ## Updating to "new" build structure To update a project to use the new silverstripe-build module; ``` $ git rm -r build/ $ git rm -r ssautesting/ $ git commit -m "Removed obsoleted build/testing modules" $ wget https://github.com/silverstripe-australia/silverstripe-base/raw/master/build.xml $ vi build.xml #replace project name in the updated build.xml to what it was previously $ composer require silverstripe-australia/build $ composer require silverstripe-australia/ssautesting $ echo build/ >> .gitignore $ echo ssautesting/ >> .gitignore ```