[dpdk-stable] [PATCH 3/4] doc: update build instructions in the Linux guide

[dpdk-stable] [PATCH 3/4] doc: update build instructions in the Linux guide

[Thomas Monjalon]

Before removing the "make" build system completely,
the Linux guide instructions are made more concise and accurate.
Some detailed explanations are also available in
doc/guides/prog_guide/dev_kit_root_make_help.rst

This is the swan song for makefile system,
in order to have accurate information backported in LTS.

Cc: stable@dpdk.org

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
 doc/guides/linux_gsg/build_dpdk.rst | 66 ++++++++---------------------
 1 file changed, 18 insertions(+), 48 deletions(-)

diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
index 4aeb4697d9..c536e354ef 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -167,60 +167,32 @@ Installation of DPDK Target Environment using Make
    is therefore recommended that DPDK installation is done using meson and
    ninja as described above.
 
-The format of a DPDK target is::
+Get a native target environment automatically::
 
-    ARCH-MACHINE-EXECENV-TOOLCHAIN
-
-where:
-
-* ``ARCH`` can be:  ``i686``, ``x86_64``, ``ppc_64``, ``arm64``
-
-* ``MACHINE`` can be:  ``native``, ``power8``, ``armv8a``
-
-* ``EXECENV`` can be:  ``linux``,  ``freebsd``
-
-* ``TOOLCHAIN`` can be:  ``gcc``,  ``icc``
-
-The targets to be installed depend on the 32-bit and/or 64-bit packages and compilers installed on the host.
-Available targets can be found in the DPDK/config directory.
-The defconfig\_ prefix should not be used.
+   make defconfig O=mybuild
 
 .. note::
 
-    Configuration files are provided with the ``RTE_MACHINE`` optimization level set.
     Within the configuration files, the ``RTE_MACHINE`` configuration value is set to native,
     which means that the compiled software is tuned for the platform on which it is built.
-    For more information on this setting, and its possible values, see the *DPDK Programmers Guide*.
 
-When using the Intel® C++ Compiler (icc), one of the following commands should be invoked for 64-bit or 32-bit use respectively.
-Notice that the shell scripts update the ``$PATH`` variable and therefore should not be performed in the same session.
-Also, verify the compiler's installation directory since the path may be different:
+Or get a specific target environment::
 
-.. code-block:: console
+   make config T=x86_64-native-linux-gcc O=mybuild
 
-    source /opt/intel/bin/iccvars.sh intel64
-    source /opt/intel/bin/iccvars.sh ia32
+The format of a DPDK target is "ARCH-MACHINE-EXECENV-TOOLCHAIN".
+Available targets can be found with::
 
-To install and make targets, use the ``make install T=<target>`` command in the top-level DPDK directory.
+   make help
 
-For example, to compile a 64-bit target using icc, run:
+Customize the target configuration in the generated ``.config`` file.
+Example for enabling the pcap PMD::
 
-.. code-block:: console
+   sed -ri 's,(PMD_PCAP=).*,\1y,' mybuild/.config
 
-    make install T=x86_64-native-linux-icc
+Compile the target::
 
-To compile a 32-bit build using gcc, the make command should be:
-
-.. code-block:: console
-
-    make install T=i686-native-linux-gcc
-
-To prepare a target without building it, for example, if the configuration changes need to be made before compilation,
-use the ``make config T=<target>`` command:
-
-.. code-block:: console
-
-    make config T=x86_64-native-linux-gcc
+   make -j4 O=mybuild
 
 .. warning::
 
@@ -229,15 +201,13 @@ use the ``make config T=<target>`` command:
     If the DPDK is not being built on the target machine,
     the ``RTE_KERNELDIR`` environment variable should be used to point the compilation at a copy of the kernel version to be used on the target machine.
 
-Once the target environment is created, the user may move to the target environment directory and continue to make code changes and re-compile.
-The user may also make modifications to the compile-time DPDK configuration by editing the .config file in the build directory.
-(This is a build-local copy of the defconfig file from the top- level config directory).
+Install the target in a separate directory::
 
-.. code-block:: console
+   make install O=mybuild DESTDIR=myinstall prefix=
 
-    cd x86_64-native-linux-gcc
-    vi .config
-    make
+The environment is ready to build a DPDK application::
+
+   RTE_SDK=$(pwd)/myinstall/share/dpdk RTE_TARGET=x86_64-native-linux-gcc make -C myapp
 
 In addition, the make clean command can be used to remove any existing compiled files for a subsequent full, clean rebuild of the code.
 
@@ -245,5 +215,5 @@ Browsing the Installed DPDK Environment Target
 ----------------------------------------------
 
 Once a target is created it contains all libraries, including poll-mode drivers, and header files for the DPDK environment that are required to build customer applications.
-In addition, the test and testpmd applications are built under the build/app directory, which may be used for testing.
+In addition, the test applications are built under the app directory, which may be used for testing.
 A kmod  directory is also present that contains kernel modules which may be loaded if needed.
-- 
2.26.2

[dpdk-stable] [PATCH v2 3/4] doc: update build instructions in the Linux guide

[Thomas Monjalon]

Before removing the "make" build system completely,
the Linux guide instructions are made more concise and accurate.
Some detailed explanations are also available in
doc/guides/prog_guide/dev_kit_root_make_help.rst

This is the swan song for makefile system,
in order to have accurate information backported in LTS.

Cc: stable@dpdk.org

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
 doc/guides/linux_gsg/build_dpdk.rst | 66 ++++++++---------------------
 1 file changed, 18 insertions(+), 48 deletions(-)

diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/build_dpdk.rst
index 4aeb4697d9..c536e354ef 100644
--- a/doc/guides/linux_gsg/build_dpdk.rst
+++ b/doc/guides/linux_gsg/build_dpdk.rst
@@ -167,60 +167,32 @@ Installation of DPDK Target Environment using Make
    is therefore recommended that DPDK installation is done using meson and
    ninja as described above.
 
-The format of a DPDK target is::
+Get a native target environment automatically::
 
-    ARCH-MACHINE-EXECENV-TOOLCHAIN
-
-where:
-
-* ``ARCH`` can be:  ``i686``, ``x86_64``, ``ppc_64``, ``arm64``
-
-* ``MACHINE`` can be:  ``native``, ``power8``, ``armv8a``
-
-* ``EXECENV`` can be:  ``linux``,  ``freebsd``
-
-* ``TOOLCHAIN`` can be:  ``gcc``,  ``icc``
-
-The targets to be installed depend on the 32-bit and/or 64-bit packages and compilers installed on the host.
-Available targets can be found in the DPDK/config directory.
-The defconfig\_ prefix should not be used.
+   make defconfig O=mybuild
 
 .. note::
 
-    Configuration files are provided with the ``RTE_MACHINE`` optimization level set.
     Within the configuration files, the ``RTE_MACHINE`` configuration value is set to native,
     which means that the compiled software is tuned for the platform on which it is built.
-    For more information on this setting, and its possible values, see the *DPDK Programmers Guide*.
 
-When using the Intel® C++ Compiler (icc), one of the following commands should be invoked for 64-bit or 32-bit use respectively.
-Notice that the shell scripts update the ``$PATH`` variable and therefore should not be performed in the same session.
-Also, verify the compiler's installation directory since the path may be different:
+Or get a specific target environment::
 
-.. code-block:: console
+   make config T=x86_64-native-linux-gcc O=mybuild
 
-    source /opt/intel/bin/iccvars.sh intel64
-    source /opt/intel/bin/iccvars.sh ia32
+The format of a DPDK target is "ARCH-MACHINE-EXECENV-TOOLCHAIN".
+Available targets can be found with::
 
-To install and make targets, use the ``make install T=<target>`` command in the top-level DPDK directory.
+   make help
 
-For example, to compile a 64-bit target using icc, run:
+Customize the target configuration in the generated ``.config`` file.
+Example for enabling the pcap PMD::
 
-.. code-block:: console
+   sed -ri 's,(PMD_PCAP=).*,\1y,' mybuild/.config
 
-    make install T=x86_64-native-linux-icc
+Compile the target::
 
-To compile a 32-bit build using gcc, the make command should be:
-
-.. code-block:: console
-
-    make install T=i686-native-linux-gcc
-
-To prepare a target without building it, for example, if the configuration changes need to be made before compilation,
-use the ``make config T=<target>`` command:
-
-.. code-block:: console
-
-    make config T=x86_64-native-linux-gcc
+   make -j4 O=mybuild
 
 .. warning::
 
@@ -229,15 +201,13 @@ use the ``make config T=<target>`` command:
     If the DPDK is not being built on the target machine,
     the ``RTE_KERNELDIR`` environment variable should be used to point the compilation at a copy of the kernel version to be used on the target machine.
 
-Once the target environment is created, the user may move to the target environment directory and continue to make code changes and re-compile.
-The user may also make modifications to the compile-time DPDK configuration by editing the .config file in the build directory.
-(This is a build-local copy of the defconfig file from the top- level config directory).
+Install the target in a separate directory::
 
-.. code-block:: console
+   make install O=mybuild DESTDIR=myinstall prefix=
 
-    cd x86_64-native-linux-gcc
-    vi .config
-    make
+The environment is ready to build a DPDK application::
+
+   RTE_SDK=$(pwd)/myinstall/share/dpdk RTE_TARGET=x86_64-native-linux-gcc make -C myapp
 
 In addition, the make clean command can be used to remove any existing compiled files for a subsequent full, clean rebuild of the code.
 
@@ -245,5 +215,5 @@ Browsing the Installed DPDK Environment Target
 ----------------------------------------------
 
 Once a target is created it contains all libraries, including poll-mode drivers, and header files for the DPDK environment that are required to build customer applications.
-In addition, the test and testpmd applications are built under the build/app directory, which may be used for testing.
+In addition, the test applications are built under the app directory, which may be used for testing.
 A kmod  directory is also present that contains kernel modules which may be loaded if needed.
-- 
2.26.2

Re: [dpdk-stable] [PATCH v2 3/4] doc: update build instructions in the Linux guide

[Bruce Richardson]

On Thu, Jun 25, 2020 at 11:43:37PM +0200, Thomas Monjalon wrote:
> Before removing the "make" build system completely,
> the Linux guide instructions are made more concise and accurate.
> Some detailed explanations are also available in
> doc/guides/prog_guide/dev_kit_root_make_help.rst
> 
> This is the swan song for makefile system,
> in order to have accurate information backported in LTS.
> 
> Cc: stable@dpdk.org
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> ---
>  doc/guides/linux_gsg/build_dpdk.rst | 66 ++++++++---------------------
>  1 file changed, 18 insertions(+), 48 deletions(-)
> 
These doc patches are hard to review without applying them an rebuilding
the docs, but I finally got round to doing so with this! 

Acked-by: Bruce Richardson <bruce.richardson@intel.com>