diff options
| -rw-r--r-- | bpkg/bpkg.cli | 22 | ||||
| -rw-r--r-- | bpkg/pkg-build.cli | 2 | ||||
| -rw-r--r-- | bpkg/repository-types.cli | 55 |
3 files changed, 39 insertions, 40 deletions
diff --git a/bpkg/bpkg.cli b/bpkg/bpkg.cli index f0e0928..bf7779a 100644 --- a/bpkg/bpkg.cli +++ b/bpkg/bpkg.cli @@ -40,11 +40,11 @@ namespace bpkg "", "", - "A \cb{bpkg} \i{build 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. + "A \cb{bpkg} \i{build configuration} is a directory that contains 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} build @@ -56,12 +56,12 @@ namespace bpkg \cb{manifest} file. \cb{bpkg} can either use package archives/directories directly from the filesystem or it can fetch them from repositories. - A \i{bpkg repository} is a collection of packages as well as prerequisite - and complement repositories. \i{Archive}, \i{directory} and \i{version - control}-based repositories are supported. A repository is identified by - its location which can be a local filesystem path or a URL. See - \l{bpkg-repository-types(1)} for details on their structure and URL - format. + A \i{bpkg repository} is a collection of packages as well as information + about prerequisite and complement repositories. \i{Archive}, + \i{directory} and \i{version control}-based repositories are supported. A + repository is identified by its location which can be a local filesystem + path or a URL. See \l{bpkg-repository-types(1)} for details on the + repository structures and URL formats. If the same version of a package is available from multiple repositories, then they are assumed to contain identical package content. In such cases diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli index 34a3683..3674688 100644 --- a/bpkg/pkg-build.cli +++ b/bpkg/pkg-build.cli @@ -112,7 +112,7 @@ namespace bpkg prerequisite repositories of dependent packages are considered as available for build as a dependency. - Packages (both built to hold and as dependents) that are specified with + Packages (both built to hold and as dependencies) that are specified with an explicit package version (<ver>) or as an archive or directory, will have their versions held, that is, they will not be automatically upgraded. diff --git a/bpkg/repository-types.cli b/bpkg/repository-types.cli index d3cdbdf..bfb20c4 100644 --- a/bpkg/repository-types.cli +++ b/bpkg/repository-types.cli @@ -29,17 +29,17 @@ path or an \cb{http(s)://} URL. \h|DIR REPOSITORIES| A \cb{dir} repository is \i{directory}-based. That is, it contains a -collection of various packages as directories (but only a single version per -package can be present in such a repository). The \cb{dir} repository location +collection of various packages as directories but only a single version per +package can be present in such a repository. The \cb{dir} repository location can be a local directory path or a \cb{file://} URL. A \cb{dir} repository is expected to contain either the \cb{manifest} or \cb{packages.manifest} file in the root directory of the repository. If it only contains \cb{manifest}, then it is assumed to be a simple, single-package repository with the \cb{manifest} file being its package manifest. Otherwise, -the \cb{packages.manifest} file should list the available packages as -described in \l{bpkg#manifest-package-list-dir Package List Manifest for -\cb{dir} Repositories}. +the \cb{packages.manifest} file should list the locations of available +packages as described in \l{bpkg#manifest-package-list-dir Package List +Manifest for \cb{dir} Repositories}. A \cb{dir} repository may also contain the \cb{repositories.manifest} file in the root directory of the repository. This file can be used to describe the @@ -51,14 +51,13 @@ for details on the format and semantics of this file. \h|GIR REPOSITORIES| A \cb{git} repository is \i{version control}-based. That is, it normally -contains multiple versions of the same package (but can also contain several -packages in the same repository). +contains multiple versions of the same package (but can also contain several, +usually related, packages in the same repository). A \cb{git} repository has the same structure and manifest files as the \cb{dir} repository. See \l{bpkg#manifest-package-list-dir Package List Manifest for \cb{dir} Repositories} and \l{bpkg#manifest-repository-list -Repository List Manifest} for details on the format and semantics of the -manifest files. +Repository List Manifest} for details on their format and semantics. Theoretically, a \cb{git} repository may contain as many package versions as there are commits. Practically, however, we are normally only interested in a @@ -67,9 +66,9 @@ for all of them could be prohibitively expensive. As a result, by default, only advertised tags in the \cb{refs/tags/v*} form where the part after \cb{v} is also a valid \l{b#module-version standard version} are considered to be sources of useful package versions. These commits normally correspond to -releases and are called the default set. +released versions and are called the \i{default set}. -Instead of the default set, it is also possible to provide a custom set of +Instead of the default set, it is possible to provide a custom set of available versions by specifying one or more commit ids and/or references and/or reference patterns in the repository URL fragment (see \cb{git-ls-remote(1)} for details on advertised references). For example: @@ -98,7 +97,7 @@ filters in the following form: Either \ci{refname}, \ci{commit}, or both must be specified. If both are specified then \ci{refname} is only used to minimize the amount of data -fetched and \ci{commit} must belong to its history. For example: +fetched and \ci{commit} is expected to belong to its history. For example: \ .../foo.git#master@48fba3625d65941bb85a39061bcf795d4949c778 @@ -127,28 +126,28 @@ sequence which matches in subdirectories, recursively. For example: \ A relative \ci{refname} is searched for in \cb{refs/}, \cb{refs/tags/}, and -\cb{refs/heads/} as well as symbolic references like \cb{HEAD}. To anchor it -to \cb{refs/} make it absolute, for example: +\cb{refs/heads/} as well as among symbolic references like \cb{HEAD}. To +anchor it to \cb{refs/} make it absolute, for example: \ .../foo.git#tags/v* - refs/tags/v1.2.3 but also refs/heads/tags/voo .../foo.git#/tags/v* - refs/tags/v1.2.3 only \ -While a \ci{refname} pattern may not match any references, a non-pattern that -doesn't resolve to a reference is invalid. +While a \ci{refname} pattern is allowed not match any references, a +non-pattern that doesn't resolve to a reference is invalid. -If a \ci{refname} starts with \cb{-} then it is treated as an exclusion filter -\- any references that it matches are excluded from the set included by the -preceding filters (or the default set). For example: +If a \ci{refname} starts with minus (\cb{-}) then it is treated as an +exclusion filter \- any references that it matches are excluded from the set +included by the preceding filters (or the default set). For example: \ .../foo.git#v*,-v1.* - exclude v1.* from v* .../foo.git##-v1.* - exclude v1.* from default set \ -To support specifying literal leading \cb{-}, a \ci{refname} that starts with -\cb{+} is treated as an inclusion filter. For example: +To support specifying literal leading minus, a \ci{refname} that starts with +plus (\cb{+}) is treated as an inclusion filter. For example: \ .../foo.git#+x - include x @@ -156,11 +155,11 @@ To support specifying literal leading \cb{-}, a \ci{refname} that starts with .../foo.git#++x - include +x \ -Supported \cb{git} protocols are \cb{git://}, \cb{http://}, and \cb{https://} -for remote repositories and \cb{file://} for local repositories. While -\cb{bpkg} tries to minimize the amount of information (history) fetched, it is -not always possible for some protocols and/or server configurations, as -discussed next. +Currently supported \cb{git} protocols are \cb{git://}, \cb{http://}, and +\cb{https://} for remote repositories and \cb{file://} for local +repositories. While \cb{bpkg} tries to minimize the amount of information +(history) fetched, it is not always possible for some protocols and/or server +configurations, as discussed next. A \cb{git} repository accessible via \cb{http(s)://} can use either \i{dumb} or \i{smart} protocol (refer to the \cb{git} documentation for details). The @@ -182,8 +181,8 @@ if fetching unadvertised commits is allowed and always assumes that it is not. Based on this information, to achieve optimal results the recommended protocol for remote repositories is smart \cb{https://}. Additionally, if you are -planning to refer to commit ids, then also consider configuring the server to -allow fetching unadvertised commits. +planning to refer to unadvertised commit ids, then also consider configuring +the server to allow fetching unadvertised commits. The \cb{file://} protocol has the same fetch minimization support as \cb{git://} and is therefore treated the same. |