diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/buildfile.rst | 22 | ||||
-rw-r--r-- | docs/source/buildreference.rst | 110 | ||||
-rw-r--r-- | docs/source/index.rst | 1 | ||||
-rw-r--r-- | docs/source/taskreference.rst | 28 |
4 files changed, 133 insertions, 28 deletions
diff --git a/docs/source/buildfile.rst b/docs/source/buildfile.rst index 4372874..58e226a 100644 --- a/docs/source/buildfile.rst +++ b/docs/source/buildfile.rst @@ -69,6 +69,28 @@ purpose of the target, or what the target accomplishes when ran. Finally, we call ``mkdir`` of the ``xnt.tasks`` module. This function, if not obvious by the name, creates a directory named 'build' (see :doc:`taskreference`). +Return Values +============= + +The targets you define can return an error code (or '0' for success) however +you see fit. Doing this will give you a status message at the end of the +invocation of Xnt that will inform you if the target ran successfully or not +given your criteria (or will just say it succeeded if you don't specify a +return value at all). For example:: + + @target + def foo(): + return 0 + +Will result in:: + + ... + Success + +Most tasks have been updated to return error codes as well to that you can +return what it returns. If you find any tasks that can be updated to behave +this way, please create an issue for it. + .. _buildProperties: Build Properties 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 9ecb765..164ea36 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -29,6 +29,7 @@ Contents: xenant 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 ========= |