diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/buildfile.rst | 81 | ||||
-rw-r--r-- | docs/source/index.rst | 1 | ||||
-rw-r--r-- | docs/source/xenant.rst | 89 |
3 files changed, 108 insertions, 63 deletions
diff --git a/docs/source/buildfile.rst b/docs/source/buildfile.rst index 3867830..4372874 100644 --- a/docs/source/buildfile.rst +++ b/docs/source/buildfile.rst @@ -69,73 +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`). -.. _runningXnt: +.. _buildProperties: -Running Xnt ------------ - -Invoking Xnt from the command line is very simple and very similar to how other -build tools are invoked (this was intentional). - -.. _defaultUse: - -Default Use -~~~~~~~~~~~ - -The most simplistic use of Xnt is as follows:: - - $ xnt - -This will attempt to invoke the `default` target in the current directory's -`build.py`. - -.. _invokeTarget: - -Invoke a Target -~~~~~~~~~~~~~~~ - -To invoke a particular target, use:: - - $ xnt {target} - -Where the value of `{target}` is dependent on your particular `build.py` file. - -.. _specialTargets: - -Special Targets -~~~~~~~~~~~~~~~ - -"Special" targets (for lack of a better name) are targets that do not exist in -the build script, but rather are a part of Xnt. - -Thus far, I have only defined one "special" target, ``list-targets`` (I don't -think this name is going to change again ...). - -* ``list-targets`` does exactly what the name should suggest: it prints a list - of the targets found in the current directory's `build.py` script, along with - any docstrings that may be defined with them. - -Usage:: - - $ xnt list-targets - -.. _xntOptions: - -Options -~~~~~~~ - -Xnt also has a few "options" that may be provided along with a regular targets. +Build Properties +================ -Usage:: +As mentioned in :ref:`xntPropertiesParameters`, Xnt can accept parameters from +the command line and pass them into the build file. Xnt doesn't necessarily +expect the dictionary (named `properties`) to exist; but if you ever intend to +use it, it will have to be defined one way or another (either to an empty +dictionary or actually hold values). For example, to define an empty +`properties` dictionary, one could write their build file as such:: - $ xnt [options] [target] + #!/usr/bin/env python -Where options can be any and all of the following (unless otherwise specified): + from xnt import target -* ``-v``: add verbose output to the execution of Xnt + properties = {} -* ``--version``: Print the version of Xnt and exit + @target + def foo(): + #uses properties somehow + return 0 -* ``--usage``: Print version, license, usage information and quit. [I've - debatted between putting this as a special target and leaving it as an - option.. not sure which is better...] +The hope for this feature is that it is easy to use because it borrows syntax +from other build tools that you may already be familiar with. diff --git a/docs/source/index.rst b/docs/source/index.rst index 6ebb18e..9ecb765 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -26,6 +26,7 @@ Contents: .. toctree:: :maxdepth: 2 + xenant buildfile taskreference diff --git a/docs/source/xenant.rst b/docs/source/xenant.rst new file mode 100644 index 0000000..86a26da --- /dev/null +++ b/docs/source/xenant.rst @@ -0,0 +1,89 @@ +Running Xnt +=========== + +Invoking Xnt from the command line is very simple and very similar to how other +build tools are invoked (this was intentional). + +.. _defaultUse: + +Default Use +----------- + +The most simplistic use of Xnt is as follows:: + + $ xnt + +This will attempt to invoke the `default` target in the current directory's +`build.py`. + +.. _invokeTarget: + +Invoke a Target +--------------- + +To invoke a particular target, use:: + + $ xnt {target} + +Where the value of `{target}` is dependent on your particular `build.py` file. + +.. _specialTargets: + +Special Targets +--------------- + +"Special" targets (for lack of a better name) are targets that do not exist in +the build script, but rather are a part of Xnt. + +Thus far, I have only defined one "special" target, ``list-targets`` (I don't +think this name is going to change again ...). + +* ``list-targets`` does exactly what the name should suggest: it prints a list + of the targets found in the current directory's `build.py` script, along with + any docstrings that may be defined with them. + +Usage:: + + $ xnt list-targets + +.. _xntOptions: + +Options +------- + +Xnt also has a few "options" that may be provided along with a regular targets. + +Usage:: + + $ xnt [options] [target] + +Where options can be any and all of the following (unless otherwise specified): + +* ``-v``: add verbose output to the execution of Xnt + +* ``--version``: Print the version of Xnt and exit + +* ``--usage``: Print version, license, usage information and quit. [I've + debatted between putting this as a special target and leaving it as an + option.. not sure which is better...] + +.. _xntPropertiesParameters: + +Properties and Parameter Passing +-------------------------------- + +Xnt now has the ability to accept command line parameters and forward them to +your `build.py` file. This can be useful for a number of reasons: flipping +debug flags, deployment flags and the like or whatever else you can imagine. + +The general semantic for passing the parameters is as follows:: + + $ xnt [-D{name}={value}]+ [options] [target] + +*Notice:* the `-D` is used to distinguish values to be passed to the `build` +file from regular options. You may specify as many parameters as you like and +there is no other real ordering required to be parsed correctly. Just know, +spaces are used to delimit arguments; if your passed value *must* have a space, +remember to quote it. + +Please see :ref:`buildProperties` to see how this works on the `build.py` side. |