summaryrefslogtreecommitdiffstats
path: root/docs/make.txt
blob: a1cf183288105bf1756eb1979fa77a19104468a2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
Drush make
----------
Drush make is an extension to drush that can create a ready-to-use drupal site,
pulling sources from various locations. It does this by parsing a flat text file
(similar to a drupal `.info` file) and downloading the sources it describes. In
practical terms, this means that it is possible to distribute a complicated
Drupal distribution as a single text file.

Among drush make's capabilities are:

- Downloading Drupal core, as well as contrib modules from drupal.org.
- Checking code out from SVN, git, and bzr repositories.
- Getting plain `.tar.gz` and `.zip` files (particularly useful for libraries
  that can not be distributed directly with drupal core or modules).
- Fetching and applying patches.
- Fetching modules, themes, and installation profiles, but also external
  libraries.


Usage
-----
The `drush make` command can be executed from a path within a Drupal codebase or
independent of any Drupal sites entirely. See the examples below for instances
where `drush make` can be used within an existing Drupal site.

    drush make [-options] [filename.make] [build path]

The `.make` file format
-----------------------
Each makefile is a plain text file that adheres to the Drupal `.info` file
syntax. See the included `example.make` for an example of a working makefile.


### Core version

The make file always begins by specifying the core version of Drupal for which
 each package must be compatible. Example:

    core = 6.x


### API version

The make file must specify which Drush Make API version it uses. This version
of Drush Make uses API version `2`

    api = 2


### Projects

An array of the projects (e.g. modules, themes, libraries, and drupal) to be
retrieved. Each project name can be specified as a single string value. If
further options need to be provided for a project, the project should be
specified as the key.

**Project with no further options:**

    projects[] = drupal

**Project using options (see below):**

    projects[drupal][version] = 7.12

Do not use both types of declarations for a single project in your makefile.


### Project options

- `version`

  Specifies the version of the project to retrieve.
  This can be as loose as the major branch number or
  as specific as a particular point release.

        projects[views][version] = 3
        projects[views][version] = 2.8
        projects[views][version] = 3.0-alpha2

        ; Shorthand syntax for versions if no other options are to be specified
        projects[views] = 3.0-alpha2

- `patch`

  One or more patches to apply to this project. An array of URLs from which
  each patch should be retrieved.

        projects[calendar][patch][rfc-fixes][url] = "http://drupal.org/files/issues/cal-760316-rfc-fixes-2.diff"
        projects[calendar][patch][rfc-fixes][md5] = "e4876228f449cb0c37ffa0f2142"

        ; shorthand syntax if no md5 checksum is specified
        projects[adminrole][patch][] = "http://drupal.org/files/issues/adminrole_exceptions.patch"

- `subdir`

  Place a project within a subdirectory of the `--contrib-destination`
  specified. In the example below, `cck` will be placed in
  `sites/all/modules/contrib` instead of the default `sites/all/modules`.

        projects[cck][subdir] = "contrib"

- `location`

  URL of an alternate project update XML server to use. Allows project XML data
  to be retrieved from sites other than `updates.drupal.org`.

        projects[tao][location] = "http://code.developmentseed.com/fserver"

- `type`

  The project type. Must be provided if an update XML source is not specified
  and/or using version control or direct retrieval for a project. May be one of
  the following values: core, module, profile, theme.

        projects[mytheme][type] = "theme"

- `directory_name`

  Provide an alternative directory name for this project. By default, the
  project name is used.

        projects[mytheme][directory_name] = "yourtheme"

- `l10n_path`

  Specific URL (can include tokens) to a translation. Allows translations to be
  retrieved from l10n servers other than `localize.drupal.org`.

        projects[mytheme][l10n_path] = "http://myl10nserver.com/files/translations/%project-%core-%version-%language.po"

- `l10n_url`

  URL to an l10n server XML info file. Allows translations to be retrieved from
  l10n servers other than `localize.drupal.org`.

        projects[mytheme][l10n_url] = "http://myl10nserver.com/l10n_server.xml"

- `overwrite`

  Allows the project to be installed in a directory that is not empty.
  If not specified this is treated as FALSE, drush_make sets an error when the directory is not empty.
  If specified TRUE, drush_make will continue and use the existing directory.
  Useful when adding extra files and folders to existing folders in libraries or module extensions.

        projects[myproject][overwrite] = TRUE

- `translations`

  Retrieve translations for the specified language, if available, for all projects.

               translations[] = es


### Project download options

  Use an alternative download method instead of retrieval through update XML.

  If no download type is specified, make defaults the type to
  `git`. Additionally, if no url is specified, make defaults to use
  Drupal.org.

  The following methods are available:

- `download[type] = file`

  Retrieve a project as a direct download. Options:

  `url` - the URL of the file. Required.
          The URL can also be a path to a local file either using the bare path or
          the file:// protocol. The path may be absolute or relative to the makefile.

  `md5`, `sha1`, `sha256`, or `sha512` - one or more checksums for the file. Optional.

  `request_type` - the request type - get or post. post depends on
  http://drupal.org/project/make_post. Optional.

  `data` - The post data to be submitted with the request. Should be a
  valid URL query string. Requires http://drupal.org/project/make_post. Optional.

  `filename` - What to name the file, if it's not an archive. Optional.

  `subtree`  - if the download is an archive, only this subtree within the
  archive will be copied to the target destination. Optional.

- `download[type] = bzr`

  Use a bazaar repository as the source for this project. Options:

  `url` - the URL of the repository. Required.

  `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files

- `download[type] = git`

  Use a git repository as the source for this project. Options:

  `url` - the URL of the repository. Required.

  `branch` - the branch to be checked out. Optional.

  `revision` - a specific revision identified by commit to check
    out. Optional. Note that it is recommended on use `branch` in
    combination with `revision` if relying on the .info file rewriting.

  `tag` - the tag to be checked out. Optional.

     projects[mytheme][download][type] = "git"
     projects[mytheme][download][url] = "git://github.com/jane_doe/mytheme.git"

  `refspec` - the git reference to fetch and checkout. Optional.

     If this is set, it will have priority over tag, revision and branch options.

  `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files

- `download[type] = svn`

  Use an SVN repository as the source for this project. Options:

  `url` - the URL of the repository. Required.

  `interactive` - whether to prompt the user for authentication credentials
  when using a private repository. Allows username and/or password options to
  be omitted. Optional.

  `username` - the username to use when retrieving an SVN project as a working
  copy or from a private repository. Optional.

  `password` - the password to use when retrieving an SVN project as a working
  copy or from a private repository. Optional.

     projects[mytheme][download][type] = "svn"
     projects[mytheme][download][url] = "http://example.com/svnrepo/cool-theme/"

  `working-copy` - If true, the checked out source will be kept as a working copy rather than exported as standalone files

### Libraries

An array of non-Drupal-specific libraries to be retrieved (e.g. js, PHP or other
Drupal-agnostic components). Each library should be specified as the key of an
array of options in the libraries array.

**Example:**

    libraries[jquery_ui][download][type] = "file"
    libraries[jquery_ui][download][url] = "http://jquery- ui.googlecode.com/files/jquery.ui-1.6.zip"
    libraries[jquery_ui][download][md5] = "c177d38bc7af59d696b2efd7dda5c605"


### Library options

Libraries share the `download`, `subdir`, and `directory_name` options with
projects. Additionally, they may specify a destination:

- `destination`

  The target path to which this library should be moved. The path is relative to
  that specified by the `--contrib-destination` option. By default, libraries
  are placed in the `libraries` directory.

        libraries[jquery_ui][destination] = "modules/contrib/jquery_ui


### Includes

An array of makefiles to include. Each include may be a local relative path
to the includer makefile directory or a direct URL to the makefile. Includes
are appended in order with the source makefile appended last, allowing latter
makefiles to override the keys/values of former makefiles.

**Example:**

    includes[example] = "example.make"
    includes[example_relative] = "../example_relative/example_relative.make"
    includes[remote] = "http://www.example.com/remote.make"

### Defaults

If all projects or libraries have identical settings for a given
attribute, the `defaults` array can be used to specify these,
rather than specifying the attribute for each project.

**Example:**

    ; Specify common subdir of "contrib"
    defaults[projects][subdir] = "contrib"
    ; Projects that don't specify subdir will go to the 'contrib' directory.
    projects[views][version] = "3.3"
    ; Override default value
    projects[devel][subdir] = "development"

### Overriding properties

Makefiles which include others may override the included makefiles properties.
Properties in the includer takes precedence over the includee.

**Example:**

`base.make`

    core = "6.x"
    projects[views][subdir] = "contrib"
    projects[cck][subdir] = "contrib"

`extender.make`

    includes[base] = "base.make"

    ; This line overrides the included makefile's 'subdir' option
    projects[views][subdir] = "patched"

    ; This line overrides the included makefile, switching the download type
    ; to a git clone
    projects[views][type] = "module"
    projects[views][download][type] = "git"
    projects[views][download][url] = "http://git.drupal.org/project/views.git"

A project or library entry of an included makefile can be removed entirely by
setting the corresponding key to FALSE:

    ; This line removes CCK entirely which was defined in base.make
    projects[cck] = FALSE


Recursion
---------
If a project that is part of a build contains a `.make` itself, drush make will
automatically parse it and recurse into a derivative build.

For example, a full build tree may look something like this:

    drush make distro.make distro

    distro.make FOUND
    - Drupal core
    - Foo bar install profile
      + foobar.make FOUND
        - CCK
        - Token
        - Module x
          + x.make FOUND
            - External library x.js
        - Views
        - etc.

Recursion can be used to nest an install profile build in a Drupal site, easily
build multiple install profiles on the same site, fetch library dependencies
for a given module, or bundle a set of module and its dependencies together.
For Drush Make to recognize a makefile embedded within a project, the makefile
itself must have the same name as the project. For instance, the makefile
embedded within the managingnews profile must be called "managingnews.make".
The file should also be in the project's root directory. Subdirectories will
be ignored.

**Build a full Drupal site with the Managing News install profile:**

    core = 6.x
    projects[] = drupal
    projects[] = managingnews

** Use a distribution as core **

    core = 7.x
    projects[commerce_kickstart][type] = "core"
    projects[commerce_kickstart][version] = "7.x-1.19"

Testing
-------
Drush make also comes with testing capabilities, designed to test drush make
itself. Writing a new test is extremely simple. The process is as follows:

1. Figure out what you want to test. Write a makefile that will test
   this out.  You can refer to existing test makefiles for
   examples. These are located in `DRUSH/tests/makefiles`.
2. Drush make your makefile, and use the --md5 option. You may also use other
   options, but be sure to take note of which ones for step 4.
3. Verify that the result you got was in fact what you expected. If so,
   continue. If not, tweak it and re-run step 2 until it's what you expected.
4. Using the md5 hash that was spit out from step 2, make a new entry in the
   tests clase (DRUSH/tests/makeTest.php), following the example below.
    'machine-readable-name' => array(
      'name'     => 'Human readable name',
      'makefile' => 'tests/yourtest.make',
      'messages' => array(
          'Build hash: f68e6510-your-hash-e04fbb4ed',
      ),
      'options'  => array('any' => TRUE, 'other' => TRUE, 'options' => TRUE),
    ),
5. Test! Run drush test suite (see DRUSH/tests/README.txt). To just
   run the make tests:

     `phpunit --filter=makeMake .`


You can check for any messages you want in the message array, but the most
basic tests would just check the build hash.

Generate
--------

Drush make has a primitive makefile generation capability. To use it, simply
change your directory to the Drupal installation from which you would like to
generate the file, and run the following command:

`drush generate-makefile /path/to/make-file.make`

This will generate a basic makefile. If you have code from other repositories,
the makefile will not complete - you'll have to fill in some information before
it is fully functional.

Maintainers
-----------
- Jonathan Hedstrom (jhedstrom)
- The rest of the Drush maintainers

Original Author
---------------
Dmitri Gaskin (dmitrig01)