generic-library/cxx
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[libcxx] Add new Sphinx documentation

Browse Source 
Summary:
This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. 

The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs

In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`.

Reviewers: chandlerc, mclow.lists, danalbert, jroelofs

Subscribers: silvas, cfe-commits

Differential Revision: http://reviews.llvm.org/D12129

git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@245788 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
Eric Fiselier 2015-08-22 19:40:49 +00:00
parent dc68c69e32
commit b9f425a434
10 changed files with 970 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
CMakeLists.txt
View File

@ -52,6 +52,7 @@ option(LIBCXX_ENABLE_ASSERTIONS "Enable assertions independent of build mode." O
option(LIBCXX_ENABLE_SHARED "Build libc++ as a shared library." ON) option(LIBCXX_ENABLE_SHARED "Build libc++ as a shared library." ON)
option(LIBCXX_INCLUDE_TESTS "Build the libc++ tests." ${LLVM_INCLUDE_TESTS}) option(LIBCXX_INCLUDE_TESTS "Build the libc++ tests." ${LLVM_INCLUDE_TESTS})
option(LIBCXX_INCLUDE_DOCS "Build the libc++ documentation." ${LLVM_INCLUDE_DOCS})
set(LIBCXX_LIBDIR_SUFFIX "${LLVM_LIBDIR_SUFFIX}" CACHE STRING set(LIBCXX_LIBDIR_SUFFIX "${LLVM_LIBDIR_SUFFIX}" CACHE STRING
"Define suffix of library directory name (32/64)") "Define suffix of library directory name (32/64)")
option(LIBCXX_INSTALL_HEADERS "Install the libc++ headers." ON) option(LIBCXX_INSTALL_HEADERS "Install the libc++ headers." ON)
@ -288,6 +289,10 @@ endif()
include_directories(include) include_directories(include)
add_subdirectory(include) add_subdirectory(include)
add_subdirectory(lib) add_subdirectory(lib)
if (LIBCXX_INCLUDE_TESTS) if (LIBCXX_INCLUDE_TESTS)
add_subdirectory(test) add_subdirectory(test)
endif() endif()
if (LIBCXX_INCLUDE_DOCS)
add_subdirectory(docs)
endif()

11
cmake/Modules/HandleOutOfTreeLLVM.cmake
View File

@ -77,6 +77,9 @@ if (CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
if (NOT DEFINED LLVM_INCLUDE_TESTS) if (NOT DEFINED LLVM_INCLUDE_TESTS)
set(LLVM_INCLUDE_TESTS ${LLVM_FOUND}) set(LLVM_INCLUDE_TESTS ${LLVM_FOUND})
endif() endif()
if (NOT DEFINED LLVM_ENABLE_SPHINX)
set(LLVM_ENABLE_SPHINX OFF)
endif()
# Required LIT Configuration ------------------------------------------------ # Required LIT Configuration ------------------------------------------------
# Define the default arguments to use with 'lit', and an option for the user # Define the default arguments to use with 'lit', and an option for the user
@ -95,6 +98,14 @@ if (CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
set(cmake_3_2_USES_TERMINAL USES_TERMINAL) set(cmake_3_2_USES_TERMINAL USES_TERMINAL)
endif() endif()
# Required doc configuration
if (LLVM_ENABLE_SPHINX)
message(STATUS "Sphinx enabled.")
find_package(Sphinx REQUIRED)
else()
message(STATUS "Sphinx disabled.")
endif()
# Add LLVM Functions -------------------------------------------------------- # Add LLVM Functions --------------------------------------------------------
include(AddLLVM OPTIONAL) include(AddLLVM OPTIONAL)
endif() endif()

1
cmake/config-ix.cmake
View File

@ -17,4 +17,3 @@ check_library_exists(c printf "" LIBCXX_HAS_C_LIB)
check_library_exists(m ccos "" LIBCXX_HAS_M_LIB) check_library_exists(m ccos "" LIBCXX_HAS_M_LIB)
check_library_exists(rt clock_gettime "" LIBCXX_HAS_RT_LIB) check_library_exists(rt clock_gettime "" LIBCXX_HAS_RT_LIB)
check_library_exists(gcc_s __gcc_personality_v0 "" LIBCXX_HAS_GCC_S_LIB) check_library_exists(gcc_s __gcc_personality_v0 "" LIBCXX_HAS_GCC_S_LIB)

279
docs/BuildingLibcxx.rst Normal file
View File

@ -0,0 +1,279 @@
===============
Building libc++
===============
.. contents::
:local:
Getting Started
===============
On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install
Xcode 4.2 or later. However if you want to install tip-of-trunk from here
(getting the bleeding edge), read on.
The basic steps needed to build libc++ are:
#. Checkout LLVM:
* ``cd where-you-want-llvm-to-live``
* ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
#. Checkout libc++:
* ``cd where-you-want-llvm-to-live``
* ``cd llvm/tools``
* ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx``
#. Checkout libc++abi:
* ``cd where-you-want-llvm-to-live``
* ``cd llvm/projects``
* ``svn co http://llvm.org/svn/llvm-project/libc++abi libc++abi``
#. Configure and build libc++ with libc++abi:
`CMake <CMake.html>`_ is the only supported configuration system. Unlike other LLVM
projects autotools is not supported for either libc++ or libc++abi.
Clang is the preferred compiler when building and using libc++.
* ``cd where you want to build llvm``
* ``mkdir build``
* ``cd build``
* ``cmake -G <generator> [options] <path to llvm sources>``
For more information about configuring libc++ see :ref:`CMake Options`.
* ``make cxx`` --- will build libc++ and libc++abi.
* ``make check-libcxx check-libcxxabi`` --- will run the test suites.
Shared libraries for libc++ and libc++ abi should now be present in llvm/build/lib.
See :ref:`using an alternate libc++ installation <alternate libcxx>`
#. **Optional**: Install libc++ and libc++abi
If your system already provides a libc++ installation it is important to be
careful not to replace it. Remember Use the CMake option ``CMAKE_INSTALL_PREFIX`` to
select a safe place to install libc++.
* ``make install-libcxx install-libcxxabi`` --- Will install the libraries and the headers
.. warning::
* Replacing your systems libc++ installation could render the system non-functional.
* Mac OS X will not boot without a valid copy of ``libc++.1.dylib`` in ``/usr/lib``.
The instructions are for building libc++ on
FreeBSD, Linux, or Mac using `libc++abi`_ as the C++ ABI library.
On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt.
It is sometimes beneficial to build outside of the LLVM tree. To build
libc++ TODO
.. code-block:: bash
$ cd where-you-want-libcxx-to-live
$ # Check out llvm, libc++ and libc++abi.
$ ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
$ ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx``
$ ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi``
$ cd where-you-want-to-build
$ mkdir build && cd build
$ export CC=clang CXX=clang++
$ cmake -DLLVM_PATH=path/to/llvm \
-DLIBCXX_CXX_ABI=libcxxabi \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxabi/include \
path/to/libcxx
$ make
$ make check-libcxx # optional
.. _`libc++abi`: http://libcxxabi.llvm.org/
.. _CMake Options:
CMake Options
=============
Here are some of the CMake variables that are used often, along with a
brief explanation and LLVM-specific notes. For full documentation, check the
CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
**CMAKE_BUILD_TYPE**:STRING
Sets the build type for ``make`` based generators. Possible values are
Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio
the user sets the build type with the IDE settings.
**CMAKE_INSTALL_PREFIX**:PATH
Path where LLVM will be installed if "make install" is invoked or the
"INSTALL" target is built.
**CMAKE_CXX_COMPILER**:STRING
The C++ compiler to use when building and testing libc++.
.. _libcxx-specific options:
libc++ specific options
-----------------------
.. option:: LIBCXX_ENABLE_ASSERTIONS:BOOL
**Default**: ``ON``
Build libc++ with assertions enabled.
.. option:: LIBCXX_BUILD_32_BITS:BOOL
**Default**: ``OFF``
Build libc++ as a 32 bit library. Also see :option:`LLVM_BUILD_32_BITS`.
.. option:: LIBCXX_ENABLE_SHARED:BOOL
**Default**: ``ON``
Build libc++ as a shared library. If ``OFF`` is specified then libc++ is
built as a static library.
.. option:: LIBCXX_LIBDIR_SUFFIX:STRING
Extra suffix to append to the directory where libraries are to be installed.
This option overrides :option:`LLVM_LIBDIR_SUFFIX`.
.. _ABI Library Specific Options:
ABI Library Specific Options
----------------------------
.. option:: LIBCXX_CXX_ABI:STRING
**Values**: ``none``, ``libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``.
Select the ABI library to build libc++ against.
.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS
Provide additional search paths for the ABI library headers.
.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH
Provide the path to the ABI library that libc++ should link against.
.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL
**Default**: ``OFF``
If this option is enabled, libc++ will try and link the selected ABI library
statically.
.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL
**Default**: ``OFF``
Build and use the LLVM unwinder. Note: This option can only be used when
libc++abi is the C++ ABI library used.
libc++ Feature options
----------------------
.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL
**Default**: ``ON``
Build libc++ with exception support.
.. option:: LIBCXX_ENABLE_RTTI:BOOL
**Default**: ``ON``
Build libc++ with run time type information.
.. _LLVM-specific variables:
LLVM-specific options
---------------------
.. option:: LLVM_LIBDIR_SUFFIX:STRING
Extra suffix to append to the directory where libraries are to be
installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
to install libraries to ``/usr/lib64``.
.. option:: LLVM_BUILD_32_BITS:BOOL
Build 32-bits executables and libraries on 64-bits systems. This option is
available only on some 64-bits unix systems. Defaults to OFF.
.. option:: LLVM_LIT_ARGS:STRING
Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
others.
Using Alternate ABI libraries
=============================
.. _libsupcxx:
Using libsupc++ on Linux
------------------------
You will need libstdc++ in order to provide libsupc++.
Figure out where the libsupc++ headers are on your system. On Ubuntu this
is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>``
You can also figure this out by running
.. code-block:: bash
$ echo | g++ -Wp,-v -x c++ - -fsyntax-only
ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu"
ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"
#include "..." search starts here:
#include &lt;...&gt; search starts here:
/usr/include/c++/4.7
/usr/include/c++/4.7/x86_64-linux-gnu
/usr/include/c++/4.7/backward
/usr/lib/gcc/x86_64-linux-gnu/4.7/include
/usr/local/include
/usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed
/usr/include/x86_64-linux-gnu
/usr/include
End of search list.
Note that the first two entries happen to be what we are looking for. This
may not be correct on other platforms.
We can now run CMake:
.. code-block:: bash
$ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \
-DLIBCXX_CXX_ABI=libstdc++ \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \
-DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \
<libc++-source-dir>
You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++``
above, which will cause the library to be linked to libsupc++ instead
of libstdc++, but this is only recommended if you know that you will
never need to link against libstdc++ in the same executable as libc++.
GCC ships libsupc++ separately but only as a static library. If a
program also needs to link against libstdc++, it will provide its
own copy of libsupc++ and this can lead to subtle problems.
.. code-block:: bash
$ make cxx
$ make install
You can now run clang with -stdlib=libc++.

9
docs/CMakeLists.txt Normal file
View File

@ -0,0 +1,9 @@
if (LLVM_ENABLE_SPHINX)
if (SPHINX_FOUND)
include(AddSphinxTarget)
if (${SPHINX_OUTPUT_HTML})
add_sphinx_target(html libcxx)
endif()
endif()
endif()

13
docs/README.txt Normal file
View File

@ -0,0 +1,13 @@
libc++ Documentation
====================
The libc++ documentation is written using the Sphinx documentation generator. It is
currently tested with Sphinx 1.1.3.
To build the documents into html configure libc++ with the following cmake options:
* -DLLVM_ENABLE_SPHINX=ON
* -DLIBCXX_INCLUDE_DOCS=ON
After configuring libc++ with these options the make rule `docs-libcxx-html`
should be available.

142
docs/TestingLibcxx.rst Normal file
View File

@ -0,0 +1,142 @@
==============
Testing libc++
==============
.. contents::
:local:
Getting Started
===============
libc++ uses LIT to configure and run its tests. The primary way to run the
libc++ tests is by using make check-libcxx. However since libc++ can be used
in any number of possible configurations it is important to customize the way
LIT builds and runs the tests. This guide provides information on how to use
LIT directly to test libc++.
Please see the `Lit Command Guide`_ for more information about LIT.
.. _LIT Command Guide: http://llvm.org/docs/CommandGuide/lit.html
Setting up the Environment
--------------------------
After building libc++ you must setup your environment to test libc++ using
LIT.
#. Create a shortcut to the actual lit executable so that you can invoke it
easily from the command line.
.. code-block:: bash
$ alias lit='python path/to/llvm/utils/lit/lit.py'
#. Tell LIT where to find your build configuration.
.. code-block:: bash
$ export LIBCXX_SITE_CONFIG=path/to/build-libcxx/test/lit.site.cfg
LIT Options
===========
:program:`lit` [*options*...] [*filenames*...]
Command Line Options
--------------------
To use these options you pass them on the LIT command line as --param NAME or
--param NAME=VALUE. Some options have default values specified during CMake's
configuration. Passing the option on the command line will override the default.
.. program:: lit
.. option:: libcxx_site_config=<path/to/lit.site.cfg>
Specify the site configuration to use when running the tests. This option
overrides the enviroment variable LIBCXX_SITE_CONFIG.
.. option:: libcxx_headers=<path/to/headers>
Specify the libc++ headers that are tested. By default the headers in the
source tree are used.
.. option:: libcxx_library=<path/to/libc++.so>
Specify the libc++ library that is tested. By default the library in the
build directory is used. This option cannot be used when use_system_lib is
provided.
.. option:: use_system_lib=<bool>
**Default**: False
Enable or disable testing against the installed version of libc++ library.
Note: This does not use the installed headers.
.. option:: use_lit_shell=<bool>
Enable or disable the use of LIT's internal shell in ShTests. If the
environment variable LIT_USE_INTERNAL_SHELL is present then that is used as
the default value. Otherwise the default value is True on Windows and False
on every other platform.
.. option:: no_default_flags=<bool>
**Default**: False
Disable all default compile and link flags from being added. When this
option is used only flags specified using the compile_flags and link_flags
will be used.
.. option:: compile_flags="<list-of-args>"
Specify additional compile flags as a space delimited string.
Note: This options should not be used to change the standard version used.
.. option:: link_flags="<list-of-args>"
Specify additional link flags as a space delimited string.
.. option:: std=<standard version>
**Values**: c++98, c++03, c++11, c++14, c++1z
Change the standard version used when building the tests.
.. option:: debug_level=<level>
**Values**: 0, 1
Enable the use of debug mode. Level 0 enables assertions and level 1 enables
assertions and debugging of iterator misuse.
.. option:: use_sanitizer=<sanitizer name>
**Values**: Memory, MemoryWithOrigins, Address, Undefined
Run the tests using the given sanitizer. If LLVM_USE_SANITIZER was given when
building libc++ then that sanitizer will be used by default.
.. option:: color_diagnostics
Enable the use of colorized compile diagnostics. If the color_diagnostics
option is specified or the environment variable LIBCXX_COLOR_DIAGNOSTICS is
present then color diagnostics will be enabled.
Environment Variables
---------------------
.. envvar:: LIBCXX_SITE_CONFIG=<path/to/lit.site.cfg>
Specify the site configuration to use when running the tests.
Also see :option:`libcxx_site_config`.
.. envvar:: LIBCXX_COLOR_DIAGNOSTICS
If ``LIBCXX_COLOR_DIAGNOSTICS`` is defined then the test suite will attempt
to use color diagnostic outputs from the compiler.
Also see :option:`color_diagnostics`.

89
docs/UsingLibcxx.rst Normal file
View File

@ -0,0 +1,89 @@
============
Using libc++
============
.. contents::
:local:
Getting Started
===============
If you already have libc++ installed you can use it with clang.
.. code-block:: bash
$ clang++ -stdlib=libc++ test.cpp
$ clang++ -std=c++11 -stdlib=libc++ test.cpp
On OS X and FreeBSD libc++ is the default standard library
and the ``-stdlib=libc++`` is not required.
.. _alternate libcxx:
If you want to select an alternate installation of libc++ you
can use the following options.
.. code-block:: bash
$ clang++ -std=c++11 -stdlib=libc++ -nostdinc++ \
-I<libcxx-install-prefix>/include/c++/v1 \
-L<libcxx-install-prefix>/lib \
-Wl,-rpath,<libcxx-install-prefix>/lib \
test.cpp
The option ``-Wl,-rpath,<libcxx-install-prefix>/lib`` adds a runtime library
search path. Meaning that the systems dynamic linker will look for libc++ in
``<libcxx-install-prefix>/lib`` whenever the program is run. Alternatively the
environment variable ``LD_LIBRARY_PATH`` (``DYLD_LIBRARY_PATH`` on OS X) can
be used to change the dynamic linkers search paths after a program is compiled.
An example of using ``LD_LIBRARY_PATH``:
.. code-block:: bash
$ clang++ -stdlib=libc++ -nostdinc++ \
-I<libcxx-install-prefix>/include/c++/v1
-L<libcxx-install-prefix>/lib \
test.cpp -o
$ ./a.out # Searches for libc++ in the systems library paths.
$ export LD_LIBRARY_PATH=<libcxx-install-prefix>/lib
$ ./a.out # Searches for libc++ along LD_LIBRARY_PATH
Using libc++ on Linux
=====================
On Linux libc++ typically links to a shared version of libc++abi. Unfortunately
you can't simply run clang with "-stdlib=libc++" as clang is not set up to
link for this configuration. To get around this you'll have to manually
link libc++abi yourself. For example:
.. code-block:: bash
$ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
Alternately, you could just add libc++abi to your libraries list, which in
most situations will give the same result:
.. code-block:: bash
$ clang++ -stdlib=libc++ test.cpp -lc++abi
Using libc++ with GCC
---------------------
GCC does not provide a way to switch from libstdc++ to libc++. You must manually
configure the compile and link commands.
In particular you must tell GCC to remove the libstdc++ include directories
using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``.
Note that ``-nodefaultlibs`` removes all of the standard system libraries and
not just libstdc++ so they must be manually linked. For example:
.. code-block:: bash
$ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 \
test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc

251
docs/conf.py Normal file
View File

@ -0,0 +1,251 @@
# -*- coding: utf-8 -*-
#
# libc++ documentation build configuration file.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'libc++'
copyright = u'2011-2015, LLVM Project'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '3.8'
# The full version, including alpha/beta/rc tags.
release = '3.8'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
today_fmt = '%Y-%m-%d'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
show_authors = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'friendly'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'haiku'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'libcxxdoc'
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('contents', 'libcxx.tex', u'libcxx Documentation',
u'LLVM project', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('contents', 'libc++', u'libc++ Documentation',
[u'LLVM project'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('contents', 'libc++', u'libc++ Documentation',
u'LLVM project', 'libc++', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# FIXME: Define intersphinx configration.
intersphinx_mapping = {}
# -- Options for extensions ----------------------------------------------------
# Enable this if you want TODOs to show up in the generated documentation.
todo_include_todos = True

171
docs/index.rst Normal file
View File

@ -0,0 +1,171 @@
.. _index:
=============================
"libc++" C++ Standard Library
=============================
Overview
========
libc++ is a new implementation of the C++ standard library, targeting C++11.
* Features and Goals
* Correctness as defined by the C++11 standard.
* Fast execution.
* Minimal memory use.
* Fast compile times.
* ABI compatibility with gcc's libstdc++ for some low-level features
such as exception objects, rtti and memory allocation.
* Extensive unit tests.
* Design and Implementation:
* Extensive unit tests
* Internal linker model can be dumped/read to textual format
* Additional linking features can be plugged in as "passes"
* OS specific and CPU specific code factored out
Getting Started with libc++
---------------------------
.. toctree::
:maxdepth: 2
UsingLibcxx
BuildingLibcxx
TestingLibcxx
Current Status
--------------
After its initial introduction, many people have asked "why start a new
library instead of contributing to an existing library?" (like Apache's
libstdcxx, GNU's libstdc++, STLport, etc). There are many contributing
reasons, but some of the major ones are:
From years of experience (including having implemented the standard
library before), we've learned many things about implementing
the standard containers which require ABI breakage and fundamental changes
to how they are implemented. For example, it is generally accepted that
building std::string using the "short string optimization" instead of
using Copy On Write (COW) is a superior approach for multicore
machines (particularly in C++11, which has rvalue references). Breaking
ABI compatibility with old versions of the library was
determined to be critical to achieving the performance goals of
libc++.
Mainline libstdc++ has switched to GPL3, a license which the developers
of libc++ cannot use. libstdc++ 4.2 (the last GPL2 version) could be
independently extended to support C++11, but this would be a fork of the
codebase (which is often seen as worse for a project than starting a new
independent one). Another problem with libstdc++ is that it is tightly
integrated with G++ development, tending to be tied fairly closely to the
matching version of G++.
STLport and the Apache libstdcxx library are two other popular
candidates, but both lack C++11 support. Our experience (and the
experience of libstdc++ developers) is that adding support for C++11 (in
particular rvalue references and move-only types) requires changes to
almost every class and function, essentially amounting to a rewrite.
Faced with a rewrite, we decided to start from scratch and evaluate every
design decision from first principles based on experience.
Further, both projects are apparently abandoned: STLport 5.2.1 was
released in Oct'08, and STDCXX 4.2.1 in May'08.
Platform and Compiler Support
-----------------------------
libc++ is known to work on the following platforms, using gcc-4.2 and
clang (lack of C++11 language support disables some functionality).
Note that functionality provided by ``<atomic>`` is only functional with clang
and GCC.
============ ==================== ============ ========================
OS Arch Compilers ABI Library
============ ==================== ============ ========================
Mac OS X i386, x86_64 Clang, GCC libc++abi
FreeBSD 10+ i386, x86_64, ARM Clang, GCC libcxxrt, libc++abi
Linux i386, x86_64 Clang, GCC libc++abi
============ ==================== ============ ========================
The following minimum compiler versions are strongly recommended.
* Clang 3.5 and above
* GCC 4.7 and above.
Anything older *may* work.
C++ Dialect Support
---------------------
* C++11 - Complete
* `C++14 - Complete <cxx14 status_>`__
* `C++1z - In Progress <cxx1z status_>`__
* `Post C++14 Technical Specifications - In Progress <ts status_>`__
.. _cxx14 status: http://libcxx.llvm.org/cxx1y_status.html
.. _cxx1z status: http://libcxx.llvm.org/cxx1z_status.html
.. _ts status: http://libcxx.llvm.org/ts1z_status.html
Notes and Known Issues
----------------------
This list contains known issues with libc++
* Building libc++ with ``-fno-rtti`` is not supported. However
linking against it with ``-fno-rtti`` is supported.
* On OS X v10.8 and older the CMake option ``-DLIBCXX_LIBCPPABI_VERSION=""``
must be used during configuration.
A full list of currently open libc++ bugs can be `found here <libcxx bug list_>`__.
.. _libcxx bug list: https://llvm.org/bugs/buglist.cgi?component=All%20Bugs&product=libc%2B%2B&query_format=advanced&resolution=---&order=changeddate%20DESC%2Cassigned_to%20DESC%2Cbug_status%2Cpriority%2Cbug_id&list_id=74184
Design Documents
----------------
* `<atomic> design <http://libcxx.llvm.org/atomic_design.html>`_
* `<type_traits> design <http://libcxx.llvm.org/type_traits_design.html>`_
* `Status of debug mode <http://libcxx.llvm.org/debug_mode.html>`_
* `Notes by Marshall Clow <clow notes_>`__
.. _clow notes: https://cplusplusmusings.wordpress.com/2012/07/05/clang-and-standard-libraries-on-mac-os-x/
Getting Involved
================
First please review our `Developer's Policy <http://llvm.org/docs/DeveloperPolicy.html>`__.
**Bug Reports**
If you think you've found a bug in libc++, please report it using
the _`LLVM Bugzilla`. If you're not sure, you
can post a message to the `cfe-dev`_. mailing list or on IRC.
Please include "libc++" in your subject.
**Patches**
If you want to contribute a patch to libc++, the best place for that is
`Phabricator <phab doc_>`__. Please include [libcxx] in the subject and
add `cfe-commits` as a subscriber.
**Discussion and Questions**
Send discussions and questions to the `clang mailing list <cfe-dev_>`__.
Please include [libcxx] in the subject.
.. _phab doc: http://llvm.org/docs/Phabricator.html
.. _cfe-dev: http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
Links
=====
* `Getting started with LLVM <http://llvm.org/docs/GettingStarted.html>`_
* `libc++abi Homepage <libc++abi_>`__
.. _`libc++abi`: http://libcxxabi.llvm.org/