From cbf04e69e15c875fbe38eaf4dd48c45a61c3cc9e Mon Sep 17 00:00:00 2001 From: Mathew Bielejeski Date: Tue, 8 Sep 2020 08:55:57 -0700 Subject: [PATCH] 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 | 56 +++++++++++++++--------- src/core/examples/wscript | 5 ++- src/core/model/command-line.cc | 8 ++++ src/core/model/version.cc | 2 +- src/core/wscript | 57 +++++++++++++++++-------- waf-tools/versioning.py | 19 +++------ 6 files changed, 93 insertions(+), 54 deletions(-) diff --git a/doc/tutorial/source/getting-started.rst b/doc/tutorial/source/getting-started.rst index a7e668026..9f0f912fb 100644 --- a/doc/tutorial/source/getting-started.rst +++ b/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. diff --git a/src/core/examples/wscript b/src/core/examples/wscript index 2b769349a..15cded122 100644 --- a/src/core/examples/wscript +++ b/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']) diff --git a/src/core/model/command-line.cc b/src/core/model/command-line.cc index f6a7fcdbb..4c02ba349 100644 --- a/src/core/model/command-line.cc +++ b/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 // transform #include // 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 diff --git a/src/core/model/version.cc b/src/core/model/version.cc index c90bc808c..a66fdc8d1 100644 --- a/src/core/model/version.cc +++ b/src/core/model/version.cc @@ -19,7 +19,7 @@ */ #include "version.h" -#include "version-defines.h" +#include "ns3/version-defines.h" #include /** diff --git a/src/core/wscript b/src/core/wscript index 97a100e50..df84c0f01 100644 --- a/src/core/wscript +++ b/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: diff --git a/waf-tools/versioning.py b/waf-tools/versioning.py index 76e063bcb..634705bbb 100644 --- a/waf-tools/versioning.py +++ b/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)