Lockfile Format¶
This document describes the lockfile format, which stores the result of concretizing an environment as JSON: the roots of the environment, and every concrete spec they depend on.
The current version of the format is v8, defined by spack.environment.environment.CURRENT_LOCKFILE_VERSION.
A lockfile is found in <environment>/spack.lock, next to the spack.yaml it was concretized from.
Structure¶
This section describes the current version of the format, v8. A lockfile holds the version of the format, the roots of the environment, and one node for each concrete spec:
{
"_meta": {
"file-type": "spack-lockfile",
"lockfile-version": 8,
"specfile-version": 6
},
"spack": {
"version": "1.3.0.dev0",
"type": "git",
"commit": "c7c444853d"
},
"roots": [
{"hash": "nic37xsihlqze3xyg3xd6pthcgqxoy6p", "spec": "zlib-ng"}
],
"concrete_specs": {
"nic37xsihlqze3xyg3xd6pthcgqxoy6p": {
"name": "zlib-ng",
"version": "2.3.3",
"provided_virtuals": ["zlib-api"],
"dependencies": [
{
"name": "gcc",
"hash": "26zpexhcroz5n23vbzm5ypre7tlfus2b",
"parameters": {"deptypes": ["build"], "virtuals": ["c", "cxx"]}
}
],
"annotations": {"original_specfile_version": 6},
"hash": "nic37xsihlqze3xyg3xd6pthcgqxoy6p"
}
}
}
To keep the example short, most keys of the node and the remaining nodes are not shown.
A lockfile is a dictionary with the following keys. The keys of previous versions are described in Version History.
_metafile-typeis alwaysspack-lockfile, andlockfile-versionis the version of the format.specfile-versionis the version of the spec file format of the nodes. It is informational, and is not used when the lockfile is read.spackThe version of Spack that wrote the lockfile.
typeisgitwhen Spack is run from a git repository, in which casecommitis also present, andreleaseotherwise.rootsThe roots of the environment, in order. Each entry has
spec, the abstract spec that was concretized, andhash, the DAG hash of the result. It also hasgroup, the group of the root, when the environment defines groups other than the default one.concrete_specsOne node dictionary for each node of the environment, keyed by DAG hash, as described in Spec File Format. For a spliced spec, the nodes of the build spec are also included.
include_concreteThe
rootsandconcrete_specsof each included concrete environment, keyed by the path of that environment. It is present only when the environment includes concrete environments, and it is nested when those include others.
Compatibility¶
A lockfile in an older version is converted only when the environment changes
Spack reads a lockfile in an older version without modifying it, and commands that do not change the roots or the concrete specs of the environment leave the file as it is.
A command that changes them, such as spack concretize after spack add, or that concretizes the roots again, writes the lockfile in the current version, after which older versions of Spack can no longer read it.
The properties below are defined in Versioned File Formats.
- Backward compatibility
Every version of Spack reads all the versions of the format up to its own. Lockfiles before version 4 are keyed by older hashes, and when Spack reads them it identifies each spec by its current DAG hash.
- Forward compatibility
None. Reading a version newer than the current one is an error.
- Rewrite policy
A lockfile is rewritten, in the current version, when a root is concretized, or when the roots, their hashes, their groups, or the included concrete environments differ from what was read. Lockfiles before version 4 are always rewritten on the next write, and a version 1 lockfile is copied to
spack.lock.backup.v1when it is read.
The following table lists the lockfile versions that each release of Spack can read:
Spack |
v1 |
v2 |
v3 |
v4 |
v5 |
v6 |
v7 |
v8 |
|---|---|---|---|---|---|---|---|---|
v0.12 |
✅ |
|||||||
v0.13 to v0.16 |
✅ |
✅ |
||||||
v0.17 |
✅ |
✅ |
✅ |
|||||
v0.18 to v0.20 |
✅ |
✅ |
✅ |
✅ |
||||
v0.21 to v0.23 |
✅ |
✅ |
✅ |
✅ |
✅ |
|||
v1.0 to v1.1 |
✅ |
✅ |
✅ |
✅ |
✅ |
✅ |
||
v1.2 |
✅ |
✅ |
✅ |
✅ |
✅ |
✅ |
✅ |
|
v1.3 (in development) |
✅ |
✅ |
✅ |
✅ |
✅ |
✅ |
✅ |
✅ |
Version History¶
The version is recorded in _meta.lockfile-version.
Each version of the lockfile is associated with one version of the spec file, which is used to read every node, including those in include_concrete.
- Version 8 (Spack v1.3)
Nodes are in spec file v6, which includes the virtuals provided by each node (#53012). A lockfile is rewritten only when its content changes (#53048). Up to Spack v1.2, every write of the environment rewrote the lockfile in the current version.
- Version 7 (Spack v1.2)
Roots have the
groupkey (#51891). The roots of a lockfile in an older version are assigned to the default group when they are read. Nodes are in spec file v5, as in version 6.- Version 6 (Spack v1.0)
Nodes are in spec file v5, where compilers are build dependencies (#45189).
- Version 5 (Spack v0.21)
Nodes are in spec file v4, where virtuals are recorded on the edges of the DAG (#34821). The
include_concretekey was added in Spack v0.22, without a new version (#33768).- Version 4 (Spack v0.18)
The build hash is removed (#28504). Nodes are in spec file v3, and are keyed by the DAG hash that includes build dependencies and the package hash. The
spackkey was added in Spack v0.20, without a new version (#32801).- Version 3 (Spack v0.17)
Nodes are in spec file v2 (#22845, #25879). They are keyed by build hash as in version 2, and their dependencies are referred to by
build_hash. The_meta.specfile-versionkey is added.- Version 2 (Spack v0.13)
Nodes are in spec file v1, as in version 1. They are keyed by build hash, and have a
hashkey with their DAG hash. Dependencies are referred to by DAG hash. Since installations are identified by the DAG hash, which at this time does not include build dependencies, a lockfile in version 2 or 3 can have several nodes with the same DAG hash. When Spack reads such a lockfile, it keeps the first of these nodes that is reached from the roots.- Version 1 (Spack v0.12)
Nodes are in spec file v1, and are keyed by the DAG hash, which includes only link and run dependencies. The nodes have no
hashkey.