diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/CodingStandards.rst | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst index 4d25c1ddfc..9456ba5ab5 100644 --- a/docs/CodingStandards.rst +++ b/docs/CodingStandards.rst @@ -43,6 +43,121 @@ The ultimate goal of these guidelines is the increase readability and maintainability of our common source base. If you have suggestions for topics to be included, please mail them to `Chris <mailto:sabre@nondot.org>`_. +Languages, Libraries, and Standards +=================================== + +Most source code in LLVM and other LLVM projects using these coding standards +is C++ code. There are some places where C code is used either due to +environment restrictions, historical restrictions, or due to third-party source +code imported into the tree. Generally, our preference is for standards +conforming, modern, and portable C++ code as the implementation language of +choice. + +C++ Standard Versions +--------------------- + +LLVM and Clang are currently written using C++98/03 conforming code, with +selective use of C++11 features when they are present in the toolchain. +Projects like LLD and LLDB are already heavily using C++11 features. + +However, LLVM and Clange are also in the process of switching to use C++11 as +the base line for standards conformance. Once completed, the same standard +baseline will be used for LLVM, Clang, and LLD. LLDB is pushing forward much +more aggressively and has their own baseline. + +C++ Standard Library +-------------------- + +Use the C++ standard library facilities whenever they are available for +a particular task. LLVM and related projects emphasize and rely on the standard +library facilities for as much as possible. Common support libraries providing +functionality missing from the standard library for which there are standard +interfaces or active work on adding standard interfaces will often be +implemented in the LLVM namespace following the expected standard interface. + +There are some exceptions such as the standard I/O streams library which are +avoided. Also, there is much more detailed information on these subjects in the +`Programmer's Manual`_. + +.. _Programmer's Manual: + http://llvm.org/docs/ProgrammersManual.html + +Supported C++11 Language and Library Features +------------------------------------------- + +.. warning:: + This section is written to reflect the expected state **AFTER** the + transition to C++11 is complete for the LLVM source tree. + +While LLVM, Clang, and LLD use C++11, not all features are available in all of +the toolchains which we support. The set of features supported for use in LLVM +is the intersection of those supported in MSVC 2012, GCC 4.7, and Clang 3.1. +The ultimate definition of this set is what build bots with those respective +toolchains accept. Don't argue with the build bots. + +Each toolchain provides a good reference for what it accepts: +* Clang: http://clang.llvm.org/cxx_status.html +* GCC: http://gcc.gnu.org/projects/cxx0x.html +* MSVC: http://msdn.microsoft.com/en-us/library/hh567368.aspx + +In most cases, the MSVC list will be the dominating factor. Here is a summary +of the features that are expected to work. Features not on this list are +unlikely to be supported by our host compilers. + +* Rvalue references: N2118_ + * But *not* Rvalue references for ``*this`` or member qualifiers (N2439_) +* Static assert: N1720_ +* ``auto`` type deduction: N1984_, N1737_ +* Trailing return types: N2541_ +* Lambdas: N2927_ +* ``decltype``: N2343_ +* Nested closing right angle brackets: N1757_ +* Extern templates: N1987_ +* ``nullptr``: N2431_ +* Strongly-typed and forward declarable enums: N2347_, N2764_ +* Local and unnamed types as template arguments: N2657_ +* Range-based for-loop: N2930_ +* ``override`` and ``final``: N2928_, N3206_, N3272_ +* Atomic operations and the C++11 memory model: N2429_ + +.. _N2118: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2118.html +.. _N2439: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2439.htm +.. _N1720: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1720.html +.. _N1984: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf +.. _N1737: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1737.pdf +.. _N2541: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2541.htm +.. _N2927: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2927.pdf +.. _N2343: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2343.pdf +.. _N1757: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1757.html +.. _N1987: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1987.htm +.. _N2431: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2431.pdf +.. _N2347: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2347.pdf +.. _N2764: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2764.pdf +.. _N2657: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2657.htm +.. _N2930: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2930.html +.. _N2928: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2928.htm +.. _N3206: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n3206.htm +.. _N3272: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n3272.htm +.. _N2429: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2429.htm + +The supported features in the C++11 standard libraries are less well tracked, +but also much greater. Most of the standard libraries implement most of C++11's +library. The most likely lowest common denominator is Linux support. For +libc++, the support is just poorly tested and undocumented but expected to be +largely complete. YMMV. For libstdc++, the support is documented in detail in +`the libstdc++ manual`_. There are some very minor missing facilities that are +unlikely to be common problems, and there are a few larger gaps that are worth +being aware of: + +* Not all of the type traits are implemented +* No regular expression library. +* While most of the atomics library is well implemented, the fences are + missing. Fortunately, they are rarely needed. +* The locale support is incomplete. + +.. _the libstdc++ manual: + http://gcc.gnu.org/onlinedocs/gcc-4.7.3/libstdc++/manual/manual/status.html#status.iso.2011 + Mechanical Source Issues ======================== |