diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.gitignore | 6 | ||||
| -rw-r--r-- | doc/buildfile | 2 | ||||
| -rwxr-xr-x | doc/cli.sh | 7 | ||||
| -rw-r--r-- | doc/intro.cli | 4 | ||||
| -rw-r--r-- | doc/packaging.cli | 212 |
5 files changed, 223 insertions, 8 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index 585f985..584c284 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,3 +1,3 @@ -build2-toolchain-*.ps -build2-toolchain-*.pdf -build2-toolchain-*.xhtml +build2-*.ps +build2-*.pdf +build2-*.xhtml diff --git a/doc/buildfile b/doc/buildfile index cae209e..5d78ced 100644 --- a/doc/buildfile +++ b/doc/buildfile @@ -4,7 +4,7 @@ define css: file css{*}: extension = css -./: doc{build2-toolchain-*} \ +./: doc{build2-*} \ css{code-box common doc pre-box toc} \ file{install.cli intro.cli doc-* *.html2ps} @@ -15,7 +15,9 @@ while [ $# -gt 0 ]; do case $1 in --clean) rm -f build2-toolchain-intro.xhtml build2-toolchain-intro*.ps \ - build2-toolchain-intro*.pdf +build2-toolchain-intro*.pdf + rm -f build2-packaging-guide.xhtml build2-packaging-guide*.ps \ +build2-packaging-guide*.pdf rm -f build2-toolchain-install.xhtml build2-toolchain-install*.ps \ build2-toolchain-install*.pdf exit 0 @@ -64,8 +66,9 @@ function gen () # <name> ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true build2-toolchain-$n-letter.ps build2-toolchain-$n-letter.pdf } -gen intro #gen intro1 +gen intro +gen packaging # Auto-heading doesn't work since it is broken into multiple doc strings. # diff --git a/doc/intro.cli b/doc/intro.cli index f25c359..b15a386 100644 --- a/doc/intro.cli +++ b/doc/intro.cli @@ -106,8 +106,8 @@ shows how the main components, namely the build system, the package dependency manager, and the project dependency manager are used together to handle the entire C/C++ project development lifecycle: creation, development, testing, and delivery. For additional information, including documentation for -individual toolchain components, man pages, etc., refer to the \c{build2} -project \l{https://build2.org/doc.xhtml Documentation} page. +individual toolchain components, man pages, HOWTOs, etc., refer to the +\c{build2} project \l{https://build2.org/doc.xhtml Documentation} page. \h1#guide|Getting Started Guide| diff --git a/doc/packaging.cli b/doc/packaging.cli new file mode 100644 index 0000000..db98c1d --- /dev/null +++ b/doc/packaging.cli @@ -0,0 +1,212 @@ +// file : doc/packaging.cli +// license : MIT; see accompanying LICENSE file + +"\name=build2-packaging-guide" +"\subject=toolchain" +"\title=Packaging Guide" + +// NOTES +// +// - Maximum <pre> line is 70 characters. +// + +" +\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 +\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 +\l{https://build2.org/doc.xhtml Documentation} page. + +\N|This document is a work in progress and is incomplete.| + + +\h1#dont-do|What Not to Do| + + +\h#dont-from-scratch|Don't write \c{buildfile}s from scratch, use \c{bdep-new}| + +Unless you have good reasons not to, create the initial project layout +automatically using \l{bdep-new(1)}, then tweak it if necessary and fill with +upstream source code. + +The main rationale here is that there are many nuances in getting the build +right and auto-generated \c{buildfile}s had years of refinement and +fine-tuning. The familiar structure also makes it easier for others to +understand your build, for example while reviewing your package submission. + +The \l{bdep-new(1)} command supports a wide variety of +\l{bdep-new.xhtml#src-layout source layouts}. While it may take a bit of time +to understand the customization points necessary to achieve the desired layout +for your first package, this will pay off in spades when you work on +converting subsequent packages. The recommended sequence of steps is +as follows: + +\ol| + +\li|Study the upstream source layout. We want to stay as close to upstream as +possible since this has the best chance of producing an issues-free result +(see \l{#dont-change-upstream Don't change upstream source code layout} for +details).| + +\li|Craft and execute the \l{bdep-new(1)} command line necessary to achieve +the upstream layout.| + +\li|Study the auto-generated \c{buildfile}s for things that don't fit and need +to change. But don't rush to start manually editing the result. First get an +overview of the required changes and then check if it's possible to achieve +these changes automatically using one of \l{bdep-new(1)} sub-options. + +For example, if you see that the generated project assumes the wrong C++ file +extensions, these can be changed with \c{--lang|-l} sub-options.| + +\li|Once you have squeezed as much as possible out of \l{bdep-new(1)}, it's +time for manual customizations. These would normally include: + +\ul| + +\li|Replace generated source code with upstream, normally as symlinks from the + \c{upstream/} \c{git} submodule.| + +\li|Tweak source subdirectory \c{buildfile} that builds the main target + (library, executable).| + +\li|Add tests and, if necessary, examples.| + +\li|Tweak \c{manifest} (in particular the \c{version}, \c{summary}, and + \c{license} values).| + +\li|Fill in \c{README.md}.||| + +| + + +\h#dont-change-upstream|Don't change upstream source code layout| + +It's a good idea to stay as close to the upstream's source code layout as +possible. This has the best chance of giving us a build without any compile +errors since the header inclusion in the project can be sensitive to this +layout. This also makes it easier for upstream to adopt the \c{build2} +build. + +Sometimes, however, there are good reasons for deviating from upstream, +especially in cases where upstream is clearly following bad practices, for +example installing generically-named headers without a library prefix. If you +do decide to change the layout, it's usually less disruptive (to the build) to +rearrange things at the outer levels than at the inner. For example, it should +normally be possible to move/rename the top-level \c{tests/} directory or to +place the library source directory into a subdirectory. + + +\h#dont-header-only|Don't make a library header-only if it can be compiled| + +Some libraries offer two alternative modes: header-only and compiled. Unless +there are good reasons not to, a \c{build2} build of such a library should use +the compiled mode. + +\N|Some libraries use the \i{precompiled} term to describe the non-header-only +mode. We don't recommend using this term in the \c{build2} build since it has +a strong association with precompiled headers and can therefore be +confusing. Instead, use the \i{compiled} term.| + +The main rationale here is that a library would not be offering a compiled +mode if there were no benefits (usually faster compile times of library +consumers) and there is no reason not to take advantage of it in the +\c{build2} build. + +There are, however, reasons why a compiled mode cannot be used, the most +common of which are: + +\ul| + +\li|The compiled mode is not well maintained/tested by upstream and therefore +offers inferior user experience.| + +\li|The compiled mode does not work on some platforms, usually Windows due to +the lack of symbol export support (but see \l{b##cc-auto-symexport Automatic +DLL Symbol Exporting}).| + +\li|Uses of the compiled version of the library requires changes to the +library consumers, for example, inclusion of different headers.| + +| + +If a compiled mode cannot be always used, then it may be tempting to support +both modes potentially 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. + +The main rationale here is that variability adds complexity which makes the +result more prone to bugs, more difficult to use, and harder to review and +maintain. If you really want to have the compiled mode, then the right +way to do it is to work with upstream to fix any issues that prevent its +use in \c{build2}. + +There are, however, reasons why supporting both mode may be needed, the most +common of which are: + +\ul| + +\li|The library is widely used in both modes but switching from one mode to +the other requires changes to the library consumers (for example, inclusion of +different headers). In this case only supporting one mode would mean not +supporting a large number of library consumers.| + +\li|The library consists of a large number of independent components and its +common for applications to only use a small subset of them. On the other hand, +compiling all of them in the compiled mode takes a substantial amount of time. +(Note that this can also be addressed by making the presence of optional +components user-configurable.)| + +| + + +\h#dont-main-target-root-buildfile|Don't build your main targets in root \c{buldfile}| + +It may be tempting to have your main targets (libraries, executables) in the +root \c{buildfile}, especially if it allows you to symlink entire directories +from \c{upstream/} (which is not possible if you have to have a \c{buildfile} +inside). However, this is a bad idea except for the simplest projects. + +Firstly, this quickly gets messy since you have to combine managing +\c{README}s, \c{LICENSE}s, and subdirectories with you main target builds. +But, more importantly, this means that when you 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/} subproject, +which is wasteful. + +Note also that it's easy to continue symlinking entire directories from +\c{upstream/} without moving everything to the root \c{buildfile} by simply +creating another subdirectory. Let's look at a concrete example. Here is +the directory structure where everything is in the root \c{buildfile}: + +\ +libigl-core/ +├── igl/ -> upstream/igl/ +├── tests/ +└── buildfile # Defines lib{igl-core}. +\ + +And here is the alternative structure where we have added the \c{libigl-core} +subdirectory with its own \c{buildfile}: + +\ +libigl-core/ +├── libigl-core/ +│ ├── igl/ -> ../upstream/igl/ +│ └── buildfile # Defines lib{igl-core}. +├── tests/ +└── buildfile +\ + +Below is the \l{bdep-new(1)} invocation that can be used to automatically +create this alternative structure (see \l{bdep-new.xhtml#src-layout SOURCE +LAYOUT} for details): + +\ +$ bdep new -t lib,prefix=libigl-core,no-subdir,no-version libigl-core +\ + +" |