build: change ABI versioning to global

[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 b1bf0d1..841ef6d 100644 (file)
--- a/doc/guides/contributing/coding_style.rst
+++ b/doc/guides/contributing/coding_style.rst
@@ -247,6 +247,15 @@ Structure Declarations
 * Use of the structures should be by separate variable declarations and those declarations must be extern if they are declared in a header file.
 * Externally visible structure definitions should have the structure name prefixed by ``rte_`` to avoid namespace collisions.
 
+.. note::
+
+    Uses of ``bool`` in structures are not preferred as is wastes space and
+    it's also not clear as to what type size the bool is. A preferred use of
+    ``bool`` is mainly as a return type from functions that return true/false,
+    and maybe local variable functions.
+
+    Ref: `LKML <https://lkml.org/lkml/2017/11/21/384>`_
+
 Queues
 ~~~~~~
 
@@ -622,10 +631,10 @@ In the DPDK environment, use the logging interface provided:
 
  /* log in debug level */
  rte_log_set_global_level(RTE_LOG_DEBUG);
- RTE_LOG(DEBUG, my_logtype1, "this is is a debug level message\n");
- RTE_LOG(INFO, my_logtype1, "this is is a info level message\n");
- RTE_LOG(WARNING, my_logtype1, "this is is a warning level message\n");
- RTE_LOG(WARNING, my_logtype2, "this is is a debug level message (not displayed)\n");
+ RTE_LOG(DEBUG, my_logtype1, "this is a debug level message\n");
+ RTE_LOG(INFO, my_logtype1, "this is a info level message\n");
+ RTE_LOG(WARNING, my_logtype1, "this is a warning level message\n");
+ RTE_LOG(WARNING, my_logtype2, "this is a debug level message (not displayed)\n");
 
  /* log in info level */
  rte_log_set_global_level(RTE_LOG_INFO);
@@ -741,8 +750,8 @@ A specialization looks like this:
  * PF/VF mailbox output: ``type.section.name.mbox``
 
 A real world example is the i40e poll mode driver which exposes two
-specializations, one for initialization ``pmd.i40e.init`` and the other for
-the remaining driver logs ``pmd.i40e.driver``.
+specializations, one for initialization ``pmd.net.i40e.init`` and the other for
+the remaining driver logs ``pmd.net.i40e.driver``.
 
 Note that specializations have no formatting rules, but please follow
 a precedent if one exists. In order to see all current log topics and
@@ -794,9 +803,8 @@ lpm, etc. For drivers, the same format of Makefile is used.
        CFLAGS += -O3
        CFLAGS += $(WERROR_FLAGS)
 
-       # the symbol version information for the library, and .so version
+       # the symbol version information for the library
        EXPORT_MAP := rte_<name>_version.map
-       LIBABIVER := 1
 
        # all source filenames are stored in SRCS-y
        SRCS-$(CONFIG_RTE_LIBRTE_<NAME>) += rte_<name>.c
@@ -816,10 +824,10 @@ format.
 .. code-block:: python
 
        sources = files('file1.c', ...)
-       headers = files('file1.c', ...)
+       headers = files('file1.h', ...)
 
 
-The will build based on a number of conventions and assumptions within the DPDK
+This will build based on a number of conventions and assumptions within the DPDK
 itself, for example, that the library name is the same as the directory name in
 which the files are stored.
 
@@ -843,12 +851,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
 
 
@@ -929,10 +940,19 @@ objs
        objects that were compiled up as part of another target given in the
        included library ``meson.build`` file.
 
-version
-       **Default Value = 1**.
-       Specifies the ABI version of the library, and is used as the major
-       version number of the resulting ``.so`` library.
+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.
 
 Meson Build File Contents - Drivers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -982,6 +1002,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