summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTristan Van Berkom <tristan.vanberkom@codethink.co.uk>2019-07-14 20:24:53 +0900
committerTristan Van Berkom <tristan.vanberkom@codethink.co.uk>2019-07-15 23:19:24 +0900
commit7aa72261ae9f5c32b153e27703b644b9ed06ea7d (patch)
treef99601da78ef85449cb3c7fc3c89408207136e5e
parentfa127a5c02e0793e8ccf95bbae1f13dde4a54d7d (diff)
downloadbuildstream-7aa72261ae9f5c32b153e27703b644b9ed06ea7d.tar.gz
man: Updated man pages for new `--max-jobs` CLI argumenttristan/bst-1/config-max-jobs
-rw-r--r--man/bst-build.14
-rw-r--r--man/bst-checkout.14
-rw-r--r--man/bst-fetch.110
-rw-r--r--man/bst-help.14
-rw-r--r--man/bst-init.18
-rw-r--r--man/bst-pull.110
-rw-r--r--man/bst-push.110
-rw-r--r--man/bst-shell.112
-rw-r--r--man/bst-show.122
-rw-r--r--man/bst-source-bundle.14
-rw-r--r--man/bst-track.110
-rw-r--r--man/bst-workspace-close.14
-rw-r--r--man/bst-workspace-list.14
-rw-r--r--man/bst-workspace-open.14
-rw-r--r--man/bst-workspace-reset.14
-rw-r--r--man/bst-workspace.119
-rw-r--r--man/bst.180
17 files changed, 101 insertions, 112 deletions
diff --git a/man/bst-build.1 b/man/bst-build.1
index 81a866494..8c465fccd 100644
--- a/man/bst-build.1
+++ b/man/bst-build.1
@@ -1,4 +1,4 @@
-.TH "BST BUILD" "1" "06-Aug-2018" "" "bst build Manual"
+.TH "BST BUILD" "1" "14-Jul-2019" "" "bst build Manual"
.SH NAME
bst\-build \- Build elements in a pipeline
.SH SYNOPSIS
@@ -24,4 +24,4 @@ Except certain dependencies from tracking
Allow tracking to cross junction boundaries
.TP
\fB\-\-track\-save\fP
-Deprecated: This is ignored \ No newline at end of file
+Deprecated: This is ignored
diff --git a/man/bst-checkout.1 b/man/bst-checkout.1
index aa3ff5913..e1c2d0374 100644
--- a/man/bst-checkout.1
+++ b/man/bst-checkout.1
@@ -1,4 +1,4 @@
-.TH "BST CHECKOUT" "1" "06-Aug-2018" "" "bst checkout Manual"
+.TH "BST CHECKOUT" "1" "14-Jul-2019" "" "bst checkout Manual"
.SH NAME
bst\-checkout \- Checkout a built artifact
.SH SYNOPSIS
@@ -22,4 +22,4 @@ Whether to run integration commands
Checkout hardlinks instead of copies (handle with care)
.TP
\fB\-\-tar\fP
-Create a tarball from the artifact contents instead of a file tree. If LOCATION is '-', the tarball will be dumped to the standard output. \ No newline at end of file
+Create a tarball from the artifact contents instead of a file tree. If LOCATION is '-', the tarball will be dumped to the standard output.
diff --git a/man/bst-fetch.1 b/man/bst-fetch.1
index 97ee37741..c6169f56b 100644
--- a/man/bst-fetch.1
+++ b/man/bst-fetch.1
@@ -1,4 +1,4 @@
-.TH "BST FETCH" "1" "06-Aug-2018" "" "bst fetch Manual"
+.TH "BST FETCH" "1" "14-Jul-2019" "" "bst fetch Manual"
.SH NAME
bst\-fetch \- Fetch sources in a pipeline
.SH SYNOPSIS
@@ -6,14 +6,14 @@ bst\-fetch \- Fetch sources in a pipeline
[OPTIONS] [ELEMENTS]...
.SH DESCRIPTION
Fetch sources required to build the pipeline
-
+.PP
By default this will only try to fetch sources which are
required for the build plan of the specified target element,
omitting sources for any elements which are already built
and available in the artifact cache.
-
+.PP
Specify `--deps` to control which sources to fetch:
-
+.PP

none: No dependencies, just the element itself
plan: Only dependencies required for the build plan
@@ -30,4 +30,4 @@ The dependencies to fetch (default: plan)
Track new source references before fetching
.TP
\fB\-J,\fP \-\-track\-cross\-junctions
-Allow tracking to cross junction boundaries \ No newline at end of file
+Allow tracking to cross junction boundaries
diff --git a/man/bst-help.1 b/man/bst-help.1
index 655e5b438..df6caf815 100644
--- a/man/bst-help.1
+++ b/man/bst-help.1
@@ -1,4 +1,4 @@
-.TH "BST HELP" "1" "06-Aug-2018" "" "bst help Manual"
+.TH "BST HELP" "1" "14-Jul-2019" "" "bst help Manual"
.SH NAME
bst\-help \- Print usage information
.SH SYNOPSIS
@@ -6,4 +6,4 @@ bst\-help \- Print usage information
[OPTIONS] COMMAND
.SH DESCRIPTION
Print usage information about a given command
- \ No newline at end of file
+
diff --git a/man/bst-init.1 b/man/bst-init.1
index 73dbed15d..91d942d7b 100644
--- a/man/bst-init.1
+++ b/man/bst-init.1
@@ -1,4 +1,4 @@
-.TH "BST INIT" "1" "06-Aug-2018" "" "bst init Manual"
+.TH "BST INIT" "1" "14-Jul-2019" "" "bst init Manual"
.SH NAME
bst\-init \- Initialize a new BuildStream project
.SH SYNOPSIS
@@ -6,10 +6,10 @@ bst\-init \- Initialize a new BuildStream project
[OPTIONS]
.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.
.SH OPTIONS
@@ -24,4 +24,4 @@ The required format version (default: 12)
The subdirectory to store elements in (default: elements)
.TP
\fB\-f,\fP \-\-force
-Allow overwriting an existing project.conf \ No newline at end of file
+Allow overwriting an existing project.conf
diff --git a/man/bst-pull.1 b/man/bst-pull.1
index e3adda1b9..8be9ec446 100644
--- a/man/bst-pull.1
+++ b/man/bst-pull.1
@@ -1,4 +1,4 @@
-.TH "BST PULL" "1" "06-Aug-2018" "" "bst pull Manual"
+.TH "BST PULL" "1" "14-Jul-2019" "" "bst pull Manual"
.SH NAME
bst\-pull \- Pull a built artifact
.SH SYNOPSIS
@@ -6,13 +6,13 @@ bst\-pull \- Pull a built artifact
[OPTIONS] [ELEMENTS]...
.SH DESCRIPTION
Pull a built artifact from the configured remote artifact cache.
-
+.PP
By default the artifact will be pulled one of the configured caches
if possible, following the usual priority order. If the `--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
all: All dependencies
@@ -22,4 +22,4 @@ Specify `--deps` to control which artifacts to pull:
The dependency artifacts to pull (default: none)
.TP
\fB\-r,\fP \-\-remote TEXT
-The URL of the remote cache (defaults to the first configured cache) \ No newline at end of file
+The URL of the remote cache (defaults to the first configured cache)
diff --git a/man/bst-push.1 b/man/bst-push.1
index 9721a8781..88cf5915f 100644
--- a/man/bst-push.1
+++ b/man/bst-push.1
@@ -1,4 +1,4 @@
-.TH "BST PUSH" "1" "06-Aug-2018" "" "bst push Manual"
+.TH "BST PUSH" "1" "14-Jul-2019" "" "bst push Manual"
.SH NAME
bst\-push \- Push a built artifact
.SH SYNOPSIS
@@ -6,12 +6,12 @@ bst\-push \- Push a built artifact
[OPTIONS] [ELEMENTS]...
.SH DESCRIPTION
Push a built artifact to a remote artifact cache.
-
+.PP
The default destination is the highest priority configured cache. You can
override this by passing a different cache URL with the `--remote` flag.
-
+.PP
Specify `--deps` to control which artifacts to push:
-
+.PP

none: No dependencies, just the element itself
all: All dependencies
@@ -21,4 +21,4 @@ Specify `--deps` to control which artifacts to push:
The dependencies to push (default: none)
.TP
\fB\-r,\fP \-\-remote TEXT
-The URL of the remote cache (defaults to the first configured cache) \ No newline at end of file
+The URL of the remote cache (defaults to the first configured cache)
diff --git a/man/bst-shell.1 b/man/bst-shell.1
index 09e5b6da8..7f0c5fc5d 100644
--- a/man/bst-shell.1
+++ b/man/bst-shell.1
@@ -1,4 +1,4 @@
-.TH "BST SHELL" "1" "06-Aug-2018" "" "bst shell Manual"
+.TH "BST SHELL" "1" "14-Jul-2019" "" "bst shell Manual"
.SH NAME
bst\-shell \- Shell into an element's sandbox environment
.SH SYNOPSIS
@@ -6,18 +6,18 @@ bst\-shell \- Shell into an element's sandbox environment
[OPTIONS] ELEMENT [COMMAND]...
.SH DESCRIPTION
Run a command in the target element's sandbox environment
-
+.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.
-
+.PP
Use the --build option to create a temporary sysroot for
building the element instead.
-
+.PP
Use the --sysroot option with an existing failed build
directory or with a checkout of the given target, in order
to use a specific sysroot.
-
+.PP
If no COMMAND is specified, the default is to attempt
to run an interactive shell.
.SH OPTIONS
@@ -32,4 +32,4 @@ An existing sysroot
Mount a file or directory into the sandbox
.TP
\fB\-\-isolate\fP
-Create an isolated build sandbox \ No newline at end of file
+Create an isolated build sandbox
diff --git a/man/bst-show.1 b/man/bst-show.1
index 4495bf21d..36d18e097 100644
--- a/man/bst-show.1
+++ b/man/bst-show.1
@@ -1,4 +1,4 @@
-.TH "BST SHOW" "1" "06-Aug-2018" "" "bst show Manual"
+.TH "BST SHOW" "1" "14-Jul-2019" "" "bst show Manual"
.SH NAME
bst\-show \- Show elements in the pipeline
.SH SYNOPSIS
@@ -6,25 +6,25 @@ bst\-show \- Show elements in the pipeline
[OPTIONS] [ELEMENTS]...
.SH DESCRIPTION
Show elements in the pipeline
-
+.PP
By default this will show all of the dependencies of the
specified target element.
-
+.PP
Specify `--deps` to control which elements to show:
-
+.PP

none: No dependencies, just the element itself
plan: Dependencies required for a build plan
run: Runtime dependencies, including the element itself
build: Build time dependencies, excluding the element itself
all: All dependencies
-
+.PP

FORMAT
~~~~~~
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
%{key} The abbreviated cache key (if all sources are consistent)
@@ -36,17 +36,17 @@ the following symbols can be used in the format string:
%{public} Public domain data
%{workspaced} If the element is workspaced
%{workspace-dirs} A list of workspace directories
-
+.PP
The value of the %{symbol} without the leading '%' character is understood
as a pythonic formatting string, so python formatting features apply,
examle:
-
+.PP

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}'
@@ -62,4 +62,4 @@ The dependencies to show (default: all)
Staging or alphabetic ordering of dependencies
.TP
\fB\-f,\fP \-\-format FORMAT
-Format string for each element \ No newline at end of file
+Format string for each element
diff --git a/man/bst-source-bundle.1 b/man/bst-source-bundle.1
index ce94dde7e..6540630ab 100644
--- a/man/bst-source-bundle.1
+++ b/man/bst-source-bundle.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE-BUNDLE" "1" "06-Aug-2018" "" "bst source-bundle Manual"
+.TH "BST SOURCE-BUNDLE" "1" "14-Jul-2019" "" "bst source-bundle Manual"
.SH NAME
bst\-source-bundle \- Produce a build bundle to be manually executed
.SH SYNOPSIS
@@ -22,4 +22,4 @@ Track new source references before bundling
Overwrite an existing tarball
.TP
\fB\-\-directory\fP TEXT
-The directory to write the tarball to \ No newline at end of file
+The directory to write the tarball to
diff --git a/man/bst-track.1 b/man/bst-track.1
index 98fa311b0..5a1319942 100644
--- a/man/bst-track.1
+++ b/man/bst-track.1
@@ -1,4 +1,4 @@
-.TH "BST TRACK" "1" "06-Aug-2018" "" "bst track Manual"
+.TH "BST TRACK" "1" "14-Jul-2019" "" "bst track Manual"
.SH NAME
bst\-track \- Track new source references
.SH SYNOPSIS
@@ -7,12 +7,12 @@ bst\-track \- Track new source references
.SH DESCRIPTION
Consults the specified tracking branches for new versions available
to build and updates the project with any newly available references.
-
+.PP
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
@@ -25,4 +25,4 @@ Except certain dependencies from tracking
The dependencies to track (default: none)
.TP
\fB\-J,\fP \-\-cross\-junctions
-Allow crossing junction boundaries \ No newline at end of file
+Allow crossing junction boundaries
diff --git a/man/bst-workspace-close.1 b/man/bst-workspace-close.1
index 4abaad358..0bcf74bf7 100644
--- a/man/bst-workspace-close.1
+++ b/man/bst-workspace-close.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE CLOSE" "1" "06-Aug-2018" "" "bst workspace close Manual"
+.TH "BST WORKSPACE CLOSE" "1" "14-Jul-2019" "" "bst workspace close Manual"
.SH NAME
bst\-workspace\-close \- Close workspaces
.SH SYNOPSIS
@@ -12,4 +12,4 @@ Close a workspace
Remove the path that contains the closed workspace
.TP
\fB\-a,\fP \-\-all
-Close all open workspaces \ No newline at end of file
+Close all open workspaces
diff --git a/man/bst-workspace-list.1 b/man/bst-workspace-list.1
index e2e67c4eb..199ff3461 100644
--- a/man/bst-workspace-list.1
+++ b/man/bst-workspace-list.1
@@ -1,8 +1,8 @@
-.TH "BST WORKSPACE LIST" "1" "06-Aug-2018" "" "bst workspace list Manual"
+.TH "BST WORKSPACE LIST" "1" "14-Jul-2019" "" "bst workspace list Manual"
.SH NAME
bst\-workspace\-list \- List open workspaces
.SH SYNOPSIS
.B bst workspace list
[OPTIONS]
.SH DESCRIPTION
-List open workspaces \ No newline at end of file
+List open workspaces
diff --git a/man/bst-workspace-open.1 b/man/bst-workspace-open.1
index a0fae85b7..176223655 100644
--- a/man/bst-workspace-open.1
+++ b/man/bst-workspace-open.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE OPEN" "1" "06-Aug-2018" "" "bst workspace open Manual"
+.TH "BST WORKSPACE OPEN" "1" "14-Jul-2019" "" "bst workspace open Manual"
.SH NAME
bst\-workspace\-open \- Open a new workspace
.SH SYNOPSIS
@@ -15,4 +15,4 @@ Do not checkout the source, only link to the given directory
Overwrite files existing in checkout directory
.TP
\fB\-\-track\fP
-Track and fetch new source references before checking out the workspace \ No newline at end of file
+Track and fetch new source references before checking out the workspace
diff --git a/man/bst-workspace-reset.1 b/man/bst-workspace-reset.1
index 29689a9c6..255840434 100644
--- a/man/bst-workspace-reset.1
+++ b/man/bst-workspace-reset.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE RESET" "1" "06-Aug-2018" "" "bst workspace reset Manual"
+.TH "BST WORKSPACE RESET" "1" "14-Jul-2019" "" "bst workspace reset Manual"
.SH NAME
bst\-workspace\-reset \- Reset a workspace to its original state
.SH SYNOPSIS
@@ -15,4 +15,4 @@ Reset workspace state without affecting its contents
Track and fetch the latest source before resetting
.TP
\fB\-a,\fP \-\-all
-Reset all open workspaces \ No newline at end of file
+Reset all open workspaces
diff --git a/man/bst-workspace.1 b/man/bst-workspace.1
index b249ed4d5..aab453ccc 100644
--- a/man/bst-workspace.1
+++ b/man/bst-workspace.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE" "1" "06-Aug-2018" "" "bst workspace Manual"
+.TH "BST WORKSPACE" "1" "14-Jul-2019" "" "bst workspace Manual"
.SH NAME
bst\-workspace \- Manipulate developer workspaces
.SH SYNOPSIS
@@ -8,21 +8,18 @@ bst\-workspace \- Manipulate developer workspaces
Manipulate developer workspaces
.SH COMMANDS
.PP
-\fBreset\fP
- Reset a workspace to its original state
- See \fBbst workspace-reset(1)\fP for full documentation on the \fBreset\fP command.
-
+\fBopen\fP
+ Open a new workspace
+ See \fBbst workspace-open(1)\fP for full documentation on the \fBopen\fP command.
.PP
\fBclose\fP
Close workspaces
See \fBbst workspace-close(1)\fP for full documentation on the \fBclose\fP command.
-
+.PP
+\fBreset\fP
+ Reset a workspace to its original state
+ See \fBbst workspace-reset(1)\fP for full documentation on the \fBreset\fP command.
.PP
\fBlist\fP
List open workspaces
See \fBbst workspace-list(1)\fP for full documentation on the \fBlist\fP command.
-
-.PP
-\fBopen\fP
- Open a new workspace
- See \fBbst workspace-open(1)\fP for full documentation on the \fBopen\fP command.
diff --git a/man/bst.1 b/man/bst.1
index dfe1a7d2c..1b5dee207 100644
--- a/man/bst.1
+++ b/man/bst.1
@@ -1,4 +1,4 @@
-.TH "BST" "1" "06-Aug-2018" "" "bst Manual"
+.TH "BST" "1" "14-Jul-2019" "" "bst Manual"
.SH NAME
bst \- Build and manipulate BuildStream projects...
.SH SYNOPSIS
@@ -6,15 +6,15 @@ bst \- Build and manipulate BuildStream projects...
[OPTIONS] COMMAND [ARGS]...
.SH DESCRIPTION
Build and manipulate BuildStream projects
-
+.PP
Most of the main options override options in the
user preferences configuration file.
.SH OPTIONS
.TP
\fB\-\-version\fP
-
+.PP
.TP
-\fB\-c,\fP \-\-config PATH
+\fB\-c,\fP \-\-config FILE
Configuration file to use
.TP
\fB\-C,\fP \-\-directory DIRECTORY
@@ -32,6 +32,9 @@ Maximum simultaneous build tasks
\fB\-\-pushers\fP INTEGER
Maximum simultaneous upload tasks
.TP
+\fB\-\-max\-jobs\fP INTEGER
+Number of parallel jobs allowed for a given build task
+.TP
\fB\-\-network\-retries\fP INTEGER
Maximum retries for network tasks
.TP
@@ -66,61 +69,50 @@ Specify a project option
The mirror to fetch from first, before attempting other mirrors
.SH COMMANDS
.PP
-\fBshow\fP
- Show elements in the pipeline
- See \fBbst-show(1)\fP for full documentation on the \fBshow\fP command.
-
+\fBhelp\fP
+ Print usage information
+ See \fBbst-help(1)\fP for full documentation on the \fBhelp\fP command.
.PP
-\fBpush\fP
- Push a built artifact
- See \fBbst-push(1)\fP for full documentation on the \fBpush\fP command.
-
+\fBinit\fP
+ Initialize a new BuildStream project
+ See \fBbst-init(1)\fP for full documentation on the \fBinit\fP command.
.PP
-\fBcheckout\fP
- Checkout a built artifact
- See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
-
+\fBbuild\fP
+ Build elements in a pipeline
+ See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command.
.PP
\fBfetch\fP
Fetch sources in a pipeline
See \fBbst-fetch(1)\fP for full documentation on the \fBfetch\fP command.
-
-.PP
-\fBworkspace\fP
- Manipulate developer workspaces
- See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command.
-
-.PP
-\fBbuild\fP
- Build elements in a pipeline
- See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command.
-
.PP
\fBtrack\fP
Track new source references
See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command.
-
.PP
-\fBsource-bundle\fP
- Produce a build bundle to be manually executed
- See \fBbst-source-bundle(1)\fP for full documentation on the \fBsource-bundle\fP command.
-
+\fBpull\fP
+ Pull a built artifact
+ See \fBbst-pull(1)\fP for full documentation on the \fBpull\fP command.
.PP
-\fBinit\fP
- Initialize a new BuildStream project
- See \fBbst-init(1)\fP for full documentation on the \fBinit\fP command.
-
+\fBpush\fP
+ Push a built artifact
+ See \fBbst-push(1)\fP for full documentation on the \fBpush\fP command.
+.PP
+\fBshow\fP
+ Show elements in the pipeline
+ See \fBbst-show(1)\fP for full documentation on the \fBshow\fP command.
.PP
\fBshell\fP
Shell into an element's sandbox environment
See \fBbst-shell(1)\fP for full documentation on the \fBshell\fP command.
-
.PP
-\fBpull\fP
- Pull a built artifact
- See \fBbst-pull(1)\fP for full documentation on the \fBpull\fP command.
-
+\fBcheckout\fP
+ Checkout a built artifact
+ See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
.PP
-\fBhelp\fP
- Print usage information
- See \fBbst-help(1)\fP for full documentation on the \fBhelp\fP command.
+\fBworkspace\fP
+ Manipulate developer workspaces
+ See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command.
+.PP
+\fBsource-bundle\fP
+ Produce a build bundle to be manually executed
+ See \fBbst-source-bundle(1)\fP for full documentation on the \fBsource-bundle\fP command.