diff options
author | Josh Triplett <josh@joshtriplett.org> | 2014-10-29 14:15:17 -0400 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2014-11-03 11:46:02 -0500 |
commit | 21228a1868692c34ade648dbb0bc3db0069ab551 (patch) | |
tree | a545010214c9e42931bef25b2fc06880be885bec /Documentation/CodingStyle | |
parent | 0df1f2487d2f0d04703f142813d53615d62a1da4 (diff) |
CodingStyle: Add a chapter on conditional compilation
Document several common practices and conventions regarding conditional
compilation, most notably the preference for ifdefs in headers rather
than .c files.
Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Acked-by: Geert Uytterhoeven <geert@linux-m68k.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/CodingStyle')
-rw-r--r-- | Documentation/CodingStyle | 43 |
1 files changed, 43 insertions, 0 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 3171822c22a5..9f28b140dc89 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle | |||
@@ -845,6 +845,49 @@ next instruction in the assembly output: | |||
845 | : /* outputs */ : /* inputs */ : /* clobbers */); | 845 | : /* outputs */ : /* inputs */ : /* clobbers */); |
846 | 846 | ||
847 | 847 | ||
848 | Chapter 20: Conditional Compilation | ||
849 | |||
850 | Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c | ||
851 | files; doing so makes code harder to read and logic harder to follow. Instead, | ||
852 | use such conditionals in a header file defining functions for use in those .c | ||
853 | files, providing no-op stub versions in the #else case, and then call those | ||
854 | functions unconditionally from .c files. The compiler will avoid generating | ||
855 | any code for the stub calls, producing identical results, but the logic will | ||
856 | remain easy to follow. | ||
857 | |||
858 | Prefer to compile out entire functions, rather than portions of functions or | ||
859 | portions of expressions. Rather than putting an ifdef in an expression, factor | ||
860 | out part or all of the expression into a separate helper function and apply the | ||
861 | conditional to that function. | ||
862 | |||
863 | If you have a function or variable which may potentially go unused in a | ||
864 | particular configuration, and the compiler would warn about its definition | ||
865 | going unused, mark the definition as __maybe_unused rather than wrapping it in | ||
866 | a preprocessor conditional. (However, if a function or variable *always* goes | ||
867 | unused, delete it.) | ||
868 | |||
869 | Within code, where possible, use the IS_ENABLED macro to convert a Kconfig | ||
870 | symbol into a C boolean expression, and use it in a normal C conditional: | ||
871 | |||
872 | if (IS_ENABLED(CONFIG_SOMETHING)) { | ||
873 | ... | ||
874 | } | ||
875 | |||
876 | The compiler will constant-fold the conditional away, and include or exclude | ||
877 | the block of code just as with an #ifdef, so this will not add any runtime | ||
878 | overhead. However, this approach still allows the C compiler to see the code | ||
879 | inside the block, and check it for correctness (syntax, types, symbol | ||
880 | references, etc). Thus, you still have to use an #ifdef if the code inside the | ||
881 | block references symbols that will not exist if the condition is not met. | ||
882 | |||
883 | At the end of any non-trivial #if or #ifdef block (more than a few lines), | ||
884 | place a comment after the #endif on the same line, noting the conditional | ||
885 | expression used. For instance: | ||
886 | |||
887 | #ifdef CONFIG_SOMETHING | ||
888 | ... | ||
889 | #endif /* CONFIG_SOMETHING */ | ||
890 | |||
848 | 891 | ||
849 | Appendix I: References | 892 | Appendix I: References |
850 | 893 | ||