diff options
| -rw-r--r-- | bpkg/pkg-fetch.cli | 8 | ||||
| -rw-r--r-- | bpkg/pkg-unpack.cli | 28 | ||||
| -rw-r--r-- | doc/manual.cli | 48 |
3 files changed, 59 insertions, 25 deletions
diff --git a/bpkg/pkg-fetch.cli b/bpkg/pkg-fetch.cli index 213c536..7228be0 100644 --- a/bpkg/pkg-fetch.cli +++ b/bpkg/pkg-fetch.cli @@ -15,7 +15,7 @@ namespace bpkg "\h|SYNOPSIS| - \c{\b{bpkg pkg-fetch} [<options>] (<pkg>\b{/}<ver> | \b{-e} <file>)} + \c{\b{bpkg pkg-fetch} [<options>] (<pkg>\b{/}<ver> | \b{--existing|-e} <file>)} \h|DESCRIPTION| @@ -32,9 +32,9 @@ namespace bpkg If the \cb{--existing|-e} option is used, then instead of the name and version arguments, \cb{pkg-fetch} expects a local path to an existing package archive. In this case, \cb{bpkg} will use the archive in place, - without copying it to the configuration or package cache directories. - Also, unless the \cb{--purge|-p} option is specified, \cb{bpkg} will not - attempt to remove this archive when the package is later purged with the + without copying it into the configuration directory. Also, unless the + \cb{--purge|-p} option is specified, \cb{bpkg} will not attempt to remove + this archive when the package is later purged with the \l{bpkg-pkg-purge(1)} command." } diff --git a/bpkg/pkg-unpack.cli b/bpkg/pkg-unpack.cli index c13d3dc..44447c5 100644 --- a/bpkg/pkg-unpack.cli +++ b/bpkg/pkg-unpack.cli @@ -11,11 +11,11 @@ include <bpkg/configuration.cli>; namespace bpkg { { - "<options> <pkg> <dir>", + "<options> <pkg> <dir> <ver>", "\h|SYNOPSIS| - \c{\b{bpkg pkg-unpack} [<options>] (<pkg> | \b{-e} <dir>)} + \c{\b{bpkg pkg-unpack} [<options>] (<pkg> | \b{--existing|-e} <dir>)} \h|DESCRIPTION| @@ -25,16 +25,28 @@ namespace bpkg If the \cb{--existing|-e} option is used, then instead of the package name, \cb{pkg-unpack} expects a local path to an existing package - directory. In this case, \cb{bpkg} will use the directory in place, - without copying it to the configuration or package cache directories. - Also, unless the \cb{--purge|-p} option is specified, \cb{bpkg} will not - attempt to remove this directory when the package is later purged with - the \l{bpkg-pkg-purge(1)} command. + directory. In this case, \cb{bpkg} will use the (source) directory in + place, without copying it into the configuration directory. Also, unless + the \cb{--purge|-p} option is specified, \cb{bpkg} will not attempt to + remove this directory when the package is later purged with the + \l{bpkg-pkg-purge(1)} command. Such a package is called \i{external}. If \cb{--existing|-e} is specified together with the \cb{--replace|-r} option, then \cb{pkg-unpack} will replace the archive and/or source directory of a package that is already in the \cb{unpacked} or - \cb{fetched} state." + \cb{fetched} state. + + An external package triggers several changes in semantics compared to a + normal package: The package (output) directory inside the configuration + is called just <pkg> rather than <pkg>\cb{-}<ver>. It is also assumed + that the packaging information (package manifest and lockfile) for such + packages may change without incrementing the package version (for + example, during development). To support this, \cb{bpkg} implements the + \i{package iteration} mechanism which may result in iteration numbers to + be shown as part of the package version, for example, \cb{1.2.3#1} (see + \l{bpkg#package-version Package Version}). Finally, it is possible to + replace one external package version with another while preserving its + output directory by specifying the \cb{--keep-out} option." } class pkg_unpack_options: configuration_options diff --git a/doc/manual.cli b/doc/manual.cli index b647a66..0143919 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -33,7 +33,7 @@ versioning and that allows automation of many version management tasks. See The \c{bpkg} package version has the following form: \ -[<epoch>~]<upstream>[-<prerel>][+<revision>] +[<epoch>~]<upstream>[-<prerel>][+<revision>][#<iteration>] \ The \i{epoch} part should be an integer. It can be used to change to a new @@ -56,6 +56,23 @@ The \i{revision} part should be an integer. It is used to version package releases that are based on the same upstream versions. If not specified, then \i{revision} defaults to \c{0}. +The \i{iteration} part is an integer. It is used internally by \c{bpkg} to +automatically version modifications to the packaging information +(specifically, to package manifest and lockfile) in \i{external packages} that +have the same upstream version and revision. As a result, the \i{iteration} +cannot not be specified by the user and is only shown in the \c{bpkg} output +(for example, by \c{pkg-status} command) in order to distinguish between +package iterations with otherwise identical versions. Note also that +\i{iteration} is relative to the \c{bpkg} configuration. Or, in other words, +it is an iteration number of a package as observed by a specific +configuration. As a result, two configuration can \"see\" the same package +state as two different iterations. [Note: package iterations are used to +support package development during which requiring the developer to manually +increment the version or revision after each modification would be +impractical. This mechanism is similar to the automatic commit versioning +provided by the \i{standard version} except that it is limited to the +packaging information but works for uncommitted changes.] + Version \c{0-} (least possible version) is reserved and specifying it explicitly is illegal. [Note: explicitly specifying this version does not make much sense since \c{libfoo < 0-} is always false and \c{libfoo > 0-} is always @@ -69,9 +86,9 @@ full-fledged package at which point it will be assigned a \"real\" version. It is assumed that this version will always be greater than the stub version. When displaying the package version or when using the version to derive the -file name, zero \i{epoch} and \i{revision} are omitted (even if they were -explicitly specified, for instance, in the package manifest). For example, -\c{0~1.2.3+0} will be used as \c{libfoo-1.2.3}. +file name, zero \i{epoch}, \i{revision}, and \i{iteration} are omitted (even +if they were explicitly specified, for instance, in the package manifest). For +example, \c{0~1.2.3+0} will be used as \c{libfoo-1.2.3}. [Note: this versioning scheme and the choice of delimiter characters (\c{~-+}) is meant to align with semantic versioning.] @@ -89,11 +106,15 @@ Some examples of versions: 1.2.3+1 1~1.2.3 1~1.2.3-alpha.1+3 +1.2.3#1 +1.2.3+1#1 +1~1.2.3+1#2 \ -The version sorting order is \i{epoch}, \i{upstream}, \i{prerel}, and, -finally, \i{revision}. The \i{upstream} and \i{prerel} parts are compared from -left to right, one component at a time, as described next. +The version sorting order is \i{epoch}, \i{upstream}, \i{prerel}, +\i{revision}, and finally, \i{iteration}. The \i{upstream} and \i{prerel} +parts are compared from left to right, one component at a time, as described +next. To compare two components, first the component types are determined. A component that only consists of digits is an integer. Otherwise, it is a @@ -152,12 +173,13 @@ have to be stored, for example, for display, to derive package archive names, etc. [Note: in quite a few contexts the implementation needs to ignore the -\i{revision} part. For example, this is needed to implement the semantics of -newer revisions of packages replacing their old ones since we do not keep -multiple revisions of the same upstream version in the same respository. As a -result, in the package object model, we have a version key as just {\i{epoch}, -\i{upstream}, \i{prerel}} but also store the package revision so that it can -be shown it to the user, etc.] +\i{revision} and/or \i{iteration} parts. For example, this is needed to +implement the semantics of newer revisions/iterations of packages replacing +their old ones since we do not keep multiple revisions/iterations of the same +upstream version in the same respository. As a result, in the package object +model, we have a version key as just {\i{epoch}, \i{upstream}, \i{prerel}} but +also store the package revision and iteration so that it can be shown it to +the user, etc.] \h1#manifests|Manifests| |