diff options
| -rw-r--r-- | doc/packaging.cli | 68 |
1 files changed, 64 insertions, 4 deletions
diff --git a/doc/packaging.cli b/doc/packaging.cli index 3ccd4b6..ada96ed 100644 --- a/doc/packaging.cli +++ b/doc/packaging.cli @@ -816,7 +816,7 @@ project include: \dl| -\li|\n\c{no-version} +\li|\n\cb{no-version} Omit the auto-generated version header. Usually upstream will provided its own equivalent to this functionality. @@ -827,7 +827,7 @@ since upstream may add it in a future version and you may end up with a conflict. Instead, work with the project maintainer to rectify this in upstream.|| -\li|\n\c{no-symexport}\n\c{auto-symexport} +\li|\n\cb{no-symexport}\n\cb{auto-symexport} The \c{no-symexport} sub-option suppresses the generation of the DLL symbol exporting header. This is an appropriate option if upstream provides its @@ -840,12 +840,72 @@ support in the existing build system. It is also recommended that you give this functionality a try even if upstream does not support building shared libraries on Windows.| -\li|\n\c{binless} +\li|\n\cb{binless} Create a header-only library template. See \l{#dont-header-only Don't make library header-only if it can be compiled} and \l{https://github.com/build2/HOWTO/blob/master/entries/make-header-only-library.md -How do I make a header-only C/C++ library?}|| +How do I make a header-only C/C++ library?}| + +\li|\n\cb{buildfile-in-prefix} + +Place header/source \c{buildfile}s into the header/source prefix directory +instead of include subdirectory. To illustrate the difference, compare these +two auto-generated layouts paying attention to the location of \c{buildfile}s: + +\ +$ bdep new ... --type lib,split libfoo +$ tree libfoo/ +libfoo/ +├── include/ +│ └── foo/ +│ ├── buildfile +│ └── foo.hpp +└── src/ + └── foo/ + ├── buildfile + └── foo.cpp +\ + +\ +$ bdep new ... --type lib,split,buildfile-in-prefix libfoo +$ tree libfoo/ +libfoo/ +├── include/ +│ ├── foo/ +│ │ └── foo.hpp +│ └── buildfile +└── src/ + ├── foo/ + │ └── foo.cpp + └── buildfile +\ + +Note that this sub-option can only be used if both the header and source +directories (\c{include/} and \c{src/} in our case) have an include +subdirectory (\c{foo/} in our case). + +Why would we want to do this? The main reason is to be able to symlink the +entire upstream directories rather than individual files. In the first +listing, the generated \c{buildfile}s are inside the \c{foo/} subdirectories +which mean we cannot just symlink \c{foo/} from upstream. This can be such a +strong motivation that it may make sense to invent an include subdirectory in +the source directory even if upstream doesn't have one. See +\l{#dont-main-target-root-buildfile Don't build your main targets in root +\c{buldfile}} for details on this technique. + +Another reason we may want to move \c{buildfile}s to prefix is to be able to +handle upstream projects that may have multiple such include subdirectories. +While this situation not very common in the header directory, it can be +enountered in the source directory of more complex projects where upstream +wishes to seperate the source code into components.|| + +@@ Terminology does not match bdep-new 'include subdirectory'. Maybe change +in bdep-new? 'source prefix directory' and 'source subdirectory' are quite +close. But then include subdirectory inside src sounds like an oxymoron. +I believe this is also consistent with Canonical Project Structure. + +@@ 'Don't build your main targets in root buldfile' needs work. Continuing with our \c{libfoo} example, assuming upstream provides own symbol exporting, the final \c{bdep-new} command line would be: |