doc: separate versioning guide into version and policy

[dpdk.git] / doc / guides / contributing / coding_style.rst

diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst
index 656563d..e95a1a2 100644 (file)
--- a/doc/guides/contributing/coding_style.rst
+++ b/doc/guides/contributing/coding_style.rst
@@ -852,12 +852,15 @@ allow_experimental_apis
 build
        **Default Value = true**
        Used to optionally compile a library, based on its dependencies or
-       environment. A simple example of use would be:
+       environment. When set to "false" the ``reason`` value, explained below, should
+       also be set to explain to the user why the component is not being built.
+       A simple example of use would be:
 
 .. code-block:: python
 
-       if host_machine.system() != 'linux'
+       if not is_linux
                build = false
+               reason = 'only supported on Linux'
        endif
 
 
@@ -938,6 +941,20 @@ objs
        objects that were compiled up as part of another target given in the
        included library ``meson.build`` file.
 
+reason
+       **Default Value = '<unknown reason>'**.
+       This variable should be used when a library is not to be built i.e. when
+       ``build`` is set to "false", to specify the reason why a library will not be
+       built. For missing dependencies this should be of the form
+       ``'missing dependency, "libname"'``.
+
+use_function_versioning
+       **Default Value = false**.
+       Specifies if the library in question has ABI versioned functions. If it
+       has, this value should be set to ensure that the C files are compiled
+       twice with suitable parameters for each of shared or static library
+       builds.
+
 version
        **Default Value = 1**.
        Specifies the ABI version of the library, and is used as the major
@@ -991,6 +1008,9 @@ pkgconfig_extra_libs
        using static libraries. Anything added here will be appended to the end
        of the ``pkgconfig --libs`` output.
 
+reason
+       As above.
+
 sources [mandatory]
        As above