From 90886ed9ad3d993830a93f2b046ef3e0b13644ca Mon Sep 17 00:00:00 2001 From: Josh Holtrop Date: Tue, 4 Jun 2019 22:59:04 -0400 Subject: [PATCH] User Guide: add glob() and Builders documentation --- doc/user_guide.md | 210 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 208 insertions(+), 2 deletions(-) diff --git a/doc/user_guide.md b/doc/user_guide.md index eaa6b1e..3757f03 100644 --- a/doc/user_guide.md +++ b/doc/user_guide.md @@ -352,6 +352,22 @@ An Environment is a collection of: All build targets must be registered within an `Environment`. +### Specifying Source Files: The glob Method + +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. + +Example use: + + build do + Environment.new do |env| + env.Program("mytests", glob("src/**/*.cc", "test/**/*.cc")) + end + end + +This example would build the `mytests` executable from all `.cc` source files +found recursively under the `src` or `test` directory. + ### Construction Variables Construction variables are values assigned to keys within an Environment. @@ -372,6 +388,198 @@ This example modifies the `CCFLAGS` construction variable to add `-O2` and `-Wall` to the compilation commands used for C and C++ source files. It also instructs the linker to link against the `m` library. +### Builders + +Rscons uses builder objects to produce *target* output files from *source* +input files. +Each builder is registered by calling a method on the `Environment` object +that matches the builder's name. +For example, a `Program` builder is registered by calling the `env.Program` +method. +There are several default builders that are built-in to Rscons: + + * `Command`, which executes a user-defined command to produce the target. + * `Copy`, which copies files or directories to a specified destination. + * `CFile`, which builds a C or C++ source file from a lex or yacc input file. + * `Directory`, which creates a directory. + * `Disassemble`, which disassembles an object file to a disassembly listing. + * `Install`, which installs files or directories to a specified destination. + * `InstallDirectory`, which creates a directory during an install operation. + * `Library`, which collects object files into a static library archive file. + * `Object`, which compiles source files to produce an object file. + * `Preprocess`, which invokes the C/C++ preprocessor on a source file. + * `Program`, which links object files to produce an executable. + * `SharedLibrary`, which links object files to produce a dynamically loadable + library. + * `SharedObject`, which compiles source files to produce an object file, in a + way that is able to be used to create a shared library. + +#### The Command Builder + +```ruby +env.Command(target, sources, "CMD" => command) +# Example +env.Command("docs.html", "docs.md", + "CMD" => ["pandoc", "-fmarkdown", "-thtml", "-o${_TARGET}", "${_SOURCES}"], + "CMD_DESC" => "PANDOC") +``` + +The `Command` builder executes a user-defined command in order to produce the +desired target file based on the provided source files. + +#### The CFile Builder + +```ruby +env.CFile(target, source) +# Example +env.CFile("^/parser/parser.c", "parser.y") +``` + +The `CFile` builder will generate a C or C++ source file from a lex (.l, .ll) +or yacc (.y, .yy) input file. + +#### The Copy Builder + +```ruby +env.Copy(destination, sources) +# Example +env.Copy("mytests", "^/mytests") +env.Copy("^/dist/share", "share") +``` + +The `Copy` builder can copy files or directories to a target location. + +#### The Directory Builder + +```ruby +env.Directory(target) +# Example +env.Directory("^/tests") +``` + +The `Directory` builder can be used to explicitly create a directory. +This can also disambiguate whether the target for a subsequent builder +(e.g. `Copy`) refers to a file path or directory path. + +#### The Disassemble Builder + +```ruby +env.Disassemble(target, source) +# Example +env.Disassemble("module.dis", "module.o") +``` + +The `Disassemble` builder generates a disassembly listing using objdump from +and object file. + +#### The Install Builder + +```ruby +env.Install(destination, sources) +# Example +env.Install("${prefix}/bin", "app.exe") +env.Install("${prefix}/share", "share") +``` + +The `Install` builder can install files or directories to their installation +target location. +`Install` builders are only processed when the user has requested to perform +an `install` operation from the command line. + +#### The InstallDirectory Builder + +```ruby +env.InstallDirectory(target) +# Example +env.InstallDirectory("${prefix}/share") +``` + +The `InstallDirectory` builder can be used to explicitly create a directory. +`InstallDirectory` builders are only processed when the user has requested to +perform an `install` operation from the command line. +This can also disambiguate whether the target for a subsequent builder +(e.g. `Install`) refers to a file path or directory path. + +#### The Library Builder + +```ruby +env.Library(target, sources) +# Example +env.Library("lib.a", Rscons.glob("src/**/*.c")) +``` + +The `Library` builder creates a static library archive from the given source +files. + +#### The Object Builder + +```ruby +env.Object(target, sources) +# Example +env.Object("module.o", "module.c") +``` + +The `Object` builder compiles the given sources to an object file. +Although it can be called explicitly, it is more commonly implicitly called by +the `Program` builder. + +#### The Preprocess Builder + +```ruby +env.Preprocess(target, source) +# Example +env.Preprocess("module-preprocessed.cc", "module.cc") +``` + +The `Preprocess` builder invokes either `${CC}` or `${CXX}` (depending on if +the source contains an extension in `${CXXSUFFIX}` or not) and writes the +preprocessed output to the target file. + +#### The Program Builder + +```ruby +env.Program(target, sources) +# Example +env.Program("myprog", Rscons.glob("src/**/*.cc")) +``` + +The `Program` builder compiles and links the given sources to an executable +file. +Object files, static library files, or source files can be given as `sources`. +A platform-dependent program suffix will be appended to the target name if one +is not specified. +This can be controlled with the `PROGSUFFIX` construction variable. + +#### The SharedLibrary Builder + +```ruby +env.SharedLibrary(target, sources) +# Example +env.SharedLibrary("mydll", Rscons.glob("src/**/*.cc")) +``` + +The `SharedLibrary` builder compiles and links the given sources to a +dynamically loadable library. +Object files or source files can be given as `sources`. +A platform-dependent prefix and suffix will be appended to the target name if +they are not specified by the user. +These values can be controlled by overriding the `SHLIBPREFIX` and +`SHLIBSUFFIX` construction variables. + +#### The SharedObject Builder + +```ruby +env.SharedObject(target, sources) +# Example +env.SharedObject("lib_module.o", "lib_module.c") +``` + +The `SharedObject` builder compiles the given sources to an object file. +Any compilation flags necessary to build the object file in a manner that +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 +the `SharedLibrary` builder. + ### Build Hooks A build hook is a Ruby block that is called whenever Rscons is about to invoke @@ -407,8 +615,6 @@ the `-Wall` flag except for sources under the `src/tests` directory. # Reference -## Default Builders - ## Default Construction Variables # License