Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Build Result

Title: Build Result

Typecombining
RequiredNo
Additional propertiesAny type allowed

Description: This schema describes the JSON representation of Nix's BuildResult type, which represents the result of building a derivation or substituting store paths.

Build results can represent either successful builds (with built outputs) or various types of failures.

PropertyTypePatternTitle/Description
- timesBuiltintegerNoTimes built
- startTimeintegerNoStart time
- stopTimeintegerNoStop time
- cpuUserintegerNoUser CPU time
- cpuSystemintegerNoSystem CPU time

1. Property Successful Build Result

Title: Successful Build Result

Typeobject
RequiredNo
Additional propertiesAny type allowed
Defined in#/$defs/success

Description: Represents a successful build with built outputs.

PropertyTypePatternTitle/Description
+ successconstNoSuccess indicator
+ statusenum (of string)NoSuccess status
+ builtOutputsobjectNoBuilt outputs

1.1. Property success

Title: Success indicator

Typeconst
RequiredYes

Description: Always true for successful build results.

Specific value: true

1.2. Property status

Title: Success status

Typeenum (of string)
RequiredYes

Description: Status string for successful builds.

Must be one of:

  • "Built"
  • "Substituted"
  • "AlreadyValid"
  • "ResolvesToAlreadyValid"

1.3. Property builtOutputs

Title: Built outputs

Typeobject
RequiredYes
Additional propertiesEach additional property must conform to the schema

Description: A mapping from output names to their build trace entries.

PropertyTypePatternTitle/Description
- objectNoBuild Trace Entry

1.3.1. Property Build Trace Entry

Title: Build Trace Entry

Typecombining
RequiredNo
Additional propertiesEach additional property must conform to the schema
Defined inbuild-trace-entry-v2.yaml

Description: A record of a successful build outcome for a specific derivation output.

This schema describes the JSON representation of a build trace entry.

Warning

This JSON format is currently experimental and subject to change.

Verision history:

  • Version 1: Original format

  • Version 2: Remove dependentRealisations

PropertyTypePatternTitle/Description
+ idobjectNo-
+ outPathobjectNo-
+ signaturesobjectNo-
- objectNo-
All of(Requirement)
Build Trace Key
Build Trace Value
1.3.1.1. Property Build Trace Key

Title: Build Trace Key

Typeobject
RequiredNo
Additional propertiesAny type allowed
Defined in#/$defs/key

Description: A build trace entry is a key-value pair. This is the "key" part, refering to a derivation and output.

PropertyTypePatternTitle/Description
+ idstringNoDerivation Output ID
1.3.1.1.1. Property id

Title: Derivation Output ID

Typestring
RequiredYes

Description: Unique identifier for the derivation output that was built.

Format: {hash-quotient-drv}!{output-name}

Example: "sha256:ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad!foo"

Restrictions
Must match regular expression^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$ Test
1.3.1.2. Property Build Trace Value

Title: Build Trace Value

Typeobject
RequiredNo
Additional propertiesAny type allowed
Defined in#/$defs/value

Description: A build trace entry is a key-value pair. This is the "value" part, describing an output.

PropertyTypePatternTitle/Description
+ outPathstringNoOutput Store Path
+ signaturesarray of stringNoBuild Signatures
1.3.1.2.1. Property outPath

Title: Output Store Path

Typestring
RequiredYes
Defined instore-path-v1.yaml

Description: The path to the store object that resulted from building this derivation for the given output name.

Restrictions
Min length34
Must match regular expression^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+$ Test
1.3.1.2.2. Property signatures

Title: Build Signatures

Typearray of string
RequiredYes

Description: A set of cryptographic signatures attesting to the authenticity of this build trace entry.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
SignatureA single cryptographic signature
1.3.1.2.2.1. Signature

Title: Signature

Typestring
RequiredNo

Description: A single cryptographic signature

1.3.1.3. Property id
Typeobject
RequiredYes
Additional propertiesAny type allowed
1.3.1.4. Property outPath
Typeobject
RequiredYes
Additional propertiesAny type allowed
1.3.1.5. Property signatures
Typeobject
RequiredYes
Additional propertiesAny type allowed
1.3.1.6. Property additionalProperties
Typeobject
RequiredNo
Additional propertiesAny type allowed

2. Property Failed Build Result

Title: Failed Build Result

Typeobject
RequiredNo
Additional propertiesAny type allowed
Defined in#/$defs/failure

Description: Represents a failed build with error information.

PropertyTypePatternTitle/Description
+ successconstNoSuccess indicator
+ statusenum (of string)NoFailure status
+ errorMsgstringNoError message
- isNonDeterministicbooleanNoNon-deterministic flag

2.1. Property success

Title: Success indicator

Typeconst
RequiredYes

Description: Always false for failed build results.

Specific value: false

2.2. Property status

Title: Failure status

Typeenum (of string)
RequiredYes

Description: Status string for failed builds.

Must be one of:

  • "PermanentFailure"
  • "InputRejected"
  • "OutputRejected"
  • "TransientFailure"
  • "CachedFailure"
  • "TimedOut"
  • "MiscFailure"
  • "DependencyFailed"
  • "LogLimitExceeded"
  • "NotDeterministic"
  • "NoSubstituters"
  • "HashMismatch"

2.3. Property errorMsg

Title: Error message

Typestring
RequiredYes

Description: Information about the error if the build failed.

2.4. Property isNonDeterministic

Title: Non-deterministic flag

Typeboolean
RequiredNo

Description: If timesBuilt > 1, whether some builds did not produce the same result.

Note that 'isNonDeterministic = false' does not mean the build is deterministic, just that we don't have evidence of non-determinism.

3. The following properties are required

  • success
  • status

4. Property timesBuilt

Title: Times built

Typeinteger
RequiredNo

Description: How many times this build was performed.

Restrictions
Minimum≥ 0

5. Property startTime

Title: Start time

Typeinteger
RequiredNo

Description: The start time of the build (or one of the rounds, if it was repeated), as a Unix timestamp.

Restrictions
Minimum≥ 0

6. Property stopTime

Title: Stop time

Typeinteger
RequiredNo

Description: The stop time of the build (or one of the rounds, if it was repeated), as a Unix timestamp.

Restrictions
Minimum≥ 0

7. Property cpuUser

Title: User CPU time

Typeinteger
RequiredNo

Description: User CPU time the build took, in microseconds.

Restrictions
Minimum≥ 0

8. Property cpuSystem

Title: System CPU time

Typeinteger
RequiredNo

Description: System CPU time the build took, in microseconds.

Restrictions
Minimum≥ 0

Examples

Successful build

{
  "builtOutputs": {
    "bar": {
      "dependentRealisations": {},
      "id": "sha256:6f869f9ea2823bda165e06076fd0de4366dead2c0e8d2dbbad277d4f15c373f5!bar",
      "outPath": "g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-bar",
      "signatures": []
    },
    "foo": {
      "dependentRealisations": {},
      "id": "sha256:6f869f9ea2823bda165e06076fd0de4366dead2c0e8d2dbbad277d4f15c373f5!foo",
      "outPath": "g1w7hy3qg1w7hy3qg1w7hy3qg1w7hy3q-foo",
      "signatures": []
    }
  },
  "cpuSystem": 604000000,
  "cpuUser": 500000000,
  "startTime": 30,
  "status": "Built",
  "stopTime": 50,
  "success": true,
  "timesBuilt": 3
}

Failed build (output rejected)

{
  "errorMsg": "no idea why",
  "isNonDeterministic": false,
  "startTime": 30,
  "status": "OutputRejected",
  "stopTime": 50,
  "success": false,
  "timesBuilt": 3
}

Failed build (non-deterministic)

{
  "errorMsg": "no idea why",
  "isNonDeterministic": false,
  "startTime": 0,
  "status": "NotDeterministic",
  "stopTime": 0,
  "success": false,
  "timesBuilt": 1
}