Index: CMakeLists.txt =================================================================== --- CMakeLists.txt +++ CMakeLists.txt @@ -52,6 +52,7 @@ 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 @@ 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() Index: cmake/Modules/HandleOutOfTreeLLVM.cmake =================================================================== --- cmake/Modules/HandleOutOfTreeLLVM.cmake +++ cmake/Modules/HandleOutOfTreeLLVM.cmake @@ -77,6 +77,9 @@ 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 @@ 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() Index: cmake/config-ix.cmake =================================================================== --- cmake/config-ix.cmake +++ cmake/config-ix.cmake @@ -17,4 +17,3 @@ 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) - Index: docs/BuildingLibcxx.rst =================================================================== --- /dev/null +++ docs/BuildingLibcxx.rst @@ -0,0 +1,279 @@ + +=============== +Building libc++ +=============== + +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. + + .. warning:: + 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++. Index: docs/CMakeLists.txt =================================================================== --- /dev/null +++ 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 Index: docs/README.txt =================================================================== --- /dev/null +++ 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. Index: docs/TestingLibcxx.rst =================================================================== --- /dev/null +++ docs/TestingLibcxx.rst @@ -0,0 +1,139 @@ +============== +Testing libc++ +============== + +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*...] + +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`. Index: docs/UsingLibcxx.rst =================================================================== --- /dev/null +++ docs/UsingLibcxx.rst @@ -0,0 +1,86 @@ +============ +Using libc++ +============ + +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 Index: docs/_static/llvm.css =================================================================== --- /dev/null +++ docs/_static/llvm.css @@ -0,0 +1,112 @@ +/* + * LLVM documentation style sheet + */ + +/* Common styles */ +.body { color: black; background: white; margin: 0 0 0 0 } + +/* No borders on image links */ +a:link img, a:visited img { border-style: none } + +address img { float: right; width: 88px; height: 31px; } +address { clear: right; } + +table { text-align: center; border: 2px solid black; + border-collapse: collapse; margin-top: 1em; margin-left: 1em; + margin-right: 1em; margin-bottom: 1em; } +tr, td { border: 2px solid gray; padding: 4pt 4pt 2pt 2pt; } +th { border: 2px solid gray; font-weight: bold; font-size: 105%; + background: url("lines.gif"); + font-family: "Georgia,Palatino,Times,Roman,SanSerif"; + text-align: center; vertical-align: middle; } +/* + * Documentation + */ +/* Common for title and header */ +.doc_title, .doc_section, .doc_subsection, h1, h2, h3 { + color: black; background: url("lines.gif"); + font-family: "Georgia,Palatino,Times,Roman,SanSerif"; font-weight: bold; + border-width: 1px; + border-style: solid none solid none; + text-align: center; + vertical-align: middle; + padding-left: 8pt; + padding-top: 1px; + padding-bottom: 2px +} + +h1, .doc_title, .title { text-align: left; font-size: 25pt } + +h2, .doc_section { text-align: center; font-size: 22pt; + margin: 20pt 0pt 5pt 0pt; } + +h3, .doc_subsection { width: 75%; + text-align: left; font-size: 12pt; + padding: 4pt 4pt 4pt 4pt; + margin: 1.5em 0.5em 0.5em 0.5em } + +h4, .doc_subsubsection { margin: 2.0em 0.5em 0.5em 0.5em; + font-weight: bold; font-style: oblique; + border-bottom: 1px solid #999999; font-size: 12pt; + width: 75%; } + +.doc_author { text-align: left; font-weight: bold; padding-left: 20pt } +.doc_text { text-align: left; padding-left: 20pt; padding-right: 10pt } + +.doc_footer { text-align: left; padding: 0 0 0 0 } + +.doc_hilite { color: blue; font-weight: bold; } + +.doc_table { text-align: center; width: 90%; + padding: 1px 1px 1px 1px; border: 1px; } + +.doc_warning { color: red; font-weight: bold } + +/*
would use this class, and
adds more padding */ +.doc_code, .literal-block + { border: solid 1px gray; background: #eeeeee; + margin: 0 1em 0 1em; + padding: 0 1em 0 1em; + display: table; + } + +blockquote pre { + padding: 1em 2em 1em 1em; + border: solid 1px gray; + background: #eeeeee; + margin: 0 1em 0 1em; + display: table; +} + +h2+div, h2+p {text-align: left; padding-left: 20pt; padding-right: 10pt;} +h3+div, h3+p {text-align: left; padding-left: 20pt; padding-right: 10pt;} +h4+div, h4+p {text-align: left; padding-left: 20pt; padding-right: 10pt;} + +/* It is preferrable to use
 everywhere instead of the
+ * 
...
construct. + * + * Once all docs use
 for code regions, this style can  be merged with the
+ * one above, and we can drop the [pre] qualifier.
+ */
+pre.doc_code, .literal-block { padding: 1em 2em 1em 1em }
+
+.doc_notes      { background: #fafafa; border: 1px solid #cecece;
+                  display: table; padding: 0 1em 0 .1em }
+
+table.layout    { text-align: left; border: none; border-collapse: collapse;
+                  padding: 4px 4px 4px 4px; }
+tr.layout, td.layout, td.left, td.right
+                { border: none; padding: 4pt 4pt 2pt 2pt; vertical-align: top; }
+td.left         { text-align: left }
+td.right        { text-align: right }
+th.layout       { border: none; font-weight: bold; font-size: 105%;
+                  text-align: center; vertical-align: middle; }
+
+/* Left align table cell */
+.td_left        { border: 2px solid gray; text-align: left; }
+
+/* ReST-specific */
+.title { margin-top: 0 }
+.topic-title{ display: none }
+div.contents ul { list-style-type: decimal }
+.toc-backref    { color: black; text-decoration: none; }
Index: docs/_templates/indexsidebar.html
===================================================================
--- /dev/null
+++ docs/_templates/indexsidebar.html
@@ -0,0 +1,12 @@
+

Bugs

+ +

libc++ bugs should be reported at the + LLVM Bugzilla.

+ +

Buildbots

+ +

libc++ buildbots can be found here

+ \ No newline at end of file Index: docs/_templates/layout.html =================================================================== --- /dev/null +++ docs/_templates/layout.html @@ -0,0 +1,12 @@ +{% extends "!layout.html" %} + +{% block extrahead %} + +{% endblock %} + +{% block rootrellink %} +
  • libc++ Home | 
  • +{% endblock %} Index: docs/_themes/llvm-theme/layout.html =================================================================== --- /dev/null +++ docs/_themes/llvm-theme/layout.html @@ -0,0 +1,23 @@ +{# + sphinxdoc/layout.html + ~~~~~~~~~~~~~~~~~~~~~ + + Sphinx layout template for the sphinxdoc theme. + + :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{% extends "basic/layout.html" %} + +{% block relbar1 %} + +{{ super() }} +{% endblock %} + +{# put the sidebar before the body #} +{% block sidebar1 %}{{ sidebar() }}{% endblock %} +{% block sidebar2 %}{% endblock %} Index: docs/_themes/llvm-theme/static/llvm-theme.css =================================================================== --- /dev/null +++ docs/_themes/llvm-theme/static/llvm-theme.css @@ -0,0 +1,371 @@ +/* + * sphinxdoc.css_t + * ~~~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- sphinxdoc theme. Originally created by + * Armin Ronacher for Werkzeug. + * + * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', + 'Verdana', sans-serif; + font-size: 14px; + line-height: 150%; + text-align: center; + background-color: #BFD1D4; + color: black; + padding: 0; + border: 1px solid #aaa; + + margin: 0px 80px 0px 80px; + min-width: 740px; +} + +div.logo { + background-color: white; + text-align: left; + padding: 10px 10px 15px 15px; +} + +div.document { + background-color: white; + text-align: left; + background-image: url(contents.png); + background-repeat: repeat-x; +} + +div.bodywrapper { + margin: 0 240px 0 0; + border-right: 1px solid #ccc; +} + +div.body { + margin: 0; + padding: 0.5em 20px 20px 20px; +} + +div.related { + font-size: 1em; +} + +div.related ul { + background-image: url(navigation.png); + height: 2em; + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; +} + +div.related ul li { + margin: 0; + padding: 0; + height: 2em; + float: left; +} + +div.related ul li.right { + float: right; + margin-right: 5px; +} + +div.related ul li a { + margin: 0; + padding: 0 5px 0 5px; + line-height: 1.75em; + color: #EE9816; +} + +div.related ul li a:hover { + color: #3CA8E7; +} + +div.sphinxsidebarwrapper { + padding: 0; +} + +div.sphinxsidebar { + margin: 0; + padding: 0.5em 15px 15px 0; + width: 210px; + float: right; + font-size: 1em; + text-align: left; +} + +div.sphinxsidebar h3, div.sphinxsidebar h4 { + margin: 1em 0 0.5em 0; + font-size: 1em; + padding: 0.1em 0 0.1em 0.5em; + color: white; + border: 1px solid #86989B; + background-color: #AFC1C4; +} + +div.sphinxsidebar h3 a { + color: white; +} + +div.sphinxsidebar ul { + padding-left: 1.5em; + margin-top: 7px; + padding: 0; + line-height: 130%; +} + +div.sphinxsidebar ul ul { + margin-left: 20px; +} + +div.footer { + background-color: #E3EFF1; + color: #86989B; + padding: 3px 8px 3px 0; + clear: both; + font-size: 0.8em; + text-align: right; +} + +div.footer a { + color: #86989B; + text-decoration: underline; +} + +/* -- body styles ----------------------------------------------------------- */ + +p { + margin: 0.8em 0 0.5em 0; +} + +a { + color: #CA7900; + text-decoration: none; +} + +a:hover { + color: #2491CF; +} + +div.body p a{ + text-decoration: underline; +} + +h1 { + margin: 0; + padding: 0.7em 0 0.3em 0; + font-size: 1.5em; + color: #11557C; +} + +h2 { + margin: 1.3em 0 0.2em 0; + font-size: 1.35em; + padding: 0; +} + +h3 { + margin: 1em 0 -0.3em 0; + font-size: 1.2em; +} + +h3 a:hover { + text-decoration: underline; +} + +div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { + color: black!important; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { + display: none; + margin: 0 0 0 0.3em; + padding: 0 0.2em 0 0.2em; + color: #aaa!important; +} + +h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, +h5:hover a.anchor, h6:hover a.anchor { + display: inline; +} + +h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, +h5 a.anchor:hover, h6 a.anchor:hover { + color: #777; + background-color: #eee; +} + +a.headerlink { + color: #c60f0f!important; + font-size: 1em; + margin-left: 6px; + padding: 0 4px 0 4px; + text-decoration: none!important; +} + +a.headerlink:hover { + background-color: #ccc; + color: white!important; +} + +cite, code, tt { + font-family: 'Consolas', 'Deja Vu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; +} + +:not(a.reference) > tt { + background-color: #f2f2f2; + border-bottom: 1px solid #ddd; + color: #333; +} + +tt.descname, tt.descclassname, tt.xref { + border: 0; +} + +hr { + border: 1px solid #abc; + margin: 2em; +} + +p a tt { + border: 0; + color: #CA7900; +} + +p a tt:hover { + color: #2491CF; +} + +a tt { + border: none; +} + +pre { + font-family: 'Consolas', 'Deja Vu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + line-height: 120%; + padding: 0.5em; + border: 1px solid #ccc; + background-color: #f8f8f8; +} + +pre a { + color: inherit; + text-decoration: underline; +} + +td.linenos pre { + padding: 0.5em 0; +} + +div.quotebar { + background-color: #f8f8f8; + max-width: 250px; + float: right; + padding: 2px 7px; + border: 1px solid #ccc; +} + +div.topic { + background-color: #f8f8f8; +} + +table { + border-collapse: collapse; + margin: 0 -0.5em 0 -0.5em; +} + +table td, table th { + padding: 0.2em 0.5em 0.2em 0.5em; +} + +div.admonition, div.warning { + font-size: 0.9em; + margin: 1em 0 1em 0; + border: 1px solid #86989B; + background-color: #f7f7f7; + padding: 0; +} + +div.admonition p, div.warning p { + margin: 0.5em 1em 0.5em 1em; + padding: 0; +} + +div.admonition pre, div.warning pre { + margin: 0.4em 1em 0.4em 1em; +} + +div.admonition p.admonition-title, +div.warning p.admonition-title { + margin: 0; + padding: 0.1em 0 0.1em 0.5em; + color: white; + border-bottom: 1px solid #86989B; + font-weight: bold; + background-color: #AFC1C4; +} + +div.warning { + border: 1px solid #940000; +} + +div.warning p.admonition-title { + background-color: #CF0000; + border-bottom-color: #940000; +} + +div.admonition ul, div.admonition ol, +div.warning ul, div.warning ol { + margin: 0.1em 0.5em 0.5em 3em; + padding: 0; +} + +div.versioninfo { + margin: 1em 0 0 0; + border: 1px solid #ccc; + background-color: #DDEAF0; + padding: 8px; + line-height: 1.3em; + font-size: 0.9em; +} + +.viewcode-back { + font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', + 'Verdana', sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} Index: docs/_themes/llvm-theme/theme.conf =================================================================== --- /dev/null +++ docs/_themes/llvm-theme/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = basic +stylesheet = llvm-theme.css +pygments_style = friendly Index: docs/conf.py =================================================================== --- /dev/null +++ docs/conf.py @@ -0,0 +1,255 @@ +# -*- 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.7' +# The full version, including alpha/beta/rc tags. +release = '3.7' + +# 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 = 'llvm-theme' +#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 = {} +#html_theme_options = { "nosidebar": True } + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ["_themes"] + +# 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 + +# If given, this must be the name of an image file (path relative to the +# configuration directory) that is the favicon of the docs. Modern browsers use +# this as icon for tabs, windows and bookmarks. It should be a Windows-style +# icon file (.ico), which is 16x16 or 32x32 pixels large. Default: None. The +# image file will be copied to the _static directory of the output HTML, but +# only if the file does not already exist there. +html_favicon = '_static/favicon.ico' + +# 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 = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%Y-%m-%d' + +# 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 = {'index': 'indexsidebar.html'} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {'index': 'index.html'} + +# 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 Index: docs/index.rst =================================================================== --- /dev/null +++ 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/