aboutsummaryrefslogtreecommitdiff
path: root/doc/packaging.cli
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2024-03-27 07:12:30 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2024-03-27 07:12:30 +0200
commit7a0fe0ebdd99155e55081178a382fe0983602645 (patch)
tree3fb01100399cbf926b44ca7ff2bfc353ac61b2e9 /doc/packaging.cli
parent08d80f6f6a80d268f569e1e4a075a478f0b254ab (diff)
Further work on packaging guide (minor tweaks)
Diffstat (limited to 'doc/packaging.cli')
-rw-r--r--doc/packaging.cli119
1 files changed, 67 insertions, 52 deletions
diff --git a/doc/packaging.cli b/doc/packaging.cli
index 2ed4ffb..d0bf6e0 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -22,27 +22,15 @@
//
// @@ Add example of propagating config.libfoo.debug to macro on build options?
//
-// @@ Note on library metadata where talk about configuration. Also about
-// autoconf.
-//
// @@ Add link from metadata HOWTO to "Modifying upstream source code with
// preprocessor".
//
-// @@ Default configuration like SQLite -- look in Debian/Fedora (want to
-// be substitutable with system-installed).
-//
-// @@ Optional dependencies like xxhash.
-//
// @@ Mapping to system package manager names/versions.
//
-// @@ bdep-new: export stub for executables.
+// !! bdep-new: export stub for executables.
//
// @@ Are upstream tests well behaved? -- add never exit/take unreasonable time
//
-// @@ Note: showing UNIX command lines but should be straightforward to adjust
-// for Windows.
-//
-// @@ Add zstd as PACKAGE-README.md examples.
"
\h0#preface|Preface|
@@ -155,6 +143,11 @@ you should have read through \l{intro The \c{build2} Toolchain Introduction}
and the \l{b#intro Introduction} chapter in the build system manual. Ideally,
you should also have some experience using \c{build2} in your own projects.
+In this guide we will only show the UNIX version of the commands. In most
+cases making a Windows version is a simple matter of adjusting paths and, if
+used, line continuations. And where this is not the case a note will be
+provided showing the equivalent Windows command.
+
\h#intro-term|Terminology|
@@ -2382,12 +2375,24 @@ not always be a good idea. See
Which C/C++ compile/link options are OK to specify in a project's buildfile?}
for the guidelines.
-Also, oftentimes, such custom options must only be specified for certain
-target platforms or when using a certain compiler. While \c{build2} provides a
-large amount of information to identify the build configuration as well as more
-advanced \c{buildfile} language mechanism (such as \l{b#intro-switch Pattern
-Matching}) to make sense of it, this is a large topic for which we refer you
-to \l{b The \c{build2} Build System} manual. Additionally,
+\N|If you are packaging a library that includes a large number of optional
+features, it may be unclear which of them would make sense to enable by
+default. The notorious example of this situation is
+\l{https://github.com/build2-packaging/sqlite \c{libsqlite3}} which provides
+hundreds of preprocessor macros to enable or tune various aspects of its
+functionality.
+
+The recommended approach in cases like this is to study the configuration of
+such a library in distributions like Debian and Fedora and use the same
+defaults. In particular, this will allow us to substitute the \c{build2}
+package with the system-installed version.|
+
+Oftentimes, custom options must only be specified for certain target platforms
+or when using a certain compiler. While \c{build2} provides a large amount of
+information to identify the build configuration as well as more advanced
+\c{buildfile} language mechanism (such as \l{b#intro-switch Pattern Matching})
+to make sense of it, this is a large topic for which we refer you to \l{b The
+\c{build2} Build System} manual. Additionally,
\l{https://github.com/build2-packaging github.com/build2-packaging} now
contains a large number of packages that you can study and search for
examples.
@@ -2704,8 +2709,7 @@ that, the executable will have to always link to the static variant of the
library).
For a real example of both of these techniques, see the
-\l{https://github.com/build2-packaging/zstd/tree/v1.5.5 \c{zstd}} package
-repository.|
+\l{https://github.com/build2-packaging/zstd \c{zstd}} package repository.|
Dealing with dependencies in executables is similar to libraries except that
here we don't have the interface/implementation distinction; see the
@@ -2730,8 +2734,8 @@ How do I convey additional information (metadata) with executables and C/C++
libraries?} See also \l{#howto-patch-upstream-source-preproc Modifying
upstream source code with C/C++ preprocessor} on how to do it without
physically modifying upstream source code. \N{See the
-\l{https://github.com/build2-packaging/zstd/tree/v1.5.5 \c{zstd}} package
-repository for a real example of doing this.}
+\l{https://github.com/build2-packaging/zstd \c{zstd}} package repository for a
+real example of doing this.}
\N|We will discuss the \c{testscript} prerequisite on the
\l{#core-test-smoke-exe Make smoke test: executables} step below.|
@@ -2968,8 +2972,7 @@ How exactly to test any given executable depends on its functionality. For
instance, for a compression utility we could write a roundtrip test that first
compresses some input, then decompresses it, and finally compares the result
to the original. For example (taken from the
-\l{https://github.com/build2-packaging/zstd/tree/v1.5.5 \c{zstd}} package
-repository):
+\l{https://github.com/build2-packaging/zstd \c{zstd}} package repository):
\
: roundtrip
@@ -3816,7 +3819,7 @@ $ bdep ci
The last package file we need to adjust is \c{PACKAGE-README.md} which
describes how to use the package from a \c{build2}-based project. The template
generated by \c{bdep-new} establishes the recommended structure and includes a
-number of placeholders enclosed in \c{< >}, such as \c{<UPSTREAM-NAME>} and
+number of placeholders enclosed in \c{<\ >}, such as \c{<UPSTREAM-NAME>} and
\c{<SUMMARY-OF-FUNCTIONALITY>}, that need to be replaced with the
package-specific content. While all the placeholders should be
self-explanatory, below are a couple of guidelines.
@@ -3825,15 +3828,11 @@ For \c{<SUMMARY-OF-FUNCTIONALITY>} it's best to copy a paragraph or two from
the upstream documentation, usually from \c{README.md} or the project's web
page.
-\N|If \c{bdep new} was able to extract the summary from upstream \c{README},
-then the summary in the heading (first line) will contain that information.
-Otherwise, you would want to adjust it, similar to \c{manifest} above. Using
-the \c{summary} value form the \c{manifest}, perhaps slightly shortened,
-is a good idea.|
-
-If there is a single package, then \c{<SUMMARY>} in the heading can be the
-same as in \c{PACKAGE-README.md}. If there are multiple packages, then use
-an overall summary of the upstream project.
+\N|If the \c{bdep new} command was able to extract the summary from upstream
+\c{README}, then the summary in the heading (first line) will contain that
+information. Otherwise, you would need to adjust it manually, similar to
+\c{manifest} above. In this case use the \c{summary} value form the
+\c{manifest}, perhaps slightly shortened.|
If the package contains a single importable target, as is typical with
libraries, then it makes sense to drop the \"Importable targets\" section
@@ -3844,12 +3843,19 @@ Similarly, if the package has no configuration variables, then it makes sense
to drop the \"Configuration variables\" section.
For inspiration, see
+
+\l{https://github.com/build2-packaging/zstd/blob/master/libzstd/PACKAGE-README.md
+\c{PACKAGE-README.md}} in \l{https://github.com/build2-packaging/zstd
+\c{zstd}} and
\l{https://github.com/build2-packaging/libevent/blob/main/PACKAGE-README.md
\c{PACKAGE-README.md}} in \l{https://github.com/build2-packaging/libevent
-\c{libevent}} (library) and
+\c{libevent}} (libraries) as well as
+\l{https://github.com/build2-packaging/zstd/blob/master/zstd/PACKAGE-README.md
+\c{PACKAGE-README.md}} in \l{https://github.com/build2-packaging/zstd
+\c{zstd}} and
\l{https://github.com/build2-packaging/xxd/blob/master/xxd/README.md
\c{README.md}} in \l{https://github.com/build2-packaging/xxd \c{xxd}}
-(executable).
+(executables).
\N|If upstream does not provide a \c{README} file, then it makes sense to
rename \c{PACKAGE-README.md} to just \c{README.md} in the \c{build2} package,
@@ -3868,7 +3874,7 @@ $ git push
\
-\h#core-proj-readme|Adjust package repository \c{README.md}|
+\h#core-repo-readme|Adjust package repository \c{README.md}|
With all the package files taken care of, the last file we need to adjust is
\c{README.md} in the root of our package repository (it was created on the
@@ -3883,14 +3889,13 @@ to continue with updating this \c{README.md}.|
The primary purpose of the package repository \c{README.md} is to provide
setup instructions as well as any other relevant information for the
-devlopment of the packages as opposed to their consumption. However, it's also
-a good idea to privide a brief summary of what this package repostiory is
-about and to point users interested in consumption to the
-\c{PACKAGE-README.md} files.
-
-The template generated by \c{bdep-new} establishes the recommended structure
-that achieves these objectives. It includes a number of placeholders enclosed
-in \c{< >}, such as \c{<UPSTREAM-URL>} and \c{<SUMMARY-OF-FUNCTIONALITY>},
+development of the packages as opposed to their consumption. However, it's also
+a good idea to give a brief summary of what this repository is about and to
+point users interested in consumption to the \c{PACKAGE-README.md} files.
+
+The template generated by \c{bdep new} establishes the recommended structure
+to achieve these objectives. It includes a number of placeholders enclosed
+in \c{<\ >}, such as \c{<UPSTREAM-URL>} and \c{<SUMMARY-OF-FUNCTIONALITY>},
that need to be replaced with the repository-specific content. While all the
placeholders should be self-explanatory, below are a couple of guidelines.
@@ -3900,11 +3905,12 @@ an overall summary of the upstream project.
For \c{<SUMMARY-OF-FUNCTIONALITY>} it's best to copy a paragraph or two from
the upstream documentation, usually from \c{README.md} or the project's web
-page.
+page. Again, for a single package, this can be copied directly from
+\c{PACKAGE-README.md}.
If there are multiple packages in the repository, then it's recommended to
replace a single link to \c{PACKAGE-README.md} with a list of links (this
-also gives an idea which packages are available). For example:
+also shows the available packages). For example:
\
... If you want to use `foo` in your `build2`-based project, then
@@ -3917,12 +3923,13 @@ instead see the accompanying `PACKAGE-README.md` files:
The remainder of the generated \c{README.md} file are the standard \c{bdep}
initialization instructions. Adjust them if your package repository requires
anything special (for example, a host configuration). This is also the place
-to mention anything unusual, such as that upstream does not use semver.
+to mention anything unusual, such as that upstream does not use semver (and
+thus only a subset of \c{bdep} functionality is usable).
For inspiration, see
-\l{https://github.com/build2-packaging/zstd/blob/v1.5.5/README.md
-\c{README.md}} in the \l{https://github.com/build2-packaging/zstd/tree/v1.5.5
-\c{zstd}} package repository.
+\l{https://github.com/build2-packaging/zstd/blob/master/README.md
+\c{README.md}} in the \l{https://github.com/build2-packaging/zstd \c{zstd}}
+package repository.
Once the repository \c{README.md} is ready, commit and push the changes. You
may also want to view the result on GitHub to make sure everything is rendered
@@ -4405,6 +4412,14 @@ Adjust \c{manifest}}) and \c{PACKAGE-README.md} (\l{#core-root-package-readme
Adjust \c{PACKAGE-README.md}}) for any updates.
+\h2#core-version-management-new-version-repo|New version: review repository \c{README.md}|
+
+If any new packages were added in this version or if there are any changes to
+the development workflow, then it makes sense to review and if necessary
+update package repository \c{README.md} (\l{#core-repo-readme Adjust package
+repository \c{README.md}}).
+
+
\h2#core-version-management-new-version-issues|New version: review/fix accumulated issues|
When a bug is identified in an already released package version, we may not