1 2 =============== 3 Building libc++ 4 =============== 5 6 .. contents:: 7 :local: 8 9 .. _build instructions: 10 11 Getting Started 12 =============== 13 14 On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install 15 Xcode 4.2 or later. However if you want to install tip-of-trunk from here 16 (getting the bleeding edge), read on. 17 18 The basic steps needed to build libc++ are: 19 20 #. Checkout LLVM: 21 22 * ``cd where-you-want-llvm-to-live`` 23 * ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` 24 25 #. Checkout libc++: 26 27 * ``cd where-you-want-llvm-to-live`` 28 * ``cd llvm/projects`` 29 * ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx`` 30 31 #. Checkout libc++abi: 32 33 * ``cd where-you-want-llvm-to-live`` 34 * ``cd llvm/projects`` 35 * ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi`` 36 37 #. Configure and build libc++ with libc++abi: 38 39 CMake is the only supported configuration system. 40 41 Clang is the preferred compiler when building and using libc++. 42 43 * ``cd where you want to build llvm`` 44 * ``mkdir build`` 45 * ``cd build`` 46 * ``cmake -G <generator> [options] <path to llvm sources>`` 47 48 For more information about configuring libc++ see :ref:`CMake Options`. 49 50 * ``make cxx`` --- will build libc++ and libc++abi. 51 * ``make check-libcxx check-libcxxabi`` --- will run the test suites. 52 53 Shared libraries for libc++ and libc++ abi should now be present in llvm/build/lib. 54 See :ref:`using an alternate libc++ installation <alternate libcxx>` 55 56 #. **Optional**: Install libc++ and libc++abi 57 58 If your system already provides a libc++ installation it is important to be 59 careful not to replace it. Remember Use the CMake option ``CMAKE_INSTALL_PREFIX`` to 60 select a safe place to install libc++. 61 62 * ``make install-libcxx install-libcxxabi`` --- Will install the libraries and the headers 63 64 .. warning:: 65 * Replacing your systems libc++ installation could render the system non-functional. 66 * Mac OS X will not boot without a valid copy of ``libc++.1.dylib`` in ``/usr/lib``. 67 68 69 The instructions are for building libc++ on 70 FreeBSD, Linux, or Mac using `libc++abi`_ as the C++ ABI library. 71 On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt. 72 73 It is sometimes beneficial to build outside of the LLVM tree. An out-of-tree 74 build would look like this: 75 76 .. code-block:: bash 77 78 $ cd where-you-want-libcxx-to-live 79 $ # Check out llvm, libc++ and libc++abi. 80 $ ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` 81 $ ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx`` 82 $ ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi`` 83 $ cd where-you-want-to-build 84 $ mkdir build && cd build 85 $ export CC=clang CXX=clang++ 86 $ cmake -DLLVM_PATH=path/to/llvm \ 87 -DLIBCXX_CXX_ABI=libcxxabi \ 88 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxabi/include \ 89 path/to/libcxx 90 $ make 91 $ make check-libcxx # optional 92 93 94 .. _`libc++abi`: http://libcxxabi.llvm.org/ 95 96 97 .. _CMake Options: 98 99 CMake Options 100 ============= 101 102 Here are some of the CMake variables that are used often, along with a 103 brief explanation and LLVM-specific notes. For full documentation, check the 104 CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. 105 106 **CMAKE_BUILD_TYPE**:STRING 107 Sets the build type for ``make`` based generators. Possible values are 108 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio 109 the user sets the build type with the IDE settings. 110 111 **CMAKE_INSTALL_PREFIX**:PATH 112 Path where LLVM will be installed if "make install" is invoked or the 113 "INSTALL" target is built. 114 115 **CMAKE_CXX_COMPILER**:STRING 116 The C++ compiler to use when building and testing libc++. 117 118 119 .. _libcxx-specific options: 120 121 libc++ specific options 122 ----------------------- 123 124 .. option:: LIBCXX_INSTALL_LIBRARY:BOOL 125 126 **Default**: ``ON`` 127 128 Toggle the installation of the library portion of libc++. 129 130 .. option:: LIBCXX_INSTALL_HEADERS:BOOL 131 132 **Default**: ``ON`` 133 134 Toggle the installation of the libc++ headers. 135 136 .. option:: LIBCXX_ENABLE_ASSERTIONS:BOOL 137 138 **Default**: ``ON`` 139 140 Build libc++ with assertions enabled. 141 142 .. option:: LIBCXX_BUILD_32_BITS:BOOL 143 144 **Default**: ``OFF`` 145 146 Build libc++ as a 32 bit library. Also see :option:`LLVM_BUILD_32_BITS`. 147 148 .. option:: LIBCXX_ENABLE_SHARED:BOOL 149 150 **Default**: ``ON`` 151 152 Build libc++ as a shared library. If ``OFF`` is specified then libc++ is 153 built as a static library. 154 155 .. option:: LIBCXX_LIBDIR_SUFFIX:STRING 156 157 Extra suffix to append to the directory where libraries are to be installed. 158 This option overrides :option:`LLVM_LIBDIR_SUFFIX`. 159 160 161 .. _libc++experimental options: 162 163 libc++experimental Specific Options 164 ------------------------------------ 165 166 .. option:: LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL 167 168 **Default**: ``ON`` 169 170 Build and test libc++experimental.a. 171 172 .. option:: LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL 173 174 **Default**: ``OFF`` 175 176 Install libc++experimental.a alongside libc++. 177 178 179 .. _ABI Library Specific Options: 180 181 ABI Library Specific Options 182 ---------------------------- 183 184 .. option:: LIBCXX_CXX_ABI:STRING 185 186 **Values**: ``none``, ``libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``. 187 188 Select the ABI library to build libc++ against. 189 190 .. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS 191 192 Provide additional search paths for the ABI library headers. 193 194 .. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH 195 196 Provide the path to the ABI library that libc++ should link against. 197 198 .. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL 199 200 **Default**: ``OFF`` 201 202 If this option is enabled, libc++ will try and link the selected ABI library 203 statically. 204 205 .. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL 206 207 **Default**: ``ON`` by default on UNIX platforms other than Apple unless 208 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``. 209 210 This option generate and installs a linker script as ``libc++.so`` which 211 links the correct ABI library. 212 213 .. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL 214 215 **Default**: ``OFF`` 216 217 Build and use the LLVM unwinder. Note: This option can only be used when 218 libc++abi is the C++ ABI library used. 219 220 221 libc++ Feature options 222 ---------------------- 223 224 .. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL 225 226 **Default**: ``ON`` 227 228 Build libc++ with exception support. 229 230 .. option:: LIBCXX_ENABLE_RTTI:BOOL 231 232 **Default**: ``ON`` 233 234 Build libc++ with run time type information. 235 236 237 libc++ Feature options 238 ---------------------- 239 240 The following options allow building libc++ for a different ABI version. 241 242 .. option:: LIBCXX_ABI_VERSION:STRING 243 244 **Default**: ``1`` 245 246 Defines the target ABI version of libc++. 247 248 .. option:: LIBCXX_ABI_UNSTABLE:BOOL 249 250 **Default**: ``OFF`` 251 252 Build the "unstable" ABI version of libc++. Includes all ABI changing features 253 on top of the current stable version. 254 255 .. _LLVM-specific variables: 256 257 LLVM-specific options 258 --------------------- 259 260 .. option:: LLVM_LIBDIR_SUFFIX:STRING 261 262 Extra suffix to append to the directory where libraries are to be 263 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 264 to install libraries to ``/usr/lib64``. 265 266 .. option:: LLVM_BUILD_32_BITS:BOOL 267 268 Build 32-bits executables and libraries on 64-bits systems. This option is 269 available only on some 64-bits unix systems. Defaults to OFF. 270 271 .. option:: LLVM_LIT_ARGS:STRING 272 273 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 274 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 275 others. 276 277 278 Using Alternate ABI libraries 279 ============================= 280 281 282 .. _libsupcxx: 283 284 Using libsupc++ on Linux 285 ------------------------ 286 287 You will need libstdc++ in order to provide libsupc++. 288 289 Figure out where the libsupc++ headers are on your system. On Ubuntu this 290 is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` 291 292 You can also figure this out by running 293 294 .. code-block:: bash 295 296 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only 297 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" 298 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" 299 #include "..." search starts here: 300 #include <...> search starts here: 301 /usr/include/c++/4.7 302 /usr/include/c++/4.7/x86_64-linux-gnu 303 /usr/include/c++/4.7/backward 304 /usr/lib/gcc/x86_64-linux-gnu/4.7/include 305 /usr/local/include 306 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed 307 /usr/include/x86_64-linux-gnu 308 /usr/include 309 End of search list. 310 311 Note that the first two entries happen to be what we are looking for. This 312 may not be correct on other platforms. 313 314 We can now run CMake: 315 316 .. code-block:: bash 317 318 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 319 -DLIBCXX_CXX_ABI=libstdc++ \ 320 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \ 321 -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \ 322 <libc++-source-dir> 323 324 325 You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` 326 above, which will cause the library to be linked to libsupc++ instead 327 of libstdc++, but this is only recommended if you know that you will 328 never need to link against libstdc++ in the same executable as libc++. 329 GCC ships libsupc++ separately but only as a static library. If a 330 program also needs to link against libstdc++, it will provide its 331 own copy of libsupc++ and this can lead to subtle problems. 332 333 .. code-block:: bash 334 335 $ make cxx 336 $ make install 337 338 You can now run clang with -stdlib=libc++. 339
