www.aleph1.co.uk Git - yaffs-website/blob - vendor/drush/drush/docs/make.md

   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 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 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
  33 makefile.
  34
  35 The older Drupal `.info` INI format is also supported. See
  36 `examples/example.make` for a working example.
  37
  38 ### Core version
  39
  40 The make file always begins by specifying the core version of Drupal
  41 for which each package must be compatible. Example:
  42
  43     core: 7.x
  44
  45 ### API version
  46
  47 The make file must specify which Drush Make API version it uses. This version
  48 of Drush Make uses API version `2`
  49
  50     api: 2
  51
  52
  53 ### Projects
  54
  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
  58 specified as the key.
  59
  60 **Project with no further options:**
  61
  62     projects:
  63       - drupal
  64
  65 **Project using options (see below):**
  66
  67     projects:
  68       drupal:
  69         version: "7.33"
  70
  71 Do not use both types of declarations for a single project in your makefile.
  72
  73
  74 ### Project options
  75
  76 - `version`
  77
  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.
  81
  82         projects:
  83           views:
  84             # Picks the latest release.
  85             version: ~
  86
  87         projects:
  88           views:
  89             version: "2.8"
  90
  91         projects:
  92           views:
  93             version: "3.0-alpha2"
  94
  95         # Shorthand syntax for versions if no other options are to be specified
  96         projects:
  97           views: "3.0-alpha2"
  98
  99   Note that version numbers should be enclosed in
 100   quotes to ensure they are interpreted correctly
 101   by the YAML parser.
 102
 103 - `patch`
 104
 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.
 107
 108         projects:
 109           calendar:
 110             patch:
 111               rfc-fixes:
 112                 url: "http://drupal.org/files/issues/cal-760316-rfc-fixes-2.diff"
 113                 md5: "e4876228f449cb0c37ffa0f2142"
 114           adminrole:
 115             # shorthand syntax if no md5 checksum is specified
 116             patch:
 117               - "http://drupal.org/files/issues/adminrole_exceptions.patch"
 118               - "http://drupal.org/files/issues/adminrole-213212-01.patch"
 119               - "adminrole-customizations.patch"
 120
 121 - `subdir`
 122
 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`.
 126
 127         projects:
 128           cck:
 129             subdir: "contrib"
 130
 131 - `location`
 132
 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`.
 135
 136         projects:
 137           tao:
 138             location: "http://code.developmentseed.com/fserver"
 139
 140 - `type`
 141
 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.
 145
 146         projects:
 147           mytheme:
 148             type: "theme"
 149
 150 - `directory_name`
 151
 152   Provide an alternative directory name for this project. By default, the
 153   project name is used.
 154
 155         projects:
 156           mytheme:
 157             directory_name: "yourtheme"
 158
 159 - `l10n_path`
 160
 161   Specific URL (can include tokens) to a translation. Allows translations to be
 162   retrieved from l10n servers other than `localize.drupal.org`.
 163
 164         projects:
 165           mytheme:
 166             l10n_path: "http://myl10nserver.com/files/translations/%project-%core-%version-%language.po"
 167
 168 - `l10n_url`
 169
 170   URL to an l10n server XML info file. Allows translations to be retrieved from
 171   l10n servers other than `localize.drupal.org`.
 172
 173         projects:
 174           mytheme:
 175             l10n_url: "http://myl10nserver.com/l10n_server.xml"
 176
 177 - `overwrite`
 178
 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.
 183
 184         projects:
 185           myproject:
 186             overwrite: TRUE
 187
 188 - `translations`
 189
 190   Retrieve translations for the specified language, if available, for all projects.
 191
 192         translations:
 193           - es
 194           - fr
 195
 196 - `do_recursion`
 197
 198   Recursively build an included makefile. Defaults to 'true'.
 199
 200         do_recursion: false
 201
 202 - `variant`
 203
 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.
 209
 210         variant: projects
 211
 212
 213
 214 ### Project download options
 215
 216   Use an alternative download method instead of retrieval through update XML.
 217
 218   If no download type is specified, make defaults the type to
 219   `git`. Additionally, if no url is specified, make defaults to use
 220   Drupal.org.
 221
 222   The following methods are available:
 223
 224 - `download[type] = file`
 225
 226   Retrieve a project as a direct download. Options:
 227
 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.
 231
 232   `md5`, `sha1`, `sha256`, or `sha512` - one or more checksums for the file. Optional.
 233
 234   `request_type` - the request type - get or post. post depends on
 235   http://drupal.org/project/make_post. Optional.
 236
 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.
 239
 240   `filename` - What to name the file, if it's not an archive. Optional.
 241
 242   `subtree`  - if the download is an archive, only this subtree within the
 243   archive will be copied to the target destination. Optional.
 244
 245 - `download[type] = copy`
 246
 247   Copies a project from a local folder. Options:
 248
 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.
 252
 253      projects[example][type] = "profile"
 254      projects[example][download][type] = "copy"
 255      projects[example][download][url] = "file://./example"
 256
 257 - `download[type] = bzr`
 258
 259   Use a bazaar repository as the source for this project. Options:
 260
 261   `url` - the URL of the repository. Required.
 262
 263   `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files
 264
 265 - `download[type] = git`
 266
 267   Use a git repository as the source for this project. Options:
 268
 269   `url` - the URL of the repository. Required.
 270
 271   `branch` - the branch to be checked out. Optional.
 272
 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.
 276
 277   `tag` - the tag to be checked out. Optional.
 278
 279      projects[mytheme][download][type] = "git"
 280      projects[mytheme][download][url] = "git://github.com/jane_doe/mytheme.git"
 281
 282   `refspec` - the git reference to fetch and checkout. Optional.
 283
 284      If this is set, it will have priority over tag, revision and branch options.
 285
 286   `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files
 287
 288 - `download[type] = svn`
 289
 290   Use an SVN repository as the source for this project. Options:
 291
 292   `url` - the URL of the repository. Required.
 293
 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.
 297
 298   `username` - the username to use when retrieving an SVN project as a working
 299   copy or from a private repository. Optional.
 300
 301   `password` - the password to use when retrieving an SVN project as a working
 302   copy or from a private repository. Optional.
 303
 304      projects:
 305        mytheme:
 306          download:
 307            type: "svn"
 308            url: "http://example.com/svnrepo/cool-theme/"
 309
 310   `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files
 311
 312   Shorthand for `download[url]` available for all download types:
 313
 314      projects:
 315        mytheme:
 316          download: "git://github.com/jane_doe/mytheme.git"
 317
 318   is equivalent to:
 319
 320      projects:
 321        mytheme:
 322          download:
 323            url: "git://github.com/jane_doe/mytheme.git"
 324
 325 ### Libraries
 326
 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.
 330
 331 **Example:**
 332
 333     libraries:
 334       jquery_ui:
 335         download:
 336           type: "file"
 337           url: "http://jquery- ui.googlecode.com/files/jquery.ui-1.6.zip"
 338           md5: "c177d38bc7af59d696b2efd7dda5c605"
 339
 340
 341 ### Library options
 342
 343 Libraries share the `download`, `subdir`, and `directory_name` options with
 344 projects. Additionally, they may specify a destination:
 345
 346 - `destination`
 347
 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.
 351
 352         libraries:
 353           jquery_ui:
 354             destination: "modules/contrib/jquery_ui"
 355
 356
 357 ### Includes
 358
 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.
 364
 365 **Example:**
 366
 367     includes:
 368       # Includes a file in the same directory.
 369       - "example.make"
 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"
 376         download:
 377           type: "git"
 378           url: "git@github.com:organisation/repository.git"
 379           # Branch could be tag or revision, it relies on the standard Drush git download feature.
 380           branch: "master"
 381
 382 The `--includes` option is available for most make commands, and allows
 383 makefiles to be included at build-time.
 384
 385 **Example:**
 386
 387     # Build from a production makefile, but add development and test projects.
 388     $ drush make production.make --includes=dev.make,test.make
 389
 390
 391 ### Overrides
 392
 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.
 396
 397 The `--overrides` option is available for most make commands, and allows
 398 overrides to be included at build-time.
 399
 400 **Example:**
 401
 402     #production.make.yml:
 403     api: 2
 404     core: 8.x
 405     includes:
 406       - core.make
 407       - contrib.make
 408     projects:
 409       custom_feature_A:
 410         type: module
 411         download:
 412           branch: production
 413           type: git
 414           url: http://github.com/example/custom_feature_A.git
 415       custom_feature_B:
 416         type: module
 417         download:
 418           branch: production
 419           type: git
 420           url: http://github.com/example/custom_feature_B.git
 421
 422      # Build production code-base.
 423      $ drush make production.make.yml
 424
 425      #testing.make
 426      projects:
 427        custom_feature_A:
 428          download:
 429            branch: dev/bug_fix
 430        custom_feature_B:
 431          download:
 432            branch: feature/new_feature
 433
 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
 436
 437
 438 ### Defaults
 439
 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.
 443
 444 **Example:**
 445
 446     # Specify common subdir of "contrib"
 447     defaults:
 448       projects:
 449         subdir: "contrib"
 450     # Projects that don't specify subdir will go to the 'contrib' directory.
 451     projects:
 452       views:
 453         version: "3.3"
 454       # Override a default value.
 455       devel:
 456         subdir: "development"
 457
 458 ### Overriding properties
 459
 460 Makefiles which include others may override the included makefiles properties.
 461 Properties in the includer takes precedence over the includee.
 462
 463 **Example:**
 464
 465 `base.make`
 466
 467     core: "6.x"
 468       views:
 469         subdir: "contrib"
 470       cck:
 471         subdir: "contrib"
 472
 473 `extender.make`
 474
 475     includes:
 476       - "base.make"
 477     projects:
 478       views:
 479         # This line overrides the included makefile's 'subdir' option
 480         subdir: "patched"
 481
 482         # These lines overrides the included makefile, switching the download type
 483         # to a git clone.
 484         type: "module"
 485         download:
 486           type: "git"
 487           url: "http://git.drupal.org/project/views.git"
 488
 489 A project or library entry of an included makefile can be removed entirely by
 490 setting the corresponding key to NULL:
 491
 492       # This line removes CCK entirely which was defined in base.make
 493       cck: ~
 494
 495
 496 Recursion
 497 ---------
 498
 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.
 501
 502 For example, a full build tree may look something like this:
 503
 504     Drush make distro.make distro
 505
 506     distro.make FOUND
 507     - Drupal core
 508     - Foo bar install profile
 509       + foobar.make.yml FOUND
 510         - CCK
 511         - Token
 512         - Module x
 513           + x.make FOUND
 514             - External library x.js
 515         - Views
 516         - etc.
 517
 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.
 527
 528 **Build a full Drupal site with the Managing News install profile:**
 529
 530     core: 6.x
 531     api: 2
 532     projects:
 533       - drupal
 534       - managingnews
 535
 536 ** Use a distribution as core **
 537
 538     core: 7.x
 539     api: 2
 540     projects:
 541       commerce_kickstart:
 542         type: "core"
 543         version: "7.x-1.19"
 544
 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:
 546
 547     core: 7.x
 548     api: 2
 549     projects:
 550       drupal:
 551         type: core
 552       hostmaster:
 553         type: profile
 554         do_recursion: false
 555
 556
 557 Testing
 558 -------
 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:
 561
 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',
 574       'messages' => array(
 575           'Build hash: f68e6510-your-hash-e04fbb4ed',
 576       ),
 577       'options'  => array('any' => TRUE, 'other' => TRUE, 'options' => TRUE),
 578     ),
 579 5. Test! Run Drush test suite (see DRUSH/tests/README.md). To just
 580    run the make tests:
 581
 582      `./unish.sh --filter=makeMake .`
 583
 584
 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.
 587
 588 Generate
 589 --------
 590
 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:
 594
 595 `drush generate-makefile /path/to/make-file.make`
 596
 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.
 600
 601 Maintainers
 602 -----------
 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)
 606
 607 Original Author
 608 ---------------
 609 [Dmitri Gaskin (dmitrig01)](https://twitter.com/dmitrig01)