From bdcd4211cf76bc75dd6f9a16fa3835632dfb7f20 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Mon, 20 Sep 2021 09:57:13 +0200 Subject: Assign pre-defined semantics to config..develop variables This variable allows a project to distinguish between development and consumption builds. While normally there is no distinction between these two modes, sometimes a project may need to provide additional functionality during development. For example, a source code generator which uses its own generated code in its implementation may need to provide a bootstrap step from the pre-generated code. Normally, such a step is only needed during development. See "Project Configuration" in the manual for details. --- doc/manual.cli | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'doc') diff --git a/doc/manual.cli b/doc/manual.cli index d344f42..6ca1d8b 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -4670,6 +4670,39 @@ The build system core reserves \c{build} and \c{import} as the second component in configuration variables as well as \c{configured} as the third and subsequent components.| +A variable in the \c{config..develop} form has pre-defined +semantics: it allows a project to distinguish between \i{development} and +\i{consumption} builds. While normally there is no distinction between these +two modes, sometimes a project may need to provide additional functionality +during development. For example, a source code generator which uses its own +generated code in its implementation may need to provide a bootstrap step from +the pre-generated code. Normally, such a step is only needed during +development. + +\N|While some communities, such as Rust, believe that building and running +tests is only done during development, we believe its reasonable for an +end-user to want to run tests for all their dependencies. As a result, we +strongly discourage restricting tests to the development mode only. Test are +an integral part of the project and should always be available.| + +If used, the \c{config..develop} variable should be explicitly +defined by the project with the \c{bool} type and the \c{false} default +value. For example: + +\ +# build/root.build + +config [bool] config.libhello.develop ?= false +\ + +\N|If the \c{config..develop} variable is specified by the user of +the project but the project does not define it (that is, the project does not +distinguish between development and consumption), then this variable is +silently ignored. By default \l{bdep-init(1)} configures projects being +initialized for development. This can be overridden with explicit +\c{config..develop=false}.| + + \h#proj-config-directive|\c{config} Directive| -- cgit v1.1