diff options
| -rw-r--r-- | doc/manual.cli | 129 | ||||
| -rw-r--r-- | doc/testscript.cli | 26 |
2 files changed, 78 insertions, 77 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index 0cd5a5e..73f15a5 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -545,7 +545,7 @@ they define new operations). Let's examine briefly the modules loaded by our \c{bootstrap.build}: The \l{#module-version \c{version}} module helps with managing our project versioning. With this module we only maintain the version in a single place -(project's \c{manifest} file) and it is automatically made available in +(the project's \c{manifest} file) and it is automatically made available in various convenient forms throughout our project (\c{buildfiles}, header files, etc). The \c{version} module also automates versioning of snapshots between releases. @@ -627,8 +627,8 @@ incrementally and many versions, while perfectly usable, are not feature-complete. As a result, a better practical strategy is to specify the set of minimum supported compiler versions rather than the C++ standard. -There is also the issue of using libraries that require newer standard in -older code. For example, headers from a library that relies on C++14 features +There is also the issue of using libraries that require a newer standard in +old code. For example, headers from a library that relies on C++14 features will not compile when included in a project that is built as C++11. And, even if the headers compile (that is, C++14 features are only used in the implementation), strictly speaking, there is no guarantee that codebases @@ -681,7 +681,7 @@ directory\" semantics. Note also that \c{dir{\}} is purely an alias and doesn't have anything to do with the filesystem. In particular, it does not create any directories. If you do want explicit directory creation (which should be rarely needed), use the -\c{fsdir{}} target type instead.| +\c{fsdir{\}} target type instead.| The \c{./} target is a special \i{default target}. If we run the build system without specifying the target explicitly, then this target is built by @@ -792,7 +792,7 @@ 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 +The source subdirectory \c{buildfile} is identical to that of the simple project minus the parts moved to \c{root.build}: \ @@ -826,8 +826,8 @@ $ hello/hello Hello, World! \ -If we don't specify a target to build (as we did above), then \c{build2} will -build the current directory or, more precisely, the default target in the +If we don't specify a target to build (as in the example above), then \c{build2} +will build the current directory or, more precisely, the default target in the \c{buildfile} in the current directory. We can also build a directory other than the current, for example: @@ -884,9 +884,9 @@ libhello/ The overall layout (\c{build/}, \c{libhello/} source directory) as well as the contents of the root files (\c{bootstrap.build}, \c{root.build}, root -\c{buildfile}) are exactly the same. There is, however, a new file, -\c{export.build}, in \c{build/}, a new subdirectory, \c{tests/}, and the -contents of the project's source subdirectory, \c{libhello/}, look quite a bit +\c{buildfile}) are exactly the same. There is, however, the new file +\c{export.build} in \c{build/}, the new subdirectory \c{tests/}, and the +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. @@ -1077,10 +1077,10 @@ Note also that only targets and not prerequisites have this notion of src/out directories. In a sense, prerequisites are relative to the target they are prerequisites of and are resolved to targets in a manner that is specific to their target types. For \c{file{\}}-based prerequisites the corresponding -target in out is first looked up and if found used. Otherwise, an existing file -in src is searched for and if found the corresponding target (now in src) is -used. In particular, this semantics gives preference to generated code over -static. +target in out is first looked up and, if found, used. Otherwise, an existing +file in src is searched for and, if found, the corresponding target (now in +src) is used. In particular, this semantics gives preference to generated code +over static. \N|More precisely, a prerequisite is relative to the scope (discussed below) in which the dependency is declared and not to the target that it is a @@ -1091,8 +1091,8 @@ points we have established so far: Every build has two parallel directory trees, src and out, with the in source build being just a special case where they are the same. Targets in a project can be either in the src or out directory though most of the time targets we mention in our \c{buildfiles} -will be in out, which is the default. Prerequsites are relative to targets -they are prerequisites of and \c{file{}}-based prerequisites are first +will be in out, which is the default. Prerequisites are relative to targets +they are prerequisites of and \c{file{\}}-based prerequisites are first searched for as declared targets in out and then as existing files in src. Note also that we can have as many out of source builds as we want and we can @@ -1183,7 +1183,7 @@ The above scope structure is very similar to what you will see (besides a lot of other things) if you build with \c{--dump\ match}. With this option the build system driver dumps the build state after matching rules to targets (see \l{#intro-diag-debug Diagnostics and Debugging} for more information). Here is -an abbreviated output of bulding our \c{hello} with \c{--dump} (assuming an in +an abbreviated output of building our \c{hello} with \c{--dump} (assuming an in source build in \c{/tmp/hello}): \ @@ -1521,8 +1521,8 @@ subdirectory structure.| Seeing this merged \c{buildfile} may make you wonder what exactly caused the loading of the source directory \c{buildfile} in our normal setup. In other -words, when we build our \c{hello} from the project root, who and why loads -\c{hello/buildfile}? +words, when we build our \c{hello} from the project root, who loads +\c{hello/buildfile} and why? Actually, in the earlier days of \c{build2}, we had to explicitly load \c{buildfiles} that define targets we depend on with the \c{include} @@ -2373,8 +2373,8 @@ $ tree /tmp/dist/hello-0.1.0/ └── manifest \ -As we can see, the distribution directory includes the project version (comes -from the \c{version} variable which, in our case, is extracted from +As we can see, the distribution directory includes the project version (from +the \c{version} variable which, in our case, is extracted from \c{manifest} by the \c{version} module). Inside the distribution directory we have our project's source files (but, for example, without any \c{.gitignore} files that we may have had in \c{hello/}). @@ -2592,7 +2592,7 @@ export $out_root/libhello/$import.target An export stub is a special kind of \c{buildfile} that bridges from the importing project into exporting. It is loaded in a special temporary scope -out of any project, in a \"no man's land\" so to speak. The only variables set +outside of any project, in a \"no man's land\" so to speak. The only variables set on the temporary scope are \c{src_root} and \c{out_root} of the project being imported as well as \c{import.target} containing the name of the target being imported (without project qualification; that is, \c{lib{hello\}} in our @@ -2948,14 +2948,14 @@ Note also that we don't need to change anything in the above \c{buildfile} if our library is header-only. In \c{build2} this is handled dynamically and automatically based on the absence of source file prerequisites. In fact, the same library can be header-only on some platforms or in some configuration and -\"source-full\" in others. +\"source-ful\" in others. \N|In \c{build2} a header-only library (or a module interface-only library) is not a different kind of library compared to static/shared libraries but is rather a binary-less, or \i{binless} for short, static or shared library. So, theoretically, it is possible to have a library that has a binless static and -a binary-full (\i{binfull}) shared variants. Note also that binless libraries -can depend on binfull libraries and are fully supported where the +a binary-ful (\i{binful}) shared variants. Note also that binless libraries +can depend on binful libraries and are fully supported where the \c{pkg-config(1)} functionality is concerned. If you are creating a new library with \l{bdep-new(1)} and are certain that it @@ -3040,7 +3040,7 @@ project somewhere else, amalgamation is physical containment. It can be project or \i{weak} where only the out directory is contained. There are several distinct use cases for amalgamations. We've already -discussed the \c{tests/} subproject in \c{libhello}. To recap, traditionally, +discussed the \c{tests/} subproject in \c{libhello}. To recap: traditionally, it is made a subproject rather than a subdirectory to support building it as a standalone project in order to test library installations. @@ -3142,7 +3142,7 @@ hello/ └── ... \ -As you can see, we now have the \c{config.build} files in both project's +As you can see, we now have the \c{config.build} files in both projects' \c{build/} subdirectories. If we examine the amalgamation's \c{config.build}, we will see the familiar picture: @@ -3222,9 +3222,10 @@ future changes to the configurations. If, for example, we need to adjust compile options in the GCC configuration, then we will have to (remember to) do it in both places. -You can probably sense where this is going: why not create a shared build -configuration (that is, an amalgamation) for GCC and Clang where we build both -of our projects (as its subprojects)? This is how we can do that: +You can probably sense where this is going: why not create two shared build +configurations (that is, amalgamations), one for GCC and one for Clang, within +each of which we build both of our projects (as their subprojects)? This is +how we can do that: \ $ b create: build-gcc/,cc config.cxx=g++ @@ -3339,11 +3340,11 @@ and variable assignment. We've already used all three but let's see another example: \ -include ../libhello/ # Directive. +include ../libhello/ # Directive. -exe{hello}: {hxx cxx}{**} ../libhello/lib{hello} # Dependency declaration. +exe{hello}: {hxx cxx}{**} ../libhello/lib{hello} # Dependency. -cxx.poptions += -DNDEBUG # Variable assignment. +cxx.poptions += -DNDEBUG # Variable. \ There is also the scope opening (we've seen one in \c{export.build}) as well @@ -3352,18 +3353,18 @@ latter two are used to assign several entity-specific variables at once. For example: \ -details/ # scope +details/ # Scope. { hxx{*}: install = false } -hxx{version}: # target-specific +hxx{version}: # Target-specific. { dist = true clean = ($src_root != $out_root) } -exe{test}: file{test.roundtrip}: # prerequisite-specific +exe{test}: file{test.roundtrip}: # Prerequisite-specific. { test.stdin = true test.stdout = true @@ -3402,7 +3403,7 @@ the last set of targets. For example: \N|All prerequisite-specific variables must be assigned at once as part of the dependency declaration since repeating the same dependency again duplicates -the prerequisite rather than references the already existing one. +the prerequisite rather than references the already existing one.| There is also the target type/pattern-specific variable assignment block, for example: @@ -3415,11 +3416,11 @@ exe{*.test}: } \ -See \l{#variables Variables} for more information.| +See \l{#variables Variables} for a more detailed discussion of variables. Each \c{buildfile} is processed linearly with directives executed and variables expanded as they are encountered. However, certain variables, for -example, \c{cxx.poptions} are also expanded by rules during execution in which +example \c{cxx.poptions}, are also expanded by rules during execution in which case they will \"see\" the final value set in the \c{buildfile}. \N|Unlike GNU \c{make(1)}, which has deferred (\c{=}) and immediate (\c{:=}) @@ -3578,7 +3579,7 @@ info ($regex.split('foo bar', ' ', '')[1]) # bar Names are split into a list at whitespace boundaries with certain other characters treated as syntax rather than as part of the value. Here are -a few example: +a few examples: \ x = $y # expansion @@ -3589,8 +3590,8 @@ x = name@value # pairs x = # start of a comment \ -The complete set of syntax characters is \c{$(){\}@#\"'} plus space and tab as -well as \c{[]} but only in certain contexts (see \l{#attributes Attributes} +The complete set of syntax characters is \c{$(){\}@#\"'} plus space and tab, as +well as \c{[]}, but only in certain contexts (see \l{#attributes Attributes} for details). If instead we need these characters to appear literally as part of the value, then we either have to \i{escape} or \i{quote} them. @@ -3611,7 +3612,7 @@ y = ($foo\[123].txt) | To escape a special character, we prefix it with a backslash (\c{\\}; to -specify a literal backslash double it). For example: +specify a literal backslash, double it). For example: \ x = \$ @@ -4074,7 +4075,7 @@ hello/ └── ... \ -Let's examine how this support is implemented in our \c{buildifle}, line by +Let's examine how this support is implemented in our \c{buildfile}, line by line. Because now we link \c{hello.cxx} object code into multiple executables (unit tests and the \c{hello} program itself), we have to place it into a \i{utility library}. This is what the first line does (it has to explicitly @@ -4210,7 +4211,7 @@ mechanisms that can help us understand the cause of a misbehaving build. To perform a build the build system goes through several phases. During the \i{load} phase the \c{buildfiles} are loaded and processed. The result of this phase is the in-memory \i{build state} that contains the scopes, targets, -variables, etc., defined by the \c{buildfiles}. Next, is the \i{match} phase +variables, etc., defined by the \c{buildfiles}. Next is the \i{match} phase during which rules are matched to the targets that need to be built, recursively. Finally, during the \i{execute} phase the matched rules are executed to perform the build. @@ -4302,7 +4303,7 @@ and, similar to \c{if}, there is also the \c{assert!} variant, which fails if the condition is \c{true}. All the diagnostics directives write to \c{stderr}. If instead we need to -write something to \c{stdout}, for example, to send some information back to +write something to \c{stdout} to, for example, send some information back to our caller, then we can use the \c{print} directive. For example, this will print the C++ compiler id and its target: @@ -4323,13 +4324,13 @@ since a prerequisite has no identity. Instead, we can use the \c{dump} directive discussed next to print the entire dependency declaration, including prerequisite-specific variables for each prerequisite.| -While printing variables values is the most common mechanism for diagnosing +While printing variable values is the most common mechanism for diagnosing \c{buildfile} issues, sometimes it is also helpful to examine targets and scopes. For that we use the \c{dump} directive. Without any arguments, \c{dump} prints (to \c{stderr}) the contents of the scope it was encountered in and at that point of processing the \c{buildfile}. -Its output includes variables, targets and their prerequsites, as well as +Its output includes variables, targets and their prerequisites, as well as nested scopes, recursively. As an example, let's print the source directory scope of our \c{hello} executable project. Here is its \c{buildfile} with the \c{dump} directive at the end: @@ -4402,7 +4403,7 @@ the state after the load phase (\c{--dump load}) and/or after the match phase (\c{--dump match}). In particular, the after match printout reflects the changes to the build state made by the matching rules, which may include entering of additional dependencies, setting of additional variables, -resolution of prerequsites to targets, assignment of file extensions, etc. As +resolution of prerequisites to targets, assignment of file extensions, etc. As a result, while the \c{dump} directive should be sufficient in most cases, sometimes you may need to use the \c{--dump} option to examine the build state just before rule execution. @@ -4603,7 +4604,7 @@ cxx.poptions += \"-DLIBHELLO_GREETING=\\\"$config.libhello.greeting\\\"\" \ \ -// lihello/hello.cxx +// libhello/hello.cxx void say_hello (ostream& o, const string& n) { @@ -5024,7 +5025,7 @@ cxx.poptions += \"-DLIBHELLO_GREETING=\\\"$config.libhello.greeting\\\"\" \ \ -// lihello/hello.cxx +// libhello/hello.cxx void say_hello (ostream& o, const string& n) { @@ -5110,7 +5111,7 @@ hxx{config}: in{config} \ \ -// lihello/hello.cxx +// libhello/hello.cxx #include <libhello/config.hxx> @@ -5155,7 +5156,7 @@ namespace hello \ \ -// lihello/hello.cxx +// libhello/hello.cxx #include <libhello/config.hxx> @@ -5189,7 +5190,7 @@ namespace hello \ \ -// lihello/hello.cxx +// libhello/hello.cxx #include <libhello/config.hxx> @@ -5631,7 +5632,7 @@ man<N> man/man<N>/ install.man<N> The \c{<project>} and \c{<private>} substitutions in these \c{config.install.*} values are replaced with the project name and private -subdirectory, respectively. If either is empty, that the corresponding +subdirectory, respectively. If either is empty, then the corresponding directory component is ignored. The optional private installation subdirectory (\c{<private>}) mechanism can @@ -5817,7 +5818,7 @@ As shown in the above example, there is nothing wrong with \"jumping\" to a further version (for example, from alpha to beta, or from beta to release, or even from alpha to release). We cannot, however, jump backwards (for example, from beta back to alpha). As a result, a sensible strategy is to start with -\c{a.0} since it can always be upgraded (but not downgrade) at a later stage. +\c{a.0} since it can always be upgraded (but not downgraded) at a later stage. When it comes to the version control systems, the recommended workflow is as follows: The change to the final version should be the last commit in the @@ -5943,12 +5944,12 @@ snapshot information). The result is a package that is specific to this commit. Besides extracting the version information and making it available as -individual components, the \c{version} module also provide rules for +individual components, the \c{version} module also provides rules for installing the manifest file as well as automatically generating version headers (or other similar version-based files). By default the project's \c{manifest} file is installed as documentation, just -like other \c{doc{}} targets (thus replacing the \c{version} file customarily +like other \c{doc{\}} targets (thus replacing the \c{version} file customarily shipped in the project root directory). The manifest installation rule in the \c{version} module in addition patches the installed manifest file with the actual snapshot number and id, just like during the preparation of @@ -6007,7 +6008,7 @@ as listed in the manifest. If it is the project itself, then the rest can refer to one of the \c{version.*} variables that we discussed earlier (in reality it can be any variable visible from the project's root scope). -If the name refers to one of the dependecies (that is, projects listed with +If the name refers to one of the dependencies (that is, projects listed with \c{depends:} in the manifest), then the following special substitutions are recognized: @@ -6092,7 +6093,7 @@ build/bootstrap.build:3:1: error: incompatible build2 version info: required 0.5.0 \ -What version constraints should be use when depending on other project. We +What version constraints should be used when depending on another project? We start with a simple case where we depend on a release. Let's say \c{libprint} \c{2.3.0} added a feature that we need in our \c{libhello}. If \c{libprint} follows the source/binary compatibility guidelines discussed above, then @@ -6115,8 +6116,8 @@ version: 2.0.0-b.1 depends: libprint == 3.0.0-b.2 \ -Finally, let's assume we are feeling adventerous and would like to test -development snapshots of \c{libprint} (most likey from our own snapshots). In +Finally, let's assume we are feeling adventurous and would like to test +development snapshots of \c{libprint} (most likely from our own snapshots). In this case the recommendation is to only allow a snapshot range for a specific pre-release with the understanding and a warning that no compatibility between snapshot versions is guaranteed. For example: @@ -6670,7 +6671,7 @@ namespace hello } \ -Up until now we've only been talking about names belonding to a module. What +Up until now we've only been talking about names belonging to a module. What about the corresponding symbols? For exported names, the resulting symbols would be the same as if those names were declared outside of a module's purview (or as if no modules were used at all). Non-exported names, on the @@ -8133,7 +8134,7 @@ not treated as an escape sequence. The lax mode is mostly useful when trying to reuse existing \c{.in} files from other build systems, such as \c{autoconf}. Note, however, that the lax mode is -still stricter than the \c{autoconf}'s semantics which also leaves unresolved +still stricter than \c{autoconf}'s semantics which also leaves unresolved substitutions as is. For example: \ diff --git a/doc/testscript.cli b/doc/testscript.cli index 49725df..d838cc0 100644 --- a/doc/testscript.cli +++ b/doc/testscript.cli @@ -65,7 +65,7 @@ execution by focusing on the following functionality: \li|Comparing to expected exit status.| -\li|Comparing to expected output for \c{stdout}/\c{stderr}, including +\li|Comparing \c{stdout}/\c{stderr} to expected output, including using regex.| \li|Setup/teardown commands and automatic file/directory cleanups.| @@ -530,7 +530,7 @@ their names (as every \c{hello} program should), then we could write a test like this: \ -$* - <<EOI | $* -d - >>EOO +$* - <<EOI | $* -r - >>EOO John Jane EOI @@ -1056,17 +1056,17 @@ after the execution (for example, to examine test setup, output, etc). Before the execution the default behavior is to warn and then automatically remove the working directory if it exists. After the execution the default behavior is to perform all the cleanups and teardowns and then remove the working -directory failing if it is not empty. This default behaviors can, however, be +directory if it is not empty. This default behavior can, however, be overridden with the \c{config.test.output} variable. The \c{config.test.output} variable contains a pair of values with the first signifying the \i{before} behavior and the second \- \i{after}. The valid -\i{before} values are \c{fail} (fail if the directory exists), \c{warn} -(warn if the directory exists then remove), \c{clean} (silently remove -the existing directory). The valid \i{after} values are \c{clean} (remove -the directory failing if it is not empty) and \c{keep} (do not run cleanups -and teardowns and do not remove the working directory). The default behavior -is thus equivalent to specifying the \c{warn@clean} pair. +\i{before} values are \c{fail} (fail if the directory exists), \c{warn} (warn +if the directory exists then remove), \c{clean} (silently remove the existing +directory). The valid \i{after} values are \c{clean} (remove the directory if +it is not empty) and \c{keep} (do not run cleanups and teardowns and do not +remove the working directory). The default behavior is thus equivalent to +specifying the \c{warn@clean} pair. If only a single value is specified in \c{config.test.output} then it is assumed to be the \i{after} value and the \i{before} value is assumed to @@ -2893,8 +2893,8 @@ consider designing a concise, textual \i{mini-format} for input (either via command line or \c{stdin}) and output rather than constructing the test data and expected results programmatically. -Documentation-wise, each test should at least include explicit id that -adequately summarizes what it tests. Add summary or even details for more +Documentation-wise, each test should at least include an explicit id that +adequately summarizes what it tests. Add a summary or even details for more complex tests. Failure tests usually fall into this category. Use the leading description for multi-line tests, for example: @@ -2977,8 +2977,8 @@ example, if the above tests were in \c{greeting.testscript}, then using the id path would then become \c{greeting/custom-greeting/john}, etc. We quote values that are \i{strings} as opposed to options, file names, paths -(unless contain spaces), integers, or boolean. When quoting, use the single -quote unless you need expansions (or single quotes) inside. Note that unlike +(unless they contain spaces), integers, or boolean. When quoting, use single +quotes unless you need expansions (or single quotes) inside. Note that unlike Bash you do not need to quote variable expansions in order to preserve whitespaces. For example: |