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.
10 Among Drush make's capabilities are:
12 - Downloading Drupal core, as well as contrib modules from drupal.org.
13 - Checking code out from 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
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.
27 drush make [-options] [filename.make] [build path]
29 The `.make` file format
30 -----------------------
31 Each makefile is a plain text file that adheres to YAML syntax. See
32 the included `examples/example.make.yml` for an example of a working
35 The older Drupal `.info` INI format is also supported. See
36 `examples/example.make` for a working example.
40 The make file always begins by specifying the core version of Drupal
41 for which each package must be compatible. Example:
47 The make file must specify which Drush Make API version it uses. This version
48 of Drush Make uses API version `2`
55 An array of the projects (e.g. modules, themes, libraries, and drupal) to be
56 retrieved. Each project name can be specified as a single string value. If
57 further options need to be provided for a project, the project should be
60 **Project with no further options:**
65 **Project using options (see below):**
71 Do not use both types of declarations for a single project in your makefile.
78 Specifies the version of the project to retrieve.
79 This can be as loose as the major branch number or
80 as specific as a particular point release.
84 # Picks the latest release.
95 # Shorthand syntax for versions if no other options are to be specified
99 Note that version numbers should be enclosed in
100 quotes to ensure they are interpreted correctly
105 One or more patches to apply to this project. An array of URLs from which
106 each patch should be retrieved.
112 url: "http://drupal.org/files/issues/cal-760316-rfc-fixes-2.diff"
113 md5: "e4876228f449cb0c37ffa0f2142"
115 # shorthand syntax if no md5 checksum is specified
117 - "http://drupal.org/files/issues/adminrole_exceptions.patch"
118 - "http://drupal.org/files/issues/adminrole-213212-01.patch"
122 Place a project within a subdirectory of the `--contrib-destination`
123 specified. In the example below, `cck` will be placed in
124 `sites/all/modules/contrib` instead of the default `sites/all/modules`.
132 URL of an alternate project update XML server to use. Allows project XML data
133 to be retrieved from sites other than `updates.drupal.org`.
137 location: "http://code.developmentseed.com/fserver"
141 The project type. Must be provided if an update XML source is not specified
142 and/or using version control or direct retrieval for a project. May be one of
143 the following values: core, module, profile, theme.
151 Provide an alternative directory name for this project. By default, the
152 project name is used.
156 directory_name: "yourtheme"
160 Specific URL (can include tokens) to a translation. Allows translations to be
161 retrieved from l10n servers other than `localize.drupal.org`.
165 l10n_path: "http://myl10nserver.com/files/translations/%project-%core-%version-%language.po"
169 URL to an l10n server XML info file. Allows translations to be retrieved from
170 l10n servers other than `localize.drupal.org`.
174 l10n_url: "http://myl10nserver.com/l10n_server.xml"
178 Allows the project to be installed in a directory that is not empty.
179 If not specified this is treated as FALSE, Drush make sets an error when the directory is not empty.
180 If specified TRUE, Drush make will continue and use the existing directory.
181 Useful when adding extra files and folders to existing folders in libraries or module extensions.
189 Retrieve translations for the specified language, if available, for all projects.
197 Recursively build an included makefile. Defaults to 'true'.
203 Which type of tarball to download for profiles. Valid options include:
204 - 'full': complete distro including Drupal core, e.g. `distro_name-core.tar.gz`
205 - 'projects': the fully built profile, projects defined drupal-org.make, etc., e.g. `distro_name-no-core.tar.gz`
206 - 'profile-only' (just the bare profile, e.g. `distro_name.tar.gz`).
207 Defaults to 'profile-only'. When using 'projects', `do_recursion: false` will be necessary to avoid recursively making any makefiles included in the profile.
213 ### Project download options
215 Use an alternative download method instead of retrieval through update XML.
217 If no download type is specified, make defaults the type to
218 `git`. Additionally, if no url is specified, make defaults to use
221 The following methods are available:
223 - `download[type] = file`
225 Retrieve a project as a direct download. Options:
227 `url` - the URL of the file. Required.
228 The URL can also be a path to a local file either using the bare path or
229 the file:// protocol. The path may be absolute or relative to the makefile.
231 `md5`, `sha1`, `sha256`, or `sha512` - one or more checksums for the file. Optional.
233 `request_type` - the request type - get or post. post depends on
234 http://drupal.org/project/make_post. Optional.
236 `data` - The post data to be submitted with the request. Should be a
237 valid URL query string. Requires http://drupal.org/project/make_post. Optional.
239 `filename` - What to name the file, if it's not an archive. Optional.
241 `subtree` - if the download is an archive, only this subtree within the
242 archive will be copied to the target destination. Optional.
244 - `download[type] = copy`
246 Copies a project from a local folder. Options:
248 `url` - the URL of the folder. Required.
249 The URL must be a path to a local folder either using the bare path or
250 the file:// protocol. The path may be absolute or relative to the makefile.
252 projects[example][type] = "profile"
253 projects[example][download][type] = "copy"
254 projects[example][download][url] = "file://./example"
256 - `download[type] = bzr`
258 Use a bazaar repository as the source for this project. Options:
260 `url` - the URL of the repository. Required.
262 `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files
264 - `download[type] = git`
266 Use a git repository as the source for this project. Options:
268 `url` - the URL of the repository. Required.
270 `branch` - the branch to be checked out. Optional.
272 `revision` - a specific revision identified by commit to check
273 out. Optional. Note that it is recommended on use `branch` in
274 combination with `revision` if relying on the .info file rewriting.
276 `tag` - the tag to be checked out. Optional.
278 projects[mytheme][download][type] = "git"
279 projects[mytheme][download][url] = "git://github.com/jane_doe/mytheme.git"
281 `refspec` - the git reference to fetch and checkout. Optional.
283 If this is set, it will have priority over tag, revision and branch options.
285 `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files
287 - `download[type] = svn`
289 Use an SVN repository as the source for this project. Options:
291 `url` - the URL of the repository. Required.
293 `interactive` - whether to prompt the user for authentication credentials
294 when using a private repository. Allows username and/or password options to
295 be omitted. Optional.
297 `username` - the username to use when retrieving an SVN project as a working
298 copy or from a private repository. Optional.
300 `password` - the password to use when retrieving an SVN project as a working
301 copy or from a private repository. Optional.
307 url: "http://example.com/svnrepo/cool-theme/"
309 `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files
311 Shorthand for `download[url]` available for all download types:
315 download: "git://github.com/jane_doe/mytheme.git"
322 url: "git://github.com/jane_doe/mytheme.git"
326 An array of non-Drupal-specific libraries to be retrieved (e.g. js, PHP or other
327 Drupal-agnostic components). Each library should be specified as the key of an
328 array of options in the libraries array.
336 url: "http://jquery- ui.googlecode.com/files/jquery.ui-1.6.zip"
337 md5: "c177d38bc7af59d696b2efd7dda5c605"
342 Libraries share the `download`, `subdir`, and `directory_name` options with
343 projects. Additionally, they may specify a destination:
347 The target path to which this library should be moved. The path is relative to
348 that specified by the `--contrib-destination` option. By default, libraries
349 are placed in the `libraries` directory.
353 destination: "modules/contrib/jquery_ui"
358 An array of makefiles to include. Each include may be a local relative path to
359 the include makefile directory, a direct URL to the makefile, or from a git
360 repository. Includes are appended in order with the source makefile appended
361 last. As a result, values in the source makefile take precedence over those in
362 includes. Use `overrides` for the reverse order of precedence.
367 # Includes a file in the same directory.
369 # Includes a file with a relative path.
370 - "../example_relative/example_relative.make"
371 # A remote-hosted file.
372 - "http://www.example.com/remote.make"
373 # A file on a git repository.
374 - makefile: "example_dir/example.make"
377 url: "git@github.com:organisation/repository.git"
378 # Branch could be tag or revision, it relies on the standard Drush git download feature.
381 The `--includes` option is available for most make commands, and allows
382 makefiles to be included at build-time.
386 # Build from a production makefile, but add development and test projects.
387 $ drush make production.make --includes=dev.make,test.make
392 Similar to `includes`, `overrides` will include content from other makefiles.
393 However, the order of precedence is reversed. That is, they override the
394 keys/values of the source makefile.
396 The `--overrides` option is available for most make commands, and allows
397 overrides to be included at build-time.
401 #production.make.yml:
413 url: http://github.com/example/custom_feature_A.git
419 url: http://github.com/example/custom_feature_B.git
421 # Build production code-base.
422 $ drush make production.make.yml
431 branch: feature/new_feature
433 # Build production code-base using development/feature branches for custom code.
434 $ drush make /path/to/production.make --overrides=http://url/of/testing.make
439 If all projects or libraries have identical settings for a given
440 attribute, the `defaults` array can be used to specify these,
441 rather than specifying the attribute for each project.
445 # Specify common subdir of "contrib"
449 # Projects that don't specify subdir will go to the 'contrib' directory.
453 # Override a default value.
455 subdir: "development"
457 ### Overriding properties
459 Makefiles which include others may override the included makefiles properties.
460 Properties in the includer takes precedence over the includee.
478 # This line overrides the included makefile's 'subdir' option
481 # These lines overrides the included makefile, switching the download type
486 url: "http://git.drupal.org/project/views.git"
488 A project or library entry of an included makefile can be removed entirely by
489 setting the corresponding key to NULL:
491 # This line removes CCK entirely which was defined in base.make
498 If a project that is part of a build contains a `.make.yml` itself, Drush make will
499 automatically parse it and recurse into a derivative build.
501 For example, a full build tree may look something like this:
503 Drush make distro.make distro
507 - Foo bar install profile
508 + foobar.make.yml FOUND
513 - External library x.js
517 Recursion can be used to nest an install profile build in a Drupal site, easily
518 build multiple install profiles on the same site, fetch library dependencies
519 for a given module, or bundle a set of module and its dependencies together.
520 For Drush Make to recognize a makefile embedded within a project, the makefile
521 itself must have the same name as the project. For instance, the makefile
522 embedded within the managingnews profile must be called "managingnews.make". If
523 no makefile matching the project's name is found, Drush Make will look for a
524 "drupal-org.make.yml" makefile instead. The file must be in the project's root
525 directory. Subdirectories will be ignored.
527 **Build a full Drupal site with the Managing News install profile:**
535 ** Use a distribution as core **
544 This behavior can be overridden globally using the `--no-recursion` option, or on a project-by-project basis by setting the `do_recursion` project parameter to 'false' in a makefile:
558 Drush make also comes with testing capabilities, designed to test Drush make
559 itself. Writing a new test is extremely simple. The process is as follows:
561 1. Figure out what you want to test. Write a makefile that will test
562 this out. You can refer to existing test makefiles for
563 examples. These are located in `DRUSH/tests/makefiles`.
564 2. Drush make your makefile, and use the --md5 option. You may also use other
565 options, but be sure to take note of which ones for step 4.
566 3. Verify that the result you got was in fact what you expected. If so,
567 continue. If not, tweak it and re-run step 2 until it's what you expected.
568 4. Using the md5 hash that was spit out from step 2, make a new entry in the
569 tests clase (DRUSH/tests/makeTest.php), following the example below.
570 'machine-readable-name' => array(
571 'name' => 'Human readable name',
572 'makefile' => 'tests/yourtest.make',
574 'Build hash: f68e6510-your-hash-e04fbb4ed',
576 'options' => array('any' => TRUE, 'other' => TRUE, 'options' => TRUE),
578 5. Test! Run Drush test suite (see DRUSH/tests/README.md). To just
581 `./unish.sh --filter=makeMake .`
584 You can check for any messages you want in the message array, but the most
585 basic tests would just check the build hash.
590 Drush make has a primitive makefile generation capability. To use it, simply
591 change your directory to the Drupal installation from which you would like to
592 generate the file, and run the following command:
594 `drush generate-makefile /path/to/make-file.make`
596 This will generate a basic makefile. If you have code from other repositories,
597 the makefile will not complete - you'll have to fill in some information before
598 it is fully functional.
602 - Jonathan Hedstrom ([jhedstrom](https://www.drupal.org/u/jhedstrom))
603 - Christopher Gervais ([ergonlogic](http://drupal.org/u/ergonlogic))
604 - [The rest of the Drush maintainers](https://github.com/drush-ops/drush/graphs/contributors)
608 [Dmitri Gaskin (dmitrig01)](https://twitter.com/dmitrig01)