UsingLibcxx.rst 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175
  1. ============
  2. Using libc++
  3. ============
  4. .. contents::
  5. :local:
  6. Getting Started
  7. ===============
  8. If you already have libc++ installed you can use it with clang.
  9. .. code-block:: bash
  10. $ clang++ -stdlib=libc++ test.cpp
  11. $ clang++ -std=c++11 -stdlib=libc++ test.cpp
  12. On OS X and FreeBSD libc++ is the default standard library
  13. and the ``-stdlib=libc++`` is not required.
  14. .. _alternate libcxx:
  15. If you want to select an alternate installation of libc++ you
  16. can use the following options.
  17. .. code-block:: bash
  18. $ clang++ -std=c++11 -stdlib=libc++ -nostdinc++ \
  19. -I<libcxx-install-prefix>/include/c++/v1 \
  20. -L<libcxx-install-prefix>/lib \
  21. -Wl,-rpath,<libcxx-install-prefix>/lib \
  22. test.cpp
  23. The option ``-Wl,-rpath,<libcxx-install-prefix>/lib`` adds a runtime library
  24. search path. Meaning that the systems dynamic linker will look for libc++ in
  25. ``<libcxx-install-prefix>/lib`` whenever the program is run. Alternatively the
  26. environment variable ``LD_LIBRARY_PATH`` (``DYLD_LIBRARY_PATH`` on OS X) can
  27. be used to change the dynamic linkers search paths after a program is compiled.
  28. An example of using ``LD_LIBRARY_PATH``:
  29. .. code-block:: bash
  30. $ clang++ -stdlib=libc++ -nostdinc++ \
  31. -I<libcxx-install-prefix>/include/c++/v1
  32. -L<libcxx-install-prefix>/lib \
  33. test.cpp -o
  34. $ ./a.out # Searches for libc++ in the systems library paths.
  35. $ export LD_LIBRARY_PATH=<libcxx-install-prefix>/lib
  36. $ ./a.out # Searches for libc++ along LD_LIBRARY_PATH
  37. Using libc++experimental and ``<experimental/...>``
  38. =====================================================
  39. Libc++ provides implementations of experimental technical specifications
  40. in a separate library, ``libc++experimental.a``. Users of ``<experimental/...>``
  41. headers may be required to link ``-lc++experimental``.
  42. .. code-block:: bash
  43. $ clang++ -std=c++14 -stdlib=libc++ test.cpp -lc++experimental
  44. Libc++experimental.a may not always be available, even when libc++ is already
  45. installed. For information on building libc++experimental from source see
  46. :ref:`Building Libc++ <build instructions>` and
  47. :ref:`libc++experimental CMake Options <libc++experimental options>`.
  48. Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__
  49. page.
  50. .. warning::
  51. Experimental libraries are Experimental.
  52. * The contents of the ``<experimental/...>`` headers and ``libc++experimental.a``
  53. library will not remain compatible between versions.
  54. * No guarantees of API or ABI stability are provided.
  55. Using libc++ on Linux
  56. =====================
  57. On Linux libc++ can typically be used with only '-stdlib=libc++'. However
  58. some libc++ installations require the user manually link libc++abi themselves.
  59. If you are running into linker errors when using libc++ try adding '-lc++abi'
  60. to the link line. For example:
  61. .. code-block:: bash
  62. $ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
  63. Alternately, you could just add libc++abi to your libraries list, which in
  64. most situations will give the same result:
  65. .. code-block:: bash
  66. $ clang++ -stdlib=libc++ test.cpp -lc++abi
  67. Using libc++ with GCC
  68. ---------------------
  69. GCC does not provide a way to switch from libstdc++ to libc++. You must manually
  70. configure the compile and link commands.
  71. In particular you must tell GCC to remove the libstdc++ include directories
  72. using ``-nostdinc++`` and to not link libstdc++.so using ``-nodefaultlibs``.
  73. Note that ``-nodefaultlibs`` removes all of the standard system libraries and
  74. not just libstdc++ so they must be manually linked. For example:
  75. .. code-block:: bash
  76. $ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 \
  77. test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc
  78. GDB Pretty printers for libc++
  79. ------------------------------
  80. GDB does not support pretty-printing of libc++ symbols by default. Unfortunately
  81. libc++ does not provide pretty-printers itself. However there are 3rd
  82. party implementations available and although they are not officially
  83. supported by libc++ they may be useful to users.
  84. Known 3rd Party Implementations Include:
  85. * `Koutheir's libc++ pretty-printers <https://github.com/koutheir/libcxx-pretty-printers>`_.
  86. Libc++ Configuration Macros
  87. ===========================
  88. Libc++ provides a number of configuration macros which can be used to enable
  89. or disable extended libc++ behavior, including enabling "debug mode" or
  90. thread safety annotations.
  91. **_LIBCPP_DEBUG**:
  92. See :ref:`using-debug-mode` for more information.
  93. **_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**:
  94. This macro is used to enable -Wthread-safety annotations on libc++'s
  95. ``std::mutex`` and ``std::lock_guard``. By default these annotations are
  96. disabled and must be manually enabled by the user.
  97. **_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**:
  98. This macro is used to disable all visibility annotations inside libc++.
  99. Defining this macro and then building libc++ with hidden visibility gives a
  100. build of libc++ which does not export any symbols, which can be useful when
  101. building statically for inclusion into another library.
  102. **_LIBCPP_ENABLE_TUPLE_IMPLICIT_REDUCED_ARITY_EXTENSION**:
  103. This macro is used to re-enable an extension in `std::tuple` which allowed
  104. it to be implicitly constructed from fewer initializers than contained
  105. elements. Elements without an initializer are default constructed. For example:
  106. .. code-block:: cpp
  107. std::tuple<std::string, int, std::error_code> foo() {
  108. return {"hello world", 42}; // default constructs error_code
  109. }
  110. Since libc++ 4.0 this extension has been disabled by default. This macro
  111. may be defined to re-enable it in order to support existing code that depends
  112. on the extension. New use of this extension should be discouraged.
  113. See `PR 27374 <http://llvm.org/PR27374>`_ for more information.
  114. Note: The "reduced-arity-initialization" extension is still offered but only
  115. for explicit conversions. Example:
  116. .. code-block:: cpp
  117. auto foo() {
  118. using Tup = std::tuple<std::string, int, std::error_code>;
  119. return Tup{"hello world", 42}; // explicit constructor called. OK.
  120. }