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 patches,
106 each specified as a URL or local path relative to the makefile.
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"
119 - "adminrole-customizations.patch"
123 Place a project within a subdirectory of the `--contrib-destination`
124 specified. In the example below, `cck` will be placed in
125 `sites/all/modules/contrib` instead of the default `sites/all/modules`.
133 URL of an alternate project update XML server to use. Allows project XML data
134 to be retrieved from sites other than `updates.drupal.org`.
138 location: "http://code.developmentseed.com/fserver"
142 The project type. Must be provided if an update XML source is not specified
143 and/or using version control or direct retrieval for a project. May be one of
144 the following values: core, module, profile, theme.
152 Provide an alternative directory name for this project. By default, the
153 project name is used.
157 directory_name: "yourtheme"
161 Specific URL (can include tokens) to a translation. Allows translations to be
162 retrieved from l10n servers other than `localize.drupal.org`.
166 l10n_path: "http://myl10nserver.com/files/translations/%project-%core-%version-%language.po"
170 URL to an l10n server XML info file. Allows translations to be retrieved from
171 l10n servers other than `localize.drupal.org`.
175 l10n_url: "http://myl10nserver.com/l10n_server.xml"
179 Allows the project to be installed in a directory that is not empty.
180 If not specified this is treated as FALSE, Drush make sets an error when the directory is not empty.
181 If specified TRUE, Drush make will continue and use the existing directory.
182 Useful when adding extra files and folders to existing folders in libraries or module extensions.
190 Retrieve translations for the specified language, if available, for all projects.
198 Recursively build an included makefile. Defaults to 'true'.
204 Which type of tarball to download for profiles. Valid options include:
205 - 'full': complete distro including Drupal core, e.g. `distro_name-core.tar.gz`
206 - 'projects': the fully built profile, projects defined drupal-org.make, etc., e.g. `distro_name-no-core.tar.gz`
207 - 'profile-only' (just the bare profile, e.g. `distro_name.tar.gz`).
208 Defaults to 'profile-only'. When using 'projects', `do_recursion: false` will be necessary to avoid recursively making any makefiles included in the profile.
214 ### Project download options
216 Use an alternative download method instead of retrieval through update XML.
218 If no download type is specified, make defaults the type to
219 `git`. Additionally, if no url is specified, make defaults to use
222 The following methods are available:
224 - `download[type] = file`
226 Retrieve a project as a direct download. Options:
228 `url` - the URL of the file. Required.
229 The URL can also be a path to a local file either using the bare path or
230 the file:// protocol. The path may be absolute or relative to the makefile.
232 `md5`, `sha1`, `sha256`, or `sha512` - one or more checksums for the file. Optional.
234 `request_type` - the request type - get or post. post depends on
235 http://drupal.org/project/make_post. Optional.
237 `data` - The post data to be submitted with the request. Should be a
238 valid URL query string. Requires http://drupal.org/project/make_post. Optional.
240 `filename` - What to name the file, if it's not an archive. Optional.
242 `subtree` - if the download is an archive, only this subtree within the
243 archive will be copied to the target destination. Optional.
245 - `download[type] = copy`
247 Copies a project from a local folder. Options:
249 `url` - the URL of the folder. Required.
250 The URL must be a path to a local folder either using the bare path or
251 the file:// protocol. The path may be absolute or relative to the makefile.
253 projects[example][type] = "profile"
254 projects[example][download][type] = "copy"
255 projects[example][download][url] = "file://./example"
257 - `download[type] = bzr`
259 Use a bazaar repository as the source for this project. Options:
261 `url` - the URL of the repository. Required.
263 `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files
265 - `download[type] = git`
267 Use a git repository as the source for this project. Options:
269 `url` - the URL of the repository. Required.
271 `branch` - the branch to be checked out. Optional.
273 `revision` - a specific revision identified by commit to check
274 out. Optional. Note that it is recommended on use `branch` in
275 combination with `revision` if relying on the .info file rewriting.
277 `tag` - the tag to be checked out. Optional.
279 projects[mytheme][download][type] = "git"
280 projects[mytheme][download][url] = "git://github.com/jane_doe/mytheme.git"
282 `refspec` - the git reference to fetch and checkout. Optional.
284 If this is set, it will have priority over tag, revision and branch options.
286 `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files
288 - `download[type] = svn`
290 Use an SVN repository as the source for this project. Options:
292 `url` - the URL of the repository. Required.
294 `interactive` - whether to prompt the user for authentication credentials
295 when using a private repository. Allows username and/or password options to
296 be omitted. Optional.
298 `username` - the username to use when retrieving an SVN project as a working
299 copy or from a private repository. Optional.
301 `password` - the password to use when retrieving an SVN project as a working
302 copy or from a private repository. Optional.
308 url: "http://example.com/svnrepo/cool-theme/"
310 `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files
312 Shorthand for `download[url]` available for all download types:
316 download: "git://github.com/jane_doe/mytheme.git"
323 url: "git://github.com/jane_doe/mytheme.git"
327 An array of non-Drupal-specific libraries to be retrieved (e.g. js, PHP or other
328 Drupal-agnostic components). Each library should be specified as the key of an
329 array of options in the libraries array.
337 url: "http://jquery- ui.googlecode.com/files/jquery.ui-1.6.zip"
338 md5: "c177d38bc7af59d696b2efd7dda5c605"
343 Libraries share the `download`, `subdir`, and `directory_name` options with
344 projects. Additionally, they may specify a destination:
348 The target path to which this library should be moved. The path is relative to
349 that specified by the `--contrib-destination` option. By default, libraries
350 are placed in the `libraries` directory.
354 destination: "modules/contrib/jquery_ui"
359 An array of makefiles to include. Each include may be a local relative path to
360 the include makefile directory, a direct URL to the makefile, or from a git
361 repository. Includes are appended in order with the source makefile appended
362 last. As a result, values in the source makefile take precedence over those in
363 includes. Use `overrides` for the reverse order of precedence.
368 # Includes a file in the same directory.
370 # Includes a file with a relative path.
371 - "../example_relative/example_relative.make"
372 # A remote-hosted file.
373 - "http://www.example.com/remote.make"
374 # A file on a git repository.
375 - makefile: "example_dir/example.make"
378 url: "git@github.com:organisation/repository.git"
379 # Branch could be tag or revision, it relies on the standard Drush git download feature.
382 The `--includes` option is available for most make commands, and allows
383 makefiles to be included at build-time.
387 # Build from a production makefile, but add development and test projects.
388 $ drush make production.make --includes=dev.make,test.make
393 Similar to `includes`, `overrides` will include content from other makefiles.
394 However, the order of precedence is reversed. That is, they override the
395 keys/values of the source makefile.
397 The `--overrides` option is available for most make commands, and allows
398 overrides to be included at build-time.
402 #production.make.yml:
414 url: http://github.com/example/custom_feature_A.git
420 url: http://github.com/example/custom_feature_B.git
422 # Build production code-base.
423 $ drush make production.make.yml
432 branch: feature/new_feature
434 # Build production code-base using development/feature branches for custom code.
435 $ drush make /path/to/production.make --overrides=http://url/of/testing.make
440 If all projects or libraries have identical settings for a given
441 attribute, the `defaults` array can be used to specify these,
442 rather than specifying the attribute for each project.
446 # Specify common subdir of "contrib"
450 # Projects that don't specify subdir will go to the 'contrib' directory.
454 # Override a default value.
456 subdir: "development"
458 ### Overriding properties
460 Makefiles which include others may override the included makefiles properties.
461 Properties in the includer takes precedence over the includee.
479 # This line overrides the included makefile's 'subdir' option
482 # These lines overrides the included makefile, switching the download type
487 url: "http://git.drupal.org/project/views.git"
489 A project or library entry of an included makefile can be removed entirely by
490 setting the corresponding key to NULL:
492 # This line removes CCK entirely which was defined in base.make
499 If a project that is part of a build contains a `.make.yml` itself, Drush make will
500 automatically parse it and recurse into a derivative build.
502 For example, a full build tree may look something like this:
504 Drush make distro.make distro
508 - Foo bar install profile
509 + foobar.make.yml FOUND
514 - External library x.js
518 Recursion can be used to nest an install profile build in a Drupal site, easily
519 build multiple install profiles on the same site, fetch library dependencies
520 for a given module, or bundle a set of module and its dependencies together.
521 For Drush Make to recognize a makefile embedded within a project, the makefile
522 itself must have the same name as the project. For instance, the makefile
523 embedded within the managingnews profile must be called "managingnews.make". If
524 no makefile matching the project's name is found, Drush Make will look for a
525 "drupal-org.make.yml" makefile instead. The file must be in the project's root
526 directory. Subdirectories will be ignored.
528 **Build a full Drupal site with the Managing News install profile:**
536 ** Use a distribution as core **
545 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:
559 Drush make also comes with testing capabilities, designed to test Drush make
560 itself. Writing a new test is extremely simple. The process is as follows:
562 1. Figure out what you want to test. Write a makefile that will test
563 this out. You can refer to existing test makefiles for
564 examples. These are located in `DRUSH/tests/makefiles`.
565 2. Drush make your makefile, and use the --md5 option. You may also use other
566 options, but be sure to take note of which ones for step 4.
567 3. Verify that the result you got was in fact what you expected. If so,
568 continue. If not, tweak it and re-run step 2 until it's what you expected.
569 4. Using the md5 hash that was spit out from step 2, make a new entry in the
570 tests clase (DRUSH/tests/makeTest.php), following the example below.
571 'machine-readable-name' => array(
572 'name' => 'Human readable name',
573 'makefile' => 'tests/yourtest.make',
575 'Build hash: f68e6510-your-hash-e04fbb4ed',
577 'options' => array('any' => TRUE, 'other' => TRUE, 'options' => TRUE),
579 5. Test! Run Drush test suite (see DRUSH/tests/README.md). To just
582 `./unish.sh --filter=makeMake .`
585 You can check for any messages you want in the message array, but the most
586 basic tests would just check the build hash.
591 Drush make has a primitive makefile generation capability. To use it, simply
592 change your directory to the Drupal installation from which you would like to
593 generate the file, and run the following command:
595 `drush generate-makefile /path/to/make-file.make`
597 This will generate a basic makefile. If you have code from other repositories,
598 the makefile will not complete - you'll have to fill in some information before
599 it is fully functional.
603 - Jonathan Hedstrom ([jhedstrom](https://www.drupal.org/u/jhedstrom))
604 - Christopher Gervais ([ergonlogic](http://drupal.org/u/ergonlogic))
605 - [The rest of the Drush maintainers](https://github.com/drush-ops/drush/graphs/contributors)
609 [Dmitri Gaskin (dmitrig01)](https://twitter.com/dmitrig01)