aboutsummaryrefslogtreecommitdiff
path: root/bpkg/bpkg.cli
diff options
context:
space:
mode:
Diffstat (limited to 'bpkg/bpkg.cli')
-rw-r--r--bpkg/bpkg.cli120
1 files changed, 112 insertions, 8 deletions
diff --git a/bpkg/bpkg.cli b/bpkg/bpkg.cli
index 295c627..f299eaf 100644
--- a/bpkg/bpkg.cli
+++ b/bpkg/bpkg.cli
@@ -22,17 +22,116 @@ namespace bpkg
\h|DESCRIPTION|
- @@ TODO Is this a good place to describe some general concepts, like
- configuration, repositories, packages?
-
- The example workflow would be:
-
- Note that the common options can also be specified as part of the
- command-specific options.
+ The \cb{build2} package manager is used to manipulate configurations,
+ packages, and repositories using a set of commands that are summarized
+ below.
For a detailed description of any command or help topic, use the \cb{help}
command or see the corresponding man page (the man pages have the
- \cb{bpkg-} prefix, for example \l{bpkg-help(1)})."
+ \cb{bpkg-} prefix, for example \l{bpkg-help(1)}). Note that the common
+ options can also be specified as part of the command-specific options, for
+ convenience."
+ }
+
+ // For usage it's nice to see the list of commands on the first page. So
+ // let's not put this "extended" description into usage.
+ //
+ {
+ "",
+ "",
+
+ "A \i{bpkg configuration} is a directory that will contain packages built
+ with similar settings. For example, a configuration can be for a specific
+ target (\cb{i686}, \cb{x86_64}), compiler (\cb{clang}, \cb{gcc}) compile
+ options (\cb{-O3}, \cb{-g}), and so on. Configurations are relatively
+ cheap and can be created and thrown away as needed. Configurations can be
+ moved and copied by simply moving and copying the directories. Note,
+ however, that a move or copy may render some packages out-of-date. In the
+ \cb{build2} build system terms a \cb{bpkg} configuration is an
+ amalgamation that contains packages as subprojects.
+
+ A \i{bpkg package} is an archive or directory that contains a \cb{build2}
+ project plus a package \cb{manifest} file. \cb{bpkg} can either use
+ package archives/directories directly from the filesystem or it can fetch
+ archives from repositories.
+
+ A \i{bpkg repository} is a collection of packages as well as prerequisite
+ and complement repositories. A repository is identified by its location,
+ which can be a local filesystem path or a remote HTTP or HTTPS URL.
+
+ A typical \cb{bpkg} workflow would consist of the following steps.
+
+ \dl|
+
+ \li|\b{Create Configuration}\n
+
+ \
+ bpkg create cxx config.cxx=clang++ config.cxx.coptions=-O3 \
+ config.install.root=/usr/local config.install.root.sudo=sudo
+ \
+
+ |
+
+ \li|\n\b{Add Source Repositories}\n
+
+ \
+ bpkg add https://pkg.cppget.org/1/stable
+ \
+
+ Repeat this command to add more repositories.
+ |
+
+ \li|\n\b{Fetch Available Packages List}\n
+
+ \
+ bpkg fetch
+ \
+
+ |
+
+ \li|\n\b{Fetch and Build Packages}\n
+
+ \
+ bpkg build libfoo bar
+ \
+
+ |
+
+ \li|\n\b{Drop Package}\n
+
+ If some packages are no longer needed, we can remove them from the
+ configuration.
+
+ \
+ bpkg drop libfoo
+ \
+
+ |
+
+ \li|\n\b{Refresh Available Packages List}\n
+
+ \
+ bpkg fetch
+ \
+
+ |
+
+ \li|\n\b{Upgrade Packages}\n
+
+ \
+ bpkg build bar
+ \
+
+ |
+
+ \li|\n\b{Install Packages}\n
+
+ \
+ bpkg install bar
+ \
+
+ ||
+ "
}
class commands
@@ -174,4 +273,9 @@ namespace bpkg
bool --help;
bool --version;
};
+
+ "\h|EXIT STATUS|
+
+ Non-zero exit status is returned in case of an error.
+ "
}