docs: Unify Getting Started Guides v2 Updates
v2 cover docs: Unify Getting Started Guides v2 Updates
This is version 2 of the patch series for updating the DPDK Documentation.
Thank you to everyone who provided feedback on the first version.
Changes since v1:
- Removed unnecessary verbiage from Section 1: Introduction
- Merged windows_install_build.rst into building_from_sources.rst
- Updated Section 2: Install and Build DPDK based on additional feedback
- Added link in guides/index.rst to Getting Started Guide so now it shows up in menu
The following patches are included in this series:
1/3: GSG Section 1: Introduction - Updated 2/3: Added link to Getting Started Guide in index.rst 3/3: GSG Section 2: Install and Build DPDK - Updated
.../building_from_sources.rst | 124 ++++++++++++++---- .../install_and_build/index.rst | 3 +- .../windows_install_build.rst | 93 ------------- doc/guides/getting_started_guide/intro.rst | 7 +- doc/guides/index.rst | 1 + 5 files changed, 99 insertions(+), 129 deletions(-) delete mode 100644 doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
Signature · 1 line
2.41.0.windows.1
PATCH v2 1/3 GSG Section 1: Introduction - Updated based on feedback
--- doc/guides/getting_started_guide/intro.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-)
doc/guides/getting_started_guide/intro.rst +2 -5
@@ -4,13 +4,10 @@ Introduction ============ -Welcome to the unified getting started guide for the Data Plane Development Kit (DPDK) covering Linux, FreeBSD, and Windows. DPDK is a set of libraries and +Welcome to the getting started guide for the Data Plane Development Kit (DPDK) covering Linux, FreeBSD, and Windows. DPDK is a set of libraries and drivers that accelerate packet processing and allow the user to create high-performance networking applications. The guide is structured to provide basic step-by-step instructions with OS-specific instructions for each operating system where necessary. By the end of this guide, you should have a solid understanding of how to implement and -use DPDK in your networking projects, regardless of the operating system you are using. - -We hope this guide serves as a valuable resource as you explore the powerful -capabilities of DPDK. +use DPDK in your networking projects, regardless of the operating system you are using.
Signature · 1 line
2.41.0.windows.1
PATCH v2 2/3 Added link to Getting Started Guide in index.rst
In reply to David Young--- doc/guides/index.rst | 1 + 1 file changed, 1 insertion(+)
doc/guides/index.rst +1 -0
@@ -7,6 +7,7 @@ DPDK documentation .. toctree:: :maxdepth: 1 + getting_started_guide/index linux_gsg/index freebsd_gsg/index windows_gsg/index
Signature · 1 line
2.41.0.windows.1
PATCH v2 3/3 GSG Section 2: Install and Build DPDK - Updated based on feedback
In reply to David YoungMerged windows_install_build.rst into building_from_sources.rst
--- .../building_from_sources.rst | 124 ++++++++++++++---- .../install_and_build/index.rst | 3 +- .../windows_install_build.rst | 93 ------------- 3 files changed, 96 insertions(+), 124 deletions(-) delete mode 100644 doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
doc/guides/getting_started_guide/install_and_build/building_from_sources.rst +95 -29
@@ -6,8 +6,7 @@ Building and Installing DPDK from Sources ========================================= -This chapter provides a comprehensive guide for building DPDK from sources on both -Linux and FreeBSD platforms. It covers the necessary steps, prerequisites, +This chapter provides a comprehensive guide for building DPDK from sources on Linux, FreeBSD, and Windows. It covers the necessary steps, prerequisites, and considerations for different architectures and compilers. Required Tools
@@ -18,91 +17,158 @@ To build DPDK, you'll need the following tools: - A C compiler like ``gcc`` (version 5+) or ``clang`` (version 3.6+) - ``pkg-config`` or ``pkgconf`` - Python 3.6 or later -- ``meson`` (version 0.53.2+) and ``ninja`` +- ``meson`` (version 0.57.0) and ``ninja`` - ``pyelftools`` (version 0.22+) -Here's how to install them: +Platform-Specific Tool Installation +----------------------------------- Linux ^^^^^ +Common Tools for All Distributions: + +.. code-block:: bash + + sudo apt install gcc pkg-config python3 meson ninja pyelftools + Alpine .. code-block:: bash sudo apk add alpine-sdk bsd-compat-headers - pip install meson ninja -Debian and Ubuntu and derivatives +Debian, Ubuntu, and derivatives .. code-block:: bash sudo apt install build-essential - pip install meson ninja Fedora and RedHat Enterprise Linux RHEL .. code-block:: bash sudo dnf groupinstall "Development Tools" - pip install meson ninja openSUSE .. code-block:: bash sudo zypper install -t pattern devel_basis python3-pyelftools - pip install meson ninja FreeBSD ^^^^^^^ -FreeBSD (as root) +Common Tools for FreeBSD: .. code-block:: bash - pkg install meson pkgconf py38-pyelftools + pkg install gcc pkgconf python3 meson ninja pyelftools -Note: If you're using FreeBSD, you'll also need kernel sources. Make sure they're included during the FreeBSD installation. +.. note:: -Getting the DPDK Source ------------------------ + If you're using FreeBSD, make sure kernel sources are included during the FreeBSD installation. -Download the DPDK source code from the official repository -``https://fast.dpdk.org/rel/``. +Windows System Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Use ``wget`` to grab the DPDK version:: +Building the DPDK and its applications on Windows requires one of the following +environments: - wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz +- The Clang-LLVM C compiler and Microsoft MSVC linker. +- The MinGW-w64 toolchain (either native or cross). -Extract the downloaded archive: +The Meson Build system is used to prepare the sources for compilation with the Ninja backend. -.. code-block:: bash +Option 1: Clang-LLVM C Compiler and Microsoft MSVC Linker +""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +1. Install the Compiler: Download and install the Clang compiler from the + `LLVM website <http://releases.llvm.org/>`_. + +2. Install the Linker: Download and install the Build Tools for Visual Studio from the + `Microsoft website <https://visualstudio.microsoft.com/downloads/>`_. + When installing build tools, select the “Visual C++ build tools” option and make sure + the Windows SDK is selected. - tar -xvf dpdk-<version>.tar.gz +Option 2: MinGW-w64 Toolchain +"""""""""""""""""""""""""""""" -Navigate to the DPDK directory: +1. On Linux (for cross-compilation): Install MinGW-w64 via a package manager. + Version 4.0.4 for Ubuntu 16.04 cannot be used due to a MinGW-w64 bug. + +2. On Windows: Obtain the latest version installer from the + `MinGW-w64 repository <https://mingw-w64.org/doku.php>`_. + Any thread model (POSIX or Win32) can be chosen, DPDK does not rely on it. + Install to a folder without spaces in its name, like ``C:\MinGW``. + This path is assumed for the rest of this guide. + +Install the Build System +^^^^^^^^^^^^^^^^^^^^^^^^ + +Download and install the build system from the +`Meson website <http://mesonbuild.com/Getting-meson.html#installing-meson-and-ninja-with-the-msi-installer>`_. +A good option to choose is the MSI installer for both meson and ninja together. +Recommended version is either Meson 0.57.0 (baseline) or the latest release. + +Getting the DPDK Source +----------------------- + +Linux and FreeBSD +^^^^^^^^^^^^^^^^^ .. code-block:: bash + wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz + tar -xvf dpdk-<version>.tar.xz cd dpdk-<version> +Windows +^^^^^^^ + +Download the DPDK source code from `DPDK's official website <https://www.dpdk.org/>`_ or clone the repository using a Git client. Extract the downloaded archive, if applicable, and navigate to the DPDK directory. + +Navigate to the directory where the DPDK source code is located: + +.. code-block:: bash + + cd C:\path\to\dpdk-<version> + Building DPDK ------------- -Configure the build based on your needs, hardware, and environment. -This might include setting specific flags or options. For example: “meson setup -Dbuildtype=debugoptimized build”. Then compile using “ninja” and install using “meson install”. +Linux and FreeBSD +^^^^^^^^^^^^^^^^^ .. code-block:: bash + meson build ninja -C build - cd build - sudo ninja install - ldconfig -For detailed information on Meson build configuration options specific to DPDK, see :ref:`DPDK Meson Build Configuration Options <dpdk_meson_build_options>`. +Windows +^^^^^^^ + +**Option 1: Using Clang-LLVM** + +.. code-block:: bash + + set CC=clang + meson setup -Dexamples=helloworld build + meson compile -C build + +**Option 2: Using MinGW-w64** + +.. code-block:: bash + + set PATH=C:\MinGW\mingw64\bin;%PATH% + meson setup -Dexamples=helloworld build + meson compile -C build + +.. note:: + + For detailed information on Meson build configuration options specific to DPDK, see :ref:`DPDK Meson Build Configuration Options <dpdk_meson_build_options>`. Cross-Compilation Instructions for Different Architectures ---------------------------------------------------------- -For instructions on building DPDK for ARM64, LoongArch, and RISC-V, refer to :ref:`cross_compile_dpdk`. +For instructions on building DPDK for ARM64, LoongArch, and RISC-V, refer to :ref:`cross_compile_dpdk`.
doc/guides/getting_started_guide/install_and_build/index.rst +1 -2
@@ -11,5 +11,4 @@ Install and Build DPDK installing_prebuilt_packages - building_from_sources - windows_install_build + building_from_sources
doc/guides/getting_started_guide/install_and_build/windows_install_build.rst deleted +0 -93
94 lines not on this page · raw message
Signature · 1 line
2.41.0.windows.1
Re: [PATCH 3/3] GSG Section 2: Install and Build DPDK - Updated based on feedback
Quoted 1 line · David Young
Merged
windows_install_build.rstintobuilding_from_sources.rst
[...]
Quoted 39 lines
doc/guides/getting_started_guide/install_and_build/building_from_sources.rst +25
-8-Download the DPDK source code from the official repository -``https://fast.dpdk.org/rel/``. +Windows System Requirements +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Use ``wget`` to grab the DPDK version:: +Building the DPDK and its applications on Windows requires one of the following +environments: - wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz +- The Clang-LLVM C compiler and Microsoft MSVC linker. +- The MinGW-w64 toolchain (either native or cross). -Extract the downloaded archive: +The Meson Build system is used to prepare the sources for compilation with the Ninja backend. -.. code-block:: bash +Option 1: Clang-LLVM C Compiler and Microsoft MSVC Linker +""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +1. Install the Compiler: Download and install the Clang compiler from the + `LLVM website <http://releases.llvm.org/>`_. + +2. Install the Linker: Download and install the Build Tools for Visual Studio from the + `Microsoft website <https://visualstudio.microsoft.com/downloads/>`_. + When installing build tools, select the “Visual C++ build tools” option and make sure + the Windows SDK is selected. - tar -xvf dpdk-<version>.tar.gz +Option 2: MinGW-w64 Toolchain +"""""""""""""""""""""""""""""" -Navigate to the DPDK directory: +1. On Linux (for cross-compilation): Install MinGW-w64 via a package manager. + Version 4.0.4 for Ubuntu 16.04 cannot be used due to a MinGW-w64 bug. + +2. On Windows: Obtain the latest version installer from the + `MinGW-w64 repository <https://mingw-w64.org/doku.php>`_. + Any thread model (POSIX or Win32) can be chosen, DPDK does not rely on it.
doc/guides/getting_started_guide/install_and_build/building_from_sources.rst To build DPDK, you'll need the following tools: · line 112
Quoted 10 lines
doc/guides/getting_started_guide/install_and_build/building_from_sources.rst +10
-0+ Install to a folder without spaces in its name, like ``C:\MinGW``. + This path is assumed for the rest of this guide. + +Install the Build System +^^^^^^^^^^^^^^^^^^^^^^^^ + +Download and install the build system from the +`Meson website <http://mesonbuild.com/Getting-meson.html#installing-meson-and-ninja-with-the-msi-installer>`_. +A good option to choose is the MSI installer for both meson and ninja together. +Recommended version is either Meson 0.57.0 (baseline) or the latest release.
^^^^^^^^^^^ maybe use the word 'Required'
We need to be explicit for Windows. *Only* Meson 0.57.x can be used the latest release of meson is not currently supported.
Quoted 53 lines
doc/guides/getting_started_guide/install_and_build/building_from_sources.rst +34
-6+ +Getting the DPDK Source +----------------------- + +Linux and FreeBSD +^^^^^^^^^^^^^^^^^ .. code-block:: bash + wget https://fast.dpdk.org/rel/dpdk-<version>.tar.xz + tar -xvf dpdk-<version>.tar.xz cd dpdk-<version> +Windows +^^^^^^^ + +Download the DPDK source code from `DPDK's official website <https://www.dpdk.org/>`_ or clone the repository using a Git client. Extract the downloaded archive, if applicable, and navigate to the DPDK directory. + +Navigate to the directory where the DPDK source code is located: + +.. code-block:: bash + + cd C:\path\to\dpdk-<version> + Building DPDK ------------- -Configure the build based on your needs, hardware, and environment. -This might include setting specific flags or options. For example: “meson setup -Dbuildtype=debugoptimized build”. Then compile using “ninja” and install using “meson install”. +Linux and FreeBSD +^^^^^^^^^^^^^^^^^ .. code-block:: bash + meson build ninja -C build - cd build - sudo ninja install - ldconfig -For detailed information on Meson build configuration options specific to DPDK, see :ref:`DPDK Meson Build Configuration Options <dpdk_meson_build_options>`. +Windows +^^^^^^^ + +**Option 1: Using Clang-LLVM** + +.. code-block:: bash + + set CC=clang + meson setup -Dexamples=helloworld build + meson compile -C build + +**Option 2: Using MinGW-w64**
doc/guides/getting_started_guide/install_and_build/building_from_sources.rst To build DPDK, you'll need the following tools: · line 169
Quoted 10 lines
doc/guides/getting_started_guide/install_and_build/building_from_sources.rst +10
-0+ +.. code-block:: bash + + set PATH=C:\MinGW\mingw64\bin;%PATH% + meson setup -Dexamples=helloworld build + meson compile -C build + +.. note:: + + For detailed information on Meson build configuration options specific to DPDK, see :ref:`DPDK Meson Build Configuration Options <dpdk_meson_build_options>`.
This looks good, thanks for the updates.
With the one minor correction suggested above.
Acked-by Tyler Retzlaff <[email protected]>