README.txt

   1
   2 Drush make
   3 ----------
   4 Drush make is an extension to drush that can create a ready-to-use drupal site,
   5 pulling sources from various locations. It does this by parsing a flat text file
   6 (similar to a drupal `.info` file) and downloading the sources it describes. In
   7 practical terms, this means that it is possible to distribute a complicated
   8 Drupal distribution as a single text file.
   9
  10 Among drush make's capabilities are:
  11
  12 - Downloading Drupal core, as well as contrib modules from drupal.org.
  13 - Checking code out from CVS, SVN, git, and bzr repositories.
  14 - Getting plain `.tar.gz` and `.zip` files (particularly useful for libraries
  15   that can not be distributed directly with drupal core or modules).
  16 - Fetching and applying patches.
  17 - Fetching modules, themes, and installation profiles, but also external
  18   libraries.
  19
  20
  21 Usage
  22 -----
  23 The `drush make` command can be executed from a path within a Drupal codebase or
  24 independent of any Drupal sites entirely. See the examples below for instances
  25 where `drush make` can be used within an existing Drupal site.
  26
  27     drush make [-options] [filename.make] [build path]
  28
  29
  30 ### Options
  31
  32     --contrib-destination=path
  33
  34       Specify a path under which modules and themes should be
  35       placed. Defaults to sites/all.
  36
  37     --force-complete
  38
  39       Force a complete build even if errors occur.
  40
  41     --ignore-checksums
  42
  43       Do not verify md5 checksums for downloaded files.
  44
  45     --md5
  46
  47       Output an md5 hash of the current build after completion.
  48
  49     --no-clean
  50
  51       Leave temporary build directories in place instead of
  52       cleaning up after completion.
  53
  54     --no-core
  55
  56       Do not require a Drupal core project to be specified.
  57
  58     --no-patch-txt
  59
  60       Do not write a PATCHES.txt file in the directory of
  61       each patched project.
  62
  63     --prepare-install
  64
  65       Prepare the built site for installation. Generate a
  66       properly permissioned settings.php and files directory.
  67
  68     --tar
  69
  70       Generate a tar archive of the build. The output filename
  71       will be [build path].tar.gz.
  72
  73     --test
  74
  75       Run a temporary test build and clean up.
  76
  77     --translations=languages
  78
  79       Retrieve translations for the specified comma-separated list
  80       of language(s) if available for all projects.
  81
  82     --working-copy
  83
  84       Where possible, retrieve a working copy of projects from
  85       their respective repositories.
  86
  87
  88 ### Examples
  89
  90 1. Build a Drupal site at `example/` including Drupal core and any projects
  91    defined in the makefile:
  92
  93         drush make example.make example
  94
  95 2. Build a tarball of the platform above as `example.tar.gz`:
  96
  97         drush make --tar example.make example
  98
  99 3. Build an installation profile within an existing Drupal site:
 100
 101         drush make --no-core --contrib-destination=. installprofile.make
 102
 103
 104 The `.make` file format
 105 -----------------------
 106 Each makefile is a plain text file that adheres to the Drupal `.info` file
 107 syntax. See the included `example.make` for an example of a working makefile.
 108
 109
 110 ### Core version
 111
 112 The make file always begins by specifying the core version of Drupal for which
 113  each package must be compatible. Example:
 114
 115     core = 6.x
 116
 117
 118 ### API version
 119
 120 The make file must specify which Drush Make API version it uses. This version
 121 of Drush Make uses API version `2`
 122
 123     api = 2
 124
 125
 126 ### Projects
 127
 128 An array of the projects (e.g. modules, themes, libraries, and drupal) to be
 129 retrieved. Each project name can be specified as a single string value. If
 130 further options need to be provided for a project, the project should be
 131 specified as the key.
 132
 133 **Project with no further options:**
 134
 135     projects[] = drupal
 136
 137 **Project using options (see below):**
 138
 139     projects[drupal][version] = 6.15
 140
 141 Do not use both types of declarations for a single project in your makefile.
 142
 143
 144 ### Project options
 145
 146 - `version`
 147
 148   Specifies the version of the project to retrieve.
 149   This can be as loose as the major branch number or
 150   as specific as a particular point release.
 151
 152         projects[views][version] = 3
 153         projects[views][version] = 2.8
 154         projects[views][version] = 3.0-alpha2
 155
 156         ; Shorthand syntax for versions if no other options are to be specified
 157         projects[views] = 3.0-alpha2
 158
 159 - `patch`
 160
 161   One or more patches to apply to this project. An array of URLs from which
 162   each patch should be retrieved.
 163
 164         projects[calendar][patch][rfc-fixes][url] = "http://drupal.org/files/issues/cal-760316-rfc-fixes-2.diff"
 165         projects[calendar][patch][rfc-fixes][md5] = "e4876228f449cb0c37ffa0f2142"
 166
 167         ; shorthand syntax if no md5 checksum is specified
 168         projects[adminrole][patch][] = "http://drupal.org/files/issues/adminrole_exceptions.patch"
 169
 170 - `subdir`
 171
 172   Place a project within a subdirectory of the `--contrib-destination`
 173   specified. In the example below, `cck` will be placed in
 174   `sites/all/modules/contrib` instead of the default `sites/all/modules`.
 175
 176         projects[cck][subdir] = "contrib"
 177
 178 - `location`
 179
 180   URL of an alternate project update XML server to use. Allows project XML data
 181   to be retrieved from sites other than `updates.drupal.org`.
 182
 183         projects[tao][location] = "http://code.developmentseed.com/fserver"
 184
 185 - `type`
 186
 187   The project type. Must be provided if an update XML source is not specified
 188   and/or using version control or direct retrieval for a project. May be one of
 189   the following values: core, module, profile, theme.
 190
 191         projects[mytheme][type] = "theme"
 192
 193 - `directory_name`
 194
 195   Provide an alternative directory name for this project. By default, the
 196   project name is used.
 197
 198         projects[mytheme][directory_name] = "yourtheme"
 199
 200 - `l10n_path`
 201
 202   Specific URL (can include tokens) to a translation. Allows translations to be
 203   retrieved from l10n servers other than `localize.drupal.org`.
 204
 205         projects[mytheme][l10n_path] = "http://myl10nserver.com/files/translations/%project-%core-%version-%language.po"
 206
 207 - `l10n_url`
 208
 209   URL to an l10n server XML info file. Allows translations to be retrieved from
 210   l10n servers other than `localize.drupal.org`.
 211
 212         projects[mytheme][l10n_url] = "http://myl10nserver.com/l10n_server.xml"
 213
 214 - `overwrite`
 215
 216   Allows the project to be installed in a directory that is not empty.
 217   If not specified this is treated as FALSE, drush_make sets an error when the directory is not empty.
 218   If specified TRUE, drush_make will continue and use the existing directory.
 219   Useful when adding extra files and folders to existing folders in libraries or module extensions.
 220
 221         projects[myproject][overwrite] = TRUE
 222
 223
 224 ### Project download options
 225
 226   Use an alternative download method instead of retrieval through update XML.
 227   The following methods are available:
 228
 229 - `download[type] = file`
 230
 231   Retrieve a project as a direct download. Options:
 232
 233   `url` - the URL of the file. Required.
 234
 235   `md5`, `sha1`, `sha256`, or `sha512` - one or more checksums for the file. Optional.
 236
 237   `request_type` - the request type - get or post. Defaults to get. Optional.
 238
 239   `data` - The post data to be submitted with the request. Should be a
 240   valid URL query string. Required.
 241
 242   `filename` - What to name the file, if it's not an archive. Optional.
 243
 244 - `download[type] = bzr`
 245
 246   Use a bazaar repository as the source for this project. Options:
 247
 248   `url` - the URL of the repository. Required.
 249
 250 - `download[type] = cvs`
 251
 252   Use a CVS repository as the source for this project. Options:
 253
 254   `date` - use the latest revision no later than specified date. See the CVS
 255   man page for more about how to use the date flag.
 256
 257   `root` - the CVS repository to use for this project. Optional. If unspecified,
 258   the `CVSROOT` environment value will first be used and finally Drupal contrib
 259   CVS is used as a last resort fallback.
 260
 261   `module` - the CVS module to retrieve. Required.
 262
 263   `revision` - a specific tag or revision to check out. Optional.
 264
 265      projects[mytheme][download][type] = "cvs"
 266      projects[mytheme][download][module] = "mytheme"
 267
 268 - `download[type] = git`
 269
 270   Use a git repository as the source for this project. Options:
 271
 272   `url` - the URL of the repository. Required.
 273
 274   `branch` - the branch to be checked out. Optional.
 275
 276   `revision` - a specific revision identified by commit to check out. Optional.
 277
 278   `tag` - the tag to be checked out. Optional.
 279
 280      projects[mytheme][download][type] = "git"
 281      projects[mytheme][download][url] = "git://github.com/jane_doe/mytheme.git"
 282
 283 - `download[type] = svn`
 284
 285   Use an SVN repository as the source for this project. Options:
 286
 287   `url` - the URL of the repository. Required.
 288
 289   `interactive` - whether to prompt the user for authentication credentials
 290   when using a private repository. Allows username and/or password options to
 291   be omitted. Optional.
 292
 293   `username` - the username to use when retrieving an SVN project as a working
 294   copy or from a private repository. Optional.
 295
 296   `password` - the password to use when retrieving an SVN project as a working
 297   copy or from a private repository. Optional.
 298
 299      projects[mytheme][download][type] = "svn"
 300      projects[mytheme][download][url] = "http://example.com/svnrepo/cool-theme/"
 301
 302
 303 ### Libraries
 304
 305 An array of non-Drupal-specific libraries to be retrieved (e.g. js, PHP or other
 306 Drupal-agnostic components). Each library should be specified as the key of an
 307 array of options in the libraries array.
 308
 309 **Example:**
 310
 311     libraries[jquery_ui][download][type] = "file"
 312     libraries[jquery_ui][download][url] = "http://jquery- ui.googlecode.com/files/jquery.ui-1.6.zip"
 313     libraries[jquery_ui][download][md5] = "c177d38bc7af59d696b2efd7dda5c605"
 314
 315
 316 ### Library options
 317
 318 Libraries share the `download`, `subdir`, and `directory_name` options with
 319 projects. Additionally, they may specify a destination:
 320
 321 - `destination`
 322
 323   The target path to which this library should be moved. The path is relative to
 324   that specified by the `--contrib-destination` option. By default, libraries
 325   are placed in the `libraries` directory.
 326
 327         libraries[jquery_ui][destination] = "modules/contrib/jquery_ui
 328
 329
 330 ### Includes
 331
 332 An array of makefiles to include. Each include may be a local relative path
 333 to the includer makefile directory or a direct URL to the makefile. Includes
 334 are appended in order with the source makefile appended last, allowing latter
 335 makefiles to override the keys/values of former makefiles.
 336
 337 **Example:**
 338
 339     includes[example] = "example.make"
 340     includes[example_relative] = "../example_relative/example_relative.make"
 341     includes[remote] = "http://www.example.com/remote.make"
 342
 343
 344 ### Overriding properties
 345
 346 Makefiles which include others may override the included makefiles properties.
 347 Properties in the includer takes precedence over the includee.
 348
 349 **Example:**
 350
 351 `base.make`
 352
 353     core = "6.x"
 354     projects[views][subdir] = "contrib"
 355     projects[cck][subdir] = "contrib"
 356
 357 `extender.make`
 358
 359     includes[base] = "base.make"
 360
 361     ; This line overrides the included makefile's 'subdir' option
 362     projects[views][subdir] = "patched"
 363
 364     ; This line overrides the included makefile, switching the download type
 365     ; to a CVS checkout
 366     projects[views][type] = "module"
 367     projects[views][download][type] = "cvs"
 368     projects[views][download][module] = "contributions/modules/views"
 369     projects[views][download][revision] = "DRUPAL-6--2"
 370
 371 A project or library entry of an included makefile can be removed entirely by
 372 setting the corresponding key to FALSE:
 373
 374     ; This line removes CCK entirely which was defined in base.make
 375     projects[cck] = FALSE
 376
 377
 378 Recursion
 379 ---------
 380 If a project that is part of a build contains a `.make` itself, drush make will
 381 automatically parse it and recurse into a derivative build.
 382
 383 For example, a full build tree may look something like this:
 384
 385     drush make distro.make distro
 386
 387     distro.make FOUND
 388     - Drupal core
 389     - Foo bar install profile
 390       + foobar.make FOUND
 391         - CCK
 392         - Token
 393         - Module x
 394           + x.make FOUND
 395             - External library x.js
 396         - Views
 397         - etc.
 398
 399 Recursion can be used to nest an install profile build in a Drupal site, easily
 400 build multiple install profiles on the same site, fetch library dependencies
 401 for a given module, or bundle a set of module and its dependencies together.
 402 For Drush Make to recognize a makefile embedded within a project, the makefile
 403 itself must have the same name as the project. For instance, the makefile
 404 embedded within the managingnews profile must be called "managingnews.make".
 405
 406 **Build a full Drupal site with the Managing News install profile:**
 407
 408     core = 6.x
 409     projects[] = drupal
 410     projects[] = managingnews
 411
 412 Testing
 413 -------
 414 Drush make also comes with testing capabilities, designed to test drush make
 415 itself. Writing a new test is extremely simple. The process is as follows:
 416
 417 1. Figure out what you want to test. Write a makefile that will test this out.
 418    You can refer to existing test makefiles for examples.
 419 2. Drush make your makefile, and use the --md5 option. You may also use other
 420    options, but be sure to take note of which ones for step 4.
 421 3. Verify that the result you got was in fact what you expected. If so,
 422    continue. If not, tweak it and re-run step 2 until it's what you expected.
 423 4. Using the md5 hash that was spit out from step 2, make a new entry in the
 424    tests array in drush_make.test.inc, following the example below.
 425     'machine-readable-name' => array(
 426       'name'     => 'Human readable name',
 427       'makefile' => 'tests/yourtest.make',
 428       'messages' => array(
 429           'Build hash: f68e6510-your-hash-e04fbb4ed',
 430       ),
 431       'options'  => array('any' => TRUE, 'other' => TRUE, 'options' => TRUE),
 432     ),
 433 5. Test! Run drush make-test machine-readable-name to see if the test passes.
 434
 435 You can check for any messages you want in the message array, but the most
 436 basic tests would just check the build hash.
 437
 438 Generate
 439 --------
 440
 441 Drush make has a primitive makefile generation capability. To use it, simply
 442 change your directory to the Drupal installation from which you would like to
 443 generate the file, and run the following command:
 444
 445 `drush generate-makefile /path/to/make-file.make`
 446
 447 This will generate a basic makefile. If you have code from other repositories,
 448 the makefile will not complete - you'll have to fill in some information before
 449 it is fully functional.
 450
 451 Maintainer
 452 ----------
 453 - Dmitri Gaskin (dmitrig01)
 454
 455 Co-maintainers
 456 ------------
 457 - Adrian Rossouw (adrian)
 458 - Antoine Beaupr� (anarcat)
 459 - Chad Phillips (hunmonk)
 460 - Jeff Miccolis (jmiccolis)
 461 - Young Hahn (yhahn)
 462