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

More user guide updates for tasks

Browse Source
This commit is contained in:
Josh Holtrop 2022-01-30 12:46:38 -05:00
parent c8a4accd12
commit f2a56f1c61
1 changed files with 29 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
doc/user_guide.md
View File

@ -358,9 +358,9 @@ It will not remove all built target files, just the installed copies.
##> Configuring the Project
A `configure` block is optional.
It can be used to perform various checks and setup operations for a project.
Example `configure` block:
Configure task actions can be used to perform various checks and setup
operations for a project.
Example `configure` action block:
```ruby
configure do
@ -369,6 +369,17 @@ configure do
end
```
If any configure task action blocks are present, they will be execute when the
configure operation is performed.
This happens if the user requests the `configure` task from the command line.
It also happens if all of the following are true:
* The project has not yet been configured.
* A task that does not have `autoconf` set to `false` is being executed.
* The global `autoconf` setting has not been set to `false`.
See ${#Configure Task} for more information about `autoconf`.
###> Checking for a Compiler
The following methods can be used within a `configure` block to check for a
@ -619,10 +630,12 @@ If set, a build define of the specified String will be added to the
##> Building Targets
The `build` block is used to create Environments and register build targets.
An Rscons build script would not be very useful without a `build` block.
Building target files is accomplished by using Environments.
Environments are typically created within the default task or any user-defined
tasks.
Here is an example `build` block demonstrating how to register a build target:
Here is an example `default` task block demonstrating how to create an
Environment and register a build target:
```ruby
default do
@ -1050,7 +1063,7 @@ In other words, build targets are not parallelized across a barrier.
env.barrier
```
##> Other Build Script Methods
##> Build Script Methods
`rscons` provides several methods that a build script can use.
@ -1101,9 +1114,12 @@ module are made available for the build script to call directly:
###> Finding Files: The glob Method
The [`glob`](../yard/Rscons/Script/GlobalDsl.html#glob-instance_method) method can be
used to find files matching the patterns specified.
It supports a syntax similar to the Ruby [Dir.glob method](https://ruby-doc.org/core-3.1.0/Dir.html#method-c-glob) but operates more deterministically.
The [`glob`](../yard/Rscons/Script/GlobalDsl.html#glob-instance_method) method
can be used to find files matching the patterns specified.
It supports a syntax similar to the Ruby
[Dir.glob method](https://ruby-doc.org/core-3.1.0/Dir.html#method-c-glob)
but operates more deterministically (results are ordered based on file names
rather than file system directory ordering).
Example use:
@ -1166,7 +1182,7 @@ configure do
rscons "subproject", "configure"
end
default do
task "build" do
rscons "subproject/Rsconscript", "build"
end
```
@ -1596,8 +1612,8 @@ end
default do
Environment.new do |env|
env["CFLAGS"] = ["-O3", "-Wall"]
env.add_build_hook do |build_op|
if build_op[:target] =~ %r{build/third-party}
env.add_build_hook do |builder|
if builder.sources.first =~ %r{src/third-party/}
build_op[:vars]["CFLAGS"] -= ["-Wall"]
end
end