Make build information accessible by programs by extracting data from the local git repository (or a standalone file if a git repository is not present).

Changes

* Adds a new class named Version to the core module
* Adds a template file to the core module named version-defines.h.in
* Adds --PrintVersion and --version arguments to the CommandLine class.
* Creates a new waf tool which queries the local git repository and extracts build information from itCreate a waf task to extract version information from git repository

doc/tutorial/source/getting-started.rst

@@ -1155,3 +1155,106 @@ except that the program and ns-3 libraries will not be rebuilt.
 .. sourcecode:: bash
 
   $ ./waf --run-no-build '<ns3-program> --arg1=value1 --arg2=value2 ...'
+
+Build version
++++++++++++++
+
+As of the ns-3.32 release, a new Waf option was introduced to print out the
+version of the ns-3 build
+
+.. sourcecode:: bash
+
+  $ ./waf --check-version
+
+Waf will collect information about the build and print out something similar
+to the output below.
+
+.. sourcecode:: text
+
+  ns-3.31+26@g82e7f5d-debug
+
+The output of ``--check-version`` depends on how ns-3 was installed.  If ns-3
+was installed from a tarball, the build information is included in one
+of the files in the tarball.  In this case, the output of ``--check-version``
+will always be the same, except for the profile value which is based 
+on the ``--build-profile`` option passed to ``waf configure``.
+
+If ns-3 was downloaded using git, the build information is generated by
+examining the current state of the git repository.  The output of 
+``--check-version`` will change whenever the state of the active branch 
+changes.
+
+The output of ``--check-version`` has the following format:
+
+.. sourcecode:: text
+
+  <version_tag>[+closest_tag][+distance_from_tag]@<commit_hash>[-tree_state]-<profile>
+
+version_tag 
+  version_tag contains the version of the ns-3 code.  The version tag is
+  defined as a git tag with the format ns-3*.  If multiple git tags match the
+  format, the tag on the active branch which is closest to the current commit
+  is chosen. 
+
+closest_tag
+  closest_tag is similar to version_tag except it is the first tag found,
+  regardless of format.  The closest tag is not included in the output when
+  closest_tag and version_tag have the same value. 
+
+distance_from_tag
+  distance_from_tag contains the number of commits between the current commit 
+  and closest_tag.  distance_from_tag is not included in the output when the 
+  value is 0 (i.e. when closest_tag points to the current commit)
+
+commit_hash
+  commit_hash is the hash of the commit at the tip of the active branch. The
+  value is 'g' followed by the first 7 characters of the commit hash. The 'g'
+  prefix is used to indicate that this is a git hash. 
+
+tree_state
+  tree_state indicates the state of the working tree.  When the working tree
+  has uncommitted changes this field has the value 'dirty'.  The tree state is 
+  not included in the version output when the working tree is clean (e.g. when 
+  there are no uncommitted changes). 
+
+profile
+  The build profile specified in the ``--build-profile`` option passed to 
+  ``waf configure``
+
+A new class, named Version, has been added to the core module.  The Version class 
+contains functions to retrieve individual fields of the build version as well 
+as functions to print the full build version like ``--check-version``.
+The ``build-version-example``  application provides an example of how to use
+the Version class to retrieve the various build version fields.  See the
+documentation for the Version class for specifics on the output of the Version
+class functions.
+
+.. sourcecode:: text
+
+  build-version-example:
+  Program Version (according to CommandLine): ns-3.31+28@gce1eb40-dirty-debug
+
+  Version fields:
+  LongVersion:        ns-3.32+28@gcefeb91-dirty-debug
+  ShortVersion:       ns-3.32+*
+  BuildSummary:       ns-3.32+*
+  VersionTag:         ns-3.32
+  Major:              3
+  Minor:              32
+  Patch:              0
+  ReleaseCandidate:
+  ClosestAncestorTag: ns-3.32
+  TagDistance:        28
+  CommitHash:         gce1eb40
+  BuildProfile:       debug
+  WorkingTree:        dirty
+
+The CommandLine class has also been updated to support the ``--version`` 
+option which will print the full build version and exit.
+
+.. sourcecode:: text
+
+  ./waf --run-no-build "command-line-example --version"
+  Waf: Entering directory `/g/g14/mdb/gitlab/mdb/ns-3-dev/build/debug'
+  ns-3.31+28@gce1eb40-dirty-debug
+