Skip to main content

Drupal versions

DRUPAL_VERSION sets the Drupal version that the build assembles. When it's unset, the build uses your project's default. This page covers building another version and how the build picks the versions of core and of every other dependency.

Build another version​

To build another version, set DRUPAL_VERSION before the build:

# Newest stable Drupal 11 release.
DRUPAL_VERSION=11 make build

# Newest Drupal 11.1.x patch release.
DRUPAL_VERSION=11.1.0 make build

# Newest Drupal 11 beta, release candidate or stable release.
DRUPAL_VERSION=11@beta make build

# Newest stable Drupal 12 release, or newest pre-release if none.
DRUPAL_VERSION=12 make build

To keep a version for every build, add a line such as DRUPAL_VERSION=11.1.0 to your project's .env file instead. A value in your shell wins over the one in .env, and an empty value counts as unset.

After you change the version, build the site again. You don't need reset first, because assemble rebuilds the codebase from scratch on every run.

The build picks the newest release that the value allows. A value with 3 numbers keeps its major and minor, so 11.1.0 and 11.1.5 both build the newest 11.1.x release. A value with 1 or 2 numbers keeps only its major. The build can't pin an exact patch release.

A pre-release is an alpha, a beta or a release candidate. A stability flag of @stable, @rc, @beta or @alpha lets pre-releases down to that stability qualify, as in 11@beta. The build rejects @dev and stops with "No Drupal release matches", because a development branch isn't a release.

The default version​

The default comes from extra.eddy.drupal-version in composer.dev.json:

"extra": {
    "eddy": {
        "drupal-version": "11"
    }
}

The installer sets it to the highest major you selected, up to 11, the newest major with a stable release. So selecting 10, 11 and 12 sets 11. When every major you selected is newer than 11, the installer sets the lowest of them. When neither DRUPAL_VERSION nor extra.eddy.drupal-version is set, the build uses Drupal 11.

How versions are resolved​

The build pins Drupal core to the newest release that matches DRUPAL_VERSION, and prints the release it picked. When no release on that line is stable enough, the build takes the newest pre-release on the line. So a major with no stable release still builds.

Every other dependency gets its most stable release that fits, because the build uses minimum-stability: dev with prefer-stable: true. A pre-release or a development branch goes in only when no stable release fits core, the other dependencies and the platform PHP. The build output lists every dependency it installed from a development branch. Each build picks up the newest releases that fit, so it follows new Drupal and tool releases with no edits to your project.

The PHP requirement​

Before it touches the build directory, the build checks its own PHP against the PHP requirement of the chosen core release. When the release needs a newer PHP, the build stops and prints the version the release needs. When the PHP fits, the build sets config.platform.php in build/composer.json to its own PHP, so a platform setting in your global Composer configuration has no effect.

To resolve for another PHP version on purpose, set config.platform.php in composer.dev.json or in your extension's composer.json. The build uses that version and checks it against the requirement too. When composer.dev.json and composer.json both set it, composer.dev.json wins.

What a version resolves to​

The following table shows the core release that each kind of value builds:

DRUPAL_VERSIONDrupal core
11The newest stable 11.x release.
11.1The newest stable 11.x release, the same as 11.
11.1.0The newest stable 11.1.x release.
11@betaThe newest 11.x release that's stable, a release candidate or a beta.
11@alphaThe same as 11@beta, with alphas too.
12The newest stable 12.x release, or the newest 12.x pre-release while 12.x has no stable release.
11@devNone: the build stops with "No Drupal release matches".

Drush resolves like any other dependency, so each build gets the most stable Drush that supports its core.

Drupal 12​

Drupal 12 requires PHP 8.5 or newer. To build Drupal 12, run the build on PHP 8.5 or newer:

DRUPAL_VERSION=12 make build

On an older PHP, the build stops before it changes anything (see The PHP requirement).

Until Drupal 12 has a stable release, DRUPAL_VERSION=12 builds its newest pre-release. After 12.0.0 ships, the same value builds the newest stable 12.x release.

A Drupal 12 build differs from the others in 3 ways:

  • It installs PHPUnit 12, which Drupal 12 core requires.
  • It installs drupal/core from source, because the Drupal 12 core packages leave out the test base classes and the PHPUnit bootstrap. The assembly takes a little longer as a result.
  • It installs Drush from its 14.x development branch until Drush tags any 14.x release, even an alpha.

In the installer, only Drupal 11 starts checked. Selecting Drupal 12 as well adds the following to your extension:

  • ^12 in core_version_requirement
  • The Drupal 12 CI jobs
  • The Drupal 12 README badge

The local build stays on Drupal 11 (see The default version). Continuous integration explains how the Drupal 12 jobs follow its releases. Upgrade a 4.x project to 5.x lists the changes your own code needs.