aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2024-03-13 14:15:55 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2024-03-13 14:15:55 +0200
commitfcc3b1bec382d592d36466384e1e376323d6ab37 (patch)
tree0979127ac89028a39f2801400d1254c716570518
parent9add04844030ece4a1f4c8e27e3b29e9dc598771 (diff)
Further work on packaging guide (proofreading)
-rw-r--r--doc/packaging.cli49
1 files changed, 39 insertions, 10 deletions
diff --git a/doc/packaging.cli b/doc/packaging.cli
index 2c3c145..f946a08 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -38,6 +38,9 @@
// @@ 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.
"
\h0#preface|Preface|
@@ -1129,6 +1132,7 @@ above example, the recommended sequence of commands would be:
$ cd libfoo/
$ b update
$ b test
+$ rm -rf /tmp/install
$ b install config.install.root=/tmp/install
$ b clean
\
@@ -1894,12 +1898,13 @@ separated physically, in the combined layout you may need to achieve the same
result (that is, avoid installing private headers) at the build system
level. If the library provides only a handful of public headers and this set
is unlikely to change often, then listing them explicitly is the most
-straightforward approach. For example:
+straightforward approach. For example (the \c{@./} qualifier tells \c{build2}
+they are in the source directory):
\
# Only install public headers into, say, /usr/include/.
#
-h{foo foo_version}: install = include/
+h{foo}@./ h{foo_version}@./: install = include/
h{*}: install = false
\
@@ -2636,7 +2641,7 @@ we cannot build and test the entire package before adjusting the generated
the library and, if it has any unit tests in the source subdirectory, even run
some tests.
-\N|Is the library is header only, there won't be anything to build unless
+\N|If the library is header only, there won't be anything to build unless
there are unit tests. Still you may want to continue with this exercise to
detect any syntactic mistakes in the \c{buildfiles}, etc.|
@@ -2655,6 +2660,14 @@ library builds and if it has unit tests, you can try to run them:
$ b test
\
+It also makes sense to test the installation and see if anything is off (such
+as private headers being installed):
+
+\
+$ rm -rf /tmp/install
+$ b install config.install.root=/tmp/install
+\
+
Once the library builds, it makes sense to commit our changes for easier
rollbacks:
@@ -2822,6 +2835,7 @@ library into a temporary directory:
\
$ cd libfoo/ # Change to the package root.
+$ rm -rf /tmp/install
$ b install config.install.root=/tmp/install
\
@@ -2925,14 +2939,19 @@ $ cd foo/ # Change to the package repository root.
$ git add .
$ git status
$ git commit -m \"Add smoke test\"
-$ git push
+$ git push -u
$ bdep ci
\
The result of the \l{bdep-ci(1)} command is a link where you can see the
-status of the builds. If any fail, view the logs to determine the cause, try
-to fix it, commit your fix, and CI again.
+status of the builds.
+
+\N|Make sure to wait until there are no more unbuilt configurations (that is,
+the number of entries with the \c{<unbuilt>} result is \c{0}).|
+
+If any builds fail, view the logs to determine the cause, try to fix it,
+commit your fix, and CI again.
\N|It is possible that upstream does not support some platforms or compilers.
For example, it's common for smaller projects not to bother with supporting
@@ -2949,7 +2968,7 @@ want to exclude these platforms/compilers from the CI builds using the
The other common cause of a failed build is a newer version of a compiler or
platform that breaks upstream. In this case there are three options: Ideally
-you would want to fix this upstream and have a new version released. Failed
+you would want to fix this in upstream and have a new version released. Failed
that, you may want to patch the upstream code to fix the issues, especially if
this is one of the major platforms and/or primary compilers (see
\l{#howto-patch-upstream-source How do I patch upstream source code?} for
@@ -3159,9 +3178,9 @@ tests/: install = false
\
If the upstream project provides any other documentation (detailed change
-logs, contributing guidelines, etc) or legal files (list of authors, code of
-conduct, etc), then you may want to symlink and list them as the \c{doc{\}}
-and \c{legal{\}} prerequisites, respectively.
+logs, contributing guidelines, etc) or legal files (alternative licenses, list
+of authors, code of conduct, etc), then you may want to symlink and list them
+as the \c{doc{\}} and \c{legal{\}} prerequisites, respectively.
\N|One file you don't need listing is \c{INSTALL} (or equivalent) which
normally contains the installation instructions for the upstream build
@@ -3184,6 +3203,12 @@ prerequisites. For this last step, there are two options: we can list the
files directly in the root \c{buildfile} or we can create a separate
\c{buildfile} in the subdirectory.
+\N|If symlinking entire subdirectories, don't forget to also list them in
+\c{.gitattributes} if you want your package to be usable from the \c{git}
+repository directly on Windows. See
+\l{https://build2.org/article/symlinks.xhtml#windows Symlinks and Windows} for
+details.|
+
Let's examine each approach using our \c{libfoo} as an example. We will
assume that the upstream project contains the \c{docs/} subdirectory with
additional \c{*.md} files that document the library's API. It would make sense
@@ -3379,6 +3404,10 @@ and \c{license}, unless correctly auto-detected by \c{bdep-new} on the
\l{#core-root-manifest-license Adjust \c{manifest}: \c{license}} below
for guidelines on changing these values.
+\N|It is not uncommon for projects to be licensed under multiple licenses.
+Note, however, that \c{bdep-new} will only detect one license and you will
+need to specify any additional licenses manually.|
+
We will also need to change \c{url} and \c{email} with the upstream project's
homepage URL and e-mail, respectively. If upstream doesn't have a dedicated
website for the project, then use its repository URL on GitHub or equivalent.