build: (fix #259, merge !411) Minimize rebuilds due to git repository update

* Add --enable-build-version option to control build version feature
 * Disable build version when --enable-build-version is not specified
 * Update getting started tutorial to reflect the new build option

doc/tutorial/source/getting-started.rst

@@ -1159,8 +1159,25 @@ except that the program and ns-3 libraries will not be rebuilt.
 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
+As of the ns-3.32 release, a new Waf configure option ``--enable-build-version`` 
+was introduced which inspects the local ns3 git repository during builds and adds 
+version metadata to the core module. 
+
+This configuration option has the following prerequisites:
+
+- The ns-3 directory must be part of a local git repository
+- The local git repository must have at least one ns-3 release tag
+
+or
+
+- A file named version.cache, containing version information, is located in the
+  src/core directory
+
+If these prerequisites are not met, the configuration will fail.
+
+When these prerequisites are met and ns-3 is configured with the 
+``--enable-build-version`` option, the waf command ``--check-version`` can be 
+used to query the local git repository and display the current version metadata. 
 
 .. sourcecode:: bash
 
@@ -1173,16 +1190,16 @@ to the output below.
 
   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 ``--check-version`` is run when ``-enable-build-version`` was not configured,
+an error message indicating that the option is disabled will be displayed instead.
 
-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.
+.. sourcecode:: text
+
+  Build version support is not enabled, reconfigure with --enable-build-version flag 
+
+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:
 
@@ -1229,6 +1246,10 @@ 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.
 
+The version information stored in the Version class is updated every time the
+git repository changes.  This may lead to frequent recompilations/linking of
+the core module when the ``--enable-build-version`` option is configured.
+
 .. sourcecode:: text
 
   build-version-example:
@@ -1258,13 +1279,6 @@ option which will print the full build version and exit.
   Waf: Entering directory `/g/g14/mdb/gitlab/mdb/ns-3-dev/build/debug'
   ns-3.31+28@gce1eb40-dirty-debug
 
-If information about the build version is absent from the ns-3 directory,
-the build system will print out a dummy build version such as follows:
-
-.. sourcecode:: text
-
-  $ ./waf --check-version
-  ns-3.xx@gxxxxxxx-debug
-
-An example situation that may lead to the lack of version information is
-if the ns-3 repository is cloned as a git shallow clone.
+If the ``--enable-build-version`` option was not configured, ``--version``
+will print out a message similar to ``--check-version`` indicating that the build
+version option is not enabled.

src/core/examples/wscript

@@ -55,9 +55,10 @@ def build(bld):
                                  ['core'])
     obj.source = 'fatal-example.cc'
 
-    obj = bld.create_ns3_program('build-version-example',
+    if bld.env['ENABLE_BUILD_VERSION']:
+        obj = bld.create_ns3_program('build-version-example',
                                  ['core'])
-    obj.source = 'build-version-example.cc'
+        obj.source = 'build-version-example.cc'
 
     if bld.env['ENABLE_THREADING'] and bld.env["ENABLE_REAL_TIME"]:
         obj = bld.create_ns3_program('main-test-sync', ['network'])

src/core/model/command-line.cc

@@ -27,7 +27,10 @@
 #include "system-path.h"
 #include "type-id.h"
 #include "string.h"
+
+#if defined (ENABLE_BUILD_VERSION)
 #include "version.h"
+#endif
 
 #include <algorithm>  // transform
 #include <cctype>     // tolower
@@ -338,7 +341,12 @@ CommandLine::PrintHelp (std::ostream &os) const
 std::string
 CommandLine::GetVersion () const
 {
+#if defined (ENABLE_BUILD_VERSION)
   return Version::LongVersion ();
+#else
+  return std::string{"Build version support is not enabled, reconfigure with "
+         "--enable-build-version flag"};
+#endif
 }
 
 void

src/core/model/version.cc

@@ -19,7 +19,7 @@
  */
 
 #include "version.h"
-#include "version-defines.h"
+#include "ns3/version-defines.h"
 #include <sstream>
 
 /**

src/core/wscript

@@ -47,6 +47,12 @@ def options(opt):
                     action="store_true", default=False,
                     dest='check_version')
 
+    opt.add_option('--enable-build-version',
+                    help=("Check git repository for changes and update build version"
+                          "during waf build"),
+                    action="store_true", default=False,
+                    dest='enable_build_version')
+
 def configure(conf):
 
     conf.load('versioning', ['waf-tools'])
@@ -154,6 +160,12 @@ int main ()
                                      "threading not enabled")
         conf.env["ENABLE_REAL_TIME"] = conf.env['ENABLE_THREADING']
 
+    if Options.options.enable_build_version:
+        conf.env['ENABLE_BUILD_VERSION'] = True 
+        conf.env.append_value('DEFINES', 'ENABLE_BUILD_VERSION=1')
+    else:
+        conf.env['ENABLE_BUILD_VERSION'] = False 
+
     conf.write_config_header('ns3/core-config.h', top=True)
 
 def build(bld):
@@ -161,22 +173,6 @@ def build(bld):
 
     bld.install_files('${INCLUDEDIR}/%s%s/ns3' % (wutils.APPNAME, wutils.VERSION), '../../ns3/core-config.h')
 
-    version_template = bld.path.find_node('model/version-defines.h.in')
-    version_header = bld.bldnode.make_node('version-defines.h') 
-
-    vers_tg = bld(features='version-defines', 
-                  source=version_template, 
-                  target=version_header)
-
-    #silence errors about no mapping for version-defines.h.in
-    vers_tg.mappings['.h'] = lambda *a, **k: None
-    vers_tg.mappings['.h.in'] = lambda *a, **k: None
-
-    if Options.options.check_version:
-        print_version(bld, vers_tg)
-        raise SystemExit(0)
-        return
-
     core = bld.create_ns3_module('core')
     core.source = [
         'model/time.cc',
@@ -239,7 +235,6 @@ def build(bld):
         'model/time-printer.cc',
         'model/show-progress.cc',
         'model/system-wall-clock-timestamp.cc',
-        'model/version.cc',
         ]
 
     if (bld.env['ENABLE_EXAMPLES']):
@@ -373,7 +368,6 @@ def build(bld):
         'model/node-printer.h',
         'model/time-printer.h',
         'model/show-progress.h',
-        'model/version.h',
         ]
 
     if (bld.env['ENABLE_EXAMPLES']):
@@ -441,6 +435,28 @@ def build(bld):
                 'test/random-variable-stream-test-suite.cc'
                 ])
 
+    vers_tg = None
+    if env['ENABLE_BUILD_VERSION']:
+        version_template = bld.path.find_node('model/version-defines.h.in')
+        version_header = bld.bldnode.make_node('ns3/version-defines.h') 
+
+        vers_tg = bld(features='version-defines', 
+                      source=version_template, 
+                      target=version_header)
+
+        #silence errors about no mapping for version-defines.h.in
+        vers_tg.mappings['.h'] = lambda *a, **k: None
+        vers_tg.mappings['.h.in'] = lambda *a, **k: None
+
+        core.source.append('model/version.cc')
+
+        headers.source.append('model/version.h')
+
+    if Options.options.check_version:
+        print_version(bld, vers_tg)
+        raise SystemExit(0)
+        return
+
     if (bld.env['ENABLE_EXAMPLES']):
         bld.recurse('examples')
 
@@ -449,6 +465,11 @@ def build(bld):
         pymod.source += ['bindings/module_helpers.cc']
 
 def print_version(bld, tg):
+
+    if tg is None:
+        print ('Build version support is not enabled, reconfigure with --enable-build-version flag')
+        return
+
     tg.post()
 
     for task in tg.tasks:

waf-tools/versioning.py

@@ -2,7 +2,7 @@
 
 import re
 
-from waflib import ConfigSet, Configure, Context, Task, TaskGen
+from waflib import ConfigSet, Configure, Context, Options, Task, TaskGen
 
 CACHE_FILE = 'version.cache'
 
@@ -91,7 +91,7 @@ class ns3_version_info(Task.Task):
 
 class git_ns3_version_info(ns3_version_info):
     '''Task to generate version fields from an ns-3 git repository'''
-    always_run = True
+    always_run = True 
 
     def _find_closest_tag(self, ctx):
         cmd = [
@@ -226,6 +226,9 @@ def configure(ctx):
     has_git_repo = False
     has_ns3_tags = False
 
+    if not Options.options.enable_build_version:
+        return
+
     if ctx.check_git_repo():
         has_git_repo = True
         has_ns3_tags = ctx.check_git_repo_has_ns3_tags()
@@ -252,16 +255,8 @@ def configure(ctx):
         else:
             ctx.end_msg(False)
 
-            #no version information, create dummy info
-            version_cache['CLOSEST_TAG'] = '"ns-3.xx"'
-            version_cache['VERSION_COMMIT_HASH'] = '"gxxxxxxx"'
-            version_cache['VERSION_DIRTY_FLAG'] = '0'
-            version_cache['VERSION_MAJOR'] = '3'
-            version_cache['VERSION_MINOR'] = '0'
-            version_cache['VERSION_PATCH'] = '0'
-            version_cache['VERSION_RELEASE_CANDIDATE'] = '""'
-            version_cache['VERSION_TAG'] = '"ns-3.xx"'
-            version_cache['VERSION_TAG_DISTANCE'] = '0'
+            ctx.fatal('Unable to find ns3 git repository or version.cache file '
+                        'containing version information')
 
         ctx.env.update(version_cache)