Project

General

Profile

Paste
Download (11.9 KB) Statistics
| Branch: | Revision:

root / .drush / drush_make / README.txt @ master

1
$Id: README.txt,v 1.1.2.19 2010/09/09 06:43:06 dmitrig01 Exp $
2

    
3
Drush make
4
----------
5
Drush make is an extension to drush that can create a ready-to-use drupal site,
6
pulling sources from various locations. It does this by parsing a flat text file
7
(similar to a drupal `.info` file) and downloading the sources it describes. In
8
practical terms, this means that it is possible to distribute a complicated
9
Drupal distribution as a single text file.
10

    
11
Among drush make's capabilities are:
12

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

    
21

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

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

    
30

    
31
### Options
32

    
33
    --contrib-destination=path
34

    
35
      Specify a path under which modules and themes should be
36
      placed. Defaults to sites/all.
37

    
38
    --force-complete
39

    
40
      Force a complete build even if errors occur.
41

    
42
    --md5
43

    
44
      Output an md5 hash of the current build after completion.
45

    
46
    --no-clean
47

    
48
      Leave temporary build directories in place instead of
49
      cleaning up after completion.
50

    
51
    --no-core
52

    
53
      Do not require a Drupal core project to be specified.
54

    
55
    --no-patch-txt
56

    
57
      Do not write a PATCHES.txt file in the directory of
58
      each patched project.
59

    
60
    --prepare-install
61

    
62
      Prepare the built site for installation. Generate a
63
      properly permissioned settings.php and files directory.
64

    
65
    --tar
66

    
67
      Generate a tar archive of the build. The output filename
68
      will be [build path].tar.gz.
69

    
70
    --test
71

    
72
      Run a temporary test build and clean up.
73

    
74
    --translations=languages
75

    
76
      Retrieve translations for the specified comma-separated list
77
      of language(s) if available for all projects.
78

    
79
    --working-copy
80

    
81
      Where possible, retrieve a working copy of projects from
82
      their respective repositories.
83

    
84

    
85
### Examples
86

    
87
1. Build a Drupal site at `example/` including Drupal core and any projects
88
   defined in the makefile:
89

    
90
        drush make example.make example
91

    
92
2. Build a tarball of the platform above as `example.tar.gz`:
93

    
94
        drush make --tar example.make example
95

    
96
3. Build an installation profile within an existing Drupal site:
97

    
98
        drush make --no-core --contrib-destination=. installprofile.make
99

    
100

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

    
106

    
107
### Core version
108

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

    
112
    core = 6.x
113

    
114

    
115
### Projects
116

    
117
An array of the projects to be retrieved. Each project name can be specified as
118
a single string value. If further options need to be provided for a project, the
119
project should be specified as the key.
120

    
121
**Project with no further options:**
122

    
123
    projects[] = drupal
124

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

    
127
    projects[drupal][version] = 6.15
128

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

    
131

    
132
### Project options
133

    
134
- `version`
135

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

    
140
        projects[views][version] = 3
141
        projects[views][version] = 2.8
142
        projects[views][version] = 3.0-alpha2
143

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

    
147
- `patch`
148

    
149
  One ore more patches to apply to this project. An array of URLs from which
150
  each patch should be retrieved.
151

    
152
        projects[adminrole][patch][] = "http://drupal.org/files/issues/adminrole_exceptions.patch"
153

    
154
- `subdir`
155

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

    
160
        projects[cck][subdir] = "contrib"
161

    
162
- `location`
163

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

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

    
169
- `type`
170

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

    
175
        projects[mytheme][type] = "theme"
176

    
177
- `directory_name`
178

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

    
182
        projects[mytheme][directory_name] = "yourtheme"
183

    
184
- `l10n_path`
185

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

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

    
191
- `l10n_url`
192

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

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

    
198

    
199
### Project download options
200

    
201
  Use an alternative download method instead of retrieval through update XML.
202
  The following methods are available:
203

    
204
- `download[type][get]`
205

    
206
  Retrieve a project as a direct download. Options:
207

    
208
  `url` - the URL of the file. Required.
209

    
210
- `download[type][post]`
211

    
212
  Retrieve a project as a direct download using an HTTP POST request. Options:
213

    
214
  `url` - the URL of the file. Required.
215

    
216
  `post_data` - The post data to be submitted with the request. Should be a
217
  valid URL query string. Required.
218

    
219
  `file_type` - A file type extension to use for the retrieved file. Optional.
220

    
221
     projects[mytheme][download][type] = "post"
222
     projects[mytheme][download][url] = "http://example.com/download/mytheme"
223
     projects[mytheme][download][post_data] = "format=zip&version=1.0"
224

    
225
- `download[type][bzr]`
226

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

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

    
231
- `download[type][cvs]`
232

    
233
  Use a CVS repository as the source for this project. Options:
234

    
235
  `date` - use the latest revision no later than specified date. See the CVS
236
  man page for more about how to use the date flag.
237

    
238
  `root` - the CVS repository to use for this project. Optional. If unspecified,
239
  the `CVSROOT` environment value will first be used and finally Drupal contrib
240
  CVS is used as a last resort fallback.
241

    
242
  `module` - the CVS module to retrieve. Required.
243

    
244
  `revision` - a specific tag or revision to check out. Optional.
245

    
246
     projects[mytheme][download][type] = "cvs"
247
     projects[mytheme][download][module] = "mytheme"
248

    
249
- `download[type][git]`
250

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

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

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

    
257
  `revision` - a specific revision identified by commit to check out. Optional.
258

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

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

    
264
- `download[type][svn]`
265

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

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

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

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

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

    
279

    
280
### Libraries
281

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

    
286
**Example:**
287

    
288
    libraries[jquery_ui][download][type] = "get"
289
    libraries[jquery_ui][download][url] = "http://jquery- ui.googlecode.com/files/jquery.ui-1.6.zip"
290

    
291

    
292
### Library options
293

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

    
297
- `destination`
298

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

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

    
305

    
306
### Includes
307

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

    
313
**Example:**
314

    
315
    includes[example] = "example.make"
316
    includes[remote] = "http://www.example.com/remote.make"
317

    
318

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

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

    
326
    drush make distro.make distro
327

    
328
    distro.make FOUND
329
    - Drupal core
330
    - Foo bar install profile
331
      + foobar.make FOUND
332
        - CCK
333
        - Token
334
        - Module x
335
          + x.make FOUND
336
            - External library x.js
337
        - Views
338
        - etc.
339

    
340
Recursion can be used to nest an install profile build in a Drupal site, easily
341
build multiple install profiles on the same site, fetch library dependencies for
342
a given module, or bundle a set of module and its dependencies together.
343

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

    
346
    core = 6.x
347
    projects[] = drupal
348
    projects[] = managingnews
349

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

    
355
1. Figure out what you want to test. Write a makefile that will test this out.
356
   You can refer to existing test makefiles for examples.
357
2. Drush make your makefile, and use the --md5 option. You may also use other
358
   options, but be sure to take note of which ones for step 4.
359
3. Verify that the result you got was in fact what you expected. If so,
360
   continue. If not, tweak it and re-run step 2 until it's what you expected.
361
4. Using the md5 hash that was spit out from step 2, make a new entry in the
362
   tests array in drush_make.test.inc, following the example below.
363
    'machine-readable-name' => array(
364
      'name'     => 'Human readable name',
365
      'makefile' => 'tests/yourtest.make',
366
      'messages' => array(
367
          'Build hash: f68e6510-your-hash-e04fbb4ed',
368
      ),
369
      'options'  => array('any' => TRUE, 'other' => TRUE, 'options' => TRUE),
370
    ),
371
5. Test! Run drush make-test machine-readable-name to see if the test passes.
372

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

    
376
Generate
377
--------
378

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

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

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

    
389
Maintainer
390
----------
391
- Dmitri Gaskin (dmitrig01)
392

    
393
Co-maintainers
394
------------
395
- Adrian Rossouw (adrian)
396
- Antoine Beaupré (anarcat)
397
- Chad Phillips (hunmonk)
398
- Jeff Miccolis (jmiccolis)
399
- Young Hahn (yhahn)