libc++ 8.0 documentation

options

$ clang++ -stdlib=libc++ test.cpp
$ clang++ -std=c++11 -stdlib=libc++ test.cpp

$ 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

$ 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

$ clang++ -std=c++14 -stdlib=libc++ test.cpp -lc++experimental

$ clang++ -stdlib=libc++ test.cpp -lc++ -lc++abi -lm -lc -lgcc_s -lgcc

$ clang++ -stdlib=libc++ test.cpp -lc++abi

$ g++ -nostdinc++ -I<libcxx-install-prefix>/include/c++/v1 \
       test.cpp -nodefaultlibs -lc++ -lc++abi -lm -lc -lgcc_s -lgcc

std::tuple<std::string, int, std::error_code> foo() {
  return {"hello world", 42}; // default constructs error_code
}

auto foo() {
  using Tup = std::tuple<std::string, int, std::error_code>;
  return Tup{"hello world", 42}; // explicit constructor called. OK.
}

$ 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

> cmake -G "Visual Studio 14 2015"              ^
        -T "LLVM-vs2014"                        ^
        -DLIBCXX_ENABLE_SHARED=YES              ^
        -DLIBCXX_ENABLE_STATIC=NO               ^
        -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^
        \path\to\libcxx
> cmake --build .

> cmake -G Ninja                                                                    ^
        -DCMAKE_MAKE_PROGRAM=/path/to/ninja                                         ^
        -DCMAKE_SYSTEM_NAME=Windows                                                 ^
        -DCMAKE_C_COMPILER=clang-cl                                                 ^
        -DCMAKE_C_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows"   ^
        -DCMAKE_CXX_COMPILER=clang-cl                                                ^
        -DCMAKE_CXX_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^
        -DLLVM_PATH=/path/to/llvm/tree                                              ^
        -DLIBCXX_ENABLE_SHARED=YES                                                  ^
        -DLIBCXX_ENABLE_STATIC=NO                                                   ^
        -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO                                     ^
        \path\to\libcxx
> /path/to/ninja cxx
> /path/to/ninja check-cxx

$ 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.

$ 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>

$ make cxx
$ make install

$ 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

$ clang++ -stdlib=libc++ helloworld.cpp \
          -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc

$ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt

$ 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

$ alias lit='python path/to/llvm/utils/lit/lit.py'

$ export LIBCXX_SITE_CONFIG=path/to/build-libcxx/test/lit.site.cfg

$ cd path/to/src/libcxx
$ lit -sv test/std/re # Run all of the std::regex tests
$ lit -sv test/std/depr/depr.c.headers/stdlib_h.pass.cpp # Run a single test
$ lit -sv test/std/atomics test/std/threads # Test std::thread and std::atomic

$ lit -sv test/std/containers # Run the tests with the newest -std
$ lit -sv --param=std=c++03 test/std/containers # Run the tests in C++03

$ lit -sv --param=compile_flags='-Wcustom-warning'
$ lit -sv --param=link_flags='-L/custom/library/path'

# Specify a custom compiler.
$ lit -sv --param=cxx_under_test=/opt/bin/g++ test/std

# Enable warnings in the test suite
$ lit -sv --param=enable_warnings=true test/std

# Use UBSAN when running the tests.
$ lit -sv --param=use_sanitizer=Undefined

$ cd build
$ cmake [options] <path to libcxx sources>
$ make cxx-benchmarks

$ cd build/benchmarks
$ make cxx-benchmarks
$ ./algorithms.libcxx.out # Runs all the benchmarks
$ ./algorithms.libcxx.out --benchmark_filter=BM_Sort.* # Only runs the sort benchmarks

// Define availability macros.
#if defined(_LIBCPP_USE_AVAILABILITY_APPLE)
#define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable))
#else  if defined(_LIBCPP_USE_AVAILABILITY_SOME_OTHER_VENDOR)
#define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS __attribute__((unavailable))
    #else
#define _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS
#endif

#define _LIBCPP_AVAILABILITY_SHARED_MUTEX                                  \
  __attribute__((availability(macosx,strict,introduced=10.12)))            \
  __attribute__((availability(ios,strict,introduced=10.0)))                \
  __attribute__((availability(tvos,strict,introduced=10.0)))               \
  __attribute__((availability(watchos,strict,introduced=3.0)))

_LIBCPP_BEGIN_NAMESPACE_EXPERIMENTAL
class _LIBCPP_EXCEPTION_ABI _LIBCPP_AVAILABILITY_BAD_OPTIONAL_ACCESS bad_optional_access
    : public std::logic_error {

#define _LIBCPP_DEBUG 1
#include <string>
int main() {
  std::__libcpp_debug_function = std::__libcpp_throw_debug_function;
  try {
    std::string::iterator bad_it;
    std::string str("hello world");
    str.insert(bad_it, '!'); // causes debug assertion
  } catch (std::__libcpp_debug_exception const&) {
    return EXIT_SUCCESS;
  }
  return EXIT_FAILURE;
}

//===----------------------------------------------------------------------===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is dual licensed under the MIT and the University of Illinois Open
// Source Licenses. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef _LIBCPP_CONFIG_SITE
#define _LIBCPP_CONFIG_SITE

/* #undef _LIBCPP_HAS_NO_GLOBAL_FILESYSTEM_NAMESPACE */
/* #undef _LIBCPP_HAS_NO_STDIN */
/* #undef _LIBCPP_HAS_NO_STDOUT */
#define _LIBCPP_HAS_NO_THREADS
/* #undef _LIBCPP_HAS_NO_MONOTONIC_CLOCK */
/* #undef _LIBCPP_HAS_NO_THREAD_UNSAFE_C_FUNCTIONS */

#endif
// -*- C++ -*-
//===--------------------------- __config ---------------------------------===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is dual licensed under the MIT and the University of Illinois Open
// Source Licenses. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef _LIBCPP_CONFIG
#define _LIBCPP_CONFIG

struct timespec {
  time_t tv_sec;
  long   tv_nsec;
};

struct _FilesystemClock {
  using period = nano;
  using rep = TBD; // What is this?

  using duration = chrono::duration<rep, period>;
  using time_point = chrono::time_point<_FilesystemClock>;

  // ... //
};

using file_time_type = _FilesystemClock::time_point;

#include <filesystem>
using namespace std::filesystem;

// Set the times using the system interface.
void set_file_times(const char* path, struct timespec ts) {
  timespec both_times[2];
  both_times[0] = ts;
  both_times[1] = ts;
  int result = ::utimensat(AT_FDCWD, path, both_times, 0);
  assert(result != -1);
}

// Called elsewhere to set the file time to something insane, and way
// out of the 300 year range we might expect.
void some_bad_persons_code() {
  struct timespec new_times;
  new_times.tv_sec = numeric_limits<time_t>::max();
  new_times.tv_nsec = 0;
  set_file_times("/tmp/foo", new_times); // OK, supported by most FSes
}

int main() {
  path p = "/tmp/foo";
  file_status st = status(p);
  if (!exists(st) || !is_regular_file(st))
    return 1;
  if ((st.permissions() & perms::others_read) == perms::none)
    return 1;
  // It seems reasonable to assume this call should succeed.
  file_time_type tp = last_write_time(p); // BAD! Throws value_too_large.
}

void test() {
  last_write_time("/tmp/foo", file_time_type::max()); // Throws
  last_write_time("/tmp/foo", file_time_type::min()); // Throws.
}

// Bug caused by an unexpected 'rep' type returned by count.
void print_time(path p) {
  // __int128_t doesn't have streaming operators, and neither would our
  // custom arithmetic types.
  cout << last_write_time(p).time_since_epoch().count() << endl;
}

// Overflow during creation bug.
file_time_type timespec_to_file_time_type(struct timespec ts) {
  // woops! chrono::seconds and chrono::nanoseconds use a 64 bit representation
  // this may overflow before it's converted to a file_time_type.
  auto dur = seconds(ts.tv_sec) + nanoseconds(ts.tv_nsec);
  return file_time_type(dur);
}

file_time_type correct_timespec_to_file_time_type(struct timespec ts) {
  // This is the correct version of the above example, where we
  // avoid using the chrono typedefs as they're not sufficient.
  // Can we expect users to avoid this bug?
  using fs_seconds = chrono::duration<file_time_type::rep>;
  using fs_nanoseconds = chrono::duration<file_time_type::rep, nano>;
  auto dur = fs_seconds(ts.tv_sec) + fs_nanoseconds(tv.tv_nsec);
  return file_time_type(dur);
}

// Implicit truncation during conversion bug.
intmax_t get_time_in_seconds(path p) {
  using fs_seconds = duration<file_time_type::rep, ratio<1, 1> >;
  auto tp = last_write_time(p);

  // This works with truncation for __int128_t, but what does it do for
  // our custom arithmetic types.
  return duration_cast<fs_seconds>().count();
}

struct fs_timespec_rep {
  fs_timespec_rep(long long v)
    : tv_sec(v / nano::den), tv_nsec(v % nano::den)
  { }
private:
  time_t tv_sec;
  long tv_nsec;
};
bool operator==(fs_timespec_rep, fs_timespec_rep);
fs_int128_rep operator+(fs_timespec_rep, fs_timespec_rep);
// ... arithmetic operators ... //

template <class Period>
timespec convert_to_timespec(duration<fs_time_rep, Period> dur) {
  fs_timespec_rep rep = dur.count();
  return {rep.tv_sec, rep.tv_nsec}; // Oops! Period may not be nanoseconds.
}

template <class Duration>
Duration convert_to_duration(timespec ts) {
  Duration dur({ts.tv_sec, ts.tv_nsec}); // Oops! Period may not be nanoseconds.
  return file_time_type(dur);
  file_time_type tp = last_write_time(p);
  auto dur =
}

time_t extract_seconds(file_time_type tp) {
  // Converting to seconds is a silly bug, but I could see it happening.
  using SecsT = chrono::duration<file_time_type::rep, ratio<1, 1>>;
  auto secs = duration_cast<Secs>(tp.time_since_epoch());
  // tv_sec is now representing gigaseconds.
  return secs.count().tv_sec; // Oops!
}

template <>
struct duration_values<fs_timespec_rep> {
  static fs_timespec_rep zero();
  static fs_timespec_rep min();
  static fs_timespec_rep max() { // assume friendship.
    fs_timespec_rep val;
    val.tv_sec = numeric_limits<time_t>::max();
    val.tv_nsec = nano::den - 1;
    return val;
  }
};

void test() {
  using rep = file_time_type::rep;
  using fs_nsec = duration<rep, nano>;
  using fs_sec = duration<rep>;
  fs_nsec nsecs(fs_seconds::max()); // Truncates
}

void c_interface_using_time_t(const char* p, time_t);

void foo(path p) {
  file_time_type tp = last_write_time(p);
  time_t secs = duration_cast<seconds>(tp.time_since_epoch()).count();
  c_interface_using_time_t(p.c_str(), secs);
}

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

“libc++” C++ Standard Library¶

Overview¶

Getting Started with libc++¶

Using libc++¶

Building libc++¶

Testing libc++¶

Current Status¶

Platform and Compiler Support¶

C++ Dialect Support¶

Notes and Known Issues¶

Design Documents¶

Availability Markup¶

Debug Mode¶

Capturing configuration information during installation¶

Libc++ ABI stability¶

Symbol Visibility Macros¶

Threading Support API¶

File Time Type¶

Build Bots and Test Coverage¶

Getting Involved¶

Quick Links¶