diff --git a/libcxx/docs/Contributing.rst b/libcxx/docs/Contributing.rst --- a/libcxx/docs/Contributing.rst +++ b/libcxx/docs/Contributing.rst @@ -34,6 +34,121 @@ 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 `_. +There are some deviations from this standard. + +In libc++, like all standard libraries, we use ``__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 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 clashes the test in +``libcxx/test/libcxx/reserved_macro_names.gen.py`` +contains the list of reserved names that are can't be used. + +Function calls in the standard library that use types provided by the +user are susceptible to ADL. This means calling ``move(UserType)`` may +not call ``std::move``. Therefore function calls are using qualified +names to avoid ADL. Some functions in the standard library +`require ADL usage `_. + +Function overloading also applies to operators. Using ``&user_object`` +may call a user defined ``operator&``. Use ``std::addressof`` instead. +Similar for ``operator,``. When using the ``,`` make sure to cast the +result to ``void``. For example: + +.. code-block:: cpp + + for (--__last, (void) --__d; __first < __last; ++__first, (void) --__d) { + difference_type __i = __uid(__g, _Pp(0, __d)); + if (__i != difference_type(0)) + swap(*__first, *(__first + __i)); + } + +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``. In libc++ this is + supported in all versions of C++. + +Other tips are: + +- Keep the number of formatting changes in patches minimal. +- Don't fix existing style issues in the same patch as bug-fixes or new + features. Please don't separate reviews. Keep in mind that large + formatting patches may cause merge conflicts in other patches under + review. In general we do not want these patches. +- Keep patches small. Large patches are harder to review and take a + significant amount of time. It's fine to have multiple patches to + implement one feature. + + +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. This means the function is + ``constexpr`` in C++20 and later. The Standard does not allow to make + 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. +- The ``#libcxx`` channel on + `LLVM's Discord server `_. + This is the place where most discussion regarding libc++ happens and + the active contributors are available for questions. + + +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 `_ used to + create the official C++ standard. This can be use to create your own + unofficial build of the standard. + +- A `html rendered version of the draft `_ is + available. This is the most commonly used place to look for the + wording of the standard. + +- An `alterative `_ is available. + This link has both recent and historic versions of the standard. + +- When implementing features there are + `general requirements `_. + Most papers use this + `jargon `_ + to describe how library functions work. + +- The `WG21 redirector `_ is a tool to quickly locate + papers, issues, and wording in the standard. + +- The `paper trail `_ 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. + +- `cppreference `_ is a good resource + for the usage of C++ library and language features. It's easier to + read than the C++ Standard. This reference lacks details needed to + properly implement library features. + + Pre-commit check list =====================