1 files changed, 134 insertions, 0 deletions

diff --git a/docs/build-manual.tex b/docs/build-manual.tex
new file mode 100644
index 0000000..a85c20e
--- /dev/null
+++ b/docs/build-manual.tex
@@ -0,0 +1,134 @@
+\documentclass[letterpaper]{book}
+\usepackage{listings}
+\begin{document}
+
+\title{Xagasoft Build Manual}
+\author{Mike Buland}
+\date{November 2012}
+\maketitle
+
+\tableofcontents
+
+\chapter{Introduction}
+Build is a self-contained, sophisticated tool for performing multi-step
+processes. The primary goal is to be able to replace the standard
+configure/make or cmake/make systems that have become quite popular.
+
+By default Build will work much as one would expect for compiling software, it
+uses file exisistance and timestamps to determine what to build, and every file
+has a list of dependant files and input files.
+
+However, this is only the default configuration, you can use anything as the
+condition for determining what to build or rebuild, and targets do not have to
+be files.
+
+Build boasts a sophisticated system for chaining rules together to take files
+through as many steps as necesarry to get them in the desirable foramt for input
+to the final step.  This may sound a little vague and confusing, but what it
+means in the end is that you can list, say, a bison file as on input to an
+executable target that requires object (.o) files.  In this case build will
+automatically figure out that it can get a .c file from the .y input file, and
+a .o file from the .c file.  It will autogenerate these targets for you and
+save a lot of time and effort on your part.
+
+\chapter{Structure of a Build File}
+Build files contain build script along with four major types of declerations.
+These are the major types that can be decared:
+
+\begin{description}
+    \item[Targets] \hfill \\
+    Explicit targets can be defined that represent units of work with a definate
+    goal and possibly inputs that can be other targets.
+    \item[Actions] \hfill \\
+    Actions are triggered from the command line and determine what targets to
+    build and how.
+    \item[Rules] \hfill \\
+    Rules determine both how to build explicit targets to make life easier as
+    well as how to auto-generate implicit targets.  An explicitly defined target
+    does not need to use a rule, but it can make everything easier.
+    \item[Functions] \hfill \\
+    Functions can be defined like in most programming languages, and called
+    anywhere in the script.  Functions can also be used in several key places in
+    targets to extend the functionality of build.
+\end{description}
+
+Build script also allows you to declare and use variables like many other
+scripting languages, which can be integers, floats, booleans, strings, lists,
+the special value null, and file handles.
+
+\section{A Quick Example}
+Let's start with a very basic example.  This example is capable of building an
+executable from any number of cpp source files:
+
+\begin{lstlisting}
+target "myprogram"
+{
+    rule "exe";
+    input files("src/*.cpp");
+}
+\end{lstlisting}
+
+This example doesn't set any special compliation or linking flags, but it is a
+complete and valid build file.  It will find all cpp files in src, generate an
+implicit target for each file to compile it into an object (.o) file, and then
+use those files as the input to the myprogram target in the end.
+
+\section{Targets}
+A target represents a unit of work.  This is usually a file in a compilation
+process, e.g. an object file, an executable, a library, et cetera.  Targets
+come in two major flavors: explicit and implicit.  Explicit targets are any
+targets that you define in a build script with the "target" keyword.  Targets
+can also be auto-generated by rules when needed, these are known as implicit
+targets.
+
+If a target is declared more than once the two targets are merged.  You can
+think of this as a newer target overriding \emph{parts} of an older target.  It
+does not replace the previous target.
+
+Targets can be declared inside of any linguistic construct, including if blocks
+and loops, this gives you a lot of flexibility, but in addition, you can
+specify a list of strings instead of a single string for the name of a target,
+this creates a target with the same specs for each name in the list.
+
+Targets can contain the following special keywords:
+
+\begin{description}
+    \item[input] \hfill \\
+    You can specify any expression that results in a string or list of strings.
+    These strings will be added to the list of inputs to this target, and if
+    they are targets they will be added as dependancies.  If you have a rule
+    specified then the list of inputs will be used to generate implicit targets
+    to satisfy dependancies.
+    \item[requires] \hfill \\
+    \item[profile] \hfill \\
+    \item[rule] \hfill \\
+    \item[tag] \hfill \\
+    \item[display] \hfill \\
+\end{description}
+
+
+\section{Actions}
+Actions are the primary interface to build scripts from the command line, when
+calling build you specify an action to run.  If no action is specified on the
+command line the action "default" is run.  If the build script doesn't specify
+a default action, one is generated for it that will attempt to build all
+explicit targets.
+
+Actions can contain almost any build script, plus an extra syntax that allows
+you to process a list of targets in a given profile (see the targets section
+for details). Basically this means that you have a lot of flexibility
+controlling how your targets are processed.
+
+Let's start with an example:
+
+\begin{lstlisting}
+action "default"
+{
+    build: "myprogram";
+}
+\end{lstlisting}
+
+This is as basic as it gets, this example will cause build to process the
+target "myprogram" using the profile "build".
+
+\end{document}