Packaging updates, started on the manual, too.

5 files changed, 293 insertions, 3 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3b055fb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# Build
+
+Xagasoft Build is a comprehensive build tool for nearly any multi-step
+automation process, but is intended primarily for compiling source code.
+
+Features:
+
+ * Does _NOT_ rely on make of any sort.
+ * Can auto-generate targets based on builtin and user proided rules.
+ * Contains it's own turing complete scripting language.
+ * Provides a variety of output modes to make errors easier to see.
+ * Supports plugins.
+ * Write much, much less and do more.
+ * Builtin understanding of dependancy tracking.
+
+## Requirements
+
+There are different requirements depending on how you got your source code and
+what you intend to do with it.  If you just want to use build, then I recommend
+getting one of the release tarballs.  They include most of the dependancies and
+are the easiest to use.
+
+### Tarball Releases
+
+To compile a tarball release you need:
+
+ * bash (or similar)
+ * C++ compiler (gcc is the primary development target)
+ * libc with pthreads and libdl support (glibc and most compatibles)
+
+### SCM Checkouts
+
+If you're getting the code from source control or want to do more there are
+these additional requirements:
+
+ * flex
+ * bison
+
+The flex and bison source code are pre-processed into C source code for the
+tarballs, so you do not need these programs in order to compile.
+
+Build also relies on libbu++, but the shell script 'build.sh' will check out
+the files it needs from libbu++ SVN.  These files are also included in the
+tarball release.
+
+Build also builds the easiest when using build.  Once you have a working
+version of build it's very easy to keep working on build.
+
+# Example Build Scripts
+
+Just to give you a taste, here are some real, simple build scripts.
+
+    target "filescan"
+    {
+        rule "exe";
+        input files("src/*.cpp");
+        CXXFLAGS += "-ggdb";
+        LDFLAGS += "-lbu++";
+    }
+
+Build has sensible defaults for many things, this creates an explicit target
+named filescan that relies on the source code in the directory src.  It adds
+debugging flags, and it links libbu++.
+
+The build system uses a variation on a standard boolean transitive closure
+algorithm to provide "path-finding" between the .cpp files and the inputs the
+"exe" rule needs to create output.  In this case it will automatically create
+targets needed to produce all of the object code.
+
+    CXXFLAGS += "-ggdb -I. -Ilibgats";
+    LDFLAGS += "-ggdb";
+
+    target "libjove.a"
+    {
+        rule "lib";
+        input files("src/libjove/*.cpp");
+    }
+
+    target "joved"
+    {
+        rule "exe";
+        input files("src/joved/*.cpp");
+        requires "libjove.a";
+
+        LDFLAGS += "-L. -ljove -lbu++ -Llibgats -lgats -lcryptopp -lpthread";
+    }
+
+This example is slightly more complex.  It sets some flags that all targets will
+use, then creates two explicit targets.  The second target, joved, also
+requires that libjove.a is up to date, but it is not treated as an input.  This
+is enough to determine order of building, all source files, targets, and even
+provides full dependancy tracking.
diff --git a/default.bld b/default.bld
index d88f3cd..467274b 100644
--- a/default.bld
+++ b/default.bld
@@ -9,6 +9,11 @@ CXXFLAGS += "-ggdb -W -Wall";
 
 CC = CXX; // We actually want to use c++ to compile our c files.
 
+if PREFIX == null then
+{
+    PREFIX = "/usr/local";
+}
+
 action "default"
 {
         build: ["build", targets("plugins")];
@@ -24,6 +29,11 @@ action "clean"
         clean: "build";
 }
 
+action "docs"
+{
+    build: targets("docs");
+}
+
 action "devinstall"
 {
         if "$(id -u)" != "0" then
@@ -106,3 +116,53 @@ for vimdir in dirs("/usr/share/vim/vim*") do
         }
 }
 
+target "docs/build-manual.pdf"
+{
+    display "pdflatex";
+    tag "docs";
+    profile "build"
+    {
+        condition always;
+        execute("mkdir -p docs/pdf");
+        // You have to do this multiple times to get the TOC right.
+        for j in range(1,3) do
+        {
+            notice "Pass ${j}...";
+            execute("cd docs/pdf; pdflatex ../build-manual.tex > /dev/null");
+        }
+        execute("mv docs/pdf/build-manual.pdf docs");
+        execute("rm -Rf docs/pdf");
+    }
+}
+
+target "docs/html-single/build-manual.html"
+{
+    display "htlatex";
+    tag "docs";
+    profile "build"
+    {
+        condition always;
+        execute("mkdir -p docs/html-single");
+        execute("cd docs/html-single; htlatex ../build-manual.tex > /dev/null");
+    }
+    profile "clean"
+    {
+        execute("rm -Rf docs/html-single");
+    }
+}
+
+target "docs/html-multi"
+{
+    display "htlatex";
+    tag "docs";
+    profile "build"
+    {
+        condition always;
+        execute("mkdir -p docs/html-multi");
+        execute("cd docs/html-multi; htlatex ../build-manual.tex \"html,3\" > /dev/null");
+    }
+    profile "clean"
+    {
+        execute("rm -Rf docs/html-multi");
+    }
+}
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}
diff --git a/pkg.bld b/pkg.bld
index 1f0e8f3..30c9668 100644
--- a/pkg.bld
+++ b/pkg.bld
@@ -22,6 +22,9 @@ target PKG_BASE
                 files("*.bld"),
                 "docs/build.1",
                 "docs/build.7",
+        files("docs/build-manual.*"),
+        files("docs/html-multi/*"),
+        files("docs/html-single/*"),
         "build.sh",
         "version",
                 "support/vim/syntax/build.vim",
@@ -79,7 +82,8 @@ target PKG_BASE + ".xz"
 rule "tarball"
 {
         input matches("*.cpp", "*.h", "*.c", "*.y", "*.l", "*.bld", "Doxyfile",
-                "*.1", "*.7", "*.vim", "*.sh", "version");
+                "*.1", "*.7", "*.vim", "*.sh", "version", "*.tex", "*.pdf", "*.html",
+        "*.css");
         profile "build"
         {
                 OUTDIR = OUTPUT.replace(".tar","");
diff --git a/src/build.l b/src/build.l
index 30c79a6..7a77bfc 100644
--- a/src/build.l
+++ b/src/build.l
@@ -140,12 +140,12 @@ int iStrDepth = 0;
         return LTR_UNDEF;
 }
 
--?([1-9][0-9]*)|(0)                                     {
+([1-9][0-9]*)|(0)                                       {
         yylval->iVal = strtol( yytext, NULL, 10 );
         return LTR_INT;
 }
 
-(0\.0+)|(-?(([1-9][0-9]*)|(0))\.[0-9]*)         {
+(0\.0+)|((([1-9][0-9]*)|(0))\.[0-9]*)           {
         yylval->fVal = strtof( yytext, NULL );
         return LTR_FLOAT;
 }