1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright 2018 The DPDK contributors
12 This document specifies the preferred style for source files in the DPDK source tree.
13 It is based on the Linux Kernel coding guidelines and the FreeBSD 7.2 Kernel Developer's Manual (see man style(9)), but was heavily modified for the needs of the DPDK.
18 The rules and guidelines given in this document cannot cover every situation, so the following general guidelines should be used as a fallback:
20 * The code style should be consistent within each individual file.
21 * In the case of creating new files, the style should be consistent within each file in a given directory or module.
22 * The primary reason for coding standards is to increase code readability and comprehensibility, therefore always use whatever option will make the code easiest to read.
24 Line length is recommended to be not more than 80 characters, including comments.
25 [Tab stop size should be assumed to be 8-characters wide].
29 The above is recommendation, and not a hard limit.
30 However, it is expected that the recommendations should be followed in all but the rarest situations.
38 These comments should be used in normal cases.
39 To document a public API, a doxygen-like format must be used: refer to :ref:`doxygen_guidelines`.
44 * VERY important single-line comments look like this.
47 /* Most single-line comments look like this. */
50 * Multi-line comments look like this. Make them real sentences. Fill
51 * them so they look like real paragraphs.
57 Each file should begin with a special comment containing the appropriate copyright and license for the file.
58 Generally this is the BSD License, except for code for Linux Kernel modules.
59 After any copyright header, a blank line should be left before any other contents, e.g. include statements in a C file.
61 C Preprocessor Directives
62 -------------------------
67 In DPDK sources, the include files should be ordered as following:
69 #. libc includes (system includes first)
71 #. DPDK misc libraries includes
72 #. application-specific includes
74 Include files from the local application directory are included using quotes, while includes from other paths are included using angle brackets: "<>".
86 #include <rte_mempool.h>
88 #include "application.h"
93 Headers should be protected against multiple inclusion with the usual:
102 #endif /* _FILE_H_ */
108 Do not ``#define`` or declare names except with the standard DPDK prefix: ``RTE_``.
109 This is to ensure there are no collisions with definitions in the application itself.
111 The names of "unsafe" macros (ones that have side effects), and the names of macros for manifest constants, are all in uppercase.
113 The expansions of expression-like macros are either a single token or have outer parentheses.
114 If a macro is an inline expansion of a function, the function name is all in lowercase and the macro has the same name all in uppercase.
115 If the macro encapsulates a compound statement, enclose it in a do-while loop, so that it can be used safely in if statements.
116 Any final statement-terminating semicolon should be supplied by the macro invocation rather than the macro, to make parsing easier for pretty-printers and editors.
122 #define MACRO(x, y) do { \
123 variable = (x) + (y); \
129 Wherever possible, enums and inline functions should be preferred to macros, since they provide additional degrees of type-safety and can allow compilers to emit extra warnings about unsafe code.
131 Conditional Compilation
132 ~~~~~~~~~~~~~~~~~~~~~~~
134 * When code is conditionally compiled using ``#ifdef`` or ``#if``, a comment may be added following the matching
135 ``#endif`` or ``#else`` to permit the reader to easily discern where conditionally compiled code regions end.
136 * This comment should be used only for (subjectively) long regions, regions greater than 20 lines, or where a series of nested ``#ifdef``'s may be confusing to the reader.
137 Exceptions may be made for cases where code is conditionally not compiled for the purposes of lint(1), or other tools, even though the uncompiled region may be small.
138 * The comment should be separated from the ``#endif`` or ``#else`` by a single space.
139 * For short conditionally compiled regions, a closing comment should not be used.
140 * The comment for ``#endif`` should match the expression used in the corresponding ``#if`` or ``#ifdef``.
141 * The comment for ``#else`` and ``#elif`` should match the inverse of the expression(s) used in the preceding ``#if`` and/or ``#elif`` statements.
142 * In the comments, the subexpression ``defined(FOO)`` is abbreviated as "FOO".
143 For the purposes of comments, ``#ifndef FOO`` is treated as ``#if !defined(FOO)``.
148 #include <sys/ktrace.h>
152 /* A large region here, or other conditional code. */
153 #else /* !COMPAT_43 */
155 #endif /* COMPAT_43 */
158 /* Yet another large region here, or other conditional code. */
159 #else /* COMPAT_43 */
161 #endif /* !COMPAT_43 */
165 Conditional compilation should be used only when absolutely necessary, as it increases the number of target binaries that need to be built and tested.
173 For fixed/minimum-size integer values, the project uses the form uintXX_t (from stdint.h) instead of older BSD-style integer identifiers of the form u_intXX_t.
178 * Enumeration values are all uppercase.
182 enum enumtype { ONE, TWO } et;
184 * Enum types should be used in preference to macros #defining a set of (sequential) values.
185 * Enum types should be prefixed with ``rte_`` and the elements by a suitable prefix [generally starting ``RTE_<enum>_`` - where <enum> is a shortname for the enum type] to avoid namespace collisions.
190 The developer should group bitfields that are included in the same integer, as follows:
207 Variable Declarations
208 ~~~~~~~~~~~~~~~~~~~~~
210 In declarations, do not put any whitespace between asterisks and adjacent tokens, except for tokens that are identifiers related to types.
211 (These identifiers are the names of basic types, type qualifiers, and typedef-names other than the one being declared.)
212 Separate these identifiers from asterisks using a single space.
218 int *x; /* no space after asterisk */
219 int * const x; /* space after asterisk when using a type qualifier */
221 * All externally-visible variables should have an ``rte_`` prefix in the name to avoid namespace collisions.
222 * Do not use uppercase letters - either in the form of ALL_UPPERCASE, or CamelCase - in variable names.
223 Lower-case letters and underscores only.
225 Structure Declarations
226 ~~~~~~~~~~~~~~~~~~~~~~
228 * In general, when declaring variables in new structures, declare them sorted by use, then by size (largest to smallest), and then in alphabetical order.
229 Sorting by use means that commonly used variables are used together and that the structure layout makes logical sense.
230 Ordering by size then ensures that as little padding is added to the structure as possible.
231 * For existing structures, additions to structures should be added to the end so for backward compatibility reasons.
232 * Each structure element gets its own line.
233 * Try to make the structure readable by aligning the member names using spaces as shown below.
234 * Names following extremely long types, which therefore cannot be easily aligned with the rest, should be separated by a single space.
239 struct foo *next; /* List of active foo. */
240 struct mumble amumble; /* Comment for mumble. */
241 int bar; /* Try to align the comments. */
242 struct verylongtypename *baz; /* Won't fit with other members */
246 * Major structures should be declared at the top of the file in which they are used, or in separate header files if they are used in multiple source files.
247 * Use of the structures should be by separate variable declarations and those declarations must be extern if they are declared in a header file.
248 * Externally visible structure definitions should have the structure name prefixed by ``rte_`` to avoid namespace collisions.
253 Use queue(3) macros rather than rolling your own lists, whenever possible.
254 Thus, the previous example would be better written:
258 #include <sys/queue.h>
261 LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */
262 struct mumble amumble; /* Comment for mumble. */
263 int bar; /* Try to align the comments. */
264 struct verylongtypename *baz; /* Won't fit with other members */
266 LIST_HEAD(, foo) foohead; /* Head of global foo list. */
269 DPDK also provides an optimized way to store elements in lockless rings.
270 This should be used in all data-path code, when there are several consumer and/or producers to avoid locking for concurrent access.
275 Avoid using typedefs for structure types.
281 struct my_struct_type {
285 struct my_struct_type my_var;
292 typedef struct my_struct_type {
296 my_struct_type my_var
299 Typedefs are problematic because they do not properly hide their underlying type;
300 for example, you need to know if the typedef is the structure itself, as shown above, or a pointer to the structure.
301 In addition, they must be declared exactly once, whereas an incomplete structure type can be mentioned as many times as necessary.
302 Typedefs are difficult to use in stand-alone header files.
303 The header that defines the typedef must be included before the header that uses it, or by the header that uses it (which causes namespace pollution),
304 or there must be a back-door mechanism for obtaining the typedef.
306 Note that #defines used instead of typedefs also are problematic (since they do not propagate the pointer type correctly due to direct text replacement).
307 For example, ``#define pint int *`` does not work as expected, while ``typedef int *pint`` does work.
308 As stated when discussing macros, typedefs should be preferred to macros in cases like this.
310 When convention requires a typedef; make its name match the struct tag.
311 Avoid typedefs ending in ``_t``, except as specified in Standard C or by POSIX.
315 It is recommended to use typedefs to define function pointer types, for reasons of code readability.
316 This is especially true when the function type is used as a parameter to another function.
323 * Definition of a remote launch function.
325 typedef int (lcore_function_t)(void *);
327 /* launch a function of lcore_function_t type */
328 int rte_eal_remote_launch(lcore_function_t *f, void *arg, unsigned slave_id);
337 * Indentation is a hard tab, that is, a tab character, not a sequence of spaces,
341 Global whitespace rule in DPDK, use tabs for indentation, spaces for alignment.
343 * Do not put any spaces before a tab for indentation.
344 * If you have to wrap a long statement, put the operator at the end of the line, and indent again.
345 * For control statements (if, while, etc.), continuation it is recommended that the next line be indented by two tabs, rather than one,
346 to prevent confusion as to whether the second line of the control statement forms part of the statement body or not.
347 Alternatively, the line continuation may use additional spaces to line up to an appropriately point on the preceding line, for example, to align to an opening brace.
351 As with all style guidelines, code should match style already in use in an existing file.
355 while (really_long_variable_name_1 == really_long_variable_name_2 &&
356 var3 == var4){ /* confusing to read as */
357 x = y + z; /* control stmt body lines up with second line of */
358 a = b + c; /* control statement itself if single indent used */
361 if (really_long_variable_name_1 == really_long_variable_name_2 &&
362 var3 == var4){ /* two tabs used */
363 x = y + z; /* statement body no longer lines up */
367 z = a + really + long + statement + that + needs +
368 two + lines + gets + indented + on + the +
369 second + and + subsequent + lines;
372 * Do not add whitespace at the end of a line.
374 * Do not add whitespace or a blank line at the end of a file.
377 Control Statements and Loops
378 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
380 * Include a space after keywords (if, while, for, return, switch).
381 * Do not use braces (``{`` and ``}``) for control statements with zero or just a single statement, unless that statement is more than a single line in which case the braces are permitted.
385 for (p = buf; *p != '\0'; ++p)
390 z = a + really + long + statement + that + needs +
391 two + lines + gets + indented + on + the +
392 second + and + subsequent + lines;
399 val = realloc(val, newsize);
402 * Parts of a for loop may be left empty.
406 for (; cnt < 15; cnt++) {
411 * Closing and opening braces go on the same line as the else keyword.
412 * Braces that are not necessary should be left out.
428 * Do not use spaces after function names.
429 * Commas should have a space after them.
430 * No spaces after ``(`` or ``[`` or preceding the ``]`` or ``)`` characters.
434 error = function(a1, a2);
442 * Unary operators do not require spaces, binary operators do.
443 * Do not use parentheses unless they are required for precedence or unless the statement is confusing without them.
444 However, remember that other people may be more easily confused than you.
449 Exits should be 0 on success, or 1 on failure.
454 * Avoid obvious comments such as
455 * "Exit 0 on success."
462 * Variables should be declared at the start of a block of code rather than in the middle.
463 The exception to this is when the variable is ``const`` in which case the declaration must be at the point of first use/assignment.
464 * When declaring variables in functions, multiple variables per line are OK.
465 However, if multiple declarations would cause the line to exceed a reasonable line length, begin a new set of declarations on the next line rather than using a line continuation.
466 * Be careful to not obfuscate the code by initializing variables in the declarations, only the last variable on a line should be initialized.
467 If multiple variables are to be initialized when defined, put one per line.
468 * Do not use function calls in initializers, except for ``const`` variables.
472 int i = 0, j = 0, k = 0; /* bad, too many initializer */
474 char a = 0; /* OK, one variable per line with initializer */
477 float x, y = 0.0; /* OK, only last variable has initializer */
483 * Casts and sizeof statements are not followed by a space.
484 * Always write sizeof statements with parenthesis.
485 The redundant parenthesis rules do not apply to sizeof(var) instances.
487 C Function Definition, Declaration and Use
488 -------------------------------------------
493 * It is recommended (and generally required by the compiler) that all non-static functions are prototyped somewhere.
494 * Functions local to one source module should be declared static, and should not be prototyped unless absolutely necessary.
495 * Functions used from other parts of code (external API) must be prototyped in the relevant include file.
496 * Function prototypes should be listed in a logical order, preferably alphabetical unless there is a compelling reason to use a different ordering.
497 * Functions that are used locally in more than one module go into a separate header file, for example, "extern.h".
498 * Do not use the ``__P`` macro.
499 * Functions that are part of an external API should be documented using Doxygen-like comments above declarations. See :ref:`doxygen_guidelines` for details.
500 * Functions that are part of the external API must have an ``rte_`` prefix on the function name.
501 * Do not use uppercase letters - either in the form of ALL_UPPERCASE, or CamelCase - in function names. Lower-case letters and underscores only.
502 * When prototyping functions, associate names with parameter types, for example:
506 void function1(int fd); /* good */
507 void function2(int); /* bad */
509 * Short function prototypes should be contained on a single line.
510 Longer prototypes, e.g. those with many parameters, can be split across multiple lines.
511 The second and subsequent lines should be further indented as for line statement continuations as described in the previous section.
515 static char *function1(int _arg, const char *_arg2,
519 static void usage(void);
523 Unlike function definitions, the function prototypes do not need to place the function return type on a separate line.
528 * The function type should be on a line by itself preceding the function.
529 * The opening brace of the function body should be on a line by itself.
534 function(int a1, int a2, float fl, int a4)
538 * Do not declare functions inside other functions.
539 ANSI C states that such declarations have file scope regardless of the nesting of the declaration.
540 Hiding file declarations in what appears to be a local scope is undesirable and will elicit complaints from a good compiler.
541 * Old-style (K&R) function declaration should not be used, use ANSI function declarations instead as shown below.
542 * Long argument lists should be wrapped as described above in the function prototypes section.
547 * All major routines should have a comment briefly describing what
548 * they do. The comment before the "main" routine should describe
549 * what the program does.
552 main(int argc, char *argv[])
558 C Statement Style and Conventions
559 ---------------------------------
564 * NULL is the preferred null pointer constant.
565 Use NULL instead of ``(type *)0`` or ``(type *)NULL``, except where the compiler does not know the destination type e.g. for variadic args to a function.
566 * Test pointers against NULL, for example, use:
570 if (p == NULL) /* Good, compare pointer to NULL */
572 if (!p) /* Bad, using ! on pointer */
575 * Do not use ! for tests unless it is a boolean, for example, use:
579 if (*p == '\0') /* check character against (char)0 */
584 * Functions which create objects, or allocate memory, should return pointer types, and NULL on error.
585 The error type should be indicated may setting the variable ``rte_errno`` appropriately.
586 * Functions which work on bursts of packets, such as RX-like or TX-like functions, should return the number of packets handled.
587 * Other functions returning int should generally behave like system calls:
588 returning 0 on success and -1 on error, setting ``rte_errno`` to indicate the specific type of error.
589 * Where already standard in a given library, the alternative error approach may be used where the negative value is not -1 but is instead ``-errno`` if relevant, for example, ``-EINVAL``.
590 Note, however, to allow consistency across functions returning integer or pointer types, the previous approach is preferred for any new libraries.
591 * For functions where no error is possible, the function type should be ``void`` not ``int``.
592 * Routines returning ``void *`` should not have their return values cast to any pointer type.
593 (Typecasting can prevent the compiler from warning about missing prototypes as any implicit definition of a function returns int,
594 which, unlike ``void *``, needs a typecast to assign to a pointer variable.)
598 The above rule about not typecasting ``void *`` applies to malloc, as well as to DPDK functions.
600 * Values in return statements should not be enclosed in parentheses.
605 In the DPDK environment, use the logging interface provided:
609 /* register log types for this application */
610 int my_logtype1 = rte_log_register("myapp.log1");
611 int my_logtype2 = rte_log_register("myapp.log2");
613 /* set global log level to INFO */
614 rte_log_set_global_level(RTE_LOG_INFO);
616 /* only display messages higher than NOTICE for log2 (default
618 rte_log_set_level(my_logtype2, RTE_LOG_NOTICE);
620 /* enable all PMD logs (whose identifier string starts with "pmd.") */
621 rte_log_set_level_pattern("pmd.*", RTE_LOG_DEBUG);
623 /* log in debug level */
624 rte_log_set_global_level(RTE_LOG_DEBUG);
625 RTE_LOG(DEBUG, my_logtype1, "this is is a debug level message\n");
626 RTE_LOG(INFO, my_logtype1, "this is is a info level message\n");
627 RTE_LOG(WARNING, my_logtype1, "this is is a warning level message\n");
628 RTE_LOG(WARNING, my_logtype2, "this is is a debug level message (not displayed)\n");
630 /* log in info level */
631 rte_log_set_global_level(RTE_LOG_INFO);
632 RTE_LOG(DEBUG, my_logtype1, "debug level message (not displayed)\n");
637 * When a test is done in a critical zone (called often or in a data path) the code can use the ``likely()`` and ``unlikely()`` macros to indicate the expected, or preferred fast path.
638 They are expanded as a compiler builtin and allow the developer to indicate if the branch is likely to be taken or not. Example:
642 #include <rte_branch_prediction.h>
648 The use of ``likely()`` and ``unlikely()`` should only be done in performance critical paths,
649 and only when there is a clearly preferred path, or a measured performance increase gained from doing so.
650 These macros should be avoided in non-performance-critical code.
652 Static Variables and Functions
653 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
655 * All functions and variables that are local to a file must be declared as ``static`` because it can often help the compiler to do some optimizations (such as, inlining the code).
656 * Functions that should be inlined should to be declared as ``static inline`` and can be defined in a .c or a .h file.
659 Static functions defined in a header file must be declared as ``static inline`` in order to prevent compiler warnings about the function being unused.
664 The ``const`` attribute should be used as often as possible when a variable is read-only.
669 The ``asm`` and ``volatile`` keywords do not have underscores. The AT&T syntax should be used.
670 Input and output operands should be named to avoid confusion, as shown in the following example:
674 asm volatile("outb %[val], %[port]"
682 * Forever loops are done with for statements, not while statements.
683 * Elements in a switch statement that cascade should have a FALLTHROUGH comment. For example:
687 switch (ch) { /* Indent the switch. */
688 case 'a': /* Don't indent the case. */
689 aflag = 1; /* Indent case body one tab. */
703 DPDK provides infrastructure to perform logging during runtime. This is very
704 useful for enabling debug output without recompilation. To enable or disable
705 logging of a particular topic, the ``--log-level`` parameter can be provided
706 to EAL, which will change the log level. DPDK code can register topics,
707 which allows the user to adjust the log verbosity for that specific topic.
709 In general, the naming scheme is as follows: ``type.section.name``
711 * Type is the type of component, where ``lib``, ``pmd``, ``bus`` and ``user``
712 are the common options.
713 * Section refers to a specific area, for example a poll-mode-driver for an
714 ethernet device would use ``pmd.net``, while an eventdev PMD uses
716 * The name identifies the individual item that the log applies to.
717 The name section must align with
718 the directory that the PMD code resides. See examples below for clarity.
722 * The virtio network PMD in ``drivers/net/virtio`` uses ``pmd.net.virtio``
723 * The eventdev software poll mode driver in ``drivers/event/sw`` uses ``pmd.event.sw``
724 * The octeontx mempool driver in ``drivers/mempool/octeontx`` uses ``pmd.mempool.octeontx``
725 * The DPDK hash library in ``lib/librte_hash`` uses ``lib.hash``
730 In addition to the above logging topic, any PMD or library can further split
731 logging output by using "specializations". A specialization could be the
732 difference between initialization code, and logs of events that occur at runtime.
734 An example could be the initialization log messages getting one
735 specialization, while another specialization handles mailbox command logging.
736 Each PMD, library or component can create as many specializations as required.
738 A specialization looks like this:
740 * Initialization output: ``type.section.name.init``
741 * PF/VF mailbox output: ``type.section.name.mbox``
743 A real world example is the i40e poll mode driver which exposes two
744 specializations, one for initialization ``pmd.net.i40e.init`` and the other for
745 the remaining driver logs ``pmd.net.i40e.driver``.
747 Note that specializations have no formatting rules, but please follow
748 a precedent if one exists. In order to see all current log topics and
749 specializations, run the ``app/test`` binary, and use the ``dump_log_types``
754 All Python code should work with Python 2.7+ and 3.2+ and be compliant with
755 `PEP8 (Style Guide for Python Code) <https://www.python.org/dev/peps/pep-0008/>`_.
757 The ``pep8`` tool can be used for testing compliance with the guidelines.
759 Integrating with the Build System
760 ---------------------------------
762 DPDK supports being built in two different ways:
764 * using ``make`` - or more specifically "GNU make", i.e. ``gmake`` on FreeBSD
765 * using the tools ``meson`` and ``ninja``
767 Any new library or driver to be integrated into DPDK should support being
768 built with both systems. While building using ``make`` is a legacy approach, and
769 most build-system enhancements are being done using ``meson`` and ``ninja``
770 there are no plans at this time to deprecate the legacy ``make`` build system.
772 Therefore all new component additions should include both a ``Makefile`` and a
773 ``meson.build`` file, and should be added to the component lists in both the
774 ``Makefile`` and ``meson.build`` files in the relevant top-level directory:
775 either ``lib`` directory or a ``driver`` subdirectory.
780 The ``Makefile`` for the component should be of the following format, where
781 ``<name>`` corresponds to the name of the library in question, e.g. hash,
782 lpm, etc. For drivers, the same format of Makefile is used.
786 # pull in basic DPDK definitions, including whether library is to be
788 include $(RTE_SDK)/mk/rte.vars.mk
791 LIB = librte_<name>.a
793 # any library cflags needed. Generally add "-O3 $(WERROR_FLAGS)"
795 CFLAGS += $(WERROR_FLAGS)
797 # the symbol version information for the library, and .so version
798 EXPORT_MAP := rte_<name>_version.map
801 # all source filenames are stored in SRCS-y
802 SRCS-$(CONFIG_RTE_LIBRTE_<NAME>) += rte_<name>.c
805 SYMLINK-$(CONFIG_RTE_LIBRTE_<NAME>)-include += rte_<name>.h
807 # pull in rules to build the library
808 include $(RTE_SDK)/mk/rte.lib.mk
810 Meson Build File Contents - Libraries
811 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
813 The ``meson.build`` file for a new DPDK library should be of the following basic
816 .. code-block:: python
818 sources = files('file1.c', ...)
819 headers = files('file1.c', ...)
822 The will build based on a number of conventions and assumptions within the DPDK
823 itself, for example, that the library name is the same as the directory name in
824 which the files are stored.
826 For a library ``meson.build`` file, there are number of variables which can be
827 set, some mandatory, others optional. The mandatory fields are:
830 **Default Value = []**.
831 This variable should list out the files to be compiled up to create the
832 library. Files must be specified using the meson ``files()`` function.
835 The optional fields are:
837 allow_experimental_apis
838 **Default Value = false**
839 Used to allow the library to make use of APIs marked as experimental.
840 Set to ``true`` if the C files in the library call any functions
841 marked as experimental in any included header files.
844 **Default Value = true**
845 Used to optionally compile a library, based on its dependencies or
846 environment. A simple example of use would be:
848 .. code-block:: python
850 if host_machine.system() != 'linux'
856 **Default Value = [<-march/-mcpu flags>]**.
857 Used to specify any additional cflags that need to be passed to compile
858 the sources in the library.
861 **Default Value = ['eal']**.
862 Used to list the internal library dependencies of the library. It should
863 be assigned to using ``+=`` rather than overwriting using ``=``. The
864 dependencies should be specified as strings, each one giving the name of
865 a DPDK library, without the ``librte_`` prefix. Dependencies are handled
866 recursively, so specifying e.g. ``mempool``, will automatically also
867 make the library depend upon the mempool library's dependencies too -
868 ``ring`` and ``eal``. For libraries that only depend upon EAL, this
869 variable may be omitted from the ``meson.build`` file. For example:
871 .. code-block:: python
877 **Default Value = []**.
878 Used to specify external dependencies of this library. They should be
879 returned as dependency objects, as returned from the meson
880 ``dependency()`` or ``find_library()`` functions. Before returning
881 these, they should be checked to ensure the dependencies have been
882 found, and, if not, the ``build`` variable should be set to ``false``.
885 .. code-block:: python
887 my_dep = dependency('libX', required: 'false')
896 **Default Value = []**.
897 Used to return the list of header files for the library that should be
898 installed to $PREFIX/include when ``ninja install`` is run. As with
899 source files, these should be specified using the meson ``files()``
903 **Default Value = []**.
904 Used to indicate any additional header file paths which should be
905 added to the header search path for other libs depending on this
906 library. EAL uses this so that other libraries building against it
907 can find the headers in subdirectories of the main EAL directory. The
908 base directory of each library is always given in the include path,
909 it does not need to be specified here.
912 **Default Value = library name derived from the directory name**.
913 If a library's .so or .a file differs from that given in the directory
914 name, the name should be specified using this variable. In practice,
915 since the convention is that for a library called ``librte_xyz.so``, the
916 sources are stored in a directory ``lib/librte_xyz``, this value should
917 never be needed for new libraries.
921 The name value also provides the name used to find the function version
922 map file, as part of the build process, so if the directory name and
923 library names differ, the ``version.map`` file should be named
924 consistently with the library, not the directory
927 **Default Value = []**.
928 This variable can be used to pass to the library build some pre-built
929 objects that were compiled up as part of another target given in the
930 included library ``meson.build`` file.
933 **Default Value = 1**.
934 Specifies the ABI version of the library, and is used as the major
935 version number of the resulting ``.so`` library.
937 Meson Build File Contents - Drivers
938 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
940 For drivers, the values are largely the same as for libraries. The variables
943 allow_experimental_apis
959 **Default Value = <driver directory>** Some drivers include a base
960 directory for additional source files and headers, so we have this
961 variable to allow the headers from that base directory to be found when
962 compiling driver sources. Should be appended to using ``+=`` rather than
963 overwritten using ``=``. The values appended should be meson include
964 objects got using the ``include_directories()`` function. For example:
966 .. code-block:: python
968 includes += include_directories('base')
971 As above, though note that each driver class can define it's own naming
972 scheme for the resulting ``.so`` files.
975 As above, generally used for the contents of the ``base`` directory.
978 **Default Value = []**
979 This variable is used to pass additional library link flags through to
980 the DPDK pkgconfig file generated, for example, to track any additional
981 libraries that may need to be linked into the build - especially when
982 using static libraries. Anything added here will be appended to the end
983 of the ``pkgconfig --libs`` output.