diff options
| -rw-r--r-- | NEWS | 106 | ||||
| -rw-r--r-- | doc/manual.cli | 62 |
2 files changed, 98 insertions, 70 deletions
@@ -2,8 +2,8 @@ Version 0.13.0 * Support for project-specific configuration. - A project can now use the new config directive to define config.* - variables similar to the build system core and modules. For example: + A project can now use the config directive to define config.<porject>.* + variables, similar to the build system core and modules. For example: config [bool] config.libhello.fancy ?= false config [string] config.libhello.greeting ?= 'Hello' @@ -21,18 +21,20 @@ Version 0.13.0 * Support for ad hoc recipes. - With ad hoc recipes we can now provide custom implementation of operations - (update, test, etc) for certain targets. For example: + With ad hoc recipes it is now possible to provide custom implementations + of operations (update, test, etc) for certain targets. For example, this + is how we can pick a config header based on the platform: - hxx{config}: hxx{config-linux}: include = ($cxx.target.class == 'linux') - hxx{config}: hxx{config-windows}: include = ($cxx.target.class == 'windows') - hxx{config}: hxx{config-macos}: include = ($cxx.target.class == 'macos') + hxx{config}: hxx{config-linux}: include = ($cxx.target.class == 'linux') + hxx{config}: hxx{config-win32}: include = ($cxx.target.class == 'windows') + hxx{config}: hxx{config-macos}: include = ($cxx.target.class == 'macos') hxx{config}: {{ cp $path($<) $path($>) }} - Another, more elaborate example: + Another, more elaborate example that shows how to embed binary data into + the source code with the help of the xxd(1) utility: import! xxd = xxd%exe{xxd} @@ -49,6 +51,10 @@ Version 0.13.0 # $xxd -s -1 -l 1 $i | sed -n -e 's/^([0-9]+):.*$/\1/p' - | set pos + if ($empty($pos)) + exit "unable to extract input size from xxd output" + end + # Write header and source. # echo "#pragma once" >$h @@ -62,9 +68,9 @@ Version 0.13.0 which means these recipes are portable. See the Testscript manual for the list of available builtins. - Ad hoc recipes can also be used to customize a part of the build chain - handled by rules. For example, in embedded systems development it is often - required to perform a custom link step: + Ad hoc recipes can also be used to customize a part of the update chain + otherwise handled by rules. For example, in embedded systems development + it is often required to perform a custom link step: obje{foo}: cxx{foo} obje{bar}: cxx{bar} @@ -75,8 +81,8 @@ Version 0.13.0 $cxx.libs $cc.libs }} - While the above recipes are for the update operation, ad hoc recipes can - be used for other operations, such as test. For example: + While the above examples are all for the update operation, ad hoc recipes + can be used for other operations, such as test. For example: exe{hello}: cxx{hello} % test @@ -100,9 +106,9 @@ Version 0.13.0 } }} - In this release support for ad hoc recipe is at the "technology preview" - stage. In particular, there is no documentation and are known rough edges, - especially around diagnostics. + Note that in this release support for ad hoc recipe is at the "technology + preview" stage. In particular, there is no documentation and are known + rough edges. * Support for project-local importation. @@ -114,7 +120,7 @@ Version 0.13.0 include ../libhello/ exe{hello}: ../libhello/lib{hello} - Can now do this: + Can now do: import lib = lib{hello} exe{hello}: $lib @@ -123,19 +129,21 @@ Version 0.13.0 in the project's export stub. In other words, project-local importation goes through the same mechanism as normal import. + See the "Target Importation" section in the manual for details. + * Support for ad hoc importation and "glue buildfiles". If the target being imported has no project name and is either absolute or is a relative directory, then this is treated as ad hoc importation. - Semantically it is similar to a normal import but with the location of the - project being imported hard-coded into the buildfile. + Semantically it is similar to normal importation but with the location of + the project being imported hard-coded into the buildfile. - This type of import can be used to create a special "glue buildfile" that - "pulls" together several projects, usually for convenience of development. - One typical case that calls for such a glue buildfile is a multi-package - project. To be able to invoke the build system driver directly in the - project root, we can add a glue buildfile that imports and builds all the - packages: + In particular, this type of import can be used to create a special "glue + buildfile" that "pulls" together several projects, usually for convenience + of development. One typical case that calls for such a glue buildfile is a + multi-package project. To be able to invoke the build system directly in + the project root, we can add a glue buildfile that imports and builds all + the packages: import pkgs = */ ./: $pkgs @@ -159,13 +167,13 @@ Version 0.13.0 ./: ... doc{README} legal{LICENSE} - $ b install ... config.install.legal=/usr/share/licenses/hello/ + $ b install ... config.install.legal='share/licenses/<project>/' * Support for <var>-substitutions in config.install.* values. The currently recognized variable names are <project> and <private> which - are substituted with the project name and private subdirectory, - respectively. This can be used along these lines: + are replaced with the project name and private subdirectory, respectively. + This can be used along these lines: $ b config.install.libexec='exec_root/lib/<project>/' install @@ -183,25 +191,26 @@ Version 0.13.0 * New $defined(<variable>) and $visibility(<variable>) functions. - * New $target.process_path() function analogous to $target.path(). + * New $target.process_path() function for exe{} targets analogous to + $target.path(). * New $bin.link_member() function. - Given a linker output target type ("exe", "lib[as]", or "libu[eas]") this - function returns the target type of lib{} group member ("liba" or "libs") - that will be picked when linking a lib{} group to this target type. + Given a linker output target type (exe, lib[as], or libu[eas]) this + function returns the target type of lib{} group member (liba or libs) that + will be picked when linking a lib{} group to this target type. * New scripting builtins: date, env. * New variable block applicability semantics in dependency chains. - Before the block used to apply to the set of prerequisites before the last + Prior the block used to apply to the set of prerequisites before the last colon. This turned out to be counterintuitive and not very useful since prerequisite-specific variables are less common than target-specific. - The new rule is if the chain ends with the colon, then the block applies - to the last set of prerequisites. Otherwise, it applies to the last set of - targets. For example: + The new rule is as follows: if the chain ends with the colon, then the + block applies to the last set of prerequisites. Otherwise, it applies to + the last set of targets. For example: ./: exe{test}: cxx{main} { @@ -216,13 +225,14 @@ Version 0.13.0 * Test and install modules are now implicitly loaded for simple projects. While these can be useful on their own, this also makes the test and - install operations available in simple projects, which is handy for "glue" - projects that "pull" (using ad hoc import) a bunch of other projects. + install operations available in simple projects, which is handy for "glue + buildfiles" that "pull" (using ad hoc import) a bunch of other projects. * The translated {c,cxx}.std options are now folded into the compiler mode - options. This makes them accessible from ad hoc recipes. + options ({c,cxx}.mode). This makes them accessible from ad hoc recipes. - * Common pkg-config .pc file in addition to static/shared-specific. + * Generation of a common pkg-config .pc file in addition to static/shared- + specific. The common .pc file is produced by ignoring any static/shared-specific poptions and splitting loptions/libs into Libs/Libs.private. @@ -234,21 +244,21 @@ Version 0.13.0 * The ~host configuration now only contains the cc and bin modules configuration. - Also added the ~build2 configuration that contains everything (except - config.dist.*) to be used for build system modules. + There is also the new ~build2 configuration that contains everything + (except config.dist.*) and is meant to be used for build system modules. * Reworked tool importation support. Specifically, now config.<tool> (like config.cli) is handled by the import - machinery (it is like a shorter alias for config.import.<tool>.<tool>.exe - that we already had). + machinery (it is a shorter alias for config.import.<tool>.<tool>.exe that + we already had). This also adds support for uniform tool metadata extraction that is handled by the import machinery. As a result, a tool that follows the "build2 way" can be imported with metadata by the buildfile and/or corresponding module without any tool-specific code or brittleness associated with parsing --version or similar outputs. See the cli - tool/module for details. + tool/module for an example of how this all fits together. Finally, two new flavors of the import directive are now supported: import! triggers immediate importation skipping any rule-specific logic @@ -262,10 +272,10 @@ Version 0.13.0 if ($cli != [null]) info "cli version $($cli:cli.version)" - * Reserved backtick (`) and bit-or (|) in evaluation context for future use. + * Backtick (`) and bit-or (|) are reserved in eval context for future use. - Specifically, they are reserved for future support of arithmetic - evaluation contexts and evaluation pipelines, respectively. + Specifically, they are reserved for planned support of arithmetic eval + contexts and evaluation pipelines, respectively. Version 0.12.0 diff --git a/doc/manual.cli b/doc/manual.cli index 5b54882..dd449ce 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -775,15 +775,22 @@ hello/ inclusion scheme where each header is prefixed with its project name. It also has a predictable name where users can expect to find our project's source code. Finally, this layout prevents clutter in the project's root directory -which usually contains various other files. See \l{intro#structure-canonical -Canonical Project Structure} for more information. +which usually contains various other files. See \l{intro#proj-struct Canonical +Project Structure} for details. + +Note, however, that this layout is not mandatory and \c{build2} is flexible +enough to support various arrangements used in today's C and C++ projects. +Furthermore, the \l{bdep-new(1)} command provides a number of customization +options and chances are you will be able to create your preferred layout +automatically. See \l{bdep-new.xhtml#src-layout SOURCE LAYOUT} for more +information and examples. Note also that while we can name our header and source files however we like -(but, again, see \l{intro#structure-canonical Canonical Project Structure} for -some sensible guidelines), C++ module interface files need to embed a -sufficient amount of the module name suffix in their names to unambiguously -resolve all the modules within a project. See \l{#cxx-modules-build -Building Modules} for details.| +(but, again, see \l{intro#proj-struct Canonical Project Structure} for some +sensible guidelines), C++ module interface files need to embed a sufficient +amount of the module name suffix in their names to unambiguously resolve all +the modules within a project. See \l{#cxx-modules-build Building Modules} for +details.| The source subdirectory \c{buildfile} is identical to the simple project's minus the parts moved to \c{root.build}: @@ -854,7 +861,7 @@ Speaking of libraries, let's see what the standard project structure looks like for one, using \c{libhello} created by \l{bdep-new(1)} as an example: \ -$ bdep new --no-init -t lib libhello +$ bdep new --no-init -l c++ -t lib libhello $ tree libhello/ libhello/ @@ -883,6 +890,17 @@ contents of the project's source subdirectory, \c{libhello/}, look quite a bit different. We will examine all of these differences in the coming sections, as we learn more about the build system. +\N|Again, this layout is not mandatory and \l{bdep-new(1)} can create a number +of alternative library structures. For example, if you prefer the +\c{include/src} split, try: + +\ +$ bdep new --no-init -l c++ -t lib,split libhello +\ + +See \l{bdep-new.xhtml#src-layout SOURCE LAYOUT} for more examples.| + + \N|The standard project structure is not type (executable, library, etc) or even language specific. In fact, the same project can contain multiple executables and/or libraries (for example, both \c{hello} and \c{libhello}). @@ -1356,9 +1374,9 @@ values end up in the \c{=+} and \c{+=} results is to imagine the new value taking the position of \c{=} and the existing value \- of \c{+}.| The above \c{buildfile} allows us to include our headers using the project's -name as a prefix, inline with the \l{intro#structure-canonical Canonical -Project Structure} guidelines. For example, if we added the \c{utility.hxx} -header to our \c{hello} project, we would include it like this: +name as a prefix, inline with the \l{intro#proj-struct Canonical Project +Structure} guidelines. For example, if we added the \c{utility.hxx} header to +our \c{hello} project, we would include it like this: \ #include <iostream> @@ -2716,11 +2734,11 @@ covered in the source subdirectory \c{buildfile} in \c{libhello}. Here it is in its entirety: \ -int_libs = # Interface dependencies. -imp_libs = # Implementation dependencies. +intf_libs = # Interface dependencies. +impl_libs = # Implementation dependencies. lib{hello}: {hxx ixx txx cxx}{** -version} hxx{version} \ - $imp_libs $int_libs + $impl_libs $intf_libs # Include the generated version header into the distribution (so that # we don't pick up an installed one) and don't remove it when cleaning @@ -2744,7 +2762,7 @@ objs{*}: cxx.poptions += -DLIBHELLO_SHARED_BUILD lib{hello}: { cxx.export.poptions = \"-I$out_root\" \"-I$src_root\" - cxx.export.libs = $int_libs + cxx.export.libs = $intf_libs } liba{hello}: cxx.export.poptions += -DLIBHELLO_STATIC @@ -2788,15 +2806,15 @@ Here are the parts relevant to the library metadata protocol in the above \c{buildfile}: \ -int_libs = # Interface dependencies. -imp_libs = # Implementation dependencies. +intf_libs = # Interface dependencies. +impl_libs = # Implementation dependencies. -lib{hello}: ... $imp_libs $int_libs +lib{hello}: ... $impl_libs $intf_libs lib{hello}: { cxx.export.poptions = \"-I$out_root\" \"-I$src_root\" - cxx.export.libs = $int_libs + cxx.export.libs = $intf_libs } liba{hello}: cxx.export.poptions += -DLIBHELLO_STATIC @@ -2853,8 +2871,8 @@ can safely treat it as an implementation dependency. The corresponding \c{import} directives in our \c{buildfile} will therefore look like this: \ -import int_libs = libformat%lib{format} -import imp_libs = libprint%lib{print} +import intf_libs = libformat%lib{format} +import impl_libs = libprint%lib{print} \ The preprocessor options (\c{poptions}) of an interface dependency must be @@ -2865,7 +2883,7 @@ listing the interface dependencies in the \c{cxx.export.libs} variable: \ lib{hello}: { - cxx.export.libs = $int_libs + cxx.export.libs = $intf_libs } \ |