agiza / drupaldistrobuilder

Use the Phing (http://phing.info) tool as build management for Drupal (http://drupal.org)

Drupal and Phing: Using DrupalDistroBuilder

DrupalDistroBuilder (DDB) is a simple tool for creating customized installation packages of Drupal. Out of the box (with no changes), DDB does the following:

• It downloads the latest version of Drupal automatically.
• Based on your configuration, it retrieves all your preferred modules and themes.
• It adds your preferred modules and themes to the Drupal package
• It removes any modules and themes that you DON'T want.

At the end of the process, you are left with a shiny new archive (named drupal-VERSION-DATE-TIME.tgz) that has everything you want.

From there, all you need to do is install the new package, following the same installation procedure as always.

But this is just the tip of the iceberg. DDB is a starting point for customization. Simply modify the build.xml file to take advantage of all of the tools and capabilities in Phing. Here are some other things you can do with DDB:

• Perform custom installs, using DDB to automatically add you preferred modules and themes.
• Perform various standard build tasks, like backing up the database, building docs, and so on.
• Update modules and themes.
• Integrate with Drush to fire off Drush commands.
• Build your own deployment and code management tool.
• Add external dependencies like jQuery plugins or other PHP scripts.

With other Phing extensions, you can even integrate with SVN, CVS, Git, and other VCS systems. Add a little bit of PHP, and you can write your own Phing tasks.

And you can customize to your liking by just modifying a single XML file.

Installation

To install DDB, you need to do the following:

Install Phing

pear channel-discover pear.phing.info
pear install phing/phing

Read the complete install instructions for manual installs or more guidance.

Download the most recent DDB package from http://github.com/technosophos/DrupalDistroBuilder/downloads

Untar the DDB package into the desired location

tar -zxvf ddb-VERSION.tgz

Remember, DDB does not depend on Drupal at all, and does not use a web server either. It can be installed anywhere on your system, though it is probably a good idea to not install it into your webroot where others could see it.

Using DDB

There are three steps to building a custom Drupal distro with DDB:

Change directories into DDB's home. DDB is directory-sensitive by design

cd DrupalDistroBuilder/

Edit drupal.properties in your favorite editor

edit drupal.properties

Run the Phing command from the same directory that has build.xml

phing

That's all there is to it. At the end of Phing's build, you will have a Drupal package with a name that looks something like this:

drupal-6.14-20091114-1653.tgz

That file will contain Drupal and all of the modules and themes you selected. If you chose to remove modules from core, they will not be included in that tar file.

From there, follow the standard Drupal installation instructions to proceed.

Viewing Help

To view DDB's built-in help, run this command:

phing help

This will display the help page. To view information about the configuration, you can run this command:

phing explain

To view a list of all available phing commands, along with brief help, run this:

phing -l

You can also look at the build.xml file and drupal.properties file. Both are documented.

drupal.properties

As of this writing, there are only four properties to configure:

# Modules you want.
drupal.modules=views,cck

Set this to a comma-separated list of modules that should be downloaded and installed. Modules must reside on Drupal.org in order to be automatically downloaded. (If you need another repository, you will have to do some minor coding to add support for your repository.)

NOTE: Phing treats whitespace as significant, so there must be NO WHITESPACE between module names. The same goes for all items in this file.

# Themes you want.
drupal.themes=zen

Set this to a comma-separated list of themes that should be downloaded and installed.

# Modules to remove from core
#drupal.exclude.modules=blog,forum,aggregator,blogapi,book,ping,poll,upload
drupal.exclude.modules=

Set this to a comma-separated list of modules that should be explicitly excluded from the distribution. For obvious reasons, this only removes modules that are in core.

# Themes to remove from core
drupal.exclude.themes=bluemarine,marvin,pushbutton,chameleon

Set this to a comma-separated list of themes that should be excluded from the distribution. This will remove core themes from the package.

That's all there is to the configuration file.

Going Beyond Basic Builders

DDB has multiple tasks that are chained together to move from downloading Drupal through cleaning up after itself. You can see a complete list of these tasks by running:

phing -l

You can also run specific tasks by name. So if you just want to clean up after a DDB run, you can run this:

phing clean

All tasks are defined in the build.xml file, and can be edited to your liking. You may add your own targets or change the configuration in your build.xml file. You are advised to back up this file before upgrading to a new version of DDB, which may overwrite your build.xml file.

More

Can DDB Be Configured To...?

DDB is highly configurable, and is not intended to be a one-size-fits-all solution. In fact, it was built on top of Phing precisely for that reason. To modify the way the package builder works, simply make a backup copy of build.xml, and then hack away at build.xml. The Phing project is fully documented

A few things you can easily make Phing do to Drupal:

• Move files and directories around. For example, by default DDB stores all modules in sites/default/all/modules (which will interoperate well with Drush). You can easily change this in Phing, though.
• Dynamically replace strings. Yes, you can programmatically remove "Blue Smurf" from the search page.
• Programmatically patch core or modules.
• Create a default settings.php file, complete with preconfigured database connections. In fact, you can even PRE-CREATE the database from within the build.xml script. See PDOSQLExecTask
• Create a custom installation profile on the fly. This takes a little bit of work and perhaps some dynamic code generation, but it is certainly possible.
• Migrate existing Drupal databases. See DbDeployTask
• Integrate with your own SVN repository. Other VCSs might be supported by third-party Phing tools. See the Svn* tasks
• Download other third-party libraries like TinyMCE or Google Analytics. See the tag.
• With a little bit of creativity, one could even configure Phing to actually run the Drupal installation routines. This would require a healthy dose of PHP code, though.

Phing provides a powerful declarative XML-based language that happens to be particularly good at file system work. A look through the Phing manual may give you lots of other ideas for extensions to this system.

DDB-specific tasks and code

DDB uses a handful of PHP classes to perform Drupal-specific build tasks. These are all located inside of src/lib. This code is licensed under the LGPL 2.1. You are free to modify it or use it as a template for you own tasks.

• DrupalComponentDownloadTask (getcomponent): This downloads a module or theme that is located within Drupal's repository. It uses the Drupal release XML files to determine newest version and download URL.
• DrupalDownloadTask (getdrupal): This downloads the latest version of Drupal.
• HttpDownloadTask (download): This will download any old URL from any source that PHP handles with a stream wrapper. Generally, this is an HTTP URL, but PHP supports others as well.
• DrupalExistingComponentTask: Update a module or theme.
• SimplePatchTask: Apply a patch. You can download the patch with HttpDownloadTask and then automatically apply it with this task.
• DrupalComponentInfoTask (showcomponent): This shows information for a particular package, and can be used to query Drupal's package server.

Why Doesn't DDB Use A Custom Install Profile

While this system could directly interact with the Drupal installer (creating, for example, a custom install profile), it does not do so by default. Why? Because there is no generic functionality that we feel we could add this way.

Is this a clone of Drush/Drush-make?

Phing is not a clone of drush or drush-make (two recent Drupal tools). Phing is a generic build system for PHP applications, and it has been around for a decade. This package just tools phing's build process to provide standard Drupal tasks.

DDB is designed as a starting point that you can tailor to your own needs. You should not have to write much, if any, PHP code to develop your own Drupal distro. (You will simply customize the build.xml and drupal.properties files.)

Drush and Drush-make are special purpose tools without the flexibility of Phing. While they provide similar functionality, customizing them will involve learning the tool's internals and then writing custom code. Our goal is to keep you from ever having to do that. (Even if you have to write custom tools for DDB in PHP, there is almost no learning curve and you needn't know any internals.)

Why Is This LGPL Instead of GPL?

DrupalDistroBuilder is LGPL in order to avoid any confusion where it is asserted that adding additional tasks requires those tasks to be released under the GPL. Only the custom PHP code in src/lib/* is considered to be licensable code anyway.

This system is designed to be extended, and designed to be used for cases where proprietary business logic may be required. For that reason, we do not view a GPL release to be desirable.

All code that comes as part of Phing is subject to Phing's own licensing terms.

Build.xml and drupal.properties are not under LGPL

build.xml is considered to be a configuration file IN THE PUBLIC DOMAIN, the contents of which are not subject to the source code license. drupal.properties is also a configuration file, and is also IN THE PUBLIC DOMAIN.

Why Is This Code Not In Drupal's CVS?

Two reasons:

1. Because there is no place in Drupal's CVS for such projects. This is not a theme, module, or translation. The current Project configuration does not allow for anything else.
2. Because this project is not released under the GPL, which is viewed as too restrictive for DrupalDistroBuilder. We do not want the build.xml file to be GPLed, as that causes your modifications to be GPLed.

Authors

DrupalDistroBuilder was written by Matt Butcher ([email protected]), it is a simple wrapper around Phing (http://phing.info).