maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity
llvm-project/libcxx/docs/BuildingLibcxx.rst

440 lines
12 KiB
ReStructuredText
Raw Normal View History

Update libcxx.llvm.org documentation by linking to new docs. Summary: Currently much of the libcxx website is duplicated between the old www/ documentation and newer Sphinx docs. This patch changes the main libc++ webpage so that it links to the new documentation where possible. This means removing numerous sections from the landing page. @mclow.lists What do you think? Reviewers: mclow.lists Subscribers: cfe-commits, mclow.lists Differential Revision: http://reviews.llvm.org/D19250 llvm-svn: 271469
2016-06-02 10:16:28 +08:00
.. _BuildingLibcxx:
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
===============
Building libc++
===============
.. contents::
:local:
Add documentation for new experimental library llvm-svn: 268456
2016-05-04 06:32:08 +08:00
.. _build instructions:
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
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``
Update paths in libc++ build instructions. Patch from Jonathan Anderson. llvm-svn: 255561
2015-12-15 06:26:28 +08:00
* ``cd llvm/projects``
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
* ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx``
#. Checkout libc++abi:
* ``cd where-you-want-llvm-to-live``
* ``cd llvm/projects``
Update paths in libc++ build instructions. Patch from Jonathan Anderson. llvm-svn: 255561
2015-12-15 06:26:28 +08:00
* ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi``
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
#. Configure and build libc++ with libc++abi:
[docs] Remove references to autoconf build. llvm-svn: 259281
2016-01-30 09:11:42 +08:00
CMake is the only supported configuration system.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
Clang is the preferred compiler when building and using libc++.
* ``cd where you want to build llvm``
* ``mkdir build``
* ``cd build``
* ``cmake -G <generator> [options] <path to llvm sources>``
For more information about configuring libc++ see :ref:`CMake Options`.
* ``make cxx`` --- will build libc++ and libc++abi.
[Docs] Update libc++ target names after r279675. llvm-svn: 279940
2016-08-29 02:33:08 +08:00
* ``make check-cxx check-cxxabi`` --- will run the test suites.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
Shared libraries for libc++ and libc++ abi should now be present in llvm/build/lib.
See :ref:`using an alternate libc++ installation <alternate libcxx>`
#. **Optional**: Install libc++ and libc++abi
If your system already provides a libc++ installation it is important to be
careful not to replace it. Remember Use the CMake option ``CMAKE_INSTALL_PREFIX`` to
select a safe place to install libc++.
[Docs] Update libc++ target names after r279675. llvm-svn: 279940
2016-08-29 02:33:08 +08:00
* ``make install-cxx install-cxxabi`` --- Will install the libraries and the headers
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
.. warning::
* Replacing your systems libc++ installation could render the system non-functional.
* Mac OS X will not boot without a valid copy of ``libc++.1.dylib`` in ``/usr/lib``.
The instructions are for building libc++ on
FreeBSD, Linux, or Mac using `libc++abi`_ as the C++ ABI library.
On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt.
Cleanup BuildingLibcxx.rst and remove TODO llvm-svn: 246952
2015-09-07 07:31:16 +08:00
It is sometimes beneficial to build outside of the LLVM tree. An out-of-tree
build would look like this:
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
.. 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
-----------------------
Add documentation for new experimental library llvm-svn: 268456
2016-05-04 06:32:08 +08:00
.. option:: LIBCXX_INSTALL_LIBRARY:BOOL
**Default**: ``ON``
Toggle the installation of the library portion of libc++.
.. option:: LIBCXX_INSTALL_HEADERS:BOOL
**Default**: ``ON``
Toggle the installation of the libc++ headers.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
.. option:: LIBCXX_ENABLE_ASSERTIONS:BOOL
**Default**: ``ON``
Build libc++ with assertions enabled.
.. option:: LIBCXX_BUILD_32_BITS:BOOL
**Default**: ``OFF``
Attempt to fix Sphinx build llvm-svn: 281697
2016-09-16 11:47:53 +08:00
Build libc++ as a 32 bit library. Also see `LLVM_BUILD_32_BITS`.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
.. option:: LIBCXX_ENABLE_SHARED:BOOL
**Default**: ``ON``
Attempt to fix Sphinx build llvm-svn: 281697
2016-09-16 11:47:53 +08:00
Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or
`LIBCXX_ENABLE_STATIC` has to be enabled.
Allow building both shared and static library This change allows building both shared and static version of libc++ in a single build, sharing object files between both versions. Differential Revision: https://reviews.llvm.org/D23232 llvm-svn: 278068
2016-08-09 06:57:25 +08:00
.. option:: LIBCXX_ENABLE_STATIC:BOOL
**Default**: ``ON``
Attempt to fix Sphinx build llvm-svn: 281697
2016-09-16 11:47:53 +08:00
Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or
`LIBCXX_ENABLE_STATIC` has to be enabled.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
.. option:: LIBCXX_LIBDIR_SUFFIX:STRING
Extra suffix to append to the directory where libraries are to be installed.
Attempt to fix Sphinx build llvm-svn: 281697
2016-09-16 11:47:53 +08:00
This option overrides `LLVM_LIBDIR_SUFFIX`.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
Add documentation for new experimental library llvm-svn: 268456
2016-05-04 06:32:08 +08:00
.. _libc++experimental options:
libc++experimental Specific Options
------------------------------------
.. option:: LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL
**Default**: ``ON``
Build and test libc++experimental.a.
.. option:: LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL
Enable installation of libc++experimental by default. When libc++experimental was originally created it was empty and therefore there was no reason to install it. Now that the library contains <experimental/memory_resource> and <experimental/filesystem> there is a good reason to install it. Specifically this patch enables the installation whenever LIBCXX_INSTALL_LIBRARY is true and LIBCPP_ENABLE_EXPERIMENTAL_LIBRARY is true. llvm-svn: 280773
2016-09-07 09:15:10 +08:00
**Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY AND LIBCXX_INSTALL_LIBRARY``
Add documentation for new experimental library llvm-svn: 268456
2016-05-04 06:32:08 +08:00
Install libc++experimental.a alongside libc++.
Add Filesystem TS -- Complete Add the completed std::experimental::filesystem implementation and tests. The implementation supports C++11 or newer. The TS is built as part of 'libc++experimental.a'. Users of the TS need to manually link this library. Building and testing the TS can be disabled using the CMake option '-DLIBCXX_ENABLE_FILESYSTEM=OFF'. Currently 'libc++experimental.a' is not installed by default. To turn on the installation of the library use '-DLIBCXX_INSTALL_EXPERIMENTAL_LIBRARY=ON'. llvm-svn: 273034
2016-06-18 03:46:40 +08:00
.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL
**Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY``
Build filesystem as part of libc++experimental.a. This allows filesystem
to be disabled without turning off the entire experimental library.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
.. _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.
[libcxx] Make libc++.so a linker script by default on most platforms. Summary: This patch turns on `LIBCXX_ENABLE_ABI_LINKER_SCRIPT` by default whenever `LLVM_HAVE_LINK_VERSION_SCRIPT` is ON. This turns out to be whenever: 1. WIN32 is not defined. 2 UNIX is defined. 3. APPLE is not defined. While `LLVM_HAVE_LINK_VERSION_SCRIPT` is meant to reflect exactly what we are asking I think it's close enough. After committing this patch Linux users will no longer have to use "-lc++abi" explicitly! Reviewers: mclow.lists, danalbert, compnerd, jroelofs Subscribers: emaste, rengolin, cbergstrom, cfe-commits Differential Revision: http://reviews.llvm.org/D13739 llvm-svn: 250469
2015-10-16 06:41:51 +08:00
.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL
**Default**: ``ON`` by default on UNIX platforms other than Apple unless
'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``.
This option generate and installs a linker script as ``libc++.so`` which
links the correct ABI library.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
.. 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.
[libcxx] Add support for benchmark tests using Google Benchmark. Summary: This patch does the following: 1. Checks in a copy of the Google Benchmark library into the libc++ repo under `utils/google-benchmark`. 2. Teaches libc++ how to build Google Benchmark against both (A) in-tree libc++ and (B) the platforms native STL. 3. Allows performance benchmarks to be built as part of the libc++ build. Building the benchmarks (and Google Benchmark) is off by default. It must be enabled using the CMake option `-DLIBCXX_INCLUDE_BENCHMARKS=ON`. When this option is enabled the tests under `libcxx/benchmarks` can be built using the `libcxx-benchmarks` target. On Linux platforms where libstdc++ is the default STL the CMake option `-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON` can be used to build each benchmark test against libstdc++ as well. This is useful for comparing performance between standard libraries. Support for benchmarks is currently very minimal. They must be manually run by the user and there is no mechanism for detecting performance regressions. Known Issues: * `-DLIBCXX_INCLUDE_BENCHMARKS=ON` is only supported for Clang, and not GCC, since the `-stdlib=libc++` option is needed to build Google Benchmark. Reviewers: danalbert, dberlin, chandlerc, mclow.lists, jroelofs Subscribers: chandlerc, dberlin, tberghammer, danalbert, srhines, hfinkel Differential Revision: https://reviews.llvm.org/D22240 llvm-svn: 276049
2016-07-20 07:07:03 +08:00
libc++ Feature Options
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
----------------------
.. 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.
[libcxx] Add support for benchmark tests using Google Benchmark. Summary: This patch does the following: 1. Checks in a copy of the Google Benchmark library into the libc++ repo under `utils/google-benchmark`. 2. Teaches libc++ how to build Google Benchmark against both (A) in-tree libc++ and (B) the platforms native STL. 3. Allows performance benchmarks to be built as part of the libc++ build. Building the benchmarks (and Google Benchmark) is off by default. It must be enabled using the CMake option `-DLIBCXX_INCLUDE_BENCHMARKS=ON`. When this option is enabled the tests under `libcxx/benchmarks` can be built using the `libcxx-benchmarks` target. On Linux platforms where libstdc++ is the default STL the CMake option `-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON` can be used to build each benchmark test against libstdc++ as well. This is useful for comparing performance between standard libraries. Support for benchmarks is currently very minimal. They must be manually run by the user and there is no mechanism for detecting performance regressions. Known Issues: * `-DLIBCXX_INCLUDE_BENCHMARKS=ON` is only supported for Clang, and not GCC, since the `-stdlib=libc++` option is needed to build Google Benchmark. Reviewers: danalbert, dberlin, chandlerc, mclow.lists, jroelofs Subscribers: chandlerc, dberlin, tberghammer, danalbert, srhines, hfinkel Differential Revision: https://reviews.llvm.org/D22240 llvm-svn: 276049
2016-07-20 07:07:03 +08:00
.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL
ABI versioning macros for libc++. C++ macros and CMake options that specify the default ABI version of the library, and can be overridden to pick up new ABI-changing features. llvm-svn: 250254
2015-10-14 07:48:28 +08:00
Turn On -DLIBCXX_ENABLE_BENCHMARKS by default. This patch enables the `cxx-benchmarks` target by default. Note that the target still has to be manually invoked since it isn't included in the default 'make' rule. This patch also gets the benchmarks building w/ GCC. The build previously required the '-stdlib=libc++' flag but upstream patches to Google Benchmark now allow the library to build w/ libc++ and GCC. These changes should make the benchmarks easier to build and test. llvm-svn: 279999
2016-08-30 03:50:49 +08:00
**Default**: ``ON``
[libcxx] Add support for benchmark tests using Google Benchmark. Summary: This patch does the following: 1. Checks in a copy of the Google Benchmark library into the libc++ repo under `utils/google-benchmark`. 2. Teaches libc++ how to build Google Benchmark against both (A) in-tree libc++ and (B) the platforms native STL. 3. Allows performance benchmarks to be built as part of the libc++ build. Building the benchmarks (and Google Benchmark) is off by default. It must be enabled using the CMake option `-DLIBCXX_INCLUDE_BENCHMARKS=ON`. When this option is enabled the tests under `libcxx/benchmarks` can be built using the `libcxx-benchmarks` target. On Linux platforms where libstdc++ is the default STL the CMake option `-DLIBCXX_BUILD_BENCHMARKS_NATIVE_STDLIB=ON` can be used to build each benchmark test against libstdc++ as well. This is useful for comparing performance between standard libraries. Support for benchmarks is currently very minimal. They must be manually run by the user and there is no mechanism for detecting performance regressions. Known Issues: * `-DLIBCXX_INCLUDE_BENCHMARKS=ON` is only supported for Clang, and not GCC, since the `-stdlib=libc++` option is needed to build Google Benchmark. Reviewers: danalbert, dberlin, chandlerc, mclow.lists, jroelofs Subscribers: chandlerc, dberlin, tberghammer, danalbert, srhines, hfinkel Differential Revision: https://reviews.llvm.org/D22240 llvm-svn: 276049
2016-07-20 07:07:03 +08:00
Build the libc++ benchmark tests and the Google Benchmark library needed
to support them.
.. option:: LIBCXX_BUILD_BENCHMARK_NATIVE_STDLIB:BOOL
**Default**:: ``OFF``
Build the libc++ benchmark tests and Google Benchmark library against the
native standard library on the platform. On linux this can be used to compare
libc++ to libstdc++ by building the benchmark tests against both standard
libraries.
libc++ ABI Feature Options
--------------------------
ABI versioning macros for libc++. C++ macros and CMake options that specify the default ABI version of the library, and can be overridden to pick up new ABI-changing features. llvm-svn: 250254
2015-10-14 07:48:28 +08:00
The following options allow building libc++ for a different ABI version.
.. option:: LIBCXX_ABI_VERSION:STRING
**Default**: ``1``
Defines the target ABI version of libc++.
.. option:: LIBCXX_ABI_UNSTABLE:BOOL
**Default**: ``OFF``
Build the "unstable" ABI version of libc++. Includes all ABI changing features
on top of the current stable version.
[libcxx] Add new Sphinx documentation Summary: This patch adds Sphinx based documentation to libc++. The goal is to make it easier to write documentation for libc++ since writing new documentation in HTML is cumbersome. This patch rewrites the main page for libc++ along with the instructions for using, building and testing libc++. The built documentation can be found and reviewed here: http://efcs.ca/libcxx-docs In order to build the sphinx documentation you need to specify the cmake options `-DLLVM_ENABLE_SPHINX=ON -DLIBCXX_INCLUDE_DOCS=ON`. This will add the makefile rule `docs-libcxx-html`. Reviewers: chandlerc, mclow.lists, danalbert, jroelofs Subscribers: silvas, cfe-commits Differential Revision: http://reviews.llvm.org/D12129 llvm-svn: 245788
2015-08-23 03:40:49 +08:00
.. _LLVM-specific variables:
LLVM-specific options
---------------------
.. option:: LLVM_LIBDIR_SUFFIX:STRING
Extra suffix to append to the directory where libraries are to be
installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
to install libraries to ``/usr/lib64``.
.. option:: LLVM_BUILD_32_BITS:BOOL
Build 32-bits executables and libraries on 64-bits systems. This option is
available only on some 64-bits unix systems. Defaults to OFF.
.. option:: LLVM_LIT_ARGS:STRING
Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
others.
Using Alternate ABI libraries
=============================
.. _libsupcxx:
Using libsupc++ on Linux
------------------------
You will need libstdc++ in order to provide libsupc++.
Figure out where the libsupc++ headers are on your system. On Ubuntu this
is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>``
You can also figure this out by running
.. code-block:: bash
$ echo | g++ -Wp,-v -x c++ - -fsyntax-only
ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu"
ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"
#include "..." search starts here:
#include &lt;...&gt; search starts here:
/usr/include/c++/4.7
/usr/include/c++/4.7/x86_64-linux-gnu
/usr/include/c++/4.7/backward
/usr/lib/gcc/x86_64-linux-gnu/4.7/include
/usr/local/include
/usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed
/usr/include/x86_64-linux-gnu
/usr/include
End of search list.
Note that the first two entries happen to be what we are looking for. This
may not be correct on other platforms.
We can now run CMake:
.. code-block:: bash
$ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \
-DLIBCXX_CXX_ABI=libstdc++ \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \
-DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \
<libc++-source-dir>
You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++``
above, which will cause the library to be linked to libsupc++ instead
of libstdc++, but this is only recommended if you know that you will
never need to link against libstdc++ in the same executable as libc++.
GCC ships libsupc++ separately but only as a static library. If a
program also needs to link against libstdc++, it will provide its
own copy of libsupc++ and this can lead to subtle problems.
.. code-block:: bash
$ make cxx
$ make install
You can now run clang with -stdlib=libc++.
Update libcxx.llvm.org documentation by linking to new docs. Summary: Currently much of the libcxx website is duplicated between the old www/ documentation and newer Sphinx docs. This patch changes the main libc++ webpage so that it links to the new documentation where possible. This means removing numerous sections from the landing page. @mclow.lists What do you think? Reviewers: mclow.lists Subscribers: cfe-commits, mclow.lists Differential Revision: http://reviews.llvm.org/D19250 llvm-svn: 271469
2016-06-02 10:16:28 +08:00
.. _libcxxrt_ref:
Using libcxxrt on Linux
------------------------
You will need to keep the source tree of `libcxxrt`_ available
on your build machine and your copy of the libcxxrt shared library must
be placed where your linker will find it.
We can now run CMake like:
.. code-block:: bash
$ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \
-DLIBCXX_CXX_ABI=libcxxrt \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr \
<libc++-source-directory>
$ make cxx
$ make install
Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as
clang is set up to link for libc++ linked to libsupc++. To get around this
you'll have to set up your linker yourself (or patch clang). For example,
.. code-block:: bash
$ clang++ -stdlib=libc++ helloworld.cpp \
-nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc
Alternately, you could just add libcxxrt to your libraries list, which in most
situations will give the same result:
.. code-block:: bash
$ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt
.. _`libcxxrt`: https://github.com/pathscale/libcxxrt/
Using a local ABI library installation
---------------------------------------
.. warning::
This is not recommended in almost all cases.
These instructions should only be used when you can't install your ABI library.
Normally you must link libc++ against a ABI shared library that the
linker can find. If you want to build and test libc++ against an ABI
library not in the linker's path you needq to set
``-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib`` when configuring CMake.
An example build using libc++abi would look like:
.. code-block:: bash
$ CC=clang CXX=clang++ cmake \
-DLIBCXX_CXX_ABI=libc++abi \
-DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" \
-DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" \
path/to/libcxx
$ make
When testing libc++ LIT will automatically link against the proper ABI
library.