diff options
| m--------- | bpkg | 0 | ||||
| -rw-r--r-- | doc/packaging.cli | 93 |
2 files changed, 91 insertions, 2 deletions
diff --git a/bpkg b/bpkg -Subproject 5e77b34314563a1943d3fa0e9706a2c4658168e +Subproject 5b5b63886b0555c9697061601f865dfbced4764 diff --git a/doc/packaging.cli b/doc/packaging.cli index 0090c67..c1e79a9 100644 --- a/doc/packaging.cli +++ b/doc/packaging.cli @@ -13,8 +13,8 @@ " \h0#preface|Preface| -This document provides guidelines for converting third-party projects to the -\c{build2} build system and making them available as packages from +This document provides guidelines for converting third-party C/C++ projects to +the \c{build2} build system and making them available as packages from \l{https://cppget.org cppget.org}, the \c{build2} community's central package repository. For additional information, including documentation for individual \c{build2} toolchain components, man pages, HOWTOs, etc., refer to the project @@ -23,6 +23,94 @@ repository. For additional information, including documentation for individual \N|This document is a work in progress and is incomplete.| +\h1#intro|Introduction| + +The aim of this guide is to ease the convertion of third-party C/C++ projects +to the \c{build2} build system and publishing them to the +\l{https://cppget.org cppget.org} package repository by codifying the best +practices and techniques. By following the presented guidelines you also make +it easier for others to review your work and help with ongoing maintenance. + +The primary focus of this guide are existing C/C++ projects that use a +different build system and that are maintained by a third-party, which we will +refer to as \i{upstream}. Unless upstream is willing to incorporate support +for \c{build2} directly into their repository, such projects are normally +packaged for \c{build2} in a separate \c{git} repository under the +\l{https://github.com/build2-packaging github.com/build2-packaging} +organization. Note, however, that many of the presented guidelines are also +applicable when converting your own projects (that is, where you are the +upstream) as well as projects that use languages other than C or C++. + +Most C/C++ packages that are published to \l{https://cppget.org cppget.org} +are either libraries or executables (projects that provide both are normally +split into several packages) with libraries being in the strong majority. +Libraries are also generally more difficult to build correctly. As a result, +this guide uses libraries as a baseline. In most cases, a library-specific +step is easily distinguished as such and can be skipped when dealing with +executables. And in cases where a more nuanced change is required, a note will +be provided. + +At the high-level, packaging a third-party project involves the following +steps: + +\ol| + +\li|Create the \c{git} repository and import upstream source code.| + +\li|Generate \c{buildfile} templates that match upstream layout.| + +\li|Tweak the generated \c{buildfiles} to match upstream build.| + +\li|Test using the \l{https://ci.cppget.org \c{build2} CI service}.| + +\li|Publish the package to \l{https://cppget.org cppget.org}.| + +| + +Once this process is completed and the package is published, new releases +normally require a small amount of work provided there are no drastic changes +in the upstream layout or build. The sequence of steps for a new release would +typical look like this: + +\ol| + +\li|Add new and/or remove old upstream source code, if any.| + +\li|Tweak \c{buildfiles} to match changes to upstream build, if any.| + +\li|Test using the \l{https://ci.cppget.org \c{build2} CI service}.| + +\li|Publish the package to \l{https://cppget.org cppget.org}.| + +| + +While packaging a simple library or executable is relatively straightforward, +the C and C++ languages and their ecosystem is famous for a large amount +varience in the platforms, compilers, and build systems used. This leads to +what appears to be an endless list of special considerations that are +applicable in certain, more complex cases. + +As result, the presented guidelines are divided into four chapters: The +\l{#core Core Guidelines} cover steps that are applicable to all or most +packaging efforts. As mentioned earlier, these steps will assume packaging a +library but they should be easy to adapt to executables. This chapter is +followed by \l{#dont-do What Not to Do} which covers the common packaging +mistakes and omissions. These are unfortunately relatively common because +experience with other build systems often does not translate directly to +\c{build2} and some techniques (such as header-only libraries) are +discouraged. The last two chapters are \l{#howto HOWTO} and \l{#faq FAQ} which +cover the above-mentioned long list of special considerations that are only +applicable in certain cases as well as answer frequent packaging-related +questions, respectively. + +Besides the presented guidelines you may also find the existing packages found +in \l{https://github.com/build2-packaging github.com/build2-packaging} a good +source of example material. The repositories pinned to the front page are the +recommended starting point. + + +\h1#core|Core Guidelines| + \h1#dont-do|What Not to Do| @@ -292,6 +380,7 @@ LAYOUT} for details): $ bdep new -t lib,prefix=libigl-core,no-subdir,no-version libigl-core \ +\h1#howto|Packaging HOWTO| \h1#faq|Packaging FAQ| |