X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fcoding_style.rst;h=b27b5fcfdbe87c8bef354c83a8b8542c83909ccc;hb=81ce0906ea2a8c496dcad30c87aecdd8db95e0ea;hp=687c5022b360256c90ca5cca20b1bc4052c84967;hpb=cb056611a8ed9ab9024f3b91bf26e97255194514;p=dpdk.git diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst index 687c5022b3..b27b5fcfdb 100644 --- a/doc/guides/contributing/coding_style.rst +++ b/doc/guides/contributing/coding_style.rst @@ -55,7 +55,7 @@ License Header ~~~~~~~~~~~~~~ Each file must begin with a special comment containing the -`Software Package Data Exchange (SPDX) License Identfier `_. +`Software Package Data Exchange (SPDX) License Identifier `_. Generally this is the BSD License, except for code granted special exceptions. The SPDX licences identifier is sufficient, a file should not contain @@ -759,7 +759,7 @@ Examples: * The virtio network PMD in ``drivers/net/virtio`` uses ``pmd.net.virtio`` * The eventdev software poll mode driver in ``drivers/event/sw`` uses ``pmd.event.sw`` * The octeontx mempool driver in ``drivers/mempool/octeontx`` uses ``pmd.mempool.octeontx`` - * The DPDK hash library in ``lib/librte_hash`` uses ``lib.hash`` + * The DPDK hash library in ``lib/hash`` uses ``lib.hash`` Specializations ~~~~~~~~~~~~~~~ @@ -798,6 +798,14 @@ Integrating with the Build System DPDK is built using the tools ``meson`` and ``ninja``. +.. note:: + + In order to catch possible issues as soon as possible, + it is recommended that developers build DPDK in "developer mode" to enable additional checks. + By default, this mode is enabled if the build is being done from a git checkout, + but the mode can be manually enabled/disabled using the + ``developer_mode`` meson configuration option. + Therefore all new component additions should include a ``meson.build`` file, and should be added to the component lists in the ``meson.build`` files in the relevant top-level directory: @@ -891,6 +899,18 @@ headers installed to $PREFIX/include when ``ninja install`` is run. As with source files, these should be specified using the meson ``files()`` function. + When ``check_includes`` build option is set to ``true``, each header file + has additional checks performed on it, for example to ensure that it is + not missing any include statements for dependent headers. + For header files which are public, but only included indirectly in + applications, these checks can be skipped by using the ``indirect_headers`` + variable rather than ``headers``. + +indirect_headers + **Default Value = []**. + As with ``headers`` option above, except that the files are not checked + for all needed include files as part of a DPDK build when + ``check_includes`` is set to ``true``. includes: **Default Value = []**. @@ -906,7 +926,7 @@ 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 + sources are stored in a directory ``lib/xyz``, this value should never be needed for new libraries. .. note:: @@ -987,5 +1007,64 @@ reason sources [mandatory] As above +headers + As above + version As above + + +Meson Coding Style +------------------ + +The following guidelines apply to the build system code in meson.build files in DPDK. + +* Indentation should be using 4 spaces, no hard tabs. + +* Line continuations should be doubly-indented to ensure visible difference from normal indentation. + Any line continuations beyond the first may be singly indented to avoid large amounts of indentation. + +* Where a line is split in the middle of a statement, e.g. a multiline `if` statement, + brackets should be used in preference to escaping the line break. + +Example:: + + if (condition1 and condition2 # line breaks inside () need no escaping + and condition3 and condition4) + x = y + endif + +* Lists of files or components must be alphabetical unless doing so would cause errors. + +* Two formats are supported for lists of files or list of components: + + * For a small number of list entries, generally 3 or fewer, all elements may be put on a single line. + In this case, the opening and closing braces of the list must be on the same line as the list items. + No trailing comma is put on the final list entry. + * For lists with more than 3 items, + it is recommended that the lists be put in the files with a *single* entry per line. + In this case, the opening brace, or ``files`` function call must be on a line on its own, + and the closing brace must similarly be on a line on its own at the end. + To help with readability of nested sublists, the closing brace should be dedented to appear + at the same level as the opening braced statement. + The final list entry must have a trailing comma, + so that adding a new entry to the list never modifies any other line in the list. + +Examples:: + + sources = files('file1.c', 'file2.c') + + subdirs = ['dir1', 'dir2'] + + headers = files( + 'header1.c', + 'header2.c', + 'header3.c', # always include trailing comma + ) # closing brace at indent level of opening brace + + components = [ + 'comp1', + 'comp2', + ... + 'compN', + ]