From eba0e0553b77ccc6ddc67e2fdd55ec1815fba8d4 Mon Sep 17 00:00:00 2001
From: kennyballou <kballou@onyx.boisestate.edu>
Date: Thu, 17 Jan 2013 09:04:44 -0700
Subject: Update documentation for new xnt.build.cc module

Move notes/documentation about build wrappers to new page and add
documentation for new "Compiler Collection" module
---
 docs/source/buildreference.rst | 110 +++++++++++++++++++++++++++++++++++++++++
 docs/source/index.rst          |   1 +
 docs/source/taskreference.rst  |  28 -----------
 3 files changed, 111 insertions(+), 28 deletions(-)
 create mode 100644 docs/source/buildreference.rst

(limited to 'docs')

diff --git a/docs/source/buildreference.rst b/docs/source/buildreference.rst
new file mode 100644
index 0000000..704c812
--- /dev/null
+++ b/docs/source/buildreference.rst
@@ -0,0 +1,110 @@
+===============
+Build Reference
+===============
+
+Xnt has several "build" modules to aid you in your compliation and project/
+sub-project build steps
+
+Overview
+========
+
+* `Make`_
+
+* `Compiler Collection`_
+
+Make
+====
+
+Apache Ant
+----------
+
+.. _xnt.build.make.ant:
+.. function:: ant(path="", target="")
+
+    Invoke Apache Ant in either the current working directory or the specified
+    directory using the empty (default) target or the specified target.
+
+Gnu Make
+--------
+
+.. _xnt.bulid.make.make:
+.. function:: make(path="", target="")
+
+    Invoke Gnu Make (*make*) in either the current working directory or the
+    specified directory using the empty (default) target or the specified
+    target.
+
+(.NET)Ant
+---------
+
+.. _xnt.build.make.nant:
+.. function:: nant(path="", target="")
+
+    Invoke NAnt in either the current working directory or the specified
+    directory using the empty (default) target or the specified target.
+
+Compiler Collection
+===================
+
+For all compilers so far, Xnt assumes they are installed and in your `$PATH`.
+If they are not, an error will be thrown (by subprocess)
+
+gcc/g++
+-------
+
+.. _xnt.build.cc.gcc:
+.. function:: gcc(src, flags=[])
+
+    Compile `src` with the `gcc` to the default `out` (:ref:`defaultOut`) of
+    that source. Passing `flags` as given.
+
+.. _xnt.build.cc.gcc_o:
+.. function:: gcc_o(src, o, flags=[])
+
+    Compile `src` with `gcc` to the out file specified by `o`. Passing `flags`
+    as given.
+
+.. _xnt.build.cc.gpp:
+.. function:: gpp(src, flags=[])
+
+    Compile `src` with `g++` to the default `out` (:ref:`defaultOut`) of that
+    source. Passing `flags` as given.
+
+.. _xnt.bulid.cc.gpp_o:
+.. function:: gpp_o(src, o, flags=[])
+
+    Compile `src` with `g++` to the out file specified by `o`. Passing `flags`
+    as given.
+
+Javac
+-----
+
+.. _xnt.build.cc.javac:
+.. function:: javac(src, flags=[])
+
+    Compile `src` with `javac` to the default out file for the source. Passing
+    `flags` as given.
+
+Notes
+-----
+
+.. _defaultOut:
+
+Default out
+~~~~~~~~~~~
+
+Most, if not all, compilers have a default name given to compiled binaries when
+no output file name is given. For example, `gcc` will give code with a `main`
+method a name of `a.out` or `%.o` for objects, and so on. `javac` defaults to
+`<class-name>.class`.
+
+.. _recompile:
+
+Recompile
+~~~~~~~~~
+
+At the current moment, all compile wrappers do not do "smart" checks for
+compilation. That is, *all* compile steps will `rebuild` regardless if the
+binary file is modified later than the source file. This would be a nice
+feature, but I fear it would be too expensive (complicated) and out of the
+scope of this project to implement correctly.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 6ebb18e..6e1462c 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -28,6 +28,7 @@ Contents:
 
    buildfile
    taskreference
+   buildreference
 
 Motivation
 ==========
diff --git a/docs/source/taskreference.rst b/docs/source/taskreference.rst
index c303b5f..1c5fbe8 100644
--- a/docs/source/taskreference.rst
+++ b/docs/source/taskreference.rst
@@ -114,34 +114,6 @@ Compile Tasks
     Invoke Python setup.py given the list of *commands* (or options) in the
     current directory or in a different directory, specified by *dir*.
 
-Apache Ant
-----------
-
-.. _xnt.build.ant.ant:
-.. function:: ant(path="", target="")
-
-    Invoke Apache Ant in either the current working directory or the specified
-    directory using the empty (default) target or the specified target.
-
-Gnu Make
---------
-
-.. _xnt.bulid.make.make:
-.. function:: make(path="", target="")
-
-    Invoke Gnu Make (*make*) in either the current working directory or the
-    specified directory using the empty (default) target or the specified
-    target.
-
-(.NET)Ant
----------
-
-.. _xnt.build.nant.nant:
-.. function:: nant(path="", target="")
-
-    Invoke NAnt in either the current working directory or the specified
-    directory using the empty (default) target or the specified target.
-
 SCM Tasks
 =========
 
-- 
cgit v1.2.1