diff options
| -rw-r--r-- | bpkg/bpkg.cli | 120 |
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. + " } |