From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 5CFBDA04DD; Wed, 21 Oct 2020 10:21:59 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id E8574AD4B; Wed, 21 Oct 2020 10:18:16 +0200 (CEST) Received: from mga17.intel.com (mga17.intel.com [192.55.52.151]) by dpdk.org (Postfix) with ESMTP id 20595AD0C for ; Wed, 21 Oct 2020 10:18:11 +0200 (CEST) IronPort-SDR: +OlLcUVkBjm7knfL/FCdAQHilYugPVrn8mqWPHVcPwxSspLZO6QD1pHWBEGwn381XEGkuhylrF nWj/vyHl+uUA== X-IronPort-AV: E=McAfee;i="6000,8403,9780"; a="147190596" X-IronPort-AV: E=Sophos;i="5.77,400,1596524400"; d="scan'208";a="147190596" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga003.jf.intel.com ([10.7.209.27]) by fmsmga107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 21 Oct 2020 01:18:11 -0700 IronPort-SDR: SQ1us4oaLvaVUPyjgLmzJ1/MMqP9WF9WAXBHInVqv4Nq0pZPg+9eS4V8tqfGKWwHfMPinUYuDT uPlmm/E0Bl+A== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.77,400,1596524400"; d="scan'208";a="316302095" Received: from silpixa00400355.ir.intel.com (HELO silpixa00400355.ger.corp.intel.com) ([10.237.222.239]) by orsmga003.jf.intel.com with ESMTP; 21 Oct 2020 01:18:10 -0700 From: Ciara Power To: dev@dpdk.org Cc: Ciara Power , Louise Kilheeney Date: Wed, 21 Oct 2020 09:17:22 +0100 Message-Id: <20201021081725.68541-13-ciara.power@intel.com> X-Mailer: git-send-email 2.22.0 In-Reply-To: <20201021081725.68541-1-ciara.power@intel.com> References: <20200807123009.21266-1-ciara.power@intel.com> <20201021081725.68541-1-ciara.power@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v7 12/14] doc: remove references to make from contributing guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Make is no longer supported for compiling DPDK, references are now removed in the documentation. Signed-off-by: Ciara Power Signed-off-by: Louise Kilheeney --- v7: - Updated exec_env and arch lists. - Updated documentation build instruction. 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 | 37 ++++++++--------------- doc/guides/contributing/documentation.rst | 31 ++++--------------- doc/guides/contributing/patches.rst | 6 ++-- 3 files changed, 21 insertions(+), 53 deletions(-) diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst index 5fe7f63942..cbd0c3dd8e 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. +* 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. -.. note:: - - As in the linux kernel, the ``CONFIG_`` prefix is not used in C code. - This is only needed in Makefiles or shell scripts. - 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``, ``RTE_ARCH_PPC_64``, ``RTE_ARCH_ARM``, ``RTE_ARCH_ARMv7`` or ``RTE_ARCH_ARM64`` 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``, ``RTE_EXEC_ENV_LINUX`` or ``RTE_EXEC_ENV_WINDOWS`` 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__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..a4e6be6aca 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 build the documentation:: - make doc + ninja -C build doc -* 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 \ + .//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. -- 2.22.0