Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/28270/?format=api
{ "id": 28270, "url": "https://patches.dpdk.org/api/patches/28270/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/20170901100416.80264-18-bruce.richardson@intel.com/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20170901100416.80264-18-bruce.richardson@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20170901100416.80264-18-bruce.richardson@intel.com", "date": "2017-09-01T10:04:16", "name": "[dpdk-dev,17/17] doc: add documentation on how to add new components to DPDK", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "cb10a2217b2b36dc634ddf9c4cc9be0d95564ce4", "submitter": { "id": 20, "url": "https://patches.dpdk.org/api/people/20/?format=api", "name": "Bruce Richardson", "email": "bruce.richardson@intel.com" }, "delegate": null, "mbox": "https://patches.dpdk.org/project/dpdk/patch/20170901100416.80264-18-bruce.richardson@intel.com/mbox/", "series": [], "comments": "https://patches.dpdk.org/api/patches/28270/comments/", "check": "success", "checks": "https://patches.dpdk.org/api/patches/28270/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@dpdk.org", "Delivered-To": "patchwork@dpdk.org", "Received": [ "from [92.243.14.124] (localhost [IPv6:::1])\n\tby dpdk.org (Postfix) with ESMTP id 8C6197D4F;\n\tFri, 1 Sep 2017 12:18:39 +0200 (CEST)", "from mga02.intel.com (mga02.intel.com [134.134.136.20])\n\tby dpdk.org (Postfix) with ESMTP id AA3717D77\n\tfor <dev@dpdk.org>; Fri, 1 Sep 2017 12:18:37 +0200 (CEST)", "from fmsmga004.fm.intel.com ([10.253.24.48])\n\tby orsmga101.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384;\n\t01 Sep 2017 03:18:37 -0700", "from silpixa00399126.ir.intel.com (HELO\n\tsilpixa00399126.ger.corp.intel.com) ([10.237.223.223])\n\tby fmsmga004.fm.intel.com with ESMTP; 01 Sep 2017 03:18:36 -0700" ], "X-ExtLoop1": "1", "X-IronPort-AV": "E=Sophos;i=\"5.41,457,1498546800\"; d=\"scan'208\";a=\"306892656\"", "From": "Bruce Richardson <bruce.richardson@intel.com>", "To": "dev@dpdk.org", "Cc": "Bruce Richardson <bruce.richardson@intel.com>", "Date": "Fri, 1 Sep 2017 11:04:16 +0100", "Message-Id": "<20170901100416.80264-18-bruce.richardson@intel.com>", "X-Mailer": "git-send-email 2.13.5", "In-Reply-To": "<20170901100416.80264-1-bruce.richardson@intel.com>", "References": "<20170901100416.80264-1-bruce.richardson@intel.com>", "Subject": "[dpdk-dev] [PATCH 17/17] doc: add documentation on how to add new\n\tcomponents to DPDK", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.15", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<http://dpdk.org/ml/options/dev>,\n\t<mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://dpdk.org/ml/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<http://dpdk.org/ml/listinfo/dev>,\n\t<mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "Add to the contributors guide details on how to add libraries and drivers\nand integrate them with the DPDK build system(s).\n\nSigned-off-by: Bruce Richardson <bruce.richardson@intel.com>\n---\n doc/guides/contributing/coding_style.rst | 214 +++++++++++++++++++++++++++++++\n 1 file changed, 214 insertions(+)", "diff": "diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst\nindex d8e4a0f9c..3c59cbca5 100644\n--- a/doc/guides/contributing/coding_style.rst\n+++ b/doc/guides/contributing/coding_style.rst\n@@ -702,3 +702,217 @@ All Python code should work with Python 2.7+ and 3.2+ and be compliant with\n `PEP8 (Style Guide for Python Code) <https://www.python.org/dev/peps/pep-0008/>`_.\n \n The ``pep8`` tool can be used for testing compliance with the guidelines.\n+\n+Integrating with the Build System\n+---------------------------------\n+\n+DPDK supports being built in two different ways:\n+\n+* using ``make`` - or more specifically \"GNU make\", i.e. ``gmake`` on FreeBSD\n+* using the tools ``meson`` and ``ninja``\n+\n+Any new library or driver to be integrated into DPDK should support being\n+built with both systems. While building using ``make`` is a legacy approach, and\n+most build-system enhancements are being done using ``meson`` and ``ninja``\n+there are no plans at this time to deprecate the legacy ``make`` build system.\n+\n+Therefore all new component additions should include both a ``Makefile`` and a\n+``meson.build`` file, and should be added to the component lists in both the\n+``Makefile`` and ``meson.build`` files in the relevant top-level directory:\n+either ``lib`` directory or a ``driver`` subdirectory.\n+\n+Makefile Contents\n+~~~~~~~~~~~~~~~~~\n+\n+The ``Makefile`` for the component should be of the following format, where\n+``<name>`` corresponds to the name of the library in question, e.g. hash,\n+lpm, etc. For drivers, the same format of Makefile is used.\n+\n+.. code-block:: makefile\n+\n+\t# pull in basic DPDK definitions, including whether library is to be\n+\t# built or not\n+\tinclude $(RTE_SDK)/mk/rte.vars.mk\n+\n+\t# library name\n+\tLIB = librte_<name>.a\n+\n+\t# any library cflags needed. Generally add \"-O3 $(WERROR_FLAGS)\"\n+\tCFLAGS += -O3\n+\tCFLAGS += $(WERROR_FLAGS)\n+\n+\t# the symbol version information for the library, and .so version\n+\tEXPORT_MAP := rte_<name>_version.map\n+\tLIBABIVER := 1\n+\n+\t# all source filenames are stored in SRCS-y\n+\tSRCS-$(CONFIG_RTE_LIBRTE_<NAME>) += rte_<name>.c\n+\n+\t# install includes\n+\tSYMLINK-$(CONFIG_RTE_LIBRTE_<NAME>)-include += rte_<name>.h\n+\n+\t# pull in rules to build the library\n+\tinclude $(RTE_SDK)/mk/rte.lib.mk\n+\n+Meson Build File Contents - Libraries\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+The ``meson.build`` file for a new DPDK library should be of the following basic\n+format.\n+\n+.. code-block:: python\n+\n+\tsources = files('file1.c', ...)\n+\theaders = files('file1.c', ...)\n+\n+\n+The will build based on a number of conventions and assumptions within the DPDK\n+itself, for example, that the library name is the same as the directory name in\n+which the files are stored.\n+\n+For a library ``meson.build`` file, there are number of variables which can be\n+set, some mandatory, others optional. The mandatory fields are:\n+\n+sources\n+\t**Default Value = []**.\n+\tThis variable should list out the files to be compiled up to create the\n+\tlibrary. Files must be specified using the meson ``files()`` function.\n+\n+\n+The optional fields are:\n+\n+build\n+\t**Default Value = true.**\n+\tUsed to optionally compile a library, based on its dependencies or\n+\tenvironment. A simple example of use would be:\n+\n+.. code-block:: python\n+\n+\tif host_machine.system() != 'linux'\n+\t build = false\n+\tendif\n+\n+\n+cflags\n+\t**Default Value = []**.\n+\tUsed to specify any additional cflags that need to be passed to compile\n+\tthe sources in the library.\n+\n+deps\n+\t**Default Value = ['eal']**.\n+\tUsed to list the internal library dependencies of the library. It should\n+\tbe assigned to using ``+=`` rather than overwriting using ``=``. The\n+\tdependencies should be specified as strings, each one giving the name of\n+\ta DPDK library, without the ``librte_`` prefix. Dependencies are handled\n+\trecursively, so specifying e.g. ``mempool``, will automatically also\n+\tmake the library depend upon the mempool library's dependencies too -\n+\t``ring`` and ``eal``. For libraries that only depend upon EAL, this\n+\tvariable may be omitted from the ``meson.build`` file. For example:\n+\n+.. code-block:: python\n+\n+\tdeps += ['ethdev']\n+\n+\n+ext_deps\n+\t**Default Value = []**.\n+\tUsed to specify external dependencies of this library. They should be\n+\treturned as dependency objects, as returned from the meson\n+\t``dependency()`` or ``find_library()`` functions. Before returning\n+\tthese, they should be checked to ensure the dependencies have been\n+\tfound, and, if not, the ``build`` variable should be set to ``false``.\n+\tFor example:\n+\n+.. code-block:: python\n+\n+\tmy_dep = dependency('libX', required: 'false')\n+\tif my_dep.found()\n+\t\text_deps += my_dep\n+\telse\n+\t\tbuild = false\n+\tendif\n+\n+\n+headers\n+\t**Default Value = []**.\n+\tUsed to return the list of header files for the library that should be\n+\tinstalled to $PREFIX/include when ``ninja install`` is run. As with\n+\tsource files, these should be specified using the meson ``files()``\n+\tfunction.\n+\n+name\n+\t**Default Value = library name derived from the directory name**.\n+\tIf a library's .so or .a file differs from that given in the directory\n+\tname, the name should be specified using this variable. In practice,\n+\tsince the convention is that for a library called ``librte_xyz.so``, the\n+\tsources are stored in a directory ``lib/librte_xyz``, this value should\n+\tnever be needed for new libraries.\n+\n+.. note::\n+\n+\tThe name value also provides the name used to find the function version\n+\tmap file, as part of the build process, so if the directory name and\n+\tlibrary names differ, the ``version.map`` file should be named\n+\tconsistently with the library, not the directory\n+\n+objs\n+\t**Default Value = []**.\n+\tThis variable can be used to pass to the library build some pre-built\n+\tobjects that were compiled up as part of another target given in the\n+\tincluded library ``meson.build`` file.\n+\n+version\n+\t**Default Value = 1**.\n+\tSpecifies the ABI version of the library, and is used as the major\n+\tversion number of the resulting ``.so`` library.\n+\n+Meson Build File Contents - Drivers\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+For drivers, the values are largely the same as for libraries. The variables\n+supported are:\n+\n+build\n+\tAs above.\n+\n+cflags\n+\tAs above.\n+\n+deps\n+\tAs above.\n+\n+ext_deps\n+\tAs above.\n+\n+includes\n+\t**Default Value = <driver directory>** Some drivers include a base\n+\tdirectory for additional source files and headers, so we have this\n+\tvariable to allow the headers from that base directory to be found when\n+\tcompiling driver sources. Should be appended to using ``+=`` rather than\n+\toverwritten using ``=``. The values appended should be meson include\n+\tobjects got using the ``include_directories()`` function. For example:\n+\n+.. code-block:: python\n+\n+\tincludes += include_directories('base')\n+\n+name\n+\tAs above, though note that each driver class can define it's own naming\n+\tscheme for the resulting ``.so`` files.\n+\n+objs\n+\tAs above, generally used for the contents of the ``base`` directory.\n+\n+pkgconfig_extra_libs\n+\t**Default Value = []**\n+\tThis variable is used to pass additional library link flags through to\n+\tthe DPDK pkgconfig file generated, for example, to track any additional\n+\tlibraries that may need to be linked into the build - especially when\n+\tusing static libraries. Anything added here will be appended to the end\n+\tof the ``pkgconfig --libs`` output.\n+\n+sources [mandatory]\n+\tAs above\n+\n+version\n+\tAs above\n", "prefixes": [ "dpdk-dev", "17/17" ] }