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

user guide: break more sections into separate pages

Browse Source
This commit is contained in:
Josh Holtrop 2019-06-14 16:23:09 -04:00
parent 5c77cac354
commit a11c27f415
2 changed files with 41 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
doc/user_guide.md
View File

@ -1,4 +1,4 @@
# Overview #> Overview
Rscons is an open-source build system for developers. Rscons is an open-source build system for developers.
It supports the following features: It supports the following features:
@ -80,7 +80,7 @@ To use Rscons on your project, you must:
1. Install the `rscons` script in your project (See ${#Installation}). 1. Install the `rscons` script in your project (See ${#Installation}).
2. Write the `Rsconscript` build script for your project (See ${#The Build Script}). 2. Write the `Rsconscript` build script for your project (See ${#The Build Script}).
# Installation #> Installation
Rscons is designed to be distributed as a stand-alone single file script that Rscons is designed to be distributed as a stand-alone single file script that
can be copied into and versioned in a project's source tree. can be copied into and versioned in a project's source tree.
@ -105,7 +105,7 @@ version control systems):
/build/ /build/
``` ```
# Command-Line Operation #> Command-Line Operation
Rscons is typically invoked from the command-line as `./rscons`. Rscons is typically invoked from the command-line as `./rscons`.
Rscons supports several build *operations*: Rscons supports several build *operations*:
@ -117,7 +117,7 @@ Rscons supports several build *operations*:
* install * install
* uninstall * uninstall
## Configure Operation ##> Configure Operation
The `configure` operation will initialize the Rscons cache file and build The `configure` operation will initialize the Rscons cache file and build
directory. directory.
@ -131,7 +131,7 @@ Such configuration checks can include:
* verifying presence of a library * verifying presence of a library
* verifying presence of an executable * verifying presence of an executable
## Build Operation ##> Build Operation
If a `build` operation is requested and a `configure` operation has not yet If a `build` operation is requested and a `configure` operation has not yet
been performed, a `configure` operation will be automatically invoked. been performed, a `configure` operation will be automatically invoked.
@ -139,13 +139,13 @@ been performed, a `configure` operation will be automatically invoked.
The `build` operation will execute all builders registered to produce build The `build` operation will execute all builders registered to produce build
targets. targets.
## Clean Operation ##> Clean Operation
A `clean` operation will remove all built target files. A `clean` operation will remove all built target files.
It will not remove items installed by an `install` operation. It will not remove items installed by an `install` operation.
It will not remove the cached configuration options. It will not remove the cached configuration options.
## Distclean Operation ##> Distclean Operation
A `distclean` operation will remove all built target files and all cached A `distclean` operation will remove all built target files and all cached
configuration options. configuration options.
@ -153,20 +153,20 @@ Generally it will get the project directory back to the state it was in when
unpacked before any configuration or build operations took place. unpacked before any configuration or build operations took place.
It will not removed items installed by an `install` operation. It will not removed items installed by an `install` operation.
## Install Operation ##> Install Operation
An `install` operation will perform a `build` (and if necessary, first a An `install` operation will perform a `build` (and if necessary, first a
`configure` as well). `configure` as well).
In addition it will execute any `Install` or `InstallDirectory` builders to In addition it will execute any `Install` or `InstallDirectory` builders to
install items into the specified install directory. install items into the specified install directory.
## Uninstall Operation ##> Uninstall Operation
An `uninstall` operation will remove any items installed by an `install` An `uninstall` operation will remove any items installed by an `install`
operation. operation.
It will not remove all built target files, just the installed copies. It will not remove all built target files, just the installed copies.
# The Build Script #> The Build Script
Rscons looks for instructions for what to build by reading a build script file Rscons looks for instructions for what to build by reading a build script file
called `Rsconscript` (or `Rsconscript.rb`). called `Rsconscript` (or `Rsconscript.rb`).
@ -186,7 +186,7 @@ called `myprog.exe` which is to be built from all C source files found
The `Rsconscript` file is a Ruby script. The `Rsconscript` file is a Ruby script.
## Configuration Operations ##> Configuration Operations
A `configure` block is optional. A `configure` block is optional.
It can be used to perform various checks and setup operations for a project. It can be used to perform various checks and setup operations for a project.
@ -199,7 +199,7 @@ configure do
end end
``` ```
### Checking for a Compiler ###> Checking for a Compiler
The following methods can be used within a `configure` block to check for a The following methods can be used within a `configure` block to check for a
working compiler: working compiler:
@ -222,7 +222,7 @@ configure do
end end
``` ```
### Checking for a Header File ###> Checking for a Header File
The following methods can be used to check for the presence of a header file: The following methods can be used to check for the presence of a header file:
@ -254,7 +254,7 @@ will not result in the configure option failing.
If set, a build define of the specified String will be added to the If set, a build define of the specified String will be added to the
`CPPDEFINES` construction variable array if the requested header is found. `CPPDEFINES` construction variable array if the requested header is found.
### Checking for a D Import ###> Checking for a D Import
The `check_d_import` method can be used to check for the presence of D import. The `check_d_import` method can be used to check for the presence of D import.
@ -269,7 +269,7 @@ configure do
end end
``` ```
### Checking for a Library ###> Checking for a Library
The `check_lib` method can be used to check for the presence of a library. The `check_lib` method can be used to check for the presence of a library.
@ -297,7 +297,7 @@ will not result in the configure option failing.
If set, a build define of the specified String will be added to the If set, a build define of the specified String will be added to the
`CPPDEFINES` construction variable array if the requested library is found. `CPPDEFINES` construction variable array if the requested library is found.
### Checking for a Program ###> Checking for a Program
The `check_program` method can check for the existence of an executable in the The `check_program` method can check for the existence of an executable in the
host operating system environment. host operating system environment.
@ -310,7 +310,7 @@ configure do
end end
``` ```
### Checking for a Package Configuration ###> Checking for a Package Configuration
The `check_cfg` method can be used to check for the existence of a package as The `check_cfg` method can be used to check for the existence of a package as
well as import any build options (e.g. include path, defines, libraries to link well as import any build options (e.g. include path, defines, libraries to link
@ -349,7 +349,7 @@ program requested will not result in the configure option failing.
If set, a build define of the specified String will be added to the If set, a build define of the specified String will be added to the
`CPPDEFINES` construction variable array if the requested package is found. `CPPDEFINES` construction variable array if the requested package is found.
## Build Operations ##> Build Operations
The `build` block is used to create Environments and register build 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. An Rscons build script would not be very useful without a `build` block.
@ -367,7 +367,7 @@ end
This `Rsconscript` would build an executable called `myprog.exe` from all C This `Rsconscript` would build an executable called `myprog.exe` from all C
source files found recursively under the `src` directory. source files found recursively under the `src` directory.
### Environments ###> Environments
An Environment includes: An Environment includes:
@ -396,7 +396,7 @@ source file under the Environment's build root.
This keeps the intermediate generated build artifacts separate from the source This keeps the intermediate generated build artifacts separate from the source
files. files.
### Specifying Source Files: The glob Method ###> Specifying Source Files: The glob Method
The `glob` method can be used to find files matching the patterns specified. The `glob` 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-2.5.1/Dir.html#method-c-glob) but operates more deterministically. It supports a syntax similar to the Ruby [Dir.glob method](https://ruby-doc.org/core-2.5.1/Dir.html#method-c-glob) but operates more deterministically.
@ -414,7 +414,7 @@ end
This example would build the `mytests` executable from all `.cc` source files This example would build the `mytests` executable from all `.cc` source files
found recursively under the `src` or `test` directory. found recursively under the `src` or `test` directory.
### Construction Variables ###> Construction Variables
Construction variables are values assigned to keys within an Environment. Construction variables are values assigned to keys within an Environment.
Construction variables are used by Builders to produce output files. Construction variables are used by Builders to produce output files.
@ -436,7 +436,7 @@ This example modifies the `CCFLAGS` construction variable to add `-O2` and
`-Wall` to the compilation commands used for C and C++ source files. `-Wall` to the compilation commands used for C and C++ source files.
It also instructs the linker to link against the `m` library. It also instructs the linker to link against the `m` library.
### Builders ###> Builders
Rscons uses builder objects to produce *target* output files from *source* Rscons uses builder objects to produce *target* output files from *source*
input files. input files.
@ -479,7 +479,7 @@ There are several default builders that are built-in to Rscons:
* `SharedObject`, which compiles source files to produce an object file, in a * `SharedObject`, which compiles source files to produce an object file, in a
way that is able to be used to create a shared library. way that is able to be used to create a shared library.
#### The Command Builder ####> The Command Builder
```ruby ```ruby
env.Command(target, sources, "CMD" => command) env.Command(target, sources, "CMD" => command)
@ -492,7 +492,7 @@ env.Command("docs.html", "docs.md",
The `Command` builder executes a user-defined command in order to produce the The `Command` builder executes a user-defined command in order to produce the
desired target file based on the provided source files. desired target file based on the provided source files.
#### The CFile Builder ####> The CFile Builder
```ruby ```ruby
env.CFile(target, source) env.CFile(target, source)
@ -503,7 +503,7 @@ env.CFile("^/parser/parser.c", "parser.y")
The `CFile` builder will generate a C or C++ source file from a lex (.l, .ll) The `CFile` builder will generate a C or C++ source file from a lex (.l, .ll)
or yacc (.y, .yy) input file. or yacc (.y, .yy) input file.
#### The Copy Builder ####> The Copy Builder
```ruby ```ruby
env.Copy(destination, sources) env.Copy(destination, sources)
@ -514,7 +514,7 @@ env.Copy("^/dist/share", "share")
The `Copy` builder can copy files or directories to a target location. The `Copy` builder can copy files or directories to a target location.
#### The Directory Builder ####> The Directory Builder
```ruby ```ruby
env.Directory(target) env.Directory(target)
@ -526,7 +526,7 @@ The `Directory` builder can be used to explicitly create a directory.
This can also disambiguate whether the target for a subsequent builder This can also disambiguate whether the target for a subsequent builder
(e.g. `Copy`) refers to a file path or directory path. (e.g. `Copy`) refers to a file path or directory path.
#### The Disassemble Builder ####> The Disassemble Builder
```ruby ```ruby
env.Disassemble(target, source) env.Disassemble(target, source)
@ -537,7 +537,7 @@ env.Disassemble("module.dis", "module.o")
The `Disassemble` builder generates a disassembly listing using objdump from The `Disassemble` builder generates a disassembly listing using objdump from
and object file. and object file.
#### The Install Builder ####> The Install Builder
```ruby ```ruby
env.Install(destination, sources) env.Install(destination, sources)
@ -551,7 +551,7 @@ target location.
`Install` builders are only processed when the user has requested to perform `Install` builders are only processed when the user has requested to perform
an `install` operation from the command line. an `install` operation from the command line.
#### The InstallDirectory Builder ####> The InstallDirectory Builder
```ruby ```ruby
env.InstallDirectory(target) env.InstallDirectory(target)
@ -565,7 +565,7 @@ 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.
#### The Library Builder ####> The Library Builder
```ruby ```ruby
env.Library(target, sources) env.Library(target, sources)
@ -576,7 +576,7 @@ env.Library("lib.a", Rscons.glob("src/**/*.c"))
The `Library` builder creates a static library archive from the given source The `Library` builder creates a static library archive from the given source
files. files.
#### The Object Builder ####> The Object Builder
```ruby ```ruby
env.Object(target, sources) env.Object(target, sources)
@ -588,7 +588,7 @@ The `Object` builder compiles the given sources to an object file.
Although it can be called explicitly, it is more commonly implicitly called by Although it can be called explicitly, it is more commonly implicitly called by
the `Program` builder. the `Program` builder.
#### The Preprocess Builder ####> The Preprocess Builder
```ruby ```ruby
env.Preprocess(target, source) env.Preprocess(target, source)
@ -600,7 +600,7 @@ The `Preprocess` builder invokes either `${CC}` or `${CXX}` (depending on if
the source contains an extension in `${CXXSUFFIX}` or not) and writes the the source contains an extension in `${CXXSUFFIX}` or not) and writes the
preprocessed output to the target file. preprocessed output to the target file.
#### The Program Builder ####> The Program Builder
```ruby ```ruby
env.Program(target, sources) env.Program(target, sources)
@ -615,7 +615,7 @@ A platform-dependent program suffix will be appended to the target name if one
is not specified. is not specified.
This can be controlled with the `PROGSUFFIX` construction variable. This can be controlled with the `PROGSUFFIX` construction variable.
#### The SharedLibrary Builder ####> The SharedLibrary Builder
```ruby ```ruby
env.SharedLibrary(target, sources) env.SharedLibrary(target, sources)
@ -631,7 +631,7 @@ they are not specified by the user.
These values can be controlled by overriding the `SHLIBPREFIX` and These values can be controlled by overriding the `SHLIBPREFIX` and
`SHLIBSUFFIX` construction variables. `SHLIBSUFFIX` construction variables.
#### The SharedObject Builder ####> The SharedObject Builder
```ruby ```ruby
env.SharedObject(target, sources) env.SharedObject(target, sources)
@ -645,7 +645,7 @@ allows it to be used to create a shared library are added.
Although it can be called explicitly, it is more commonly implicitly called by Although it can be called explicitly, it is more commonly implicitly called by
the `SharedLibrary` builder. the `SharedLibrary` builder.
### Build Hooks ###> Build Hooks
A build hook is a Ruby block that is called whenever Rscons is about to invoke A build hook is a Ruby block that is called whenever Rscons is about to invoke
a builder to produce a build target. a builder to produce a build target.
@ -674,17 +674,17 @@ end
This example script would compile all C sources under the `src` directory with 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.
## Extending Rscons ##> Extending Rscons
### Adding New Languages ### Adding New Languages
### Adding New Builders ### Adding New Builders
# Reference #> Reference
## Default Construction Variables ## Default Construction Variables
# License #> License
Rscons is licensed under the terms of the MIT License: Rscons is licensed under the terms of the MIT License:
@ -692,6 +692,6 @@ Rscons is licensed under the terms of the MIT License:
${include LICENSE.txt} ${include LICENSE.txt}
``` ```
# Change Log #> Change Log
${changelog} ${changelog}

2
rb/gen_user_guide.rb
View File

@ -125,7 +125,7 @@ class Generator
@sections.each do |section| @sections.each do |section|
indent = section.number.split(".").size - 1 indent = section.number.split(".").size - 1
toc_content += %[<span style="padding-left: #{4 * indent}ex;">] toc_content += %[<span style="padding-left: #{4 * indent}ex;">]
toc_content += %[<a href="#{section.page}##{section.anchor}">#{section.number} #{section.title}</a><br/>\n] toc_content += %[<a href="#{section.page}.html##{section.anchor}">#{section.number} #{section.title}</a><br/>\n]
toc_content += %[</span>] toc_content += %[</span>]
end end
toc_content toc_content