aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2023-12-12 06:21:32 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2023-12-12 06:21:32 +0200
commita87c8b2399294b75387a84e451a30d61faee390e (patch)
tree5f78c30a67645f6858e71e223bda848635141743
parentc54ac2b018c7d9b95f5f4d8e7722564efb5b0032 (diff)
Further work on packaging guide
-rw-r--r--doc/packaging.cli50
1 files changed, 42 insertions, 8 deletions
diff --git a/doc/packaging.cli b/doc/packaging.cli
index cd22e10..d754852 100644
--- a/doc/packaging.cli
+++ b/doc/packaging.cli
@@ -1267,6 +1267,14 @@ package repository root:
$ bdep sync -a
\
+\N|If you have any build-time dependencies (see
+\l{intro#guide-build-time-linked Build-Time Dependencies and Linked
+Configurations} for background), then you will get a warning about the
+corresponding \c{config.import.*} variable being unused and therefore
+dropped. This is because we haven't yet added the corresponding \c{import}
+directives to our \c{buildfiles}. For now you can ignore this warning and we
+will fix it later, when we adjust the generated \c{buildfiles}.|
+
This command should first fetch the metadata for the repository we specified
in \c{repositories.manifest} and then fetch, unpack and configure each
dependency that we specified in \c{manifest}. We can examine the resulting
@@ -1464,7 +1472,7 @@ need to tweak it are not uncommon and include:
than manually. For example:
\
- bdep new --lang c++,c ...
+ $ bdep new --lang c++,c ...
\
||
@@ -1491,6 +1499,17 @@ Also, in C++ projects, if you don't have any inline or template files, then
you can drop the assignment of the file extension for the \c{ixx} and \c{txx}
target types, respectively.
+If you have added any configuration variables and would like to use
+non-default values for some of them in your build, then you will need to
+reconfigure the package. For example, let' say we have added the
+\c{config.libfoo.debug} variable to our \c{libfoo} package which enables
+additional debugging facilities in the library. This is how we can reconfigure
+all our builds to enable this functionality:
+
+\
+$ bdep sync -a config.libfoo.debug=true
+\
+
If you have made any changes, commit them (similar to the previous step, we
cannot test things just yet):
@@ -1775,7 +1794,16 @@ If you do have have dependencies, then let's handle them now.
\N|Here we will assume dependencies on other libraries, which is the common
case. If you have dependencies on executables, for example, source code
generators, see \l{intro#guide-build-time-linked Build-Time Dependencies and
-Linked Configurations} on how to handle that.|
+Linked Configurations} on how to handle that. In this case you will also
+need to reconfigure your package after adding the corresponding \c{import}
+directives in order to re-acquire the previously dropped \c{config.import.*}
+values:
+
+\
+$ bdep sync -a --disfigure
+\
+
+|
For each library that your package depends on (and which you have added
to \c{manifest} on the \l{#core-fill-depend Add dependencies} step),
@@ -2509,7 +2537,7 @@ $ rm -r /tmp/dist
\
-\h2#core-test-smoke-ci|Test with CI|
+\h2#core-test-smoke-ci|Commit and test with CI|
With local testing complete, let's commit our changes and submit a remote CI
job to test our library on all the major platforms and with all the major
@@ -2545,20 +2573,26 @@ 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
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. Finally, you can
-just leave the build failing with the expectation that it will be fixed in the
-next upstream version. Note that in this case you should not exclude the
-failing build from CI.|
+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
+details). Finally, you can just leave the build failing with the expectation
+that it will be fixed in the next upstream version. Note that in this case you
+should not exclude the failing build from CI.|
-@@ Are we committing (untested) library build?
+@@ Are we committing (untested) library build? Yes
@@ bdep sync -a
@@ library unit tests: can run them earlier
+@@ Next section: convert smoke test to upstream tests.
+@@ Next section: adjust root buildfile and manifest.
+@@ Next section: release and publish (see README in build2-packaging/).
========
+@@ Add example of propagating config.libfoo.debug to macro on build options?
+
@@ Upstream tests: link to HOWTO on how to sanitize.
@@ Note on library metadata where talk about configuration. Also about