[v6,12/14] doc: remove references to make from contributing guide
diff mbox series

Message ID 20201009102140.20730-13-ciara.power@intel.com
State Superseded
Delegated to: Thomas Monjalon
Headers show
Series
  • remove make support in DPDK
Related show

Checks

Context Check Description
ci/checkpatch success coding style OK

Commit Message

Ciara Power Oct. 9, 2020, 10:21 a.m. UTC
Make is no longer supported for compiling DPDK, references are now
removed in the documentation.

Signed-off-by: Ciara Power <ciara.power@intel.com>
Signed-off-by: Louise Kilheeney <louise.kilheeney@intel.com>

---
v5:
  - Removed reference to test-build.sh used for Make.
  - Added point back in for handling specific code, reworded as
    necessary.
  - Added library statistics section, removing only the mention of
    CONFIG options.
---
 doc/guides/contributing/design.rst        | 41 ++++++++---------------
 doc/guides/contributing/documentation.rst | 31 ++++-------------
 doc/guides/contributing/patches.rst       |  6 ++--
 3 files changed, 23 insertions(+), 55 deletions(-)

Comments

Thomas Monjalon Oct. 11, 2020, 8:52 p.m. UTC | #1
09/10/2020 12:21, Ciara Power:
> -   As in the linux kernel, the ``CONFIG_`` prefix is not used in C code.
> -   This is only needed in Makefiles or shell scripts.
> +* Use build definition macros and conditions in the Meson build file. This is done when the differences
> +  are more significant. In this case, the code is split into two separate files that are architecture
> +  or environment specific. This should only apply inside the EAL library.

When writing new sentences, it's better splitting lines after a punctuation,
preferably the end of a sentence.


>  Per Architecture Sources
>  ~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -The following config options can be used:
> +The following macro options can be used:
>  
> -* ``CONFIG_RTE_ARCH`` is a string that contains the name of the architecture.
> -* ``CONFIG_RTE_ARCH_I686``, ``CONFIG_RTE_ARCH_X86_64``, ``CONFIG_RTE_ARCH_X86_64_32`` or ``CONFIG_RTE_ARCH_PPC_64`` are defined only if we are building for those architectures.
> +* ``RTE_ARCH`` is a string that contains the name of the architecture.
> +* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_64_32`` or ``RTE_ARCH_PPC_64`` are defined only if we are building for those architectures.

This is out of date. Arm is notably missing.

>  Per Execution Environment Sources
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -The following config options can be used:
> +The following macro options can be used:
>  
> -* ``CONFIG_RTE_EXEC_ENV`` is a string that contains the name of the executive environment.
> -* ``CONFIG_RTE_EXEC_ENV_FREEBSD`` or ``CONFIG_RTE_EXEC_ENV_LINUX`` are defined only if we are building for this execution environment.
> +* ``RTE_EXEC_ENV`` is a string that contains the name of the executive environment.
> +* ``RTE_EXEC_ENV_FREEBSD`` or ``RTE_EXEC_ENV_LINUX`` are defined only if we are building for this execution environment.

This is out of date. Windows is missing.

[...]
> -* Generate all the documentation targets::
> +To enable doc building::
>  
> -     make doc
> +   meson configure -Denable_docs=true

No need of this option.
"ninja -C build doc" works even without it.

Patch
diff mbox series

diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst
index 5fe7f63942..3e24dc1c7b 100644
--- a/doc/guides/contributing/design.rst
+++ b/doc/guides/contributing/design.rst
@@ -21,7 +21,7 @@  A file located in a subdir of "linux" is specific to this execution environment.
 
 When absolutely necessary, there are several ways to handle specific code:
 
-* Use a ``#ifdef`` with the CONFIG option in the C code.
+* Use a ``#ifdef`` with a build definition macro in the C code.
   This can be done when the differences are small and they can be embedded in the same C file:
 
   .. code-block:: c
@@ -32,30 +32,25 @@  When absolutely necessary, there are several ways to handle specific code:
      titi();
      #endif
 
-* Use the CONFIG option in the Makefile. This is done when the differences are more significant.
-  In this case, the code is split into two separate files that are architecture or environment specific.
-  This should only apply inside the EAL library.
-
-.. note::
-
-   As in the linux kernel, the ``CONFIG_`` prefix is not used in C code.
-   This is only needed in Makefiles or shell scripts.
+* Use build definition macros and conditions in the Meson build file. This is done when the differences
+  are more significant. In this case, the code is split into two separate files that are architecture
+  or environment specific. This should only apply inside the EAL library.
 
 Per Architecture Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following config options can be used:
+The following macro options can be used:
 
-* ``CONFIG_RTE_ARCH`` is a string that contains the name of the architecture.
-* ``CONFIG_RTE_ARCH_I686``, ``CONFIG_RTE_ARCH_X86_64``, ``CONFIG_RTE_ARCH_X86_64_32`` or ``CONFIG_RTE_ARCH_PPC_64`` are defined only if we are building for those architectures.
+* ``RTE_ARCH`` is a string that contains the name of the architecture.
+* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_64_32`` or ``RTE_ARCH_PPC_64`` are defined only if we are building for those architectures.
 
 Per Execution Environment Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following config options can be used:
+The following macro options can be used:
 
-* ``CONFIG_RTE_EXEC_ENV`` is a string that contains the name of the executive environment.
-* ``CONFIG_RTE_EXEC_ENV_FREEBSD`` or ``CONFIG_RTE_EXEC_ENV_LINUX`` are defined only if we are building for this execution environment.
+* ``RTE_EXEC_ENV`` is a string that contains the name of the executive environment.
+* ``RTE_EXEC_ENV_FREEBSD`` or ``RTE_EXEC_ENV_LINUX`` are defined only if we are building for this execution environment.
 
 Mbuf features
 -------------
@@ -87,22 +82,14 @@  requirements for preventing ABI changes when implementing statistics.
 Mechanism to allow the application to turn library statistics on and off
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Each library that maintains statistics counters should provide a single build
-time flag that decides whether the statistics counter collection is enabled or
-not. This flag should be exposed as a variable within the DPDK configuration
-file. When this flag is set, all the counters supported by current library are
+Having runtime support for enabling/disabling library statistics is recommended,
+as build-time options should be avoided. However, if build-time options are used,
+for example as in the table library, the options can be set using c_args.
+When this flag is set, all the counters supported by current library are
 collected for all the instances of every object type provided by the library.
 When this flag is cleared, none of the counters supported by the current library
 are collected for any instance of any object type provided by the library:
 
-.. code-block:: console
-
-   # DPDK file config/common_linux, config/common_freebsd, etc.
-   CONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n
-
-The default value for this DPDK configuration file variable (either "yes" or
-"no") is decided by each library.
-
 
 Prevention of ABI changes due to library statistics support
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index be985e6cf8..fd73e6538b 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -218,25 +218,14 @@  Build commands
 ~~~~~~~~~~~~~~
 
 The documentation is built using the standard DPDK build system.
-Some examples are shown below:
 
-* Generate all the documentation targets::
+To enable doc building::
 
-     make doc
+   meson configure -Denable_docs=true
 
-* Generate the Doxygen API documentation in Html::
+See :doc:`../linux_gsg/build_dpdk` for more detail on compiling DPDK with meson.
 
-     make doc-api-html
-
-* Generate the guides documentation in Html::
-
-     make doc-guides-html
-
-* Generate the guides documentation in Pdf::
-
-     make doc-guides-pdf
-
-The output of these commands is generated in the ``build`` directory::
+The output is generated in the ``build`` directory::
 
    build/doc
          |-- html
@@ -251,10 +240,6 @@  The output of these commands is generated in the ``build`` directory::
 
    Make sure to fix any Sphinx or Doxygen warnings when adding or updating documentation.
 
-The documentation output files can be removed as follows::
-
-   make doc-clean
-
 
 Document Guidelines
 -------------------
@@ -304,7 +289,7 @@  Line Length
   Long literal command lines can be shown wrapped with backslashes. For
   example::
 
-     testpmd -l 2-3 -n 4 \
+     dpdk-testpmd -l 2-3 -n 4 \
              --vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
              -- -i --tx-offloads=0x0000002c --enable-lro --txq=2 --rxq=2 \
              --txd=1024 --rxd=1024
@@ -456,7 +441,7 @@  Code and Literal block sections
   For long literal lines that exceed that limit try to wrap the text at sensible locations.
   For example a long command line could be documented like this and still work if copied directly from the docs::
 
-     build/app/testpmd -l 0-2 -n3 --vdev=net_pcap0,iface=eth0     \
+     ./<build_dir>/app/dpdk-testpmd -l 0-2 -n3 --vdev=net_pcap0,iface=eth0    \
                                --vdev=net_pcap1,iface=eth1     \
                                -- -i --nb-cores=2 --nb-ports=2 \
                                   --total-num-mbufs=2048
@@ -739,9 +724,5 @@  The following are some guidelines for use of Doxygen in the DPDK API documentati
      /** Array of physical page addresses for the mempool buffer. */
      phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT];
 
-* Check for Doxygen warnings in new code by checking the API documentation build::
-
-     make doc-api-html >/dev/null
-
 * Read the rendered section of the documentation that you have added for correctness, clarity and consistency
   with the surrounding text.
diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst
index 9ff60944c3..9fa5a79c85 100644
--- a/doc/guides/contributing/patches.rst
+++ b/doc/guides/contributing/patches.rst
@@ -486,9 +486,9 @@  By default, ABI compatibility checks are disabled.
 To enable them, a reference version must be selected via the environment
 variable ``DPDK_ABI_REF_VERSION``.
 
-The ``devtools/test-build.sh`` and ``devtools/test-meson-builds.sh`` scripts
-then build this reference version in a temporary directory and store the
-results in a subfolder of the current working directory.
+The ``devtools/test-meson-builds.sh`` script then build this reference version
+in a temporary directory and store the results in a subfolder of the current
+working directory.
 The environment variable ``DPDK_ABI_REF_DIR`` can be set so that the results go
 to a different location.