How to create and use a drush makefile

drush drupal

It is hard to imagine a tool as useful as drush make when automating updates or running continuous integration.drush make allows you to exactly replicate a site’s core and contrib code based on a single file. You can specify which patches to apply to contrib modules, if any. When a module is not version-pinned, it also allows you to update to the latest stable version automatically. You can even download modules from third-party sites, or from git or svn repositories.

This guide presumes that you have installed drush 8 and that drush command is somewhere in your path. Drush 8 has support for YAML makefiles, which we will be using in these examples. (It also has support for the older .ini makefile format used by drush 7 and below.) Drush 8 works great with both Drupal 7 and 8.

The official drush documentation is a good place to start reading if your questions aren’t answered here.

Generating a makefile for the first time from an existing site

Navigate to your Drupal docroot and run this command:

drush generate-makefile /path/to/sitename.make.yml

This will create sitename.make.yml as a YAML file. Now let’s open that file in an editor and take a look around. Note that only projects containing modules and themes that are enabled will be listed.

Structure of the makefile

There are several top-level properties in the YAML. The most commonly-encountered ones are coreapiprojects and libraries.

core and api

The core setting indicates which major version of Drupal your site is running (either 7 or 8). Do not edit this value unless you are upgrading and know exactly what you’re doing. The api setting indicates which drush api version the makefile is compatible with. Do not edit this value, ever.

projects

This section lists all the module and theme projects which drush make will build into your site. In order fordrush make to incorporate a project, it has to have at least one sub-entry. A newly-generated makefile will have a hardcoded version number for each project; if you wantdrush make to auto-update that module when it is run, you should remove the version tag altogether. On the other hand, if you need to pin the version of a module, or if you need to use an unstable version (such as a dev version), you should leave the version number in. Note that if in the future you need to update such projects, you will need to manually enter the updated version number in the makefile.

drush generate-makefile will helpfully add all your custom modules and themes as well, but you probably don’t want those in the makefile unless they live in their own git repository. For now I recommend removing them.

You’ll notice that the first project listed in a file generated bydrush generate-makefile is Drupal itself. If you want Drupal core to be auto-updated, or if you want to exclude Drupal core from thedrush make process, you should remove it here.

Each project can have one or more of the following attributes:

  • subdir: tells which subdirectory a module belongs in. A value of ‘contrib’ for example will cause the module to be located in sites/all/modules/contrib in Drupal 7, and in modules/contrib in Drupal 8.
  • version: tellsdrush make which version of the project to install.
  • type: either ‘theme’ or ‘module’
  • patch: an optional array of URLs to patches to apply to the project. If you have stored patches locally, you can reference them by absolute path, or by a path relative to the path of the makefile.
  • directory_name: name of the directory within the target subdir. If omitted, it will default to the name of the project.
  • download: an associative array of download options. Sub-options include:
    • type: may be ‘file’ (default), ‘git’, ‘svn’, etc.
    • url: If ‘type’ is file, this URL should point to the zipball or tarball containing the project. If ‘type’ is git or svn, it should be the URL of the repository.
    • revision: revision number or git commit, if ‘type’ was git or svn. If you specify revision, you must also specify branch.
    • branch: branch to clone from , if ‘type’ was git or svn
  • custom_download: a boolean value indicating whether this project cannot be downloaded from drupal.org. You can and probably should omit this key, though a makefile generated bydrush generate-makefile will include it.

libraries

This section lists things which should be installed into sites/all/libraries (in Drupal 7) or /libraries (in Drupal 8). Each library here can take the following keys:

  • destination: should be ‘libraries’ to store things in sites/all/libraries in Drupal 7, or /libraries in Drupal 8.
  • directory_name: the name of the directory in which the library should be stored, under the ‘destination’ directory.
  • download: structured the same way as the ‘download’ option under projects.
  • patch: structured the same way as the ‘patch’ option under projects.

Building with your makefile

To rebuild your entire site including Drupal core, you’d do this:

drush make /path/to/sitename.make.yml

To rebuild, omitting Drupal core:

drush make --no-core /path/to/sitename.make.yml

To build, placing all built projects and libraries in a profile’s subdirectory instead of sites/all:

drush make --contrib-destination=./profiles/myprofile /path/to/sitename.make.yml

There are many other command-line options you can pass todrush make, which are explained more thoroughly in the official documentation.