From: Bruce Richardson <bruce.richardson@intel.com>
To: dev@dpdk.org
Cc: Bruce Richardson <bruce.richardson@intel.com>
Subject: [dpdk-dev] [PATCH 17/17] doc: add documentation on how to add new components to DPDK
Date: Fri, 1 Sep 2017 11:04:16 +0100 [thread overview]
Message-ID: <20170901100416.80264-18-bruce.richardson@intel.com> (raw)
In-Reply-To: <20170901100416.80264-1-bruce.richardson@intel.com>
Add to the contributors guide details on how to add libraries and drivers
and integrate them with the DPDK build system(s).
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
doc/guides/contributing/coding_style.rst | 214 +++++++++++++++++++++++++++++++
1 file changed, 214 insertions(+)
diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst
index d8e4a0f9c..3c59cbca5 100644
--- a/doc/guides/contributing/coding_style.rst
+++ b/doc/guides/contributing/coding_style.rst
@@ -702,3 +702,217 @@ All Python code should work with Python 2.7+ and 3.2+ and be compliant with
`PEP8 (Style Guide for Python Code) <https://www.python.org/dev/peps/pep-0008/>`_.
The ``pep8`` tool can be used for testing compliance with the guidelines.
+
+Integrating with the Build System
+---------------------------------
+
+DPDK supports being built in two different ways:
+
+* using ``make`` - or more specifically "GNU make", i.e. ``gmake`` on FreeBSD
+* using the tools ``meson`` and ``ninja``
+
+Any new library or driver to be integrated into DPDK should support being
+built with both systems. While building using ``make`` is a legacy approach, and
+most build-system enhancements are being done using ``meson`` and ``ninja``
+there are no plans at this time to deprecate the legacy ``make`` build system.
+
+Therefore all new component additions should include both a ``Makefile`` and a
+``meson.build`` file, and should be added to the component lists in both the
+``Makefile`` and ``meson.build`` files in the relevant top-level directory:
+either ``lib`` directory or a ``driver`` subdirectory.
+
+Makefile Contents
+~~~~~~~~~~~~~~~~~
+
+The ``Makefile`` for the component should be of the following format, where
+``<name>`` corresponds to the name of the library in question, e.g. hash,
+lpm, etc. For drivers, the same format of Makefile is used.
+
+.. code-block:: makefile
+
+ # pull in basic DPDK definitions, including whether library is to be
+ # built or not
+ include $(RTE_SDK)/mk/rte.vars.mk
+
+ # library name
+ LIB = librte_<name>.a
+
+ # any library cflags needed. Generally add "-O3 $(WERROR_FLAGS)"
+ CFLAGS += -O3
+ CFLAGS += $(WERROR_FLAGS)
+
+ # the symbol version information for the library, and .so version
+ EXPORT_MAP := rte_<name>_version.map
+ LIBABIVER := 1
+
+ # all source filenames are stored in SRCS-y
+ SRCS-$(CONFIG_RTE_LIBRTE_<NAME>) += rte_<name>.c
+
+ # install includes
+ SYMLINK-$(CONFIG_RTE_LIBRTE_<NAME>)-include += rte_<name>.h
+
+ # pull in rules to build the library
+ include $(RTE_SDK)/mk/rte.lib.mk
+
+Meson Build File Contents - Libraries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``meson.build`` file for a new DPDK library should be of the following basic
+format.
+
+.. code-block:: python
+
+ sources = files('file1.c', ...)
+ headers = files('file1.c', ...)
+
+
+The 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.
+
+For a library ``meson.build`` file, there are number of variables which can be
+set, some mandatory, others optional. The mandatory fields are:
+
+sources
+ **Default Value = []**.
+ This variable should list out the files to be compiled up to create the
+ library. Files must be specified using the meson ``files()`` function.
+
+
+The optional fields are:
+
+build
+ **Default Value = true.**
+ Used to optionally compile a library, based on its dependencies or
+ environment. A simple example of use would be:
+
+.. code-block:: python
+
+ if host_machine.system() != 'linux'
+ build = false
+ endif
+
+
+cflags
+ **Default Value = []**.
+ Used to specify any additional cflags that need to be passed to compile
+ the sources in the library.
+
+deps
+ **Default Value = ['eal']**.
+ Used to list the internal library dependencies of the library. It should
+ be assigned to using ``+=`` rather than overwriting using ``=``. The
+ dependencies should be specified as strings, each one giving the name of
+ a DPDK library, without the ``librte_`` prefix. Dependencies are handled
+ recursively, so specifying e.g. ``mempool``, will automatically also
+ make the library depend upon the mempool library's dependencies too -
+ ``ring`` and ``eal``. For libraries that only depend upon EAL, this
+ variable may be omitted from the ``meson.build`` file. For example:
+
+.. code-block:: python
+
+ deps += ['ethdev']
+
+
+ext_deps
+ **Default Value = []**.
+ Used to specify external dependencies of this library. They should be
+ returned as dependency objects, as returned from the meson
+ ``dependency()`` or ``find_library()`` functions. Before returning
+ these, they should be checked to ensure the dependencies have been
+ found, and, if not, the ``build`` variable should be set to ``false``.
+ For example:
+
+.. code-block:: python
+
+ my_dep = dependency('libX', required: 'false')
+ if my_dep.found()
+ ext_deps += my_dep
+ else
+ build = false
+ endif
+
+
+headers
+ **Default Value = []**.
+ Used to return the list of header files for the library that should be
+ installed to $PREFIX/include when ``ninja install`` is run. As with
+ source files, these should be specified using the meson ``files()``
+ function.
+
+name
+ **Default Value = library name derived from the directory name**.
+ If a library's .so or .a file differs from that given in the directory
+ name, the name should be specified using this variable. In practice,
+ since the convention is that for a library called ``librte_xyz.so``, the
+ sources are stored in a directory ``lib/librte_xyz``, this value should
+ never be needed for new libraries.
+
+.. note::
+
+ The name value also provides the name used to find the function version
+ map file, as part of the build process, so if the directory name and
+ library names differ, the ``version.map`` file should be named
+ consistently with the library, not the directory
+
+objs
+ **Default Value = []**.
+ This variable can be used to pass to the library build some pre-built
+ 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.
+
+Meson Build File Contents - Drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For drivers, the values are largely the same as for libraries. The variables
+supported are:
+
+build
+ As above.
+
+cflags
+ As above.
+
+deps
+ As above.
+
+ext_deps
+ As above.
+
+includes
+ **Default Value = <driver directory>** Some drivers include a base
+ directory for additional source files and headers, so we have this
+ variable to allow the headers from that base directory to be found when
+ compiling driver sources. Should be appended to using ``+=`` rather than
+ overwritten using ``=``. The values appended should be meson include
+ objects got using the ``include_directories()`` function. For example:
+
+.. code-block:: python
+
+ includes += include_directories('base')
+
+name
+ As above, though note that each driver class can define it's own naming
+ scheme for the resulting ``.so`` files.
+
+objs
+ As above, generally used for the contents of the ``base`` directory.
+
+pkgconfig_extra_libs
+ **Default Value = []**
+ This variable is used to pass additional library link flags through to
+ the DPDK pkgconfig file generated, for example, to track any additional
+ libraries that may need to be linked into the build - especially when
+ using static libraries. Anything added here will be appended to the end
+ of the ``pkgconfig --libs`` output.
+
+sources [mandatory]
+ As above
+
+version
+ As above
--
2.13.5
next prev parent reply other threads:[~2017-09-01 10:18 UTC|newest]
Thread overview: 107+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-09-01 10:03 [dpdk-dev] [PATCH 00/17] build DPDK libs and some drivers with meson/ninja Bruce Richardson
2017-09-01 10:04 ` [dpdk-dev] [PATCH 01/17] build: add initial infrastructure for meson & ninja builds Bruce Richardson
2017-09-04 13:36 ` Van Haaren, Harry
2017-09-04 13:51 ` Bruce Richardson
2017-09-06 16:18 ` Bruce Richardson
2017-09-07 13:52 ` Bruce Richardson
2017-09-07 16:21 ` [dpdk-dev] [dpdk-dev, " Neil Horman
2017-09-07 16:47 ` Wiles, Keith
2017-09-07 17:12 ` Neil Horman
2017-09-08 8:50 ` Bruce Richardson
2017-09-08 11:57 ` Neil Horman
2017-09-08 13:55 ` Bruce Richardson
2017-09-08 14:00 ` Bruce Richardson
2017-09-08 16:03 ` [dpdk-dev] [PATCH " Van Haaren, Harry
2017-09-08 16:13 ` Richardson, Bruce
2017-09-12 9:56 ` Bruce Richardson
2017-09-01 10:04 ` [dpdk-dev] [PATCH 02/17] eal: add eal library to meson build Bruce Richardson
2017-09-04 13:53 ` Van Haaren, Harry
2017-09-07 16:25 ` [dpdk-dev] [dpdk-dev, " Neil Horman
2017-09-08 8:51 ` Bruce Richardson
2017-09-01 10:04 ` [dpdk-dev] [PATCH 03/17] igb_uio: add igb_uio kmod " Bruce Richardson
2017-09-01 13:32 ` Luca Boccassi
2017-09-01 13:55 ` Bruce Richardson
2017-09-01 14:27 ` Luca Boccassi
2017-09-04 13:57 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 04/17] build: add DPDK libraries to build Bruce Richardson
2017-09-04 14:08 ` Van Haaren, Harry
2017-09-04 14:55 ` Bruce Richardson
2017-09-01 10:04 ` [dpdk-dev] [PATCH 05/17] build: add buildtools to meson build Bruce Richardson
2017-09-04 14:24 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 06/17] build: add infrastructure for building PMDs Bruce Richardson
2017-09-04 14:27 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 07/17] drivers/mempool: add SW mempool drivers to meson build Bruce Richardson
2017-09-04 14:28 ` Van Haaren, Harry
2017-09-04 14:29 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 08/17] drivers/crypto: add crypto drv class and null PMD to meson Bruce Richardson
2017-09-04 14:30 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 09/17] crypto/openssl: add driver to meson build Bruce Richardson
2017-09-04 14:30 ` Van Haaren, Harry
2017-09-04 14:31 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 10/17] crypto/qat: " Bruce Richardson
2017-09-04 14:32 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 11/17] drivers/net: add net driver support " Bruce Richardson
2017-09-04 14:32 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 12/17] drivers/net: add set of vdev PMDs to build Bruce Richardson
2017-09-04 14:34 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 13/17] drivers/net: add drivers for Intel NICs to meson build Bruce Richardson
2017-09-01 10:04 ` [dpdk-dev] [PATCH 14/17] app/test-pmd: add test-pmd " Bruce Richardson
2017-09-04 15:01 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 15/17] usertools: add usertools installation " Bruce Richardson
2017-09-04 15:00 ` Van Haaren, Harry
2017-09-01 10:04 ` [dpdk-dev] [PATCH 16/17] build: add option to version libs using DPDK version Bruce Richardson
2017-09-07 17:07 ` [dpdk-dev] [dpdk-dev, " Neil Horman
2017-09-08 8:58 ` Bruce Richardson
2017-09-01 10:04 ` Bruce Richardson [this message]
2017-09-01 10:38 ` [dpdk-dev] [PATCH 00/17] build DPDK libs and some drivers with meson/ninja Bruce Richardson
2017-09-12 10:37 ` [dpdk-dev] [PATCH v2 " Bruce Richardson
2017-09-12 10:37 ` [dpdk-dev] [PATCH v2 01/17] build: add initial infrastructure for meson & ninja builds Bruce Richardson
2017-09-12 10:37 ` [dpdk-dev] [PATCH v2 02/17] eal: add eal library to meson build Bruce Richardson
2017-09-12 10:37 ` [dpdk-dev] [PATCH v2 03/17] igb_uio: add igb_uio kmod " Bruce Richardson
2017-09-12 10:37 ` [dpdk-dev] [PATCH v2 04/17] build: add DPDK libraries to build Bruce Richardson
2017-09-12 10:37 ` [dpdk-dev] [PATCH v2 05/17] build: add buildtools to meson build Bruce Richardson
2017-09-12 10:37 ` [dpdk-dev] [PATCH v2 06/17] build: add infrastructure for building PMDs Bruce Richardson
2017-09-12 10:37 ` [dpdk-dev] [PATCH v2 07/17] drivers/mempool: add SW mempool drivers to meson build Bruce Richardson
2017-09-12 10:38 ` [dpdk-dev] [PATCH v2 08/17] drivers/crypto: add crypto drv class and null PMD to meson Bruce Richardson
2017-09-12 10:38 ` [dpdk-dev] [PATCH v2 09/17] crypto/openssl: add driver to meson build Bruce Richardson
2017-09-12 10:38 ` [dpdk-dev] [PATCH v2 10/17] crypto/qat: " Bruce Richardson
2017-09-12 10:38 ` [dpdk-dev] [PATCH v2 11/17] drivers/net: add net driver support " Bruce Richardson
2017-09-12 10:38 ` [dpdk-dev] [PATCH v2 12/17] drivers/net: add set of vdev PMDs to build Bruce Richardson
2017-09-12 10:38 ` [dpdk-dev] [PATCH v2 13/17] drivers/net: add drivers for Intel NICs to meson build Bruce Richardson
2017-09-12 10:38 ` [dpdk-dev] [PATCH v2 14/17] app/test-pmd: add test-pmd " Bruce Richardson
2017-09-12 10:38 ` [dpdk-dev] [PATCH v2 15/17] usertools: add usertools installation " Bruce Richardson
2017-09-12 10:38 ` [dpdk-dev] [PATCH v2 16/17] build: add option to version libs using DPDK version Bruce Richardson
2017-09-13 11:32 ` Luca Boccassi
2017-09-13 13:11 ` Bruce Richardson
2017-09-13 17:02 ` Luca Boccassi
2017-09-12 10:38 ` [dpdk-dev] [PATCH v2 17/17] doc: add documentation on how to add new components to DPDK Bruce Richardson
2017-09-12 13:21 ` [dpdk-dev] [PATCH v2 00/17] build DPDK libs and some drivers with meson/ninja Wiles, Keith
2017-09-12 13:24 ` Bruce Richardson
2017-09-12 13:26 ` Wiles, Keith
2017-09-12 14:00 ` Wiles, Keith
2017-09-12 15:46 ` Bruce Richardson
2017-09-12 19:19 ` Neil Horman
2017-09-12 20:36 ` Wiles, Keith
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 " Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 01/17] build: add initial infrastructure for meson & ninja builds Bruce Richardson
2017-09-20 10:10 ` Timothy M. Redaelli
2017-09-20 10:24 ` Bruce Richardson
2017-09-20 10:33 ` Timothy M. Redaelli
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 02/17] eal: add eal library to meson build Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 03/17] igb_uio: add igb_uio kmod " Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 04/17] build: add DPDK libraries to build Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 05/17] build: add buildtools to meson build Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 06/17] build: add infrastructure for building PMDs Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 07/17] drivers/mempool: add SW mempool drivers to meson build Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 08/17] drivers/crypto: add crypto drv class and null PMD to meson Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 09/17] crypto/openssl: add driver to meson build Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 10/17] crypto/qat: " Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 11/17] drivers/net: add net driver support " Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 12/17] drivers/net: add set of vdev PMDs to build Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 13/17] drivers/net: add drivers for Intel NICs to meson build Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 14/17] app/test-pmd: add test-pmd " Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 15/17] usertools: add usertools installation " Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 16/17] build: add option to version libs using DPDK version Bruce Richardson
2017-09-13 14:12 ` [dpdk-dev] [PATCH v3 17/17] doc: add documentation on how to add new components to DPDK Bruce Richardson
2017-09-13 17:01 ` [dpdk-dev] [PATCH v3 00/17] build DPDK libs and some drivers with meson/ninja Luca Boccassi
2017-09-14 13:57 ` Bruce Richardson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20170901100416.80264-18-bruce.richardson@intel.com \
--to=bruce.richardson@intel.com \
--cc=dev@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).