add doc/user_guide.md

doc/user_guide.md

@@ -0,0 +1,153 @@
+# Overview
+
+Rscons is an open-source build system for developers.
+It supports the following features:
+
+  * multi-threaded job execution
+  * auto-configuration
+  * built-in builders for several common operations
+  * out-of-the-box support for C, C++, and D languages
+  * extensibility for other languages or custom builders
+  * compatible with Windows, Linux, and OS X
+  * colorized output with build progress
+  * build hooks
+
+At its core, Rscons is mainly an engine to:
+
+  - determine the proper order to perform build operations,
+  - 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.
+
+Along the way, Rscons provides a concise syntax for specifying common types of
+build operations, but also provides an extensible framework for performing
+custom build operations as well.
+
+Rscons is written in Ruby, and is inspired by SCons and waf.
+
+## Design Principles
+
+### Build Correctness
+
+The number one design principle in Rscons is build correctness.
+This means that a build operation will be performed when Rscons cannot
+determine that a build target is already up-to-date.
+A build target will be built whenever:
+
+  * the target file has been removed or changed since it was last built
+  * the command to build the target file is different from the previous command
+    used to build it
+  * any of the target file's dependency files have changed since the last time
+    the target was built
+
+Importantly, Rscons uses the content of a source (dependency) file to determine
+whether a rebuild is necessary, not simply the timestamp of the file, which can
+lead to an incorrect decision being made to not rebuild when a rebuild is
+necessary.
+
+### Build Flexibility
+
+Rscons supports multiple configurations of compilation flags or build options
+across multiple environments to build output files in different ways according
+to the user's desire.
+For example, the same source files can be built into a release executable, but
+also compiled with different compilation flags or build options into a test
+executable.
+Rscons also supports build hooks, which allow the user to further fine-tune the
+build system's operation.
+A build hook, for example, can be used to set a build option for only source
+files coming from a particular source directory.
+
+### Build Efficiency
+
+Rscons will automatically determine the number of threads to use based on the
+host CPU configuration, and will schedule jobs as efficiently as possible
+across the available threads in order to complete the build operation in as
+little time as possible.
+As development occurs and build operations are executed, Rscons makes use of a
+cache file in order to avoid rebuilding a target when it is already up to date.
+
+### Build Directory
+
+Rscons was designed to store temporary build artifacts (for example, object
+files, dependency files, etc...) in a `build` directory.
+This keeps files generated by the build cleanly separated from user-controlled
+source files.
+
+# Installation
+
+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.
+The only dependency required to run Rscons is to have a Ruby interpreter
+installed.
+The latest release can be downloaded from [TODO].
+Simply copy the `rscons` executable script into the desired location within
+the project to be built (typically the root of the repository).
+
+## Version Control Setup
+
+The following files should be added to source control:
+
+  * `rscons`
+  * `Rsconscript`
+
+Add the following line to `.gitignore` (or the equivalent thereof for different
+version control systems):
+
+    /.rscons*
+    /build/
+
+# The Build Script
+
+Rscons looks for instructions for what to build by reading a build script file
+called `Rsconscript` (or `Rsconscript.rb`).
+Here is a simple example `Rsconscript` file:
+
+    build do
+      Environment.new do |env|
+        env.Program("myprog.exe", glob("src/**/*.c"))
+      end
+    end
+
+This `Rsconscript` file would instruct Rscons to produce a *Program* target
+called `myprog.exe` which is to be built from all C source files found
+(recursively) under the `src` directory.
+
+The `Rsconscript` file is a Ruby script.
+
+# Command-Line Operation
+
+Rscons is typically invoked from the command-line as `./rscons`.
+Rscons supports several build *operations*:
+
+  * configure
+  * build
+  * clean
+  * distclean
+  * install
+  * uninstall
+
+## Configure Operation
+
+The `configure` operation will initialize the Rscons cache file and build
+directory.
+It will also perform any configuration checks requested by the build script.
+Such configuration checks can include:
+
+  * verifying operation of a compiler
+  * loading compilation/linker flags from a config program (e.g. `pkg-config`)
+  * verifying presence of a C/C++ header file
+  * verifying presence of a D import
+  * verifying presence of a library
+  * verifying presence of an executable
+
+
+
+# Build Script Authoring
+
+# License
+
+Rscons is licensed under the terms of the MIT License.
+
+# Change Log
+
+[TODO]