diff --git a/man/bst-artifact-checkout.1 b/man/bst-artifact-checkout.1 index 34b22c991..16e7b1217 100644 --- a/man/bst-artifact-checkout.1 +++ b/man/bst-artifact-checkout.1 @@ -1,4 +1,4 @@ -.TH "BST ARTIFACT CHECKOUT" "1" "2025-04-24" "2.5" "bst artifact checkout Manual" +.TH "BST ARTIFACT CHECKOUT" "1" "2025-05-09" "2.5" "bst artifact checkout Manual" .SH NAME bst\-artifact\-checkout \- Checkout contents of an artifact .SH SYNOPSIS @@ -7,9 +7,9 @@ bst\-artifact\-checkout \- Checkout contents of an artifact .SH DESCRIPTION Checkout contents of an artifact .PP -When this command is executed from a workspace directory, the default -is to checkout the artifact of the workspace element. -.PP + When this command is executed from a workspace directory, the default + is to checkout the artifact of the workspace element. + .SH OPTIONS .TP \fB\-f,\fP \-\-force diff --git a/man/bst-artifact-delete.1 b/man/bst-artifact-delete.1 index ea650ccb0..b4ddeb51f 100644 --- a/man/bst-artifact-delete.1 +++ b/man/bst-artifact-delete.1 @@ -1,4 +1,4 @@ -.TH "BST ARTIFACT DELETE" "1" "2025-04-24" "2.5" "bst artifact delete Manual" +.TH "BST ARTIFACT DELETE" "1" "2025-05-09" "2.5" "bst artifact delete Manual" .SH NAME bst\-artifact\-delete \- Remove artifacts from the local cache .SH SYNOPSIS diff --git a/man/bst-artifact-list-contents.1 b/man/bst-artifact-list-contents.1 index 86ea9a2c4..9a7d1ded3 100644 --- a/man/bst-artifact-list-contents.1 +++ b/man/bst-artifact-list-contents.1 @@ -1,4 +1,4 @@ -.TH "BST ARTIFACT LIST-CONTENTS" "1" "2025-04-24" "2.5" "bst artifact list-contents Manual" +.TH "BST ARTIFACT LIST-CONTENTS" "1" "2025-05-09" "2.5" "bst artifact list-contents Manual" .SH NAME bst\-artifact\-list-contents \- List the contents of an artifact .SH SYNOPSIS @@ -7,9 +7,9 @@ bst\-artifact\-list-contents \- List the contents of an artifact .SH DESCRIPTION List the contents of an artifact. .PP -Note that 'artifacts' can be element names, which must end in '.bst', -or artifact references, which must be in the format `//`. -.PP + Note that 'artifacts' can be element names, which must end in '.bst', + or artifact references, which must be in the format `//`. + .SH OPTIONS .TP \fB\-l,\fP \-\-long diff --git a/man/bst-artifact-log.1 b/man/bst-artifact-log.1 index abd09ebbc..a08fa69c3 100644 --- a/man/bst-artifact-log.1 +++ b/man/bst-artifact-log.1 @@ -1,4 +1,4 @@ -.TH "BST ARTIFACT LOG" "1" "2025-04-24" "2.5" "bst artifact log Manual" +.TH "BST ARTIFACT LOG" "1" "2025-05-09" "2.5" "bst artifact log Manual" .SH NAME bst\-artifact\-log \- Show logs of artifacts .SH SYNOPSIS diff --git a/man/bst-artifact-pull.1 b/man/bst-artifact-pull.1 index 239a3b3f2..1e9a9a44a 100644 --- a/man/bst-artifact-pull.1 +++ b/man/bst-artifact-pull.1 @@ -1,4 +1,4 @@ -.TH "BST ARTIFACT PULL" "1" "2025-04-24" "2.5" "bst artifact pull Manual" +.TH "BST ARTIFACT PULL" "1" "2025-05-09" "2.5" "bst artifact pull Manual" .SH NAME bst\-artifact\-pull \- Pull a built artifact .SH SYNOPSIS @@ -7,25 +7,25 @@ bst\-artifact\-pull \- Pull a built artifact .SH DESCRIPTION Pull a built artifact from the configured remote artifact cache. .PP -Specifying no elements will result in pulling the default targets -of the project. If no default targets are configured, all project -elements will be pulled. + Specifying no elements will result in pulling the default targets + of the project. If no default targets are configured, all project + elements will be pulled. .PP -When this command is executed from a workspace directory, the default -is to pull the workspace element. + When this command is executed from a workspace directory, the default + is to pull the workspace element. .PP -By default the artifact will be pulled one of the configured caches -if possible, following the usual priority order. If the `--artifact-remote` -flag is given, only the specified cache will be queried. + By default the artifact will be pulled one of the configured caches + if possible, following the usual priority order. If the `--artifact-remote` + flag is given, only the specified cache will be queried. .PP -Specify `--deps` to control which artifacts to pull: -.PP - - none: No dependencies, just the element itself - run: Runtime dependencies, including the element itself - build: Build time dependencies, excluding the element itself - all: All dependencies + Specify `--deps` to control which artifacts to pull: .PP +  + none: No dependencies, just the element itself + run: Runtime dependencies, including the element itself + build: Build time dependencies, excluding the element itself + all: All dependencies + .SH OPTIONS .TP \fB\-d,\fP \-\-deps [build|none|run|all] diff --git a/man/bst-artifact-push.1 b/man/bst-artifact-push.1 index 334b95ab7..7ed6544f3 100644 --- a/man/bst-artifact-push.1 +++ b/man/bst-artifact-push.1 @@ -1,4 +1,4 @@ -.TH "BST ARTIFACT PUSH" "1" "2025-04-24" "2.5" "bst artifact push Manual" +.TH "BST ARTIFACT PUSH" "1" "2025-05-09" "2.5" "bst artifact push Manual" .SH NAME bst\-artifact\-push \- Push a built artifact .SH SYNOPSIS @@ -7,25 +7,25 @@ bst\-artifact\-push \- Push a built artifact .SH DESCRIPTION Push built artifacts to a remote artifact cache, possibly pulling them first. .PP -Specifying no elements will result in pushing the default targets -of the project. If no default targets are configured, all project -elements will be pushed. + Specifying no elements will result in pushing the default targets + of the project. If no default targets are configured, all project + elements will be pushed. .PP -When this command is executed from a workspace directory, the default -is to push the workspace element. + When this command is executed from a workspace directory, the default + is to push the workspace element. .PP -If bst has been configured to include build trees on artifact pulls, -an attempt will be made to pull any required build trees to avoid the -skipping of partial artifacts being pushed. + If bst has been configured to include build trees on artifact pulls, + an attempt will be made to pull any required build trees to avoid the + skipping of partial artifacts being pushed. .PP -Specify `--deps` to control which artifacts to push: -.PP - - none: No dependencies, just the element itself - run: Runtime dependencies, including the element itself - build: Build time dependencies, excluding the element itself - all: All dependencies + Specify `--deps` to control which artifacts to push: .PP +  + none: No dependencies, just the element itself + run: Runtime dependencies, including the element itself + build: Build time dependencies, excluding the element itself + all: All dependencies + .SH OPTIONS .TP \fB\-d,\fP \-\-deps [build|none|run|all] diff --git a/man/bst-artifact-show.1 b/man/bst-artifact-show.1 index 7d1fa4223..ad4334e2f 100644 --- a/man/bst-artifact-show.1 +++ b/man/bst-artifact-show.1 @@ -1,4 +1,4 @@ -.TH "BST ARTIFACT SHOW" "1" "2025-04-24" "2.5" "bst artifact show Manual" +.TH "BST ARTIFACT SHOW" "1" "2025-05-09" "2.5" "bst artifact show Manual" .SH NAME bst\-artifact\-show \- Show the cached state of artifacts .SH SYNOPSIS diff --git a/man/bst-artifact.1 b/man/bst-artifact.1 index 9086a0313..aced3c2a3 100644 --- a/man/bst-artifact.1 +++ b/man/bst-artifact.1 @@ -1,4 +1,4 @@ -.TH "BST ARTIFACT" "1" "2025-04-24" "2.5" "bst artifact Manual" +.TH "BST ARTIFACT" "1" "2025-05-09" "2.5" "bst artifact Manual" .SH NAME bst\-artifact \- Manipulate cached artifacts. .SH SYNOPSIS @@ -7,34 +7,34 @@ bst\-artifact \- Manipulate cached artifacts. .SH DESCRIPTION Manipulate cached artifacts .PP -Some subcommands take artifact references as arguments. Artifacts -can be specified in two ways: + Some subcommands take artifact references as arguments. Artifacts + can be specified in two ways: .PP - -- artifact refs: triples of the form // -- element names +  + - artifact refs: triples of the form // + - element names .PP -When elements are given, the artifact is looked up by observing the element -and it's current cache key. + When elements are given, the artifact is looked up by observing the element + and it's current cache key. .PP -The commands also support shell-style wildcard expansion: `?` matches a -single character, `*` matches zero or more characters but does not match the `/` -path separator, and `**` matches zero or more characters including `/` path separators. + The commands also support shell-style wildcard expansion: `?` matches a + single character, `*` matches zero or more characters but does not match the `/` + path separator, and `**` matches zero or more characters including `/` path separators. .PP -If the wildcard expression ends with `.bst`, then it will be used to search -element names found in the project, otherwise, it will be used to search artifacts -that are present in the local artifact cache. + If the wildcard expression ends with `.bst`, then it will be used to search + element names found in the project, otherwise, it will be used to search artifacts + that are present in the local artifact cache. .PP -Some example arguments are: -.PP - -- `myproject/hello/8276376b077eda104c812e6ec2f488c7c9eea211ce572c83d734c10bf241209f` -- `myproject/he*/827637*` -- `core/*.bst` (all elements in the core directory) -- `**.bst` (all elements) -- `myproject/**` (all artifacts from myproject) -- `myproject/myelement/*` (all cached artifacts for a specific element) + Some example arguments are: .PP +  + - `myproject/hello/8276376b077eda104c812e6ec2f488c7c9eea211ce572c83d734c10bf241209f` + - `myproject/he*/827637*` + - `core/*.bst` (all elements in the core directory) + - `**.bst` (all elements) + - `myproject/**` (all artifacts from myproject) + - `myproject/myelement/*` (all cached artifacts for a specific element) + .SH COMMANDS .PP \fBshow\fP diff --git a/man/bst-build.1 b/man/bst-build.1 index 86c826596..d212e6678 100644 --- a/man/bst-build.1 +++ b/man/bst-build.1 @@ -1,4 +1,4 @@ -.TH "BST BUILD" "1" "2025-04-24" "2.5" "bst build Manual" +.TH "BST BUILD" "1" "2025-05-09" "2.5" "bst build Manual" .SH NAME bst\-build \- Build elements in a pipeline .SH SYNOPSIS @@ -7,23 +7,23 @@ bst\-build \- Build elements in a pipeline .SH DESCRIPTION Build elements in a pipeline .PP -Specifying no elements will result in building the default targets -of the project. If no default targets are configured, all project -elements will be built. + Specifying no elements will result in building the default targets + of the project. If no default targets are configured, all project + elements will be built. .PP -When this command is executed from a workspace directory, the default -is to build the workspace element. + When this command is executed from a workspace directory, the default + is to build the workspace element. .PP -Specify `--deps` to control which dependencies must be built: + Specify `--deps` to control which dependencies must be built: .PP - - none: No dependencies, just the element itself - build: Build time dependencies, excluding the element itself - all: All dependencies -.PP -Dependencies that are consequently required to build the requested -elements will be built on demand. +  + none: No dependencies, just the element itself + build: Build time dependencies, excluding the element itself + all: All dependencies .PP + Dependencies that are consequently required to build the requested + elements will be built on demand. + .SH OPTIONS .TP \fB\-d,\fP \-\-deps [none|build|all] diff --git a/man/bst-help.1 b/man/bst-help.1 index e475127ce..a44c9424e 100644 --- a/man/bst-help.1 +++ b/man/bst-help.1 @@ -1,4 +1,4 @@ -.TH "BST HELP" "1" "2025-04-24" "2.5" "bst help Manual" +.TH "BST HELP" "1" "2025-05-09" "2.5" "bst help Manual" .SH NAME bst\-help \- Print usage information .SH SYNOPSIS diff --git a/man/bst-init.1 b/man/bst-init.1 index 80d2f3251..d81fd721d 100644 --- a/man/bst-init.1 +++ b/man/bst-init.1 @@ -1,4 +1,4 @@ -.TH "BST INIT" "1" "2025-04-24" "2.5" "bst init Manual" +.TH "BST INIT" "1" "2025-05-09" "2.5" "bst init Manual" .SH NAME bst\-init \- Initialize a new BuildStream project .SH SYNOPSIS @@ -7,12 +7,12 @@ bst\-init \- Initialize a new BuildStream project .SH DESCRIPTION Initialize a new BuildStream project .PP -Creates a new BuildStream project.conf in the project -directory. -.PP -Unless `--project-name` is specified, this will be an -interactive session. + Creates a new BuildStream project.conf in the project + directory. .PP + Unless `--project-name` is specified, this will be an + interactive session. + .SH OPTIONS .TP \fB\-\-project\-name\fP TEXT diff --git a/man/bst-shell.1 b/man/bst-shell.1 index 50bfa25d9..de08a2607 100644 --- a/man/bst-shell.1 +++ b/man/bst-shell.1 @@ -1,4 +1,4 @@ -.TH "BST SHELL" "1" "2025-04-24" "2.5" "bst shell Manual" +.TH "BST SHELL" "1" "2025-05-09" "2.5" "bst shell Manual" .SH NAME bst\-shell \- Shell into an element's sandbox environment .SH SYNOPSIS @@ -7,25 +7,25 @@ bst\-shell \- Shell into an element's sandbox environment .SH DESCRIPTION Run a command in the target element's sandbox environment .PP -When this command is executed from a workspace directory, the default -is to shell into the workspace element. + When this command is executed from a workspace directory, the default + is to shell into the workspace element. .PP -This will stage a temporary sysroot for running the target -element, assuming it has already been built and all required -artifacts are in the local cache. + This will stage a temporary sysroot for running the target + element, assuming it has already been built and all required + artifacts are in the local cache. .PP -Use '--' to separate a command from the options to bst, -otherwise bst may respond to them instead. e.g. + Use '--' to separate a command from the options to bst, + otherwise bst may respond to them instead. e.g. .PP - - bst shell example.bst -- df -h +  + bst shell example.bst -- df -h .PP -Use the --build option to create a temporary sysroot for -building the element instead. -.PP -If no COMMAND is specified, the default is to attempt -to run an interactive shell. + Use the --build option to create a temporary sysroot for + building the element instead. .PP + If no COMMAND is specified, the default is to attempt + to run an interactive shell. + .SH OPTIONS .TP \fB\-b,\fP \-\-build diff --git a/man/bst-show.1 b/man/bst-show.1 index 1524d18d1..95facd13f 100644 --- a/man/bst-show.1 +++ b/man/bst-show.1 @@ -1,4 +1,4 @@ -.TH "BST SHOW" "1" "2025-04-24" "2.5" "bst show Manual" +.TH "BST SHOW" "1" "2025-05-09" "2.5" "bst show Manual" .SH NAME bst\-show \- Show elements in the pipeline .SH SYNOPSIS @@ -7,60 +7,61 @@ bst\-show \- Show elements in the pipeline .SH DESCRIPTION Show elements in the pipeline .PP -Specifying no elements will result in showing the default targets -of the project. If no default targets are configured, all project -elements will be shown. + Specifying no elements will result in showing the default targets + of the project. If no default targets are configured, all project + elements will be shown. .PP -When this command is executed from a workspace directory, the default -is to show the workspace element. + When this command is executed from a workspace directory, the default + is to show the workspace element. .PP -By default this will show all of the dependencies of the -specified target element. + By default this will show all of the dependencies of the + specified target element. .PP -Specify ``--deps`` to control which elements to show: + Specify ``--deps`` to control which elements to show: .PP - - none: No dependencies, just the element itself - run: Runtime dependencies, including the element itself - build: Build time dependencies, excluding the element itself - all: All dependencies +  + none: No dependencies, just the element itself + run: Runtime dependencies, including the element itself + build: Build time dependencies, excluding the element itself + all: All dependencies .PP -**FORMAT** + **FORMAT** .PP -The ``--format`` option controls what should be printed for each element, -the following symbols can be used in the format string: + The ``--format`` option controls what should be printed for each element, + the following symbols can be used in the format string: .PP - - %{name} The element name - %{description} The element description, on a single line (Since: 2.3) - %{key} The abbreviated cache key (if all sources are consistent) - %{full-key} The full cache key (if all sources are consistent) - %{state} cached, buildable, waiting, inconsistent or junction - %{config} The element configuration - %{vars} Variable configuration - %{env} Environment settings - %{public} Public domain data - %{workspaced} If the element is workspaced - %{workspace-dirs} A list of workspace directories - %{deps} A list of all dependencies - %{build-deps} A list of build dependencies - %{runtime-deps} A list of runtime dependencies - %{source-info} Source provenance information +  + %{name} The element name + %{description} The element description, on a single line (Since: 2.3) + %{key} The abbreviated cache key (if all sources are consistent) + %{full-key} The full cache key (if all sources are consistent) + %{state} cached, buildable, waiting, inconsistent or junction + %{config} The element configuration + %{vars} Variable configuration + %{env} Environment settings + %{public} Public domain data + %{workspaced} If the element is workspaced + %{workspace-dirs} A list of workspace directories + %{deps} A list of all dependencies + %{build-deps} A list of build dependencies + %{runtime-deps} A list of runtime dependencies + %{source-info} Source provenance information + %{artifact-cas-digest} The CAS digest of the built artifact .PP -The value of the %{symbol} without the leading '%' character is understood -as a pythonic formatting string, so python formatting features apply, -example: + The value of the %{symbol} without the leading '%' character is understood + as a pythonic formatting string, so python formatting features apply, + example: .PP - - bst show target.bst --format \ - 'Name: %{name: ^20} Key: %{key: ^8} State: %{state}' +  + bst show target.bst --format \ + 'Name: %{name: ^20} Key: %{key: ^8} State: %{state}' .PP -If you want to use a newline in a format string in bash, use the '$' modifier: -.PP - - bst show target.bst --format \ - $'---------- %{name} ----------\n%{vars}' + If you want to use a newline in a format string in bash, use the '$' modifier: .PP +  + bst show target.bst --format \ + $'---------- %{name} ----------\n%{vars}' + .SH OPTIONS .TP \fB\-\-except\fP PATH diff --git a/man/bst-source-checkout.1 b/man/bst-source-checkout.1 index 190b54b78..1124b75a2 100644 --- a/man/bst-source-checkout.1 +++ b/man/bst-source-checkout.1 @@ -1,4 +1,4 @@ -.TH "BST SOURCE CHECKOUT" "1" "2025-04-24" "2.5" "bst source checkout Manual" +.TH "BST SOURCE CHECKOUT" "1" "2025-05-09" "2.5" "bst source checkout Manual" .SH NAME bst\-source\-checkout \- Checkout sources of an element .SH SYNOPSIS @@ -7,9 +7,9 @@ bst\-source\-checkout \- Checkout sources of an element .SH DESCRIPTION Checkout sources of an element to the specified location .PP -When this command is executed from a workspace directory, the default -is to checkout the sources of the workspace element. -.PP + When this command is executed from a workspace directory, the default + is to checkout the sources of the workspace element. + .SH OPTIONS .TP \fB\-f,\fP \-\-force diff --git a/man/bst-source-fetch.1 b/man/bst-source-fetch.1 index 258dab668..3283804bd 100644 --- a/man/bst-source-fetch.1 +++ b/man/bst-source-fetch.1 @@ -1,4 +1,4 @@ -.TH "BST SOURCE FETCH" "1" "2025-04-24" "2.5" "bst source fetch Manual" +.TH "BST SOURCE FETCH" "1" "2025-05-09" "2.5" "bst source fetch Manual" .SH NAME bst\-source\-fetch \- Fetch sources in a pipeline .SH SYNOPSIS @@ -7,24 +7,24 @@ bst\-source\-fetch \- Fetch sources in a pipeline .SH DESCRIPTION Fetch sources required to build the pipeline .PP -Specifying no elements will result in fetching the default targets -of the project. If no default targets are configured, all project -elements will be fetched. + Specifying no elements will result in fetching the default targets + of the project. If no default targets are configured, all project + elements will be fetched. .PP -When this command is executed from a workspace directory, the default -is to fetch the workspace element. + When this command is executed from a workspace directory, the default + is to fetch the workspace element. .PP -By default this will only try to fetch sources for the specified -elements. + By default this will only try to fetch sources for the specified + elements. .PP -Specify `--deps` to control which sources to fetch: -.PP - - none: No dependencies, just the element itself - run: Runtime dependencies, including the element itself - build: Build time dependencies, excluding the element itself - all: All dependencies + Specify `--deps` to control which sources to fetch: .PP +  + none: No dependencies, just the element itself + run: Runtime dependencies, including the element itself + build: Build time dependencies, excluding the element itself + all: All dependencies + .SH OPTIONS .TP \fB\-\-except\fP PATH diff --git a/man/bst-source-push.1 b/man/bst-source-push.1 index 6a71818e7..d1c15de6c 100644 --- a/man/bst-source-push.1 +++ b/man/bst-source-push.1 @@ -1,4 +1,4 @@ -.TH "BST SOURCE PUSH" "1" "2025-04-24" "2.5" "bst source push Manual" +.TH "BST SOURCE PUSH" "1" "2025-05-09" "2.5" "bst source push Manual" .SH NAME bst\-source\-push \- Push sources in a pipeline .SH SYNOPSIS @@ -7,24 +7,24 @@ bst\-source\-push \- Push sources in a pipeline .SH DESCRIPTION Push sources required to build the pipeline .PP -Specifying no elements will result in pushing the sources of the default -targets of the project. If no default targets are configured, sources of -all project elements will be pushed. + Specifying no elements will result in pushing the sources of the default + targets of the project. If no default targets are configured, sources of + all project elements will be pushed. .PP -When this command is executed from a workspace directory, the default -is to push the sources of the workspace element. + When this command is executed from a workspace directory, the default + is to push the sources of the workspace element. .PP -By default this will only try to push sources for the specified -elements. + By default this will only try to push sources for the specified + elements. .PP -Specify `--deps` to control which sources to fetch: -.PP - - none: No dependencies, just the element itself - run: Runtime dependencies, including the element itself - build: Build time dependencies, excluding the element itself - all: All dependencies + Specify `--deps` to control which sources to fetch: .PP +  + none: No dependencies, just the element itself + run: Runtime dependencies, including the element itself + build: Build time dependencies, excluding the element itself + all: All dependencies + .SH OPTIONS .TP \fB\-\-except\fP PATH diff --git a/man/bst-source-track.1 b/man/bst-source-track.1 index fdcd2ad5e..c493fad58 100644 --- a/man/bst-source-track.1 +++ b/man/bst-source-track.1 @@ -1,4 +1,4 @@ -.TH "BST SOURCE TRACK" "1" "2025-04-24" "2.5" "bst source track Manual" +.TH "BST SOURCE TRACK" "1" "2025-05-09" "2.5" "bst source track Manual" .SH NAME bst\-source\-track \- Track new source references .SH SYNOPSIS @@ -6,26 +6,26 @@ bst\-source\-track \- Track new source references [OPTIONS] [ELEMENTS]... .SH DESCRIPTION Consults the specified tracking branches for new versions available -to build and updates the project with any newly available references. + to build and updates the project with any newly available references. .PP -Specifying no elements will result in tracking the default targets -of the project. If no default targets are configured, all project -elements will be tracked. + Specifying no elements will result in tracking the default targets + of the project. If no default targets are configured, all project + elements will be tracked. .PP -When this command is executed from a workspace directory, the default -is to track the workspace element. + When this command is executed from a workspace directory, the default + is to track the workspace element. .PP -If no default is declared, all elements in the project will be tracked + If no default is declared, all elements in the project will be tracked .PP -By default this will track just the specified element, but you can also -update a whole tree of dependencies in one go. + By default this will track just the specified element, but you can also + update a whole tree of dependencies in one go. .PP -Specify `--deps` to control which sources to track: -.PP - - none: No dependencies, just the specified elements - all: All dependencies of all specified elements + Specify `--deps` to control which sources to track: .PP +  + none: No dependencies, just the specified elements + all: All dependencies of all specified elements + .SH OPTIONS .TP \fB\-\-except\fP PATH diff --git a/man/bst-source.1 b/man/bst-source.1 index 6730bd665..8d3666353 100644 --- a/man/bst-source.1 +++ b/man/bst-source.1 @@ -1,4 +1,4 @@ -.TH "BST SOURCE" "1" "2025-04-24" "2.5" "bst source Manual" +.TH "BST SOURCE" "1" "2025-05-09" "2.5" "bst source Manual" .SH NAME bst\-source \- Manipulate sources for an element .SH SYNOPSIS diff --git a/man/bst-workspace-close.1 b/man/bst-workspace-close.1 index b6f223a1e..258b78288 100644 --- a/man/bst-workspace-close.1 +++ b/man/bst-workspace-close.1 @@ -1,4 +1,4 @@ -.TH "BST WORKSPACE CLOSE" "1" "2025-04-24" "2.5" "bst workspace close Manual" +.TH "BST WORKSPACE CLOSE" "1" "2025-05-09" "2.5" "bst workspace close Manual" .SH NAME bst\-workspace\-close \- Close workspaces .SH SYNOPSIS diff --git a/man/bst-workspace-list.1 b/man/bst-workspace-list.1 index 113c047d3..edfd6b7d4 100644 --- a/man/bst-workspace-list.1 +++ b/man/bst-workspace-list.1 @@ -1,4 +1,4 @@ -.TH "BST WORKSPACE LIST" "1" "2025-04-24" "2.5" "bst workspace list Manual" +.TH "BST WORKSPACE LIST" "1" "2025-05-09" "2.5" "bst workspace list Manual" .SH NAME bst\-workspace\-list \- List open workspaces .SH SYNOPSIS diff --git a/man/bst-workspace-open.1 b/man/bst-workspace-open.1 index e894a6a5e..dee6deb44 100644 --- a/man/bst-workspace-open.1 +++ b/man/bst-workspace-open.1 @@ -1,4 +1,4 @@ -.TH "BST WORKSPACE OPEN" "1" "2025-04-24" "2.5" "bst workspace open Manual" +.TH "BST WORKSPACE OPEN" "1" "2025-05-09" "2.5" "bst workspace open Manual" .SH NAME bst\-workspace\-open \- Open a new workspace .SH SYNOPSIS diff --git a/man/bst-workspace-reset.1 b/man/bst-workspace-reset.1 index 8e7fc9987..bdecb8dc6 100644 --- a/man/bst-workspace-reset.1 +++ b/man/bst-workspace-reset.1 @@ -1,4 +1,4 @@ -.TH "BST WORKSPACE RESET" "1" "2025-04-24" "2.5" "bst workspace reset Manual" +.TH "BST WORKSPACE RESET" "1" "2025-05-09" "2.5" "bst workspace reset Manual" .SH NAME bst\-workspace\-reset \- Reset a workspace to its original state .SH SYNOPSIS diff --git a/man/bst-workspace.1 b/man/bst-workspace.1 index 15f9cd570..bcd48b56a 100644 --- a/man/bst-workspace.1 +++ b/man/bst-workspace.1 @@ -1,4 +1,4 @@ -.TH "BST WORKSPACE" "1" "2025-04-24" "2.5" "bst workspace Manual" +.TH "BST WORKSPACE" "1" "2025-05-09" "2.5" "bst workspace Manual" .SH NAME bst\-workspace \- Manipulate developer workspaces .SH SYNOPSIS diff --git a/man/bst.1 b/man/bst.1 index 0a113b6d3..70a32cb91 100644 --- a/man/bst.1 +++ b/man/bst.1 @@ -1,4 +1,4 @@ -.TH "BST" "1" "2025-04-24" "2.5" "bst Manual" +.TH "BST" "1" "2025-05-09" "2.5" "bst Manual" .SH NAME bst \- Build and manipulate BuildStream projects .SH SYNOPSIS @@ -7,9 +7,9 @@ bst \- Build and manipulate BuildStream projects .SH DESCRIPTION Build and manipulate BuildStream projects .PP -Most of the main options override options in the -user preferences configuration file. -.PP + Most of the main options override options in the + user preferences configuration file. + .SH OPTIONS .TP \fB\-\-version\fP diff --git a/src/buildstream/_frontend/cli.py b/src/buildstream/_frontend/cli.py index 9daa25c05..9d7619bae 100644 --- a/src/buildstream/_frontend/cli.py +++ b/src/buildstream/_frontend/cli.py @@ -614,6 +614,7 @@ def show(app, elements, deps, except_, order, format_): %{build-deps} A list of build dependencies %{runtime-deps} A list of runtime dependencies %{source-info} Source provenance information + %{artifact-cas-digest} The CAS digest of the built artifact The value of the %{symbol} without the leading '%' character is understood as a pythonic formatting string, so python formatting features apply, @@ -639,7 +640,8 @@ def show(app, elements, deps, except_, order, format_): state_match = re.search(r"%(\{(state)[^%]*?\})", format_) key_match = re.search(r"%(\{(key)[^%]*?\})", format_) full_key_match = re.search(r"%(\{(full-key)[^%]*?\})", format_) - need_state = bool(state_match or key_match or full_key_match) + artifact_cas_digest_match = re.search(r"%(\{(artifact-cas-digest)[^%]*?\})", format_) + need_state = bool(state_match or key_match or full_key_match or artifact_cas_digest_match) if not elements: elements = app.project.get_default_targets() diff --git a/src/buildstream/_frontend/widget.py b/src/buildstream/_frontend/widget.py index 8303f0148..f2607fee9 100644 --- a/src/buildstream/_frontend/widget.py +++ b/src/buildstream/_frontend/widget.py @@ -461,6 +461,20 @@ def show_pipeline(self, dependencies, format_): # Dump the SourceInfo provenance objects in yaml format line = p.fmt_subst(line, "source-info", _yaml.roundtrip_dump_string(all_source_infos)) + # Artifact CAS Digest + if "%{artifact-cas-digest" in format_: + artifact = element._get_artifact() + if artifact.cached(): + artifact_files = artifact.get_files() + # We call the private CasBasedDirectory._get_digest() for + # the moment, we should make it public on Directory. + artifact_digest = artifact_files._get_digest() + formated_artifact_digest = "{}/{}".format(artifact_digest.hash, artifact_digest.size_bytes) + line = p.fmt_subst(line, "artifact-cas-digest", formated_artifact_digest) + else: + line = p.fmt_subst(line, "artifact-cas-digest", "") + element.warn("Cannot obtain CAS digest because artifact is not cached") + report += line + "\n" return report.rstrip("\n") diff --git a/tests/frontend/show_artifact_cas_digest.py b/tests/frontend/show_artifact_cas_digest.py new file mode 100644 index 000000000..9caf712d6 --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest.py @@ -0,0 +1,240 @@ +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +# Pylint doesn't play well with fixtures and dependency injection from pytest +# pylint: disable=redefined-outer-name + +import os + +import pytest + +from buildstream._testing import cli # pylint: disable=unused-import + +from tests.testutils import ( + create_artifact_share, + assert_shared, + assert_not_shared, +) + + +DATA_DIR = os.path.join(os.path.dirname(os.path.realpath(__file__)), "show_artifact_cas_digest_project") + + +# This tests that a target that hasn't been built locally +# and that isn't cached remotely has not artifact CAS +# digest. +# +# The test is performed without a remote cache. +# +@pytest.mark.datafiles(DATA_DIR) +@pytest.mark.parametrize( + "target", + [ + "import-basic-files.bst", + "import-executable-files.bst", + "import-symlinks.bst", + ], + ids=["basic-files", "executable-files", "symlinks"], +) +def test_show_artifact_cas_digest_uncached(cli, tmpdir, datafiles, target): + project = str(datafiles) + expected_no_digest = "" + + # Check the target has not been built locally and is not existing in the remote cache + assert ( + # May be "buildable" or "waiting" but shouldn't be "cached" + cli.get_element_state(project, target) + != "cached" + ) + + # Check the target has no artifact digest + result = cli.run(project=project, silent=True, args=["show", "--format", "%{name},%{artifact-cas-digest}", target]) + result.assert_success() + + received_digest = result.output.splitlines()[0] + assert received_digest == "{target},{digest}".format(target=target, digest=expected_no_digest) + + +# This tests that a target that has been built locally and +# with no remote has an artifact CAS digest. +# +# The test is performed without a remote cache. +# +@pytest.mark.datafiles(DATA_DIR) +@pytest.mark.parametrize( + "target, expected_digest", + [ + ("import-basic-files.bst", "7093d3c89029932ce1518bd2192e1d3cf60fd88e356b39195d10b87b598c78f0/168"), + ("import-executable-files.bst", "133a9ae2eda30945a363272ac14bb2c8a941770b5a37c2847c99934f2972ce4f/170"), + ("import-symlinks.bst", "95947ea55021e26cec4fd4f9de90d2b7f4f7d803ccc91656b3e1f2c9923ddf19/131"), + ], + ids=["basic-files", "executable-files", "symlinks"], +) +def test_show_artifact_cas_digest_cached(cli, tmpdir, datafiles, target, expected_digest): + project = str(datafiles) + + # Build the target locally + result = cli.run(project=project, silent=True, args=["build", target]) + result.assert_success() + + # Check the target has been built locally and is existing in the remote cache + assert cli.get_element_state(project, target) == "cached" + + # Check the target has an artifact digest + result = cli.run(project=project, silent=True, args=["show", "--format", "%{name},%{artifact-cas-digest}", target]) + result.assert_success() + + received_digest = result.output.splitlines()[0] + assert received_digest == "{target},{digest}".format(target=target, digest=expected_digest) + + +# This tests that the target and its dependencies are built +# as expected and that all their artifact CAS digests are +# available. +# +# The test is performed without a remote cache. +# +@pytest.mark.datafiles(DATA_DIR) +@pytest.mark.parametrize( + "target, expected_digests", + [ + ( + "dependencies.bst", + { + "dependencies.bst": "7093d3c89029932ce1518bd2192e1d3cf60fd88e356b39195d10b87b598c78f0/168", + "import-symlinks.bst": "95947ea55021e26cec4fd4f9de90d2b7f4f7d803ccc91656b3e1f2c9923ddf19/131", + }, + ), + ], + ids=["dependencies"], +) +def test_show_artifact_cas_digest_dependencies(cli, tmpdir, datafiles, target, expected_digests): + project = str(datafiles) + expected_no_digest = "" + + # Check the target and its dependencies have not been built locally + for component in sorted(expected_digests.keys()): + assert ( + # May be "buildable" or "waiting" but shouldn't be "cached" + cli.get_element_state(project, component) + != "cached" + ) + + # Check the target and its dependencies have no artifact digest + result = cli.run(project=project, silent=True, args=["show", "--format", "%{name},%{artifact-cas-digest}", target]) + result.assert_success() + + digests = dict(line.split(",", 2) for line in result.output.splitlines()) + assert len(digests) == len(expected_digests) + + for component, received in sorted(digests.items()): + assert received == expected_no_digest + + # Build the target and its dependencies locally + result = cli.run(project=project, silent=True, args=["build", target]) + result.assert_success() + + # Check the target and its dependencies have been built locally + for component in sorted(expected_digests.keys()): + assert cli.get_element_state(project, component) == "cached" + + # Check the target and its dependencies have an artifact digest + result = cli.run(project=project, silent=True, args=["show", "--format", "%{name},%{artifact-cas-digest}", target]) + result.assert_success() + + digests = dict(line.split(",", 2) for line in result.output.splitlines()) + assert len(digests) == len(expected_digests) + + for component, received in sorted(digests.items()): + assert received == expected_digests[component] + + +# This tests: +# - that a target that hasn't been built locally and that +# isn't cached remotely has no artifact CAS digest, +# - that a target that has been built locally and that is +# cached remotely has an artifact CAS digest, +# - that a target that hasn't been built locally and that +# is cached remotely has no artifact CAS digest. +# +# The test is performed with a remote cache, multiple tests +# are performed at once and on a single element because +# setting up a share is expensive. +# +@pytest.mark.datafiles(DATA_DIR) +def test_show_artifact_cas_digest_remote(cli, tmpdir, datafiles): + project = str(datafiles) + target = "import-basic-files.bst" + expected_no_digest = "" + + # Configure a local cache + local_cache = os.path.join(str(tmpdir), "cache") + cli.configure({"cachedir": local_cache}) + + with create_artifact_share(os.path.join(str(tmpdir), "artifactshare")) as share: + + cli.configure({"artifacts": {"servers": [{"url": share.repo, "push": True}]}}) + + # Test a target cached neither locally or remotely has no digest + + # Check the target has not been built locally and is not existing in the remote cache + assert cli.get_element_state(project, target) == "buildable" + assert_not_shared(cli, share, project, target) + + # Check the target has no artifact digest + result = cli.run( + project=project, silent=True, args=["show", "--format", "%{name},%{artifact-cas-digest}", target] + ) + result.assert_success() + + received_digest = result.output.splitlines()[0] + assert received_digest == "{target},{digest}".format(target=target, digest=expected_no_digest) + + # Test a target cached locally has a digest + + # Build the target locally and cache it remotely + result = cli.run(project=project, silent=True, args=["build", target]) + result.assert_success() + + # Check the target has been built and shared + assert cli.get_element_state(project, target) == "cached" + assert_shared(cli, share, project, target) + + # Check the target has an artifact digest + result = cli.run( + project=project, silent=True, args=["show", "--format", "%{name},%{artifact-cas-digest}", target] + ) + result.assert_success() + + received_digest = result.output.splitlines()[0] + assert received_digest != "{target},{digest}".format(target=target, digest=expected_no_digest) + + # Test a target cached remotely but not locally has no digest + + # Delete the locally cached target + result = cli.run(project=project, silent=True, args=["artifact", "delete", target]) + result.assert_success() + + # Check the target has been deleted locally but not remotely + assert cli.get_element_state(project, target) == "buildable" + assert_shared(cli, share, project, target) + + # Check the target has an artifact digest + result = cli.run( + project=project, silent=True, args=["show", "--format", "%{name},%{artifact-cas-digest}", target] + ) + result.assert_success() + + received_digest = result.output.splitlines()[0] + assert received_digest == "{target},{digest}".format(target=target, digest=expected_no_digest) diff --git a/tests/frontend/show_artifact_cas_digest_project/elements/dependencies.bst b/tests/frontend/show_artifact_cas_digest_project/elements/dependencies.bst new file mode 100644 index 000000000..371085b0a --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest_project/elements/dependencies.bst @@ -0,0 +1,6 @@ +kind: import +sources: +- kind: local + path: files/basic-files +depends: +- import-symlinks.bst diff --git a/tests/frontend/show_artifact_cas_digest_project/elements/import-basic-files.bst b/tests/frontend/show_artifact_cas_digest_project/elements/import-basic-files.bst new file mode 100644 index 000000000..a39a107fe --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest_project/elements/import-basic-files.bst @@ -0,0 +1,4 @@ +kind: import +sources: +- kind: local + path: files/basic-files diff --git a/tests/frontend/show_artifact_cas_digest_project/elements/import-executable-files.bst b/tests/frontend/show_artifact_cas_digest_project/elements/import-executable-files.bst new file mode 100644 index 000000000..f807a2e37 --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest_project/elements/import-executable-files.bst @@ -0,0 +1,4 @@ +kind: import +sources: +- kind: local + path: files/executable-files diff --git a/tests/frontend/show_artifact_cas_digest_project/elements/import-symlinks.bst b/tests/frontend/show_artifact_cas_digest_project/elements/import-symlinks.bst new file mode 100644 index 000000000..cca0b5b03 --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest_project/elements/import-symlinks.bst @@ -0,0 +1,4 @@ +kind: import +sources: +- kind: local + path: files/symlinks diff --git a/tests/frontend/show_artifact_cas_digest_project/files/basic-files/basicfile b/tests/frontend/show_artifact_cas_digest_project/files/basic-files/basicfile new file mode 100644 index 000000000..d03e2425c --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest_project/files/basic-files/basicfile @@ -0,0 +1 @@ +file contents diff --git a/tests/frontend/show_artifact_cas_digest_project/files/basic-files/basicfolder/subdir-file b/tests/frontend/show_artifact_cas_digest_project/files/basic-files/basicfolder/subdir-file new file mode 100644 index 000000000..e69de29bb diff --git a/tests/frontend/show_artifact_cas_digest_project/files/executable-files/basicfile b/tests/frontend/show_artifact_cas_digest_project/files/executable-files/basicfile new file mode 100755 index 000000000..d03e2425c --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest_project/files/executable-files/basicfile @@ -0,0 +1 @@ +file contents diff --git a/tests/frontend/show_artifact_cas_digest_project/files/executable-files/basicfolder/subdir-file b/tests/frontend/show_artifact_cas_digest_project/files/executable-files/basicfolder/subdir-file new file mode 100755 index 000000000..e69de29bb diff --git a/tests/frontend/show_artifact_cas_digest_project/files/symlinks/broken-symlink b/tests/frontend/show_artifact_cas_digest_project/files/symlinks/broken-symlink new file mode 120000 index 000000000..1cecd2cd9 --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest_project/files/symlinks/broken-symlink @@ -0,0 +1 @@ +missing-file \ No newline at end of file diff --git a/tests/frontend/show_artifact_cas_digest_project/files/symlinks/symlink b/tests/frontend/show_artifact_cas_digest_project/files/symlinks/symlink new file mode 120000 index 000000000..1de565933 --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest_project/files/symlinks/symlink @@ -0,0 +1 @@ +target \ No newline at end of file diff --git a/tests/frontend/show_artifact_cas_digest_project/files/symlinks/target b/tests/frontend/show_artifact_cas_digest_project/files/symlinks/target new file mode 100644 index 000000000..eb5a316cb --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest_project/files/symlinks/target @@ -0,0 +1 @@ +target diff --git a/tests/frontend/show_artifact_cas_digest_project/project.conf b/tests/frontend/show_artifact_cas_digest_project/project.conf new file mode 100644 index 000000000..7e690f56f --- /dev/null +++ b/tests/frontend/show_artifact_cas_digest_project/project.conf @@ -0,0 +1,10 @@ +# Project config for frontend build test +name: test +min-version: 2.0 +element-path: elements + +plugins: +- origin: pip + package-name: sample-plugins + sources: + - git