Start packaging guide

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}
 
diff --git a/doc/cli.sh b/doc/cli.sh
index e9acd6d..4ae9b63 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -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
+\
+
+"