Support naming environments - close #140

doc/user_guide.md

@@ -82,6 +82,15 @@ files, dependency files, etc...) and build system metadata in a
 "build directory".
 This keeps files generated by the build cleanly separated from user-controlled
 source files.
+
+In contrast to other build systems or build system generators, rscons executes
+from the project base directory (up to the user) rather than executing from
+*within* the build directory.
+This keeps any file paths printed by compilers (such as in warning or error
+messages) accurate relative to the project directory, so that the user does not
+need to translate any paths to the correct path within a terminal or editor
+application, for example.
+
 By default a build directory named "build" is used, but this can be overridden
 by the user by using the `-b`/`--build` command-line option.
 
@@ -495,21 +504,26 @@ source files found recursively under the `src` directory.
 
 An Environment includes:
 
+  - a name
   - a collection of construction variables
   - a collection of build hooks
   - a collection of user-registered build targets
   - a build root
 
 All build targets must be registered within an `Environment`.
+If the user does not specify a name for the environment, a name will be
+automatically generated based on the Environment's internal ID, for example
+"e.1".
 The Environment's build root is a directory created within the top-level
 Rscons build directory.
+It is based on the Environment name.
 By default it holds all intermediate files generated by Rscons that are needed
 to produce a user-specified build target.
 For example, for the `Rsconscript`:
 
 ```ruby
 build do
-  Environment.new do |env|
+  Environment.new(name: "myproj") do |env|
     env.Program("myprog.exe", glob("src/**/*.c"))
   end
 end
@@ -517,6 +531,8 @@ end
 
 Rscons will place an object file and dependency file corresponding to each C
 source file under the Environment's build root.
+Assuming a top-level build directory of "build", the Environment's build root
+would be "build/myproj".
 This keeps the intermediate generated build artifacts separate from the source
 files.