diff --git a/libcxx/CMakeLists.txt b/libcxx/CMakeLists.txt index be6fbbe61fbd..6816c350c9bd 100644 --- a/libcxx/CMakeLists.txt +++ b/libcxx/CMakeLists.txt @@ -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_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 "Define suffix of library directory name (32/64)") option(LIBCXX_INSTALL_HEADERS "Install the libc++ headers." ON) @@ -288,6 +289,10 @@ endif() include_directories(include) add_subdirectory(include) add_subdirectory(lib) + if (LIBCXX_INCLUDE_TESTS) add_subdirectory(test) endif() +if (LIBCXX_INCLUDE_DOCS) + add_subdirectory(docs) +endif() diff --git a/libcxx/cmake/Modules/HandleOutOfTreeLLVM.cmake b/libcxx/cmake/Modules/HandleOutOfTreeLLVM.cmake index 53adb0638c71..3bf5d601b0d5 100644 --- a/libcxx/cmake/Modules/HandleOutOfTreeLLVM.cmake +++ b/libcxx/cmake/Modules/HandleOutOfTreeLLVM.cmake @@ -77,6 +77,9 @@ if (CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR) if (NOT DEFINED LLVM_INCLUDE_TESTS) set(LLVM_INCLUDE_TESTS ${LLVM_FOUND}) endif() + if (NOT DEFINED LLVM_ENABLE_SPHINX) + set(LLVM_ENABLE_SPHINX OFF) + endif() # Required LIT Configuration ------------------------------------------------ # 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) 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 -------------------------------------------------------- include(AddLLVM OPTIONAL) endif() diff --git a/libcxx/cmake/config-ix.cmake b/libcxx/cmake/config-ix.cmake index ace7aca4b183..3b747b2e4116 100644 --- a/libcxx/cmake/config-ix.cmake +++ b/libcxx/cmake/config-ix.cmake @@ -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(rt clock_gettime "" LIBCXX_HAS_RT_LIB) check_library_exists(gcc_s __gcc_personality_v0 "" LIBCXX_HAS_GCC_S_LIB) - diff --git a/libcxx/docs/BuildingLibcxx.rst b/libcxx/docs/BuildingLibcxx.rst new file mode 100644 index 000000000000..aa3a385cbde8 --- /dev/null +++ b/libcxx/docs/BuildingLibcxx.rst @@ -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 `_ 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 [options] `` + + 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 ` + +#. **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++ ` 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++/`` and ``/usr/include/c++//`` + +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 <...> 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 \ + + + +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++. diff --git a/libcxx/docs/CMakeLists.txt b/libcxx/docs/CMakeLists.txt new file mode 100644 index 000000000000..f63ee00a5a02 --- /dev/null +++ b/libcxx/docs/CMakeLists.txt @@ -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() \ No newline at end of file diff --git a/libcxx/docs/README.txt b/libcxx/docs/README.txt new file mode 100644 index 000000000000..06d94f5b5fc4 --- /dev/null +++ b/libcxx/docs/README.txt @@ -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. diff --git a/libcxx/docs/TestingLibcxx.rst b/libcxx/docs/TestingLibcxx.rst new file mode 100644 index 000000000000..906b943d1a48 --- /dev/null +++ b/libcxx/docs/TestingLibcxx.rst @@ -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= + + Specify the site configuration to use when running the tests. This option + overrides the enviroment variable LIBCXX_SITE_CONFIG. + +.. option:: libcxx_headers= + + Specify the libc++ headers that are tested. By default the headers in the + source tree are used. + +.. option:: libcxx_library= + + 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= + + **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= + + 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= + + **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="" + + 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="" + + Specify additional link flags as a space delimited string. + +.. option:: std= + + **Values**: c++98, c++03, c++11, c++14, c++1z + + Change the standard version used when building the tests. + +.. option:: debug_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= + + **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= + + 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`. diff --git a/libcxx/docs/UsingLibcxx.rst b/libcxx/docs/UsingLibcxx.rst new file mode 100644 index 000000000000..8de58d8659ed --- /dev/null +++ b/libcxx/docs/UsingLibcxx.rst @@ -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/include/c++/v1 \ + -L/lib \ + -Wl,-rpath,/lib \ + test.cpp + +The option ``-Wl,-rpath,/lib`` adds a runtime library +search path. Meaning that the systems dynamic linker will look for libc++ in +``/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/include/c++/v1 + -L/lib \ + test.cpp -o + $ ./a.out # Searches for libc++ in the systems library paths. + $ export LD_LIBRARY_PATH=/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/include/c++/v1 \ + test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc diff --git a/libcxx/docs/conf.py b/libcxx/docs/conf.py new file mode 100644 index 000000000000..915daa47a514 --- /dev/null +++ b/libcxx/docs/conf.py @@ -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 +# " v 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 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 diff --git a/libcxx/docs/index.rst b/libcxx/docs/index.rst new file mode 100644 index 000000000000..baca123609ce --- /dev/null +++ b/libcxx/docs/index.rst @@ -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 ```` 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 `__ +* `C++1z - In Progress `__ +* `Post C++14 Technical Specifications - In Progress `__ + +.. _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: 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 +---------------- + +* ` design `_ +* ` design `_ +* `Status of debug mode `_ +* `Notes by Marshall Clow `__ + +.. _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 `__. + +**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 `__. 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 `__. +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 `_ +* `libc++abi Homepage `__ + +.. _`libc++abi`: http://libcxxabi.llvm.org/