diff options
Diffstat (limited to 'doc/packaging.cli')
| -rw-r--r-- | doc/packaging.cli | 243 |
1 files changed, 128 insertions, 115 deletions
diff --git a/doc/packaging.cli b/doc/packaging.cli index 9d18f80..07486a5 100644 --- a/doc/packaging.cli +++ b/doc/packaging.cli @@ -27,13 +27,8 @@ // // @@ Mapping to system package manager names/versions. // -// !! bdep-new: export stub for executables. -// // @@ Are upstream tests well behaved? -- add never exit/take unreasonable time // -// !! on step -> in step -// !! failed that -> failing that -// " \h0#preface|Preface| @@ -1068,10 +1063,23 @@ projects will use the \c{\"\"} style inclusion for own headers. For example: \ $ bdep new --package \ --lang c++ \ - --type exe,no-subdir,prefix=foo \ + --type exe,no-subdir,prefix=foo,export-stub \ foo \ +\N|The \c{export-stub} sub-option causes the generation of +\c{build/export.build}, an export stub that facilitates the importation of +targets from our package (see \l{b#intro-import Target Importation} for +details). The generation of this file for a library is the default since it +will normally be used by other projects and thus imported. An executable, +however, will only need an export stub if it can plausibly be used during the +build (see \l{intro#guide-build-time-linked Build-Time Dependencies and Linked +Configurations} for background). Source code generators are an obvious example +of such executables. A less obvious example would be compression utilities +such as \c{gzip} or \c{zstd}. If you are unsure, it's best to provide an +export stub.| + + \h2#core-package-review|Review and test auto-generated \c{buildfile} templates| Let's get a more complete view of what got generated by the final \c{bdep-new} @@ -1337,7 +1345,7 @@ Let's see how this works for our \c{libfoo} example. Say, the upstream version that we are packaging is \c{2.1.0}. This means we start with \c{2.1.0-a.0.z}. \N|Naturally, the upstream version that we are using should correspond to the -commit of the \c{upstream} submodule we have added on the +commit of the \c{upstream} submodule we have added in the \l{#core-repo-submodule Add upstream repository as \c{git} submodule} step.| Next we edit the \c{manifest} file in the \c{libfoo} package and change the @@ -1603,7 +1611,7 @@ $ git commit -m \"Add dependencies\" \h2#core-fill-source|Fill with upstream source code| Now we are ready to begin replacing the \c{bdep-new}-generated files with -upstream source code symlinks. We start with library's header and source +upstream source code symlinks. We start with the library's header and source files. Continuing with our \c{libfoo} example, this is what we currently have (notice that \c{LICENSE}, \c{README.md}, and \c{NEWS} are already symlinks to upstream): @@ -1632,8 +1640,8 @@ libfoo/ └── PACKAGE-README.md \ -Now we replace generated \c{include/foo/foo.hpp} with library's real headers -and \c{src/foo.cpp} with its real source files: +Now we replace generated \c{include/foo/foo.hpp} with the library's real +headers and \c{src/foo.cpp} with its real source files: \ $ cd libfoo/ # Change to the package root. @@ -1676,11 +1684,11 @@ make sure nothing is missing. Specifically, look out for: \li|Header/sources with other extensions, for example, C, Objective-C, etc.| -\li|Other files that may be need, for example, \c{.def}, \c{config.h.in}, etc.| +\li|Other files that may be needed, for example, \c{.def}, \c{config.h.in}, etc.| \li|Subdirectories that contain more header/source files.|| -If upstream contains subdirectories with addition header/source files, then +If upstream contains subdirectories with additional header/source files, then you can symlink entire subdirectories instead of doing it file by file. For example, let's say \c{libfoo}'s upstream source directory contains the \c{impl/} subdirectory with additional source files: @@ -1712,10 +1720,10 @@ libfoo/ Wouldn't it be nice if we could symlink the entire top-level subdirectories (\c{include/foo/} and \c{src/} in our case) instead of symlinking individual files? As discussed in \l{#core-package-craft-cmd Craft \c{bdep new} command -line to create package}, we can but we will need to change the package layout. -Specifically, we will need to move the \c{buildfiles} out of the source -subdirectories with the help of the \c{buildfile-in-prefix} sub-option of -\c{bdep-new}. In the above case, we will also need to invent a source +line to create package}, we can, but we will need to change the package +layout. Specifically, we will need to move the \c{buildfiles} out of the +source subdirectories with the help of the \c{buildfile-in-prefix} sub-option +of \c{bdep-new}. In the above case, we will also need to invent a source subdirectory in \c{src/}. Whether this is a worthwhile change largely depends on how many files you have to symlink individually. If it's just a handful, then it's probably not worth the complication, especially if you have to @@ -1777,8 +1785,8 @@ export stub that facilitates the importation of targets from our package (see Normally you don't need to change anything in \c{bootstrap.build} \- all it does is specify the build system project name and load a standard set of core -build system modules. Likewise, \c{export.build} is good as generated unless -you need to do something special, like exporting targets from different +build system modules. Likewise, \c{export.build} is ok as generated unless you +need to do something special, like exporting targets from different subdirectories of your package. While \c{root.build} is also often good as is, situations where you may @@ -1786,7 +1794,7 @@ need to tweak it are not uncommon and include: \ul| -\li|Loading additional build system module. +\li|Loading an additional build system module. For example, if your package makes use of Objective-C/C++ (see \l{b#c-objc Objective-C Compilation} and \l{b#cxx-objcxx Objective-C++ Compilation}) @@ -1827,7 +1835,7 @@ you can drop the assignment of the file extension for the \c{ixx{\}} and 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 +reconfigure the package. For example, let's 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: @@ -1889,9 +1897,9 @@ executables}.| The \c{buildfile} in \c{include/foo/} is pretty simple: -\N|The \c{buildfile} in your package may look slightly differently depending -on the exact \c{bdep-new} sub-options used. However, all the relevant -definitions discussed below should still be easily recognizable.| +\N|The \c{buildfile} in your package may look slightly different, depending on +the exact \c{bdep-new} sub-options used. However, all the relevant definitions +discussed below should still be easily recognizable.| \ pub_hdrs = {hxx ixx txx}{**} @@ -1908,7 +1916,7 @@ pub_hdrs = {hxx ixx txx}{**} } \ -Normally the only change that you would make to this \c{buildfile} is to +Normally, the only change that you would make to this \c{buildfile} is to adjust the installation location of headers (see \l{b#intro-operations-install Installing} for background). In particular, if our headers were included without the \c{<foo/...>} prefix but instead contained the library name in @@ -1962,7 +1970,7 @@ installation subdirectory?} Next is the \c{buildfile} in \c{src/}: -\N|Again, the \c{buildfile} in your package may look slightly differently +\N|Again, the \c{buildfile} in your package may look slightly different, depending on the exact \c{bdep-new} sub-options used. However, all the relevant definitions discussed below should still be easily recognizable. @@ -2060,7 +2068,7 @@ lib{foo}: \N|If you do have auto-generated headers, then in the split layout you can remove \c{out_pfx_inc} if you only have private auto-generated headers and -\c{out_pfx_src} if you only have public.| +\c{out_pfx_src} if you only have public ones.| \N|In the combined layout the single \c{buildfile} does not set the \c{*_pfx_*} variables. Instead it uses the \c{src_root} and \c{out_root} @@ -2157,7 +2165,7 @@ $ bdep sync -a --disfigure config.libfoo.debug=true | 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), +to \c{manifest} in the \l{#core-fill-depend Add dependencies} step), you need to first determine whether it's an interface of implementation dependency and then import it either into the \c{intf_libs} or \c{impl_libs} variable, respectively. @@ -2226,7 +2234,7 @@ here. If you need to exclude some headers, it should be done in the header \c{buildfile} in the \c{include/} directory. \N|In the combined layout the single \c{buildfile} does not have such code. -Instead, all the headers are covered by the wildcard pattern in following +Instead, all the headers are covered by the wildcard pattern in the following block.| @@ -2345,7 +2353,7 @@ lib{foo}: #libs{foo}: cxx.export.poptions += -DFOO_SHARED \ -The build options are in effect when the library itself is being build and the +The build options are in effect when the library itself is being built and the exported options are propagated to the library consumers (see \l{b#intro-lib Library Exportation and Versioning} for background on exported options). For now we will ignore the commented out lines that add \c{-DFOO_STATIC*} and @@ -2394,9 +2402,9 @@ 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, +\c{buildfile} language mechanisms (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. @@ -2418,7 +2426,7 @@ Note that outright replacing the preprocessor macros with metadata can be done if this information is only used by the library consumers. In other words, if the library's public headers rely on the presence of such macros, then we have no choice but to export them, potentially also providing the metadata so that -this information is easily accessible form \c{buildfiles}.| +this information is easily accessible from \c{buildfiles}.| Let's consider a representative example based on our \c{libfoo} to get a sense of what this normally looks like as well as to highlight a few nuances. We @@ -2484,7 +2492,7 @@ contain some values specified by the user with their \c{config.*.*} counterparts. On the other hand, the \c{*.export.*} variables are assigned. Secondly, the order in which we append to the variables is important for the -value to accumulate correctly. You want to fist append all the scope-level +value to accumulate correctly. You want to first append all the scope-level values, then target type/pattern-specific, and finally any target-specific; that is, from more general to more specific (see \l{b#intro-lang Buildfile Language} for background). To illustrate this point, let's say in our @@ -2518,11 +2526,11 @@ Let's now turn to a special sub-topic of the build and export options that relates to the shared library symbol exporting. To recap, a shared library on Windows must explicitly specify the symbols (functions and global data) that it wishes to make accessible by its consumers (executables and other shared -libraries). This can be achieved in three different way: The library can +libraries). This can be achieved in three different ways: The library can explicitly mark in its source code the names whose symbols should be exported. Alternatively, the library can provide a \c{.def} file to the linker that lists the symbols to be exported. Finally, the library can request -automatic exporting of all symbols, which is the default semantics on +the automatic exporting of all symbols, which is the default semantics on non-Windows platforms. Note that the last two approaches only work for exporting functions, not data, unless special extra steps are taken by the library consumers. Let's discuss each of these approaches in the reverse @@ -2634,8 +2642,8 @@ versioning where the package's major and minor version components are embedded into the shared library binary name (and \c{soname}) under the assumption that only patch versions are ABI-compatible. -The two situation where you would want to change this are when the above -assumption does not hold and/or when the upstream provides platform-specific +The two situations where you would want to change this are when the above +assumption does not hold and/or when upstream provides platform-specific shared library versions which you would like to re-create in your \c{build2} build. See \l{b#intro-lib Library Exportation and Versioning} for background and details. @@ -2649,7 +2657,10 @@ This \c{buildfile} will also be much simpler compared to the library's. For example, give the following \c{bdep-new} command: \ -$ bdep new --package --lang c++ --type exe,no-subdir,prefix=foo foo +$ bdep new --package \ + --lang c++ \ + --type exe,no-subdir,prefix=foo,export-stub \ + foo \ The resulting source \c{buildfile} will look like this: @@ -2686,7 +2697,7 @@ libs = exe{foo}: {hxx ixx txx cxx}{**} $libs testscript \ -\N|Unfortunately it's not uncommon for projects that provide both a library +\N|Unfortunately, it's not uncommon for projects that provide both a library and an executable, for the executable source code to include public and/or private library headers with the relative \c{\"\"} style inclusion. For example: @@ -2709,7 +2720,7 @@ that simply include the corresponding public header from the library using the For private headers we can provide, again in the appropriate places within the executable package, our own symlinks for a subset of private headers. Note that this will only work if the use of private headers within the executable -does not depend on any symbols that are not exported by the library (failed +does not depend on any symbols that are not exported by the library (failing that, the executable will have to always link to the static variant of the library). @@ -2742,7 +2753,7 @@ physically modifying upstream source code. \N{See the \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 +\N|We will discuss the \c{testscript} prerequisite in the \l{#core-test-smoke-exe Make smoke test: executables} step below.| @@ -2805,10 +2816,10 @@ the library and, if it has any unit tests in the source subdirectory, even run some tests. \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 +there are unit tests. Still, you may want to continue with this exercise to detect any syntactic mistakes in the \c{buildfiles}, etc.| -To build only a specific subdirectory of our package we use the build system +To build only a specific subdirectory of our package, we use the build system directly (continuing with our \c{libfoo} example): \ @@ -3113,9 +3124,9 @@ $ b test then the above \c{configure} operation will most likely fail because such dependencies cannot be found (it may succeed if they are available as system-installed). The error message will suggest specifying the location of -each dependency with \c{config.import.*} variable. You can fix this by setting -each such \c{config.import.*} to the location of the default build -configuration (created on the \l{#core-fill-init Initialize package in build +each dependency with the \c{config.import.*} variable. You can fix this by +setting each such \c{config.import.*} to the location of the default build +configuration (created in the \l{#core-fill-init Initialize package in build configurations} step) which should contain all the necessary dependencies. Simply re-run the \c{configure} operation until you have discovered and specified all the necessary \c{config.import.*} variables, for @@ -3181,9 +3192,9 @@ 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 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 +you would want to fix this in upstream and have a new version released. +Failing 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 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 @@ -3284,7 +3295,7 @@ In this case it is natural to replace the contents of the smoke test with the upstream source code, potentially renaming the test subdirectory (\c{basics/}) to better match upstream naming. -If upstream has multiple test executables, then they could all be in single +If upstream has multiple test executables, then they could all be in a single test subdirectory (potentially reusing some common bits) or spread over multiple subdirectories. In both cases it's a good idea to follow the upstream structure unless you have good reasons to deviate. In the former case (all @@ -3305,10 +3316,10 @@ following section for an example.| \li|\b{Are upstream tests well behaved?} -Unfortunately it's not uncommon for upstream tests not to behave well, such as -write diagnostics to \c{stdout} instead of \c{stderr}, create temporary files -without cleaning them up, or assume presence of input files in the current -working directory. For details on how to deal with such situations see +Unfortunately, it's not uncommon for upstream tests not to behave well, such +as to write diagnostics to \c{stdout} instead of \c{stderr}, create temporary +files without cleaning them up, or assume presence of input files in the +current working directory. For details on how to deal with such situations see \l{https://github.com/build2/HOWTO/blob/master/entries/sanitize-test-execution.md How do I sanitize the execution of my tests?}|| @@ -3423,7 +3434,7 @@ subdirectories that need building plus list targets that are usually found in the root directory of a project, typically \c{README.md}, \c{LICENSE}, etc. This is what the generated root \c{buildfile} looks like for our \c{libfoo} project assuming we have symlinked \c{README.md}, \c{LICENSE}, and -\c{NEWS} from upstream on the \l{#core-package-create Create final package} +\c{NEWS} from upstream in the \l{#core-package-create Create final package} step: \ @@ -3451,7 +3462,7 @@ called \c{foo.1}: | -\N|One file you don't need listing is \c{INSTALL} (or equivalent) which +\N|One file you don't need to list is \c{INSTALL} (or equivalent) which normally contains the installation instructions for the upstream build system. In the \c{build2} package of a third-party project the \c{PACKAGE-README.md} file serves this purpose (see @@ -3461,8 +3472,8 @@ system. In the \c{build2} package of a third-party project the \h2#core-root-buildfile-doc|Adjust root \c{buildfile}: other subdirectories| If the upstream project has other subdirectories that makes sense to include -into the \c{build2} package, then now is good time to take care of that. The -most common such case will be extra documentation (besides the root +into the \c{build2} package, then now is a good time to take care of that. +The most common such case will be extra documentation (besides the root \c{README}), typically in a subdirectory called \c{doc/}, \c{docs/}, or \c{documentation/}. @@ -3493,7 +3504,7 @@ $ cd libfoo/ # Change to the package root. $ ln -s ../upstream/docs ./ \ -The adjustment to the root \c{buildfile} are pretty straightforward: we +The adjustments to the root \c{buildfile} are pretty straightforward: we exclude the \c{docs/} subdirectory (since it has no \c{buildfile}) and list the \c{*.md} files as prerequisites using the \c{doc{\}} target type (which, in particular, makes sure they are installed into the appropriate location): @@ -3511,7 +3522,7 @@ installation location of the files in \c{docs/} because there is another \c{README.md} inside and that would conflict with the root one when installed into the same location. This time we cannot symlink the top-level \c{docs/} subdirectory (because we need to place a \c{buildfile} there). The two options -here is to either symlink the individual files or introduce another +here are to either symlink the individual files or introduce another subdirectory level inside \c{docs/} (which is the same approach as discussed in \l{#dont-main-target-root-buildfile Don't build your main targets in the root \c{buildfile}}). Let's illustrate both sub-cases. @@ -3575,9 +3586,9 @@ doc{*}: } \ -\N|A yet another option would be to open a scope for the \c{docs/} -subdirectory directly in the root \c{buildfile} (see \l{b#intro-dirs-scopes -Output Directories and Scopes} for background). For example: +\N|Yet another option would be to open a scope for the \c{docs/} subdirectory +directly in the root \c{buildfile} (see \l{b#intro-dirs-scopes Output +Directories and Scopes} for background). For example: \ $ cd libfoo/ # Change to the package root. @@ -3667,7 +3678,7 @@ You can find the description of these and other package \c{manifest} values in in \l{bpkg#manifest-format Manifest Format}). In the above listing the values that we likely need to adjust are \c{summary} -and \c{license}, unless correctly auto-detected by \c{bdep-new} on the +and \c{license}, unless correctly auto-detected by \c{bdep-new} in the \l{#core-package-create Create final package} step. See \l{#core-root-manifest-summary Adjust \c{manifest}: \c{summary}} and \l{#core-root-manifest-license Adjust \c{manifest}: \c{license}} below @@ -3882,7 +3893,7 @@ $ git push \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 +\c{README.md} in the root of our package repository (it was created in the \l{#core-repo-init Initialize package repository with \c{bdep new}} step). \N|If you need to add additional packages and are doing this one package at a @@ -3993,8 +4004,8 @@ as the organization to transfer to, and complete the transfer. Once transferred, you will be considered the maintainer of this package going forward. If other members of the \c{build2-packaging} organization wish to participate in the package maintenance, the correct etiquette is to do this -via pull requests. However, if you loose interest in maintaining a package or -otherwise become unresponsive, we may allow a new maintainer may take over +via pull requests. However, if you lose interest in maintaining a package or +otherwise become unresponsive, we may allow a new maintainer to take over this role. \N|In extraordinary circumstances the \c{build2-packaging} administrators may @@ -4021,8 +4032,8 @@ background). Besides replacing the \c{version} value in the package the \c{git} command to do so). This command also by default \"opens\" the next development version, which is something that we normally want for our own projects but not when we package a third-party one (since we cannot predict -which version the upstream will release next). So we disable this -functionality. For example: +which version upstream will release next). So we disable this functionality. +For example: \ $ cd foo/ # Change to the package repository root. @@ -4059,8 +4070,9 @@ $ bdep publish The \c{bdep-publish} command prepares the source distribution of your package, uploads the resulting archive to the package repository, and prints a link to the package submission in the queue. Open this link in the browser and check -that there are no surprises in build results (they should match the earlier CI -results) or in the displayed package information (\c{PACKAGE-README.md}, etc). +that there are no surprises in the build results (they should match the +earlier CI results) or in the displayed package information +(\c{PACKAGE-README.md}, etc). \N|While there should normally be no discrepancies in the build results compared to our earlier CI submissions, the way the packages are built on CI @@ -4101,7 +4113,7 @@ package. Updating such a file without changing the version is ok since the package remains unchanged.| While in our own projects we can change the versions as we see fit, with -third-party projects the versions are dictated by the upstream and as a result +third-party projects the versions are dictated by upstream and as a result we are limited to what we can use to fix issues in our packaging work itself. It may be tempting (and perhaps even conceptually correct) to release a patch version for our own fixes, however, we will be in trouble if later @@ -4133,13 +4145,13 @@ procedure.| \li|When a new upstream version is released, for example version \c{2.2.0}, and we wish to upgrade our package to this version, we switch to its -pre-release snapshot version (\c{2.2.0-a.0.z}) the same way as we did on the +pre-release snapshot version (\c{2.2.0-a.0.z}) the same way as we did in the \l{#core-package-adjust-version Adjust package version} step initially. See \l{#core-version-management-new-version New version} for the detailed procedure.| \li|Once we are done upgrading to the new upstream version, we release the -final version just like on the \l{#core-release-publish-release Release final +final version just like in the \l{#core-release-publish-release Release final version} step initially. At this point the package enters another revision phase.|| @@ -4164,7 +4176,7 @@ accumulated issues that didn't warrant a revision on their own. See accumulated issues} for background.| In the revision phase of the package version lifecycle (i.e., when the version -does not end with \c{-a.0.z}), every commit must be accompanies by the +does not end with \c{-a.0.z}), every commit must be accompanied by the revision increment to maintain continuous versioning. As a result, each revision release commit necessarily also contains the changes in this revision. Below is a typical workflow for releasing and publishing the @@ -4365,7 +4377,7 @@ in \c{buildfiles} to the existing package. In a sense, this approach uses \h2#core-version-management-new-version-dependencies|New version: new/old dependencies| If upstream added new or removed old dependencies, then you will need to -replicate these changes in your package as on the \l{#core-fill-depend Add +replicate these changes in your package as in the \l{#core-fill-depend Add dependencies} and \l{#core-adjust-build-src-source-dep Adjust source \c{buildfile}: dependencies} initial packaging steps. @@ -4373,7 +4385,7 @@ dependencies} and \l{#core-adjust-build-src-source-dep Adjust source \h2#core-version-management-new-version-sources|New version: new/old source files| If upstream added new or removed old source files, then you will need to -replicate these changes in your package as on the \l{#core-fill-source Fill +replicate these changes in your package as in the \l{#core-fill-source Fill with upstream source code} and possibly \l{#core-adjust-build-src-header Adjust header \c{buildfile}} and \l{#core-adjust-build-src-source-src Adjust source \c{buildfile}: sources, private headers} initial packaging steps. @@ -4383,7 +4395,7 @@ remove old source files (typically new tests). See \l{#core-test-upstream-convert Convert smoke test to upstream tests}. If there are any manual modifications to the upstream source code, then you -will also need to re-apply them to the new version as discussion in +will also need to re-apply them to the new version as discussed in \l{#howto-patch-upstream-source-manual Modifying upstream source code manually}. @@ -4534,16 +4546,16 @@ package} for details. \h#dont-fix-upstream|Avoid fixing upstream issues in the \c{build2} package| Any deviations from upstream makes the \c{build2} package more difficult to -maintain. In particular, if you make a large number of changes to upstream +maintain. In particular, if you make a large number of changes to the upstream source code, releasing a new version will require a lot of work. As a result, it is recommended to avoid fixing upstream issues in the \c{build2} package. Instead, try to have the issues fixed upstream and wait for them to be released as a new version. -Sometimes, however, you may have no choice. For example, the upstream is -inactive or has no plans to release a new version with your fixes any time -soon. Or you may want to add support for a platform/compiler that upstream is -not willing or capable of supporting. +Sometimes, however, you may have no choice. For example, upstream is inactive +or has no plans to release a new version with your fixes any time soon. Or you +may want to add support for a platform/compiler that upstream is not willing +or capable of supporting. Note that even if you do fix some issues in the \c{build2} package directly, try hard to also incorporate them upstream so that you don't need to maintain @@ -4593,7 +4605,7 @@ library consumers, for example, inclusion of different headers.| | -If a compiled mode cannot be always used, then it may be tempting to support +If a compiled mode cannot always be used, then it may be tempting to support both modes by making the mode user-configurable. Unless there are strong reasons to, you should resist this temptation and, if the compiled mode is not universally usable, then use the header-only mode everywhere. @@ -4604,7 +4616,7 @@ maintain. If you really want to have the compiled mode, then the right way to achieve it is to work with upstream to fix any issues that prevent its use in \c{build2}. -There are, however, valid reasons why supporting both mode may be needed, the +There are, however, valid reasons why supporting both modes may be needed, the most common of which are: \ul| @@ -4631,7 +4643,7 @@ framework. This is especially common with \l{https://cppget.org/catch2 \c{catch2}} where one often encounters a comical situation with only a few kilobytes of library source code and over 600KB of \c{catch2.hpp}. -The extra size, while wasteful, if not the main issue, however. The bigger +The extra size, while wasteful, is not the main issue, however. The bigger problem is that if a bug is fixed in the bundled dependency, then to propagate the fix we will need to release a new version (or revision) of each package that bundles it. Needless to say this is not scalable. @@ -4643,7 +4655,7 @@ the same build with the symptoms ranging from compile errors to subtle runtime issues that are hard to diagnose. As a result, it is strongly recommended that you unbundle any dependencies -that the upstream may have bundled. In case of testing frameworks, see +that upstream may have bundled. In case of testing frameworks, see \l{https://github.com/build2/HOWTO/blob/master/entries/handle-tests-with-extra-dependencies.md How do I handle tests that have extra dependencies?} for the recommended way to deal with such cases. @@ -4664,7 +4676,7 @@ inside). However, this is not recommended except for the simplest of projects. Firstly, this quickly gets messy since you have to combine managing \c{README}, \c{LICENSE}, etc., and subdirectories with your main target -builds. More importantly, this also means that when you main target is +builds. More importantly, this also means that when your main target is imported (and thus the \c{buildfile} that defines this target must be loaded), your entire project will be loaded, including any \c{tests/} and \c{examples/} subprojects, and that is wasteful. @@ -4773,10 +4785,11 @@ drawback: you will have to keep re-applying the changes for every subsequent version unless and until upstream incorporates your changes. The other two options try to work around this drawback. -The first alternative option is to modify upstream source code automatically -during the build, typically using an ad hoc recipe. This approach works best -when the changes are regular and can be applied mechanically with something -like the \l{testscript#builtins-sed \c{sed} builtin}. +The first alternative option is to modify the upstream source code +automatically during the build, typically using an ad hoc recipe. This +approach works best when the changes are regular and can be applied +mechanically with something like the \l{testscript#builtins-sed \c{sed} +builtin}. The second alternative option is to use the C/C++ preprocessor to make the necessary changes to the upstream source code during compilation. Unlike the @@ -4859,7 +4872,7 @@ $ patch <foo.cpp.patch If some hunks of the patch could not be applied, manually resolve any conflicts.| -\li|If on the previous step the patch did not apply cleanly, regenerate it: +\li|If in the previous step the patch did not apply cleanly, regenerate it: \ $ diff -u foo.cpp.orig foo.cpp >foo.cpp.patch @@ -4948,13 +4961,13 @@ int main (int argc, const char** argv) The idea here is to rename the original \c{main()} with the help of the C preprocessor and provide our own \c{main()} which, after handling \c{--build2-metadata} calls the original. One notable deal-breaker for this -approach are C++ implementations of \c{main()} that don't have the explicit -\c{return}. There is also a better chance in C++ for the \c{main} macro to -replace something unintended. +approach would be a C++ implementation of \c{main()} that doesn't have the +explicit \c{return}. There is also a better chance in C++ for the \c{main} +macro to replace something unintended. -To complete this we also need to exclude \c{main.c} from compilation in -our \c{buildfile} (since it is compiled as part of \c{main-build2.c} via -the preprocessor inclusion). For example: +To complete this we also need to modify our \c{buildfile} to exclude +\c{main.c} from compilation (since it is compiled as part of \c{main-build2.c} +via the preprocessor inclusion). For example: \ exe{foo}: {h c}{** -main} @@ -4964,7 +4977,7 @@ exe{foo}: c{main}: include = adhoc # Included in main-build2.c. \h#howto-bad-inclusion-practice|How do I deal with bad header inclusion practice?| -This sections explains how to deal with libraries that include their public, +This section explains how to deal with libraries that include their public, generically-named headers without the library name as a subdirectory prefix. Such libraries cannot coexist, neither in the same build nor when installed. @@ -4992,18 +5005,18 @@ longer be possible to use a system-installed version of the package (because it presumably still uses the unqualified inclusion scheme). Note, however, that distributions like Debian and Fedora have the same co-existence issue as we do and are generally strict about potential header clashes. In -particular, it is not uncommon to find Debian packages installing library's +particular, it is not uncommon to find Debian packages installing library headers into subdirectories of \c{/usr/include} to avoid such clashes. And if you find this to be the case for the library you are packaging, then it may make sense to use the same prefix as used by the main distributions for compatibility. -It is also possible that distributions disregard this considerations for some +It is also possible that distributions disregard these considerations for some libraries. This usually happens for older, well-known libraries that happened to be installed this way in the early days and changing things now will be too disruptive. In a sense, it is understood that such libraries effectively -\"own\" the unqualified headers names that they happen to be using. If you -think you are packaging such a libraries, +\"own\" the unqualified header names that they happen to be using. If you +think you are packaging such a library, \l{https://build2.org/community.xhtml#help get in touch} to discuss this further since it may make sense to also disregard this rule in \l{https://cppget.org cppget.org}.| @@ -5116,7 +5129,7 @@ lib{foo}: cxx.pkgconfig.include = include/ include/libfoo/ \h#howto-extra-header-install-subdir|How do I handle extra header installation subdirectory?| -This sections explains how to handle an additional header installation +This section explains how to handle an additional header installation subdirectory. As an illustration of the problem, consider the \c{libfoo} example from the previous sections (see the \l{#core-fill-source Fill with upstream source code} step for a refresher). In that example the library @@ -5167,7 +5180,7 @@ lib{foo}: cxx.pkgconfig.include = include/\"foo-v$version.major\"/ \N|The variable will be \c{c.pkgconfig.include} for a C library.| -\h#howto-no-extension-header|How do I handle headers without extensions?| +\h#howto-no-extension-header|How do I handle headers without an extension?| If all the headers in a project have no extension, then you can simply specify the empty \c{extension} value for the \c{hxx{\}} target type @@ -5217,13 +5230,13 @@ for details. \h#howto-debug-macro|How do I expose extra debug macros of a library?| -Sometime libraries provide extra debugging facilities that are usually enabled -or disabled with a macro. For example, \c{libfoo} may provide the +Sometimes libraries provide extra debugging facilities that are usually +enabled or disabled with a macro. For example, \c{libfoo} may provide the \c{LIBFOO_DEBUG} macro that enables additional sanity checks, tracing, etc. -Normally such facilities are disable by default. +Normally, such facilities are disabled by default. While it may seem like a good idea to detect a debug build and enable this -automatically, it is not: such facilities usually impose substantial overhead +automatically, it is not: such facilities usually impose substantial overheads and the presence of debug information does not mean that performance is not important (people routinely make optimized builds with debug information). @@ -5268,7 +5281,7 @@ semantics), the other option is to hook it up to the standard \c{NDEBUG} macro, for example, in the library's configuration header file.| Note that such \c{.debug} configuration variables should primarily be meant -for the user to selectively enabled extra debugging support in certain +for the user to selectively enable extra debugging support in certain libraries of their build. However, if your project depends on a number of libraries with such extra debugging support and it generally makes sense to also enable this support in dependencies if it is enabled in your project, @@ -5279,9 +5292,9 @@ should still allow the user to override this decision on the per-dependency basis. Continuing with the above example, let's say we have \c{libbar} with -\c{config.libbar.debug} that depends on \c{libfoo} and that wishes to by -default enable debugging in \c{libfoo} if it is enabled in \c{libbar}. -This is how we can correctly arrange for this in \c{libbar}'s \c{manifest}: +\c{config.libbar.debug} that depends on \c{libfoo} and wishes by default to +enable debugging in \c{libfoo} if it is enabled in \c{libbar}. This is how we +can correctly arrange for this in \c{libbar}'s \c{manifest}: \ depends: |