142 changes: 142 additions & 0 deletions libcxx/docs/TestingLibcxx.rst
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 89 additions & 0 deletions libcxx/docs/UsingLibcxx.rst
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 251 additions & 0 deletions libcxx/docs/conf.py
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 171 additions & 0 deletions libcxx/docs/index.rst
View file
Original file line number Diff line number Diff line change
@@ -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/