Merge pull request #3910 from Rohde-Schwarz/feature/module_lifecycle

Feature: Module Lifecycle and Experimental/Deprecated Features

configure.py

@@ -385,6 +385,16 @@ def process_command_line(args):
     target_group.add_option('--without-os-features', action='append', metavar='FEAT',
                             help='specify OS features to disable')
 
+    target_group.add_option('--enable-experimental-features', dest='enable_experimental_features',
+                            action='store_true', default=False, help='enable building of experimental features and modules')
+    target_group.add_option('--disable-experimental-features', dest='enable_experimental_features',
+                            action='store_false', help=optparse.SUPPRESS_HELP)
+
+    target_group.add_option('--enable-deprecated-features', dest='enable_deprecated_features',
+                            action='store_true', default=True, help=optparse.SUPPRESS_HELP)
+    target_group.add_option('--disable-deprecated-features', dest='enable_deprecated_features',
+                            action='store_false', help='disable building of deprecated features and modules')
+
     isa_extensions = [
         'SSE2', 'SSSE3', 'SSE4.1', 'SSE4.2', 'AVX2', 'BMI2', 'RDRAND', 'RDSEED',
         'AES-NI', 'SHA-NI',
@@ -941,9 +951,12 @@ def _parse_module_info(self, lex):
         self.name = info["name"]
         self.brief = info.get("brief") # possibly None
         self.type = info.get("type") or "Public"
+        self.lifecycle = info.get("lifecycle") or "Stable"
 
         if self.type not in ["Public", "Internal", "Virtual"]:
             raise InternalError("Module '%s' has an unknown type: %s" % (self.basename, self.type))
+        if self.lifecycle not in ["Stable", "Experimental", "Deprecated"]:
+            raise InternalError("Module '%s' has an unknown lifecycle status: %s" % (self.basename, self.lifecycle))
 
     @staticmethod
     def _validate_defines_content(defines):
@@ -1160,6 +1173,15 @@ def is_internal(self):
     def is_virtual(self):
         return self.type == "Virtual"
 
+    def is_stable(self):
+        return self.lifecycle == "Stable"
+
+    def is_experimental(self):
+        return self.lifecycle == "Experimental"
+
+    def is_deprecated(self):
+        return self.lifecycle == "Deprecated"
+
 class ModulePolicyInfo(InfoObject):
     def __init__(self, infofile):
         super().__init__(infofile)
@@ -2291,6 +2313,9 @@ def test_exe_extra_ldflags():
         'cpu_features': arch.supported_isa_extensions(cc, options),
         'system_cert_bundle': options.system_cert_bundle,
 
+        'enable_experimental_features': options.enable_experimental_features,
+        'disable_deprecated_features': not options.enable_deprecated_features,
+
         'fuzzer_mode': options.unsafe_fuzzer_mode,
         'building_fuzzers': options.build_fuzzers,
         'fuzzer_type': options.build_fuzzers.upper() if options.build_fuzzers else '',
@@ -2398,6 +2423,12 @@ def _check_usable(self, module, modname):
         elif not module.compatible_compiler(self._ccinfo, self._cc_min_version, self._archinfo.basename):
             self._not_using_because['incompatible compiler'].add(modname)
             return False
+        elif module.is_deprecated() and not self._options.enable_deprecated_features:
+            self._not_using_because['deprecated'].add(modname)
+            return False
+        elif module.is_experimental() and modname not in self._options.enabled_modules and not self._options.enable_experimental_features:
+            self._not_using_because['experimental'].add(modname)
+            return False
         return True
 
     @staticmethod
@@ -2415,13 +2446,27 @@ def _display_module_information_unused(cls, all_modules, skipped_modules):
     def _display_module_information_to_load(cls, all_modules, modules_to_load):
         sorted_modules_to_load = cls._remove_virtual_modules(all_modules, sorted(modules_to_load))
 
+        deprecated = []
+        experimental = []
         for modname in sorted_modules_to_load:
             if all_modules[modname].comment:
                 logging.info('%s: %s', modname, all_modules[modname].comment)
             if all_modules[modname].warning:
                 logging.warning('%s: %s', modname, all_modules[modname].warning)
             if all_modules[modname].load_on == 'vendor':
                 logging.info('Enabling use of external dependency %s', modname)
+            if all_modules[modname].is_deprecated():
+                deprecated.append(modname)
+            if all_modules[modname].is_experimental():
+                experimental.append(modname)
+
+        if deprecated:
+            logging.warning('These modules are deprecated and will be removed in a future release (consider disabling with --disable-deprecated-features): %s',
+                            ' '.join(deprecated))
+
+        if experimental:
+            logging.warning('These modules are experimental and may change or be removed in a future release: %s',
+                            ' '.join(experimental))
 
         if sorted_modules_to_load:
             logging.info('Loading modules: %s', ' '.join(sorted_modules_to_load))
@@ -3448,6 +3493,8 @@ def escape_build_lines(contents):
                                               'title': info.name,
                                               'internal': info.is_internal(),
                                               'virtual': info.is_virtual(),
+                                              'deprecated': info.is_deprecated(),
+                                              'experimental': info.is_experimental(),
                                               'brief': info.brief,
                                               'public_headers': info.header_public,
                                               'internal_headers': info.header_internal,

doc/building.rst

@@ -75,6 +75,15 @@ want the resulting binary to depend on. For instance to enable zlib
 support, add ``--with-zlib`` to your invocation of ``configure.py``.
 All available modules can be listed with ``--list-modules``.
 
+Some modules may be marked as 'deprecated' or 'experimental'. Deprecated
+modules are available and built by default, but they will be removed in a
+future release of the library. Use ``--disable-deprecated-features`` to
+disable all of these modules or ``--disable-modules=MODS`` for finer grained
+control. Experimental modules are under active development and not built
+by default. Their API may change in future minor releases. Applications may
+still enable and use such modules using ``--enable-modules=MODS`` or using
+``--enable-experimental-features`` to enable all experimental features.
+
 You can control which algorithms and modules are built using the
 options ``--enable-modules=MODS`` and ``--disable-modules=MODS``, for
 instance ``--enable-modules=zlib`` and ``--disable-modules=xtea,idea``.
@@ -706,6 +715,30 @@ Specify an OS feature to enable. See ``src/build-data/os`` and
 
 Specify an OS feature to disable.
 
+``--enable-experimental-features``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enable all experimental modules and features. Note that these are unstable and
+may change or even be removed in future releases. Also note that individual
+experimental modules can be explicitly enabled using ``--enable-modules=MODS``.
+
+``--disable-experimental-features``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Disable all experimental modules and features. This is the default.
+
+``--enable-deprecated-features``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enable all deprecated modules and features. Note that these are scheduled for
+removal in future releases. This is the default.
+
+``--disable-deprecated-features``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Disable all deprecated modules and features. Note that individual deprecated
+modules can be explicitly disabled using ``--disable-modules=MODS``.
+
 ``--disable-sse2``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/dev_ref/configure.rst

@@ -213,6 +213,16 @@ Maps:
      * ``Virtual`` This module does not contain any implementation but acts as
        a container for other sub-modules. It cannot be interacted with by the
        library user and cannot be depended upon directly.
+   * ``lifecycle`` specifies the module's lifecycle (defaults to ``Stable``)
+
+     * ``Stable`` The module is stable and will not change in a way that would
+       break backwards compatibility.
+     * ``Experimental`` The module is experimental and may change in a way that
+       would break backwards compatibility. Not enabled in a default build.
+       Either use ``--enable-modules`` or ``--enable-experimental-features``.
+     * ``Deprecated`` The module is deprecated and will be removed in a future
+       release. It remains to be enabled in a default build. Either use
+       ``--disable-modules`` or ``--disable-deprecated-features``.
 
  * ``libs`` specifies additional libraries which should be linked if this module is
    included. It maps from the OS name to a list of libraries (comma seperated).

doc/sem_ver.rst

@@ -10,6 +10,11 @@ If on upgrading to a new minor version, you encounter a problem where your
 existing code either fails to compile, or the code behaves differently in some
 way that causes trouble, it is probably a bug; please report it on Github.
 
+Note that none of these guarantees apply to "experimental modules" that are not
+built by default. The functionality as well as API of such modules may change or
+even disappear in a minor version without warning. See :ref:`building` for more
+information on enabling or disabling these modules.
+
 Exception
 -----------------------
 

src/build-data/buildh.in

@@ -65,6 +65,14 @@
 #define BOTAN_FUZZER_IS_%{fuzzer_type}
 %{endif}
 
+%{if disable_deprecated_features}
+#define BOTAN_DISABLE_DEPRECATED_FEATURES
+%{endif}
+
+%{if enable_experimental_features}
+#define BOTAN_ENABLE_EXPERIMENTAL_FEATURES
+%{endif}
+
 #define BOTAN_INSTALL_PREFIX R"(%{prefix})"
 #define BOTAN_INSTALL_HEADER_DIR R"(%{includedir}/botan-%{version_major})"
 #define BOTAN_INSTALL_LIB_DIR R"(%{libdir})"

src/build-data/module_info.in

@@ -19,6 +19,22 @@
  *       build policy nor `--enable-modules`. Please feel free to enable/disable
  *       the sub-modules listed.
  *
+%{endif}
+%{if deprecated}
+ * @deprecated This module is scheduled for removal in a future release of the
+ *             library. Users should move away from it before updating to a new
+ *             version of the library. Note that deprecated modules may be explicitly
+ *             disabled using `--disable-modules=MODS` or generically using
+ *             `--disable-deprecated-features`.
+%{endif}
+%{if experimental}
+ * @warning This module is marked as 'experimental'. Its functionality and API
+ *          may change in future (minor) releases. Also, its implementation
+ *          quality must be considered 'beta' at best. Applications may still
+ *          enable and use it explicitly via `--enable-modules=MODS` or
+ *          generically using `--enable-experimental-features`. Early feedback
+ *          is very welcome.
+ *
 %{endif}
  *
 %{if dependencies}

src/scripts/ci_build.py

@@ -170,7 +170,8 @@ def sanitize_kv(some_string):
              '--os=%s' % (target_os),
              '--build-targets=%s' % ','.join(build_targets(target, target_os)),
              '--with-build-dir=%s' % build_dir,
-             '--link-method=symlink']
+             '--link-method=symlink',
+             '--enable-experimental-features']
 
     if ccache is not None:
         flags += ['--no-store-vc-rev', '--compiler-cache=%s' % (ccache)]