josh/rscons
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Remove references to build operation in the user guide

Browse Source
This commit is contained in:
Josh Holtrop 2022-01-30 21:56:42 -05:00
parent df120af953
commit 3914dd896c
1 changed files with 43 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
doc/user_guide.md
View File

@ -15,12 +15,12 @@ It supports the following features:
At its core, Rscons is mainly an engine to: At its core, Rscons is mainly an engine to:
* determine the proper order to perform build operations, * determine the proper order to perform build steps,
* determine whether each build target is up to date or in need of rebuild, and * determine whether each build target is up to date or in need of rebuild, and
* schedule those build operations across multiple threads as efficiently as possible. * schedule those build steps across multiple threads as efficiently as possible.
Along the way, Rscons provides a concise syntax for specifying common types of Along the way, Rscons provides a concise syntax for specifying common types of
build operations, but also provides an extensible framework for performing build steps, but also provides an extensible framework for performing
custom build operations as well. custom build operations as well.
Rscons takes inspiration from: Rscons takes inspiration from:
@ -48,8 +48,8 @@ ${/remove}
### Build Correctness ### Build Correctness
The number one design principle in Rscons is build correctness. The number one design principle in Rscons is build correctness.
This means that a build operation will be performed when Rscons cannot This means that a target will be built when Rscons cannot determine that a
determine that a build target is already up-to-date. build target is already up-to-date.
A build target will be built whenever: A build target will be built whenever:
* the target file has been removed or changed since it was last built * the target file has been removed or changed since it was last built
@ -80,10 +80,10 @@ files coming from a particular source directory.
Rscons will automatically determine the number of threads to use based on the Rscons will automatically determine the number of threads to use based on the
host CPU configuration, and will schedule jobs as efficiently as possible host CPU configuration, and will schedule jobs as efficiently as possible
across the available threads in order to complete the build operation in as across the available threads in order to complete the build in as little time
little time as possible. as possible.
As development occurs and build operations are executed, Rscons makes use of a As development occurs and builders are executed, Rscons makes use of a cache
cache file in order to avoid rebuilding a target when it is already up to date. file in order to avoid rebuilding a target when it is already up to date.
### Build Directory ### Build Directory
@ -130,8 +130,8 @@ The following files should be added to source control:
* `rscons` * `rscons`
* `Rsconscript` * `Rsconscript`
Add the following contents to `.gitignore` (or the equivalent thereof for different Add the following contents to `.gitignore` (or the equivalent thereof for
version control systems): different version control systems):
``` ```
/.rscons* /.rscons*
@ -649,8 +649,8 @@ The command and its output are also logged to the config.log file.
The [`store_merge`](../yard/Rscons/ConfigureOp.html#store_merge-instance_method), The [`store_merge`](../yard/Rscons/ConfigureOp.html#store_merge-instance_method),
[`store_append`](../yard/Rscons/ConfigureOp.html#store_append-instance_method), [`store_append`](../yard/Rscons/ConfigureOp.html#store_append-instance_method),
and [`store_parse`](../yard/Rscons/ConfigureOp.html#store_parse-instance_method) and [`store_parse`](../yard/Rscons/ConfigureOp.html#store_parse-instance_method)
methods can be used to store construction variables for Environments created methods can be used to store construction variables to be used in Environments
during the `build` operation. created later.
Finally, the [`complete`](../yard/Rscons/ConfigureOp.html#complete-instance_method) Finally, the [`complete`](../yard/Rscons/ConfigureOp.html#complete-instance_method)
method can be used to complete the configuration check and indicate a success method can be used to complete the configuration check and indicate a success
or failure. or failure.
@ -831,7 +831,7 @@ There are several default builders that are built-in to Rscons:
* `Directory`, which creates a directory. * `Directory`, which creates a directory.
* `Disassemble`, which disassembles an object file to a disassembly listing. * `Disassemble`, which disassembles an object file to a disassembly listing.
* `Install`, which installs files or directories to a specified destination. * `Install`, which installs files or directories to a specified destination.
* `InstallDirectory`, which creates a directory during an install operation. * `InstallDirectory`, which creates a directory in an install destination.
* `Library`, which collects object files into a static library archive file. * `Library`, which collects object files into a static library archive file.
* `Object`, which compiles source files to produce an object file. * `Object`, which compiles source files to produce an object file.
* `Preprocess`, which invokes the C/C++ preprocessor on a source file. * `Preprocess`, which invokes the C/C++ preprocessor on a source file.
@ -923,8 +923,12 @@ env.Install("${prefix}/share", "share")
The `Install` builder can install files or directories to their installation The `Install` builder can install files or directories to their installation
target location. target location.
`Install` builders are only processed when the user has requested to perform It functions almost identically to the `Copy` builder.
an `install` operation from the command line. The only difference relates to the `clean` and `uninstall` tasks.
The `clean` task removes targets created by the `Copy` builder but not by
the `Install` builder.
The `uninstall` task removes targets created by the `Install` builder but not
by the `Copy` builder.
####> The InstallDirectory Builder ####> The InstallDirectory Builder
@ -934,12 +938,18 @@ env.InstallDirectory(target)
env.InstallDirectory("${prefix}/share") env.InstallDirectory("${prefix}/share")
``` ```
The `InstallDirectory` builder can be used to explicitly create a directory. The `InstallDirectory` builder can be used to explicitly create a directory in
`InstallDirectory` builders are only processed when the user has requested to an installation location.
perform an `install` operation from the command line.
This can also disambiguate whether the target for a subsequent builder This can also disambiguate whether the target for a subsequent builder
(e.g. `Install`) refers to a file path or directory path. (e.g. `Install`) refers to a file path or directory path.
It functions almost identically to the `Directory` builder.
The only difference relates to the `clean` and `uninstall` tasks.
The `clean` task removes targets created by the `Directory` builder but not by
the `InstallDirectory` builder.
The `uninstall` task removes targets created by the `InstallDirectory` builder
but not by the `Directory` builder.
####> The Library Builder ####> The Library Builder
```ruby ```ruby
@ -1133,7 +1143,7 @@ This example script would compile all C sources under the `src` directory with
the `-Wall` flag except for sources under the `src/tests` directory. the `-Wall` flag except for sources under the `src/tests` directory.
A post-build hook can be added with `env.add_post_build_hook`. A post-build hook can be added with `env.add_post_build_hook`.
Post-build hooks are only invoked if the build operation was a success. Post-build hooks are only invoked if the build step was a success.
Build hooks and post-build hooks can register new build targets. Build hooks and post-build hooks can register new build targets.
@ -1248,10 +1258,10 @@ environment variable.
The The
[`rscons`](../yard/Rscons/Script/GlobalDsl.html#rscons-instance_method) [`rscons`](../yard/Rscons/Script/GlobalDsl.html#rscons-instance_method)
build script method can be used to invoke an rscons subprocess to build script method can be used to invoke an rscons subprocess using a
perform an operation using a subsidiary rscons build script. subsidiary rscons build script.
This can be used, for example, when a subproject is imported and a top-level This can be used, for example, when a subproject is imported and a top-level
`configure` or `build` operation should also perform the same operation in the `configure` or `build` task should also perform the same task in the
subproject directory. subproject directory.
The first argument to the `rscons` method specifies either a directory name, or The first argument to the `rscons` method specifies either a directory name, or
@ -1273,7 +1283,7 @@ task "build" do
end end
``` ```
It is also perfectly valid to perform a different operation in the subsidiary It is also perfectly valid to perform different task(s) in the subsidiary
script from the one being performed in the top-level script. script from the one being performed in the top-level script.
For example, in a project that requires a particular cross compiler, the For example, in a project that requires a particular cross compiler, the
top-level `configure` script could build the necessary cross compiler using a top-level `configure` script could build the necessary cross compiler using a
@ -1445,13 +1455,13 @@ The base constructor will set several instance attributes within the builder:
* `@env` will contain a reference to the Environment object that registered * `@env` will contain a reference to the Environment object that registered
the build target using the builder the build target using the builder
* `@vars` will contain any user-specified construction variable values that * `@vars` will contain any user-specified construction variable values that
should be used for the build operation (overriding any Environment-wide should be used for the builder execution (overriding any Environment-wide
construction variable values) construction variable values)
####> Custom Builder Operation ####> Custom Builder Operation
In order for a builder to perform a build operation, the builder class must In order for a builder to run, the builder class must implement a the
implement a the `Builder#run()` method. `Builder#run()` method.
Generally, the `run()` method will use the source file(s) to produce the target Generally, the `run()` method will use the source file(s) to produce the target
file. file.
Here is an example of a trivial builder: Here is an example of a trivial builder:
@ -1469,16 +1479,15 @@ end
##### Return Value ##### Return Value
If the build operation has completed and failed, the `run` method should return If the builder has completed and failed, the `run` method should return
`false`. `false`.
In this case, generally the command executed or the builder itself would be In this case, generally the command executed or the builder itself would be
expected to output something to `$stderr` indicating the reason for the build expected to output something to `$stderr` indicating the reason for the build
failure. failure.
If the build operation has completed successfully, the `run` method should If the builder has completed successfully, the `run` method should
return `true`. return `true`.
If the build operation is not yet complete and is waiting on other operations, If the builder is not yet complete and is waiting on other steps, the `run`
the `run` method should return the return value from the `Builder#wait_for` method should return the return value from the `Builder#wait_for` method.
method.
See ${#Custom Builder Parallelization}. See ${#Custom Builder Parallelization}.
##### Printing Build Status ##### Printing Build Status
@ -1552,9 +1561,9 @@ In any of these cases, the builder's `run` method should make use of
`Builder#wait_for` to "sleep" until one of the items being waited for has `Builder#wait_for` to "sleep" until one of the items being waited for has
completed. completed.
###### Using a Ruby Thread to Parallelize a Build Operation ###### Using a Ruby Thread to Parallelize a Builder
Here is an example of using a Ruby thread to parallelize a build operation: Here is an example of using a Ruby thread to parallelize a builder:
```ruby ```ruby
${include build_tests/custom_builder/wait_for_thread.rb} ${include build_tests/custom_builder/wait_for_thread.rb}