mirror of
https://github.com/capstone-engine/llvm-capstone.git
synced 2024-12-15 12:09:51 +00:00
[libc++][doc] Improves contribution page.
This adds more information regarding the libc++ coding style and reference that are useful when working on a standard library implementation. This information is based on review comments and tips I give to new contributors an information I wish I'd know when I started working on libc++. Depends on D156051 Reviewed By: #libc, jloser, var-const, ldionne Differential Revision: https://reviews.llvm.org/D156052
This commit is contained in:
parent
8383d768f2
commit
195015cf67
@ -34,6 +34,123 @@ This will ensure that you work in a direction that the project endorses and will
|
||||
contribution as directional questions can be raised early. Including a WIP patch is not mandatory, but
|
||||
it can be useful to ground the discussion in something concrete.
|
||||
|
||||
Coding standards
|
||||
================
|
||||
|
||||
In general, libc++ follows the
|
||||
`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_.
|
||||
There are some deviations from these standards.
|
||||
|
||||
Libc++ uses ``__ugly_names``. These names are reserved for implementations, so
|
||||
users may not use them in their own applications. When using a name like ``T``,
|
||||
a user may have defined a macro that changes the meaning of ``T``. By using
|
||||
``__ugly_names`` we avoid that problem. Other standard libraries and compilers
|
||||
use these names too. To avoid common clashes with other uglified names used in
|
||||
other implementations (e.g. system headers), the test in
|
||||
``libcxx/test/libcxx/system_reserved_names.gen.py`` contains the list of
|
||||
reserved names that can't be used.
|
||||
|
||||
Unqualified function calls are susceptible to
|
||||
`argument-dependent lookup (ADL) <https://en.cppreference.com/w/cpp/language/adl>`_.
|
||||
This means calling ``move(UserType)`` might not call ``std::move``. Therefore,
|
||||
function calls must use qualified names to avoid ADL. Some functions in the
|
||||
standard library `require ADL usage <http://eel.is/c++draft/contents#3>`_.
|
||||
Names of classes, variables, concepts, and type aliases are not subject to ADL.
|
||||
They don't need to be qualified.
|
||||
|
||||
Function overloading also applies to operators. Using ``&user_object`` may call
|
||||
a user-defined ``operator&``. Use ``std::addressof`` instead. Similarly, to
|
||||
avoid invoking a user-defined ``operator,``, make sure to cast the result to
|
||||
``void`` when using the ``,``. For example:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
for (; __first1 != __last1; ++__first1, (void)++__first2) {
|
||||
...
|
||||
}
|
||||
|
||||
In general, try to follow the style of existing code. There are a few
|
||||
exceptions:
|
||||
|
||||
- ``_VSTD::foo`` is no longer used in new code. Use ``std::foo`` instead.
|
||||
- ``_LIBCPP_INLINE_VISIBILITY`` is no longer used in new code. Use
|
||||
``_LIBCPP_HIDE_FROM_ABI`` instead.
|
||||
- Prefer ``using foo = int`` over ``typedef int foo``. The compilers supported
|
||||
by libc++ accept alias declarations in all standard modes.
|
||||
|
||||
Other tips are:
|
||||
|
||||
- Keep the number of formatting changes in patches minimal.
|
||||
- Provide separate patches for style fixes and for bug fixes or features. Keep in
|
||||
mind that large formatting patches may cause merge conflicts with other patches
|
||||
under review. In general, we prefer to avoid large reformatting patches.
|
||||
- Keep patches self-contained. Large and/or complicated patches are harder to
|
||||
review and take a significant amount of time. It's fine to have multiple
|
||||
patches to implement one feature if the feature can be split into
|
||||
self-contained sub-tasks.
|
||||
|
||||
|
||||
Resources
|
||||
=========
|
||||
|
||||
Libc++ specific
|
||||
---------------
|
||||
|
||||
- ``libcxx/include/__config`` -- this file contains the commonly used
|
||||
macros in libc++. Libc++ supports all C++ language versions. Newer versions
|
||||
of the Standard add new features. For example, making functions ``constexpr``
|
||||
in C++20 is done by using ``_LIBCPP_CONSTEXPR_SINCE_CXX20``. This means the
|
||||
function is ``constexpr`` in C++20 and later. The Standard does not allow
|
||||
making this available in C++17 or earlier, so we use a macro to implement
|
||||
this requirement.
|
||||
- ``libcxx/test/support/test_macros.h`` -- similar to the above, but for the
|
||||
test suite.
|
||||
|
||||
|
||||
ISO C++ Standard
|
||||
----------------
|
||||
|
||||
Libc++ implements the library part of the ISO C++ standard. The official
|
||||
publication must be bought from ISO or your national body. This is not
|
||||
needed to work on libc++, there are other free resources available.
|
||||
|
||||
- The `LaTeX sources <https://github.com/cplusplus/draft>`_ used to
|
||||
create the official C++ standard. This can be used to create your own
|
||||
unofficial build of the standard.
|
||||
|
||||
- An `HTML rendered version of the draft <https://eel.is/c++draft/>`_ is
|
||||
available. This is the most commonly used place to look for the
|
||||
wording of the standard.
|
||||
|
||||
- An `alternative <https://github.com/timsong-cpp/cppwp>`_ is available.
|
||||
This link has both recent and historic versions of the standard.
|
||||
|
||||
- When implementing features, there are
|
||||
`general requirements <https://eel.is/c++draft/#library>`_.
|
||||
Most papers use this
|
||||
`jargon <http://eel.is/c++draft/structure#specifications>`_
|
||||
to describe how library functions work.
|
||||
|
||||
- The `WG21 redirect service <https://wg21.link/>`_ is a tool to quickly locate
|
||||
papers, issues, and wording in the standard.
|
||||
|
||||
- The `paper trail <https://github.com/cplusplus/papers/issues>`_ of
|
||||
papers is publicly available, including the polls taken. It
|
||||
contains links to the minutes of paper's discussion. Per ISO rules,
|
||||
these minutes are only accessible by members of the C++ committee.
|
||||
|
||||
- `Feature-Test Macros and Policies
|
||||
<https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations>`_
|
||||
contains information about feature-test macros in C++.
|
||||
It contains a list with all feature-test macros, their versions, and the paper
|
||||
that introduced them.
|
||||
|
||||
- `cppreference <https://en.cppreference.com/w/>`_ is a good resource
|
||||
for the usage of C++ library and language features. It's easier to
|
||||
read than the C++ Standard, but it lacks details needed to properly implement
|
||||
library features.
|
||||
|
||||
|
||||
Pre-commit check list
|
||||
=====================
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user