# "libc++abi" C++ Standard Library Support

libc++abi is a new implementation of low level support for a standard C++ library.

All of the code in libc++abi is dual licensed under the MIT license and the UIUC License (a BSD-like license).

## Features and Goals

- Correctness as defined by the C++11 standard.
- Provide a portable sublayer to ease the porting of libc++
- On Mac OS X, be ABI compatible with the existing low-level support.

## Platform Support

libc++abi is known to work on the following platforms, using clang.

- Darwin

## Current Status

libc++abi is complete. Here is a list of functionality.

## Get it and get involved!

To check out the code (including llvm and others), use:

- `git clone https://github.com/llvm/llvm-project.git`

To build:

- `cd llvm-project`
- `mkdir build && cd build`
- `cmake -DLLVM_ENABLE_PROJECTS=libcxxabi ../llvm # on linux you may need to specify -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++`
- `make`

To do a standalone build:

- Check out the source tree. This includes the other subprojects, but you'll only use the libcxxabi part.
- `cd llvm-project`
- `mkdir build-libcxxabi && cd build-libcxxabi`
- `cmake ../libcxxabi # on linux you may need -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++`
- `make`

By default CMake uses `llvm-config` to locate the required LLVM sources. If CMake cannot find `llvm-config` then you must configure CMake using either of the following options.

- `-DLLVM_CONFIG_PATH=path/to/llvm-config`
- `-DLLVM_PATH=path/to/llvm-source-root`

To run the tests:

- `make check-cxxabi`

Note: in a standalone build, the system's libc++ will be used for tests. If the system's libc++ was statically linked against libc++abi (or linked against a different ABI library), this may interfere with test results.

Send discussions to the (libcxx-dev mailing list).

## Frequently asked questions

Q: Why are the destructors for the standard exception classes defined in libc++abi? They're just empty, can't they be defined inline?

A: The destructors for them live in libc++abi because they are "key" functions. The Itanium ABI describes a "key" function as the first virtual declared. And wherever the key function is defined, that is where the `type_info` gets defined. And in libc++ types are the same type if and only if they have the same `type_info` (as in there must be only one type info per type in the entire application). And on OS X, libstdc++ and libc++ share these exception types. So to be able to throw in one dylib and catch in another (a `std::exception` for example), there must be only one `std::exception type_info` in the entire app. That typeinfo gets laid down beside `~exception()` in libc++abi (for both libstdc++ and libc++).

--Howard Hinnant