Lockfile¶

A lockfile freezes the exact release of a TRM package and of its dependencies, so that installing it today or in six months gives the same result.

Why you need one¶

A package declares its dependencies as version ranges, for example ^1.0.0 (any 1.x.x release). When you install it, TRM picks the newest release in each range. That release changes over time: as soon as a dependency publishes 1.0.1, the next install receives 1.0.1 instead of 1.0.0.

Most of the time that is what you want. It isn't when the same installation must be repeated exactly:

• the system you tested on and the system you deliver to must get the same versions;
• a pipeline must install the same versions on every run;
• a customer must receive the combination you validated.

A lockfile records the versions installed on a reference system, together with a fingerprint of each release, and makes later installs use exactly those.

What a lockfile contains¶

A lockfile is a JSON file, named trm-lock.json by default:

{
  "lockfileVersion": 1,
  "source": "DEV",
  "name": "@acme/sales-tools",
  "version": "2.1.0",
  "registry": "public",
  "integrity": "<SHA-512 hash, base64>",
  "packages": [
    {
      "name": "@acme/core-utils",
      "version": "1.4.2",
      "registry": "public",
      "integrity": "<SHA-512 hash, base64>"
    }
  ]
}

A registry is recorded as public for the public TRM Registry, otherwise as its endpoint.

The integrity is a SHA-512 hash of the release file. If a release with the same name and version ever had different content, the hash would no longer match.

Generating a lockfile¶

Install the package and its dependencies on a reference system (typically the one you tested on), then run:

trm lock <package name> [output path]

TRM reads the versions installed on the connected system, not the newest ones in the registry: the lockfile describes the system as it is.

• A dependency that isn't installed on the system is left out, with a warning. Installs then treat it as unlocked (see below).
• A package with a dependency on a local .trm file can't be locked: the lockfile needs a registry to verify the release.
• If TRM can't find the integrity of an installed dependency, reinstall that dependency and try again. If it's the integrity of the package itself that is missing, the lockfile is generated without it and a warning is shown: reinstall the package to have its release verified too.

Keep the lockfile with your project, for example in the Git repository of the package, and regenerate it whenever you deliberately upgrade a dependency.

Installing with a lockfile¶

trm clean-install <package name> [version] --lock-file trm-lock.json

--lock-file defaults to trm-lock.json in the current folder.

For the package itself, TRM installs the release recorded in the lockfile:

• The package must be the one the lockfile was generated for. A lockfile generated for another package stops the install.
• The version comes from the lockfile. Leave the version out: TRM installs the locked version. If you pass a version (or a distribution tag such as latest) that resolves to a different release, the install stops; to install another release, install it on the reference system and regenerate the lockfile.
• The registry and the integrity are verified, when the lockfile records them. A release from another registry, or whose hash doesn't match, stops the install. Passing --integrity with a value other than the locked one stops it too.

These checks run before anything is changed on the system.

For every dependency, TRM:

1. Uses the locked version instead of the newest one in the range.
2. Checks that the locked version fits the range the package declares. If the package has moved to a new range since the lockfile was generated, the install stops: regenerate the lockfile.
3. Verifies the integrity. The release in the registry, and the file downloaded from it, must both match the hash in the lockfile. If they don't, the install stops with a security error before installing the dependency. Report it to the registry.
4. Replaces an installed dependency with a different version. If the system already has the dependency in a version other than the locked one, TRM installs the locked version. Replacing a newer version with an older one is a downgrade: TRM asks for confirmation (--allow-downgrade in pipelines).

A dependency that isn't in the lockfile is installed the usual way, from the newest release in its range.

💡 trm clean-install @acme/sales-tools --lock-file trm-lock.json is enough: the lockfile pins both the package and its dependencies. Passing the version explicitly (trm clean-install @acme/sales-tools 2.1.0) only adds a check that it is the locked one.

One version per system¶

An SAP system can hold only one version of a TRM package. If two packages on the same system need the same dependency, both must accept the version in the lockfile. When they don't, TRM stops before installing anything, and you have to choose a version that suits both packages. See What happens when two packages require incompatible versions of one dependency?

See also¶

• Install with a lockfile, a step-by-step example
• Dependencies
• Installing and updating a package