diff --git a/.arcconfig b/.arcconfig index 7f45342a433..7540b46523a 100644 --- a/.arcconfig +++ b/.arcconfig @@ -1,4 +1,4 @@ { "project_id" : "clang", - "conduit_uri" : "http://llvm-reviews.chandlerc.com/" + "conduit_uri" : "http://reviews.llvm.org/" } diff --git a/CMakeLists.txt b/CMakeLists.txt index 8d02bf05f82..02374e20f43 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,76 +1,169 @@ +cmake_minimum_required(VERSION 2.8.8) + +# FIXME: It may be removed when we use 2.8.12. +if(CMAKE_VERSION VERSION_LESS 2.8.12) + # Invalidate a couple of keywords. + set(cmake_2_8_12_INTERFACE) + set(cmake_2_8_12_PRIVATE) +else() + # Use ${cmake_2_8_12_KEYWORD} intead of KEYWORD in target_link_libraries(). + set(cmake_2_8_12_INTERFACE INTERFACE) + set(cmake_2_8_12_PRIVATE PRIVATE) + if(POLICY CMP0022) + cmake_policy(SET CMP0022 NEW) # automatic when 2.8.12 is required + endif() +endif() + # If we are not building as a part of LLVM, build Clang as an # standalone project, using LLVM as an external library: if( CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR ) project(Clang) - cmake_minimum_required(VERSION 2.8) - set(CLANG_PATH_TO_LLVM_SOURCE "" CACHE PATH - "Path to LLVM source code. Not necessary if using an installed LLVM.") - set(CLANG_PATH_TO_LLVM_BUILD "" CACHE PATH - "Path to the directory where LLVM was built or installed.") - - if( CLANG_PATH_TO_LLVM_SOURCE ) - if( NOT EXISTS "${CLANG_PATH_TO_LLVM_SOURCE}/cmake/config-ix.cmake" ) - message(FATAL_ERROR "Please set CLANG_PATH_TO_LLVM_SOURCE to the root directory of LLVM source code.") + # Rely on llvm-config. + set(CONFIG_OUTPUT) + find_program(LLVM_CONFIG "llvm-config") + if(LLVM_CONFIG) + message(STATUS "Found LLVM_CONFIG as ${LLVM_CONFIG}") + set(CONFIG_COMMAND ${LLVM_CONFIG} + "--assertion-mode" + "--bindir" + "--libdir" + "--includedir" + "--prefix" + "--src-root") + execute_process( + COMMAND ${CONFIG_COMMAND} + RESULT_VARIABLE HAD_ERROR + OUTPUT_VARIABLE CONFIG_OUTPUT + ) + if(NOT HAD_ERROR) + string(REGEX REPLACE + "[ \t]*[\r\n]+[ \t]*" ";" + CONFIG_OUTPUT ${CONFIG_OUTPUT}) else() - get_filename_component(LLVM_MAIN_SRC_DIR ${CLANG_PATH_TO_LLVM_SOURCE} - ABSOLUTE) - list(APPEND CMAKE_MODULE_PATH "${LLVM_MAIN_SRC_DIR}/cmake/modules") + string(REPLACE ";" " " CONFIG_COMMAND_STR "${CONFIG_COMMAND}") + message(STATUS "${CONFIG_COMMAND_STR}") + message(FATAL_ERROR "llvm-config failed with status ${HAD_ERROR}") endif() + else() + message(FATAL_ERROR "llvm-config not found -- ${LLVM_CONFIG}") endif() - if (EXISTS "${CLANG_PATH_TO_LLVM_BUILD}/bin/llvm-config${CMAKE_EXECUTABLE_SUFFIX}") - set (PATH_TO_LLVM_CONFIG "${CLANG_PATH_TO_LLVM_BUILD}/bin/llvm-config${CMAKE_EXECUTABLE_SUFFIX}") - elseif (EXISTS "${CLANG_PATH_TO_LLVM_BUILD}/bin/Debug/llvm-config${CMAKE_EXECUTABLE_SUFFIX}") - # Looking for bin/Debug/llvm-config is a complete hack. How can we get - # around this? - set (PATH_TO_LLVM_CONFIG "${CLANG_PATH_TO_LLVM_BUILD}/bin/Debug/llvm-config${CMAKE_EXECUTABLE_SUFFIX}") + list(GET CONFIG_OUTPUT 0 ENABLE_ASSERTIONS) + list(GET CONFIG_OUTPUT 1 TOOLS_BINARY_DIR) + list(GET CONFIG_OUTPUT 2 LIBRARY_DIR) + list(GET CONFIG_OUTPUT 3 INCLUDE_DIR) + list(GET CONFIG_OUTPUT 4 LLVM_OBJ_ROOT) + list(GET CONFIG_OUTPUT 5 MAIN_SRC_DIR) + + if(NOT MSVC_IDE) + set(LLVM_ENABLE_ASSERTIONS ${ENABLE_ASSERTIONS} + CACHE BOOL "Enable assertions") + # Assertions should follow llvm-config's. + mark_as_advanced(LLVM_ENABLE_ASSERTIONS) + endif() + + set(LLVM_TOOLS_BINARY_DIR ${TOOLS_BINARY_DIR} CACHE PATH "Path to llvm/bin") + set(LLVM_LIBRARY_DIR ${LIBRARY_DIR} CACHE PATH "Path to llvm/lib") + set(LLVM_MAIN_INCLUDE_DIR ${INCLUDE_DIR} CACHE PATH "Path to llvm/include") + set(LLVM_BINARY_DIR ${LLVM_OBJ_ROOT} CACHE PATH "Path to LLVM build tree") + set(LLVM_MAIN_SRC_DIR ${MAIN_SRC_DIR} CACHE PATH "Path to LLVM source tree") + + find_program(LLVM_TABLEGEN_EXE "llvm-tblgen" ${LLVM_TOOLS_BINARY_DIR} + NO_DEFAULT_PATH) + + set(LLVM_CMAKE_PATH "${LLVM_BINARY_DIR}/share/llvm/cmake") + set(LLVMCONFIG_FILE "${LLVM_CMAKE_PATH}/LLVMConfig.cmake") + if(EXISTS ${LLVMCONFIG_FILE}) + list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_PATH}") + include(${LLVMCONFIG_FILE}) else() - message(FATAL_ERROR "Please set CLANG_PATH_TO_LLVM_BUILD to a directory containing a LLVM build.") + message(FATAL_ERROR "Not found: ${LLVMCONFIG_FILE}") endif() - list(APPEND CMAKE_MODULE_PATH "${CLANG_PATH_TO_LLVM_BUILD}/share/llvm/cmake") + # They are used as destination of target generators. + set(LLVM_RUNTIME_OUTPUT_INTDIR ${CMAKE_BINARY_DIR}/${CMAKE_CFG_INTDIR}/bin) + set(LLVM_LIBRARY_OUTPUT_INTDIR ${CMAKE_BINARY_DIR}/${CMAKE_CFG_INTDIR}/lib) - get_filename_component(PATH_TO_LLVM_BUILD ${CLANG_PATH_TO_LLVM_BUILD} - ABSOLUTE) + option(LLVM_INSTALL_TOOLCHAIN_ONLY + "Only include toolchain files in the 'install' target." OFF) - option(LLVM_INSTALL_TOOLCHAIN_ONLY "Only include toolchain files in the 'install' target." OFF) + option(LLVM_FORCE_USE_OLD_HOST_TOOLCHAIN + "Set to ON to force using an old, unsupported host toolchain." OFF) include(AddLLVM) include(TableGen) - include("${CLANG_PATH_TO_LLVM_BUILD}/share/llvm/cmake/LLVMConfig.cmake") include(HandleLLVMOptions) set(PACKAGE_VERSION "${LLVM_PACKAGE_VERSION}") - set(LLVM_MAIN_INCLUDE_DIR "${LLVM_MAIN_SRC_DIR}/include") - set(LLVM_BINARY_DIR ${CMAKE_BINARY_DIR}) - - set(CMAKE_INCLUDE_CURRENT_DIR ON) - include_directories("${PATH_TO_LLVM_BUILD}/include" "${LLVM_MAIN_INCLUDE_DIR}") - link_directories("${PATH_TO_LLVM_BUILD}/lib") - - exec_program("${PATH_TO_LLVM_CONFIG} --bindir" OUTPUT_VARIABLE LLVM_BINARY_DIR) - set(LLVM_TABLEGEN_EXE "${LLVM_BINARY_DIR}/llvm-tblgen${CMAKE_EXECUTABLE_SUFFIX}") - - # Define the default arguments to use with 'lit', and an option for the user - # to override. - set(LIT_ARGS_DEFAULT "-sv") - if (MSVC OR XCODE) - set(LIT_ARGS_DEFAULT "${LIT_ARGS_DEFAULT} --no-progress-bar") + if (NOT DEFINED LLVM_INCLUDE_TESTS) + set(LLVM_INCLUDE_TESTS ON) endif() - set(LLVM_LIT_ARGS "${LIT_ARGS_DEFAULT}" CACHE STRING "Default options for lit") + + include_directories("${LLVM_BINARY_DIR}/include" "${LLVM_MAIN_INCLUDE_DIR}") + link_directories("${LLVM_LIBRARY_DIR}") set( CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin ) set( CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib ) set( CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib ) + if(LLVM_INCLUDE_TESTS) + # Check prebuilt llvm/utils. + if(EXISTS ${LLVM_TOOLS_BINARY_DIR}/FileCheck${CMAKE_EXECUTABLE_SUFFIX} + AND EXISTS ${LLVM_TOOLS_BINARY_DIR}/count${CMAKE_EXECUTABLE_SUFFIX} + AND EXISTS ${LLVM_TOOLS_BINARY_DIR}/not${CMAKE_EXECUTABLE_SUFFIX}) + set(LLVM_UTILS_PROVIDED ON) + endif() + + if(EXISTS ${LLVM_MAIN_SRC_DIR}/utils/lit/lit.py) + set(LLVM_LIT ${LLVM_MAIN_SRC_DIR}/utils/lit/lit.py) + if(NOT LLVM_UTILS_PROVIDED) + add_subdirectory(${LLVM_MAIN_SRC_DIR}/utils/FileCheck utils/FileCheck) + add_subdirectory(${LLVM_MAIN_SRC_DIR}/utils/count utils/count) + add_subdirectory(${LLVM_MAIN_SRC_DIR}/utils/not utils/not) + set(LLVM_UTILS_PROVIDED ON) + set(CLANG_TEST_DEPS FileCheck count not) + endif() + set(UNITTEST_DIR ${LLVM_MAIN_SRC_DIR}/utils/unittest) + if(EXISTS ${UNITTEST_DIR}/googletest/include/gtest/gtest.h + AND NOT EXISTS ${LLVM_LIBRARY_DIR}/${CMAKE_STATIC_LIBRARY_PREFIX}gtest${CMAKE_STATIC_LIBRARY_SUFFIX} + AND EXISTS ${UNITTEST_DIR}/CMakeLists.txt) + add_subdirectory(${UNITTEST_DIR} utils/unittest) + endif() + else() + # Seek installed Lit. + find_program(LLVM_LIT "lit.py" ${LLVM_MAIN_SRC_DIR}/utils/lit + DOC "Path to lit.py") + endif() + + if(LLVM_LIT) + # Define the default arguments to use with 'lit', and an option for the user + # to override. + set(LIT_ARGS_DEFAULT "-sv") + if (MSVC OR XCODE) + set(LIT_ARGS_DEFAULT "${LIT_ARGS_DEFAULT} --no-progress-bar") + endif() + set(LLVM_LIT_ARGS "${LIT_ARGS_DEFAULT}" CACHE STRING "Default options for lit") + + # On Win32 hosts, provide an option to specify the path to the GnuWin32 tools. + if( WIN32 AND NOT CYGWIN ) + set(LLVM_LIT_TOOLS_DIR "" CACHE PATH "Path to GnuWin32 tools") + endif() + else() + set(LLVM_INCLUDE_TESTS OFF) + endif() + endif() + set( CLANG_BUILT_STANDALONE 1 ) + set(BACKEND_PACKAGE_STRING "LLVM ${LLVM_PACKAGE_VERSION}") +else() + set(BACKEND_PACKAGE_STRING "${PACKAGE_STRING}") +endif() - find_package(LibXml2) - if (LIBXML2_FOUND) - set(CLANG_HAVE_LIBXML 1) - endif () +find_package(LibXml2) +if (LIBXML2_FOUND) + set(CLANG_HAVE_LIBXML 1) endif() set(CLANG_RESOURCE_DIR "" CACHE STRING @@ -160,15 +253,11 @@ if (LLVM_COMPILER_IS_GCC_COMPATIBLE) endif() endif () -if (APPLE) - set(CMAKE_MODULE_LINKER_FLAGS "${CMAKE_MODULE_LINKER_FLAGS} -Wl,-flat_namespace -Wl,-undefined -Wl,suppress") -endif () - configure_file( ${CLANG_SOURCE_DIR}/include/clang/Config/config.h.cmake ${CLANG_BINARY_DIR}/include/clang/Config/config.h) -include(LLVMParseArguments) +include(CMakeParseArguments) function(clang_tablegen) # Syntax: @@ -183,59 +272,29 @@ function(clang_tablegen) # executing the custom command depending on output-file. It is # possible to list more files to depend after DEPENDS. - parse_arguments( CTG "SOURCE;TARGET;DEPENDS" "" ${ARGN} ) + cmake_parse_arguments(CTG "" "SOURCE;TARGET" "" ${ARGN}) if( NOT CTG_SOURCE ) message(FATAL_ERROR "SOURCE source-file required by clang_tablegen") endif() set( LLVM_TARGET_DEFINITIONS ${CTG_SOURCE} ) - tablegen( CLANG ${CTG_DEFAULT_ARGS} ) + tablegen(CLANG ${CTG_UNPARSED_ARGUMENTS}) - list( GET CTG_DEFAULT_ARGS 0 output_file ) - if( CTG_TARGET ) - add_custom_target( ${CTG_TARGET} DEPENDS ${output_file} ${CTG_DEPENDS} ) + if(CTG_TARGET) + add_public_tablegen_target(${CTG_TARGET}) set_target_properties( ${CTG_TARGET} PROPERTIES FOLDER "Clang tablegenning") + set_property(GLOBAL APPEND PROPERTY CLANG_TABLEGEN_TARGETS ${CTG_TARGET}) endif() endfunction(clang_tablegen) -# FIXME: Generalize and move to llvm. -function(add_clang_symbol_exports target_name export_file) - # Makefile.rules contains special cases for different platforms. - # We restrict ourselves to Darwin for the time being. - if(${CMAKE_SYSTEM_NAME} MATCHES "Darwin") - add_custom_command(OUTPUT symbol.exports - COMMAND sed -e "s/^/_/" < ${export_file} > symbol.exports - DEPENDS ${export_file} - VERBATIM - COMMENT "Creating export file for ${target_name}") - add_custom_target(${target_name}_exports DEPENDS symbol.exports) - set_property(DIRECTORY APPEND - PROPERTY ADDITIONAL_MAKE_CLEAN_FILES symbol.exports) - - get_property(srcs TARGET ${target_name} PROPERTY SOURCES) - foreach(src ${srcs}) - get_filename_component(extension ${src} EXT) - if(extension STREQUAL ".cpp") - set(first_source_file ${src}) - break() - endif() - endforeach() - - # Force re-linking when the exports file changes. Actually, it - # forces recompilation of the source file. The LINK_DEPENDS target - # property only works for makefile-based generators. - set_property(SOURCE ${first_source_file} APPEND PROPERTY - OBJECT_DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/symbol.exports) - - set_property(TARGET ${target_name} APPEND_STRING PROPERTY - LINK_FLAGS " -Wl,-exported_symbols_list,${CMAKE_CURRENT_BINARY_DIR}/symbol.exports") - add_dependencies(${target_name} ${target_name}_exports) - endif() -endfunction(add_clang_symbol_exports) - macro(add_clang_library name) - llvm_process_sources(srcs ${ARGN}) + cmake_parse_arguments(ARG + "" + "" + "ADDITIONAL_HEADERS" + ${ARGN}) + set(srcs) if(MSVC_IDE OR XCODE) # Add public headers file(RELATIVE_PATH lib_path @@ -255,34 +314,32 @@ macro(add_clang_library name) source_group("TableGen descriptions" FILES ${tds}) set_source_files_properties(${tds}} PROPERTIES HEADER_FILE_ONLY ON) - set(srcs ${srcs} ${headers} ${tds}) + if(headers OR tds) + set(srcs ${headers} ${tds}) + endif() endif() endif(MSVC_IDE OR XCODE) - if (MODULE) - set(libkind MODULE) - elseif (SHARED_LIBRARY) - set(libkind SHARED) - else() - set(libkind) - endif() - add_library( ${name} ${libkind} ${srcs} ) - if( LLVM_COMMON_DEPENDS ) - add_dependencies( ${name} ${LLVM_COMMON_DEPENDS} ) - endif( LLVM_COMMON_DEPENDS ) - - llvm_config( ${name} ${LLVM_LINK_COMPONENTS} ) - target_link_libraries( ${name} ${LLVM_COMMON_LIBS} ) - link_system_libs( ${name} ) - - if (SHARED_LIBRARY AND EXPORTED_SYMBOL_FILE) - add_clang_symbol_exports( ${name} ${EXPORTED_SYMBOL_FILE} ) + if(srcs OR ARG_ADDITIONAL_HEADERS) + set(srcs + ADDITIONAL_HEADERS + ${srcs} + ${ARG_ADDITIONAL_HEADERS} # It may contain unparsed unknown args. + ) endif() + llvm_add_library(${name} ${ARG_UNPARSED_ARGUMENTS} ${srcs}) + + if(TARGET ${name}) + target_link_libraries(${name} ${cmake_2_8_12_INTERFACE} ${LLVM_COMMON_LIBS}) - if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY OR ${name} STREQUAL "libclang") - install(TARGETS ${name} - LIBRARY DESTINATION lib${LLVM_LIBDIR_SUFFIX} - ARCHIVE DESTINATION lib${LLVM_LIBDIR_SUFFIX} - RUNTIME DESTINATION bin) + if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY OR ${name} STREQUAL "libclang") + install(TARGETS ${name} + LIBRARY DESTINATION lib${LLVM_LIBDIR_SUFFIX} + ARCHIVE DESTINATION lib${LLVM_LIBDIR_SUFFIX} + RUNTIME DESTINATION bin) + endif() + else() + # Add empty "phony" target + add_custom_target(${name}) endif() set_target_properties(${name} PROPERTIES FOLDER "Clang libraries") @@ -293,13 +350,15 @@ macro(add_clang_executable name) set_target_properties(${name} PROPERTIES FOLDER "Clang executables") endmacro(add_clang_executable) +set(CMAKE_INCLUDE_CURRENT_DIR ON) + include_directories(BEFORE ${CMAKE_CURRENT_BINARY_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR}/include ) if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY) - install(DIRECTORY include/ + install(DIRECTORY include/clang include/clang-c DESTINATION include FILES_MATCHING PATTERN "*.def" @@ -308,7 +367,7 @@ if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY) PATTERN ".svn" EXCLUDE ) - install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/include/ + install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/include/clang DESTINATION include FILES_MATCHING PATTERN "CMakeFiles" EXCLUDE @@ -326,15 +385,17 @@ install(DIRECTORY include/clang-c add_definitions( -D_GNU_SOURCE ) option(CLANG_ENABLE_ARCMT "Build ARCMT." ON) -option(CLANG_ENABLE_REWRITER "Build rewriter." ON) -option(CLANG_ENABLE_STATIC_ANALYZER "Build static analyzer." ON) - -if (NOT CLANG_ENABLE_REWRITER AND CLANG_ENABLE_ARCMT) - message(FATAL_ERROR "Cannot disable rewriter while enabling ARCMT") +if (CLANG_ENABLE_ARCMT) + set(ENABLE_CLANG_ARCMT "1") +else() + set(ENABLE_CLANG_ARCMT "0") endif() -if (NOT CLANG_ENABLE_REWRITER AND CLANG_ENABLE_STATIC_ANALYZER) - message(FATAL_ERROR "Cannot disable rewriter while enabling static analyzer") +option(CLANG_ENABLE_STATIC_ANALYZER "Build static analyzer." ON) +if (CLANG_ENABLE_STATIC_ANALYZER) + set(ENABLE_CLANG_STATIC_ANALYZER "1") +else() + set(ENABLE_CLANG_STATIC_ANALYZER "0") endif() if (NOT CLANG_ENABLE_STATIC_ANALYZER AND CLANG_ENABLE_ARCMT) @@ -343,9 +404,7 @@ endif() if(CLANG_ENABLE_ARCMT) add_definitions(-DCLANG_ENABLE_ARCMT) -endif() -if(CLANG_ENABLE_REWRITER) - add_definitions(-DCLANG_ENABLE_REWRITER) + add_definitions(-DCLANG_ENABLE_OBJC_REWRITER) endif() if(CLANG_ENABLE_STATIC_ANALYZER) add_definitions(-DCLANG_ENABLE_STATIC_ANALYZER) @@ -363,11 +422,21 @@ mark_as_advanced(CLANG_EXECUTABLE_VERSION LIBCLANG_LIBRARY_VERSION) add_subdirectory(utils/TableGen) add_subdirectory(include) + +# All targets below may depend on all tablegen'd files. +get_property(CLANG_TABLEGEN_TARGETS GLOBAL PROPERTY CLANG_TABLEGEN_TARGETS) +list(APPEND LLVM_COMMON_DEPENDS ${CLANG_TABLEGEN_TARGETS}) + add_subdirectory(lib) add_subdirectory(tools) add_subdirectory(runtime) option(CLANG_BUILD_EXAMPLES "Build CLANG example programs by default." OFF) +if (CLANG_BUILD_EXAMPLES) + set(ENABLE_CLANG_EXAMPLES "1") +else() + set(ENABLE_CLANG_EXAMPLES "0") +endif() add_subdirectory(examples) option(CLANG_INCLUDE_TESTS @@ -375,8 +444,30 @@ option(CLANG_INCLUDE_TESTS ${LLVM_INCLUDE_TESTS}) if( CLANG_INCLUDE_TESTS ) + if(EXISTS ${LLVM_MAIN_SRC_DIR}/utils/unittest/googletest/include/gtest/gtest.h) + add_subdirectory(unittests) + list(APPEND CLANG_TEST_DEPS ClangUnitTests) + list(APPEND CLANG_TEST_PARAMS + clang_unit_site_config=${CMAKE_CURRENT_BINARY_DIR}/test/Unit/lit.site.cfg + ) + endif() add_subdirectory(test) - add_subdirectory(unittests) + + if(CLANG_BUILT_STANDALONE) + # Add a global check rule now that all subdirectories have been traversed + # and we know the total set of lit testsuites. + get_property(LLVM_LIT_TESTSUITES GLOBAL PROPERTY LLVM_LIT_TESTSUITES) + get_property(LLVM_LIT_PARAMS GLOBAL PROPERTY LLVM_LIT_PARAMS) + get_property(LLVM_LIT_DEPENDS GLOBAL PROPERTY LLVM_LIT_DEPENDS) + get_property(LLVM_LIT_EXTRA_ARGS GLOBAL PROPERTY LLVM_LIT_EXTRA_ARGS) + add_lit_target(check-all + "Running all regression tests" + ${LLVM_LIT_TESTSUITES} + PARAMS ${LLVM_LIT_PARAMS} + DEPENDS ${LLVM_LIT_DEPENDS} + ARGS ${LLVM_LIT_EXTRA_ARGS} + ) + endif() endif() option(CLANG_INCLUDE_DOCS "Generate build targets for the Clang docs." @@ -385,17 +476,5 @@ if( CLANG_INCLUDE_DOCS ) add_subdirectory(docs) endif() -# Workaround for MSVS10 to avoid the Dialog Hell -# FIXME: This could be removed with future version of CMake. -if( CLANG_BUILT_STANDALONE AND MSVC_VERSION EQUAL 1600 ) - set(CLANG_SLN_FILENAME "${CMAKE_CURRENT_BINARY_DIR}/Clang.sln") - if( EXISTS "${CLANG_SLN_FILENAME}" ) - file(APPEND "${CLANG_SLN_FILENAME}" "\n# This should be regenerated!\n") - endif() -endif() - -set(BUG_REPORT_URL "http://llvm.org/bugs/" CACHE STRING - "Default URL where bug reports are to be submitted.") - set(CLANG_ORDER_FILE "" CACHE FILEPATH "Order file to use when compiling clang in order to improve startup time.") diff --git a/CODE_OWNERS.TXT b/CODE_OWNERS.TXT index af508318471..bbd3142bc87 100644 --- a/CODE_OWNERS.TXT +++ b/CODE_OWNERS.TXT @@ -8,6 +8,10 @@ beautification by scripts. The fields are: name (N), email (E), web-address (W), PGP key ID and fingerprint (P), description (D), and snail-mail address (S). +N: Aaron Ballman +E: aaron@aaronballman.com +D: Clang attributes + N: Chandler Carruth E: chandlerc@gmail.com E: chandlerc@google.com diff --git a/LICENSE.TXT b/LICENSE.TXT index e31223a486a..3b1153db44e 100644 --- a/LICENSE.TXT +++ b/LICENSE.TXT @@ -4,7 +4,7 @@ LLVM Release License University of Illinois/NCSA Open Source License -Copyright (c) 2007-2013 University of Illinois at Urbana-Champaign. +Copyright (c) 2007-2014 University of Illinois at Urbana-Champaign. All rights reserved. Developed by: diff --git a/Makefile b/Makefile index cb2566a0a17..bbc521f4c0e 100644 --- a/Makefile +++ b/Makefile @@ -23,6 +23,12 @@ ifeq ($(BUILD_EXAMPLES),1) endif endif +ifeq ($(BUILD_EXAMPLES),1) + ENABLE_CLANG_EXAMPLES := 1 +else + ENABLE_CLANG_EXAMPLES := 0 +endif + ifeq ($(MAKECMDGOALS),libs-only) DIRS := $(filter-out tools docs, $(DIRS)) OPTIONAL_DIRS := diff --git a/NOTES.txt b/NOTES.txt index 107ec5ad48c..53f35a01863 100644 --- a/NOTES.txt +++ b/NOTES.txt @@ -34,11 +34,11 @@ TODO: File Manager Speedup: 3. File UIDs are created on request, not when files are opened. These changes make it possible to efficiently have FileEntry objects for files that exist on the file system, but have not been used yet. - + Once this is done: 1. DirectoryEntry gets a boolean value "has read entries". When false, not all entries in the directory are in the file mgr, when true, they are. - 2. Instead of stat'ing the file in FileManager::getFile, check to see if + 2. Instead of stat'ing the file in FileManager::getFile, check to see if the dir has been read. If so, fail immediately, if not, read the dir, then retry. 3. Reading the dir uses the getdirentries syscall, creating a FileEntry @@ -55,18 +55,18 @@ The "selection of target" behavior is defined as follows: (1) If the user does not specify -triple, we default to the host triple. (2) If the user specifies a -arch, that overrides the arch in the host or - specified triple. + specified triple. //===---------------------------------------------------------------------===// -verifyInputConstraint and verifyOutputConstraint should not return bool. +verifyInputConstraint and verifyOutputConstraint should not return bool. Instead we should return something like: enum VerifyConstraintResult { Valid, - + // Output only OutputOperandConstraintLacksEqualsCharacter, MatchingConstraintNotValidInOutputOperand, @@ -74,7 +74,7 @@ enum VerifyConstraintResult { // Input only InputOperandConstraintContainsEqualsCharacter, MatchingConstraintReferencesInvalidOperandNumber, - + // Both PercentConstraintUsedWithLastOperand }; diff --git a/README.txt b/README.txt index 44ce723acef..474c67cf59e 100644 --- a/README.txt +++ b/README.txt @@ -8,7 +8,7 @@ compiler infrastructure project. Unlike many other compiler frontends, Clang is useful for a number of things beyond just compiling code: we intend for Clang to be host to a number of -different source level tools. One example of this is the Clang Static Analyzer. +different source-level tools. One example of this is the Clang Static Analyzer. If you're interested in more (including how to build Clang) it is best to read the relevant web sites. Here are some pointers: diff --git a/bindings/python/clang/cindex.py b/bindings/python/clang/cindex.py index c103c707800..517b3c1bac6 100644 --- a/bindings/python/clang/cindex.py +++ b/bindings/python/clang/cindex.py @@ -272,7 +272,7 @@ def __contains__(self, other): return False if other.file is None and self.start.file is None: pass - elif ( self.start.file.name != other.file.name or + elif ( self.start.file.name != other.file.name or other.file.name != self.end.file.name): # same file name return False @@ -361,13 +361,13 @@ def __getitem__(self, key): @property def category_number(self): - """The category number for this diagnostic.""" + """The category number for this diagnostic or 0 if unavailable.""" return conf.lib.clang_getDiagnosticCategory(self) @property def category_name(self): """The string name of the category for this diagnostic.""" - return conf.lib.clang_getDiagnosticCategoryName(self.category_number) + return conf.lib.clang_getDiagnosticCategoryText(self) @property def option(self): @@ -748,7 +748,7 @@ def __repr__(self): # that has not yet been resolved to a specific function or function template. CursorKind.OVERLOADED_DECL_REF = CursorKind(49) -# A reference to a variable that occurs in some non-expression +# A reference to a variable that occurs in some non-expression # context, e.g., a C++ lambda capture list. CursorKind.VARIABLE_REF = CursorKind(50) @@ -937,7 +937,7 @@ def __repr__(self): # Represents a C++ lambda expression that produces a local function # object. -# +# # \code # void abssort(float *x, unsigned N) { # std::sort(x, x + N, @@ -947,7 +947,7 @@ def __repr__(self): # } # \endcode CursorKind.LAMBDA_EXPR = CursorKind(144) - + # Objective-c Boolean Literal. CursorKind.OBJ_BOOL_LITERAL_EXPR = CursorKind(145) @@ -1079,6 +1079,13 @@ def __repr__(self): CursorKind.ANNOTATE_ATTR = CursorKind(406) CursorKind.ASM_LABEL_ATTR = CursorKind(407) CursorKind.PACKED_ATTR = CursorKind(408) +CursorKind.PURE_ATTR = CursorKind(409) +CursorKind.CONST_ATTR = CursorKind(410) +CursorKind.NODUPLICATE_ATTR = CursorKind(411) +CursorKind.CUDACONSTANT_ATTR = CursorKind(412) +CursorKind.CUDADEVICE_ATTR = CursorKind(413) +CursorKind.CUDAGLOBAL_ATTR = CursorKind(414) +CursorKind.CUDAHOST_ATTR = CursorKind(415) ### # Preprocessing @@ -1159,10 +1166,6 @@ def kind(self): @property def spelling(self): """Return the spelling of the entity pointed at by the cursor.""" - if not self.kind.is_declaration(): - # FIXME: clang_getCursorSpelling should be fixed to not assert on - # this, for consistency with clang_getCursorUSR. - return None if not hasattr(self, '_spelling'): self._spelling = conf.lib.clang_getCursorSpelling(self) @@ -1204,6 +1207,17 @@ def extent(self): return self._extent + @property + def access_specifier(self): + """ + Retrieves the access specifier (if any) of the entity pointed at by the + cursor. + """ + if not hasattr(self, '_access_specifier'): + self._access_specifier = conf.lib.clang_getCXXAccessSpecifier(self) + + return AccessSpecifier.from_id(self._access_specifier) + @property def type(self): """ @@ -1331,7 +1345,7 @@ def translation_unit(self): @property def referenced(self): """ - For a cursor that is a reference, returns a cursor + For a cursor that is a reference, returns a cursor representing the entity that it references. """ if not hasattr(self, '_referenced'): @@ -1343,7 +1357,7 @@ def referenced(self): def brief_comment(self): """Returns the brief comment text associated with that Cursor""" return conf.lib.clang_Cursor_getBriefCommentText(self) - + @property def raw_comment(self): """Returns the raw comment text associated with that Cursor""" @@ -1373,6 +1387,16 @@ def visitor(child, parent, children): children) return iter(children) + def walk_preorder(self): + """Depth-first preorder walk over the cursor and its descendants. + + Yields cursors. + """ + yield self + for child in self.get_children(): + for descendant in child.walk_preorder(): + yield descendant + def get_tokens(self): """Obtain Token instances formulating that compose this Cursor. @@ -1426,6 +1450,54 @@ def from_cursor_result(res, fn, args): res._tu = args[0]._tu return res +### C++ access specifiers ### + +class AccessSpecifier(object): + """ + Describes the access of a C++ class member + """ + + # The unique kind objects, index by id. + _kinds = [] + _name_map = None + + def __init__(self, value): + if value >= len(AccessSpecifier._kinds): + AccessSpecifier._kinds += [None] * (value - len(AccessSpecifier._kinds) + 1) + if AccessSpecifier._kinds[value] is not None: + raise ValueError,'AccessSpecifier already loaded' + self.value = value + AccessSpecifier._kinds[value] = self + AccessSpecifier._name_map = None + + def from_param(self): + return self.value + + @property + def name(self): + """Get the enumeration name of this access specifier.""" + if self._name_map is None: + self._name_map = {} + for key,value in AccessSpecifier.__dict__.items(): + if isinstance(value,AccessSpecifier): + self._name_map[value] = key + return self._name_map[self] + + @staticmethod + def from_id(id): + if id >= len(AccessSpecifier._kinds) or not AccessSpecifier._kinds[id]: + raise ValueError,'Unknown access specifier %d' % id + return AccessSpecifier._kinds[id] + + def __repr__(self): + return 'AccessSpecifier.%s' % (self.name,) + +AccessSpecifier.INVALID = AccessSpecifier(0) +AccessSpecifier.PUBLIC = AccessSpecifier(1) +AccessSpecifier.PROTECTED = AccessSpecifier(2) +AccessSpecifier.PRIVATE = AccessSpecifier(3) +AccessSpecifier.NONE = AccessSpecifier(4) + ### Type Kinds ### class TypeKind(object): @@ -1820,7 +1892,7 @@ class _CXUnsavedFile(Structure): # 5 : CompletionChunk.Kind("CurrentParameter"), 6: '(', # CompletionChunk.Kind("LeftParen"), 7: ')', # CompletionChunk.Kind("RightParen"), - 8: ']', # CompletionChunk.Kind("LeftBracket"), + 8: '[', # CompletionChunk.Kind("LeftBracket"), 9: ']', # CompletionChunk.Kind("RightBracket"), 10: '{', # CompletionChunk.Kind("LeftBrace"), 11: '}', # CompletionChunk.Kind("RightBrace"), @@ -1934,7 +2006,7 @@ def __repr__(self): return "" % self def __len__(self): - self.num_chunks + return self.num_chunks @CachedProperty def num_chunks(self): @@ -2501,7 +2573,7 @@ class CompilationDatabaseError(Exception): constants in this class. """ - # An unknown error occured + # An unknown error occurred ERROR_UNKNOWN = 0 # The database could not be loaded @@ -2607,6 +2679,14 @@ def getCompileCommands(self, filename): return conf.lib.clang_CompilationDatabase_getCompileCommands(self, filename) + def getAllCompileCommands(self): + """ + Get an iterable object providing all the CompileCommands available from + the database. + """ + return conf.lib.clang_CompilationDatabase_getAllCompileCommands(self) + + class Token(Structure): """Represents a single token from the preprocessor. @@ -2673,6 +2753,11 @@ def cursor(self): c_object_p, CompilationDatabase.from_result), + ("clang_CompilationDatabase_getAllCompileCommands", + [c_object_p], + c_object_p, + CompileCommands.from_result), + ("clang_CompilationDatabase_getCompileCommands", [c_object_p, c_char_p], c_object_p, @@ -2909,8 +2994,8 @@ def cursor(self): [Diagnostic], c_uint), - ("clang_getDiagnosticCategoryName", - [c_uint], + ("clang_getDiagnosticCategoryText", + [Diagnostic], _CXString, _CXString.from_result), @@ -3329,8 +3414,8 @@ def set_compatibility_check(check_status): python bindings can disable the compatibility check. This will cause the python bindings to load, even though they are written for a newer version of libclang. Failures now arise if unsupported or incompatible - features are accessed. The user is required to test himself if the - features he is using are available and compatible between different + features are accessed. The user is required to test themselves if the + features they are using are available and compatible between different libclang versions. """ if Config.loaded: diff --git a/bindings/python/examples/cindex/cindex-dump.py b/bindings/python/examples/cindex/cindex-dump.py index af7ddab6ea5..5556ad121a3 100644 --- a/bindings/python/examples/cindex/cindex-dump.py +++ b/bindings/python/examples/cindex/cindex-dump.py @@ -63,8 +63,8 @@ def main(): parser = OptionParser("usage: %prog [options] {filename} [clang-args*]") parser.add_option("", "--show-ids", dest="showIDs", - help="Don't compute cursor IDs (very slow)", - default=False) + help="Compute cursor IDs (very slow)", + action="store_true", default=False) parser.add_option("", "--max-depth", dest="maxDepth", help="Limit cursor expansion to depth N", metavar="N", type=int, default=None) diff --git a/bindings/python/tests/cindex/test_access_specifiers.py b/bindings/python/tests/cindex/test_access_specifiers.py new file mode 100644 index 00000000000..cfa04dc8657 --- /dev/null +++ b/bindings/python/tests/cindex/test_access_specifiers.py @@ -0,0 +1,34 @@ + +from clang.cindex import AccessSpecifier +from clang.cindex import Cursor +from clang.cindex import TranslationUnit + +from .util import get_cursor +from .util import get_tu + +def test_access_specifiers(): + """Ensure that C++ access specifiers are available on cursors""" + + tu = get_tu(""" +class test_class { +public: + void public_member_function(); +protected: + void protected_member_function(); +private: + void private_member_function(); +}; +""", lang = 'cpp') + + test_class = get_cursor(tu, "test_class") + assert test_class.access_specifier == AccessSpecifier.INVALID; + + public = get_cursor(tu.cursor, "public_member_function") + assert public.access_specifier == AccessSpecifier.PUBLIC + + protected = get_cursor(tu.cursor, "protected_member_function") + assert protected.access_specifier == AccessSpecifier.PROTECTED + + private = get_cursor(tu.cursor, "private_member_function") + assert private.access_specifier == AccessSpecifier.PRIVATE + diff --git a/bindings/python/tests/cindex/test_cdb.py b/bindings/python/tests/cindex/test_cdb.py index d0f580ea9f4..e1f824f797f 100644 --- a/bindings/python/tests/cindex/test_cdb.py +++ b/bindings/python/tests/cindex/test_cdb.py @@ -32,6 +32,27 @@ def test_lookup_succeed(): cmds = cdb.getCompileCommands('/home/john.doe/MyProject/project.cpp') assert len(cmds) != 0 +def test_all_compilecommand(): + """Check we get all results from the db""" + cdb = CompilationDatabase.fromDirectory(kInputsDir) + cmds = cdb.getAllCompileCommands() + assert len(cmds) == 3 + expected = [ + { 'wd': '/home/john.doe/MyProjectA', + 'line': ['clang++', '-o', 'project2.o', '-c', + '/home/john.doe/MyProject/project2.cpp']}, + { 'wd': '/home/john.doe/MyProjectB', + 'line': ['clang++', '-DFEATURE=1', '-o', 'project2-feature.o', '-c', + '/home/john.doe/MyProject/project2.cpp']}, + { 'wd': '/home/john.doe/MyProject', + 'line': ['clang++', '-o', 'project.o', '-c', + '/home/john.doe/MyProject/project.cpp']} + ] + for i in range(len(cmds)): + assert cmds[i].directory == expected[i]['wd'] + for arg, exp in zip(cmds[i].arguments, expected[i]['line']): + assert arg == exp + def test_1_compilecommand(): """Check file with single compile command""" cdb = CompilationDatabase.fromDirectory(kInputsDir) diff --git a/bindings/python/tests/cindex/test_cursor.py b/bindings/python/tests/cindex/test_cursor.py index a27525cfe55..43150450224 100644 --- a/bindings/python/tests/cindex/test_cursor.py +++ b/bindings/python/tests/cindex/test_cursor.py @@ -8,9 +8,6 @@ from .util import get_tu kInput = """\ -// FIXME: Find nicer way to drop builtins and other cruft. -int start_decl; - struct s0 { int a; int b; @@ -33,11 +30,7 @@ def test_get_children(): tu = get_tu(kInput) - # Skip until past start_decl. it = tu.cursor.get_children() - while it.next().spelling != 'start_decl': - pass - tu_nodes = list(it) assert len(tu_nodes) == 3 @@ -49,7 +42,7 @@ def test_get_children(): assert tu_nodes[0].spelling == 's0' assert tu_nodes[0].is_definition() == True assert tu_nodes[0].location.file.name == 't.c' - assert tu_nodes[0].location.line == 4 + assert tu_nodes[0].location.line == 1 assert tu_nodes[0].location.column == 8 assert tu_nodes[0].hash > 0 assert tu_nodes[0].translation_unit is not None diff --git a/bindings/python/tests/cindex/test_translation_unit.py b/bindings/python/tests/cindex/test_translation_unit.py index f77998e5245..be6cd671ae0 100644 --- a/bindings/python/tests/cindex/test_translation_unit.py +++ b/bindings/python/tests/cindex/test_translation_unit.py @@ -1,5 +1,6 @@ import gc import os +import tempfile from clang.cindex import CursorKind from clang.cindex import Cursor @@ -93,15 +94,7 @@ def save_tu(tu): Returns the filename it was saved to. """ - - # FIXME Generate a temp file path using system APIs. - base = 'TEMP_FOR_TRANSLATIONUNIT_SAVE.c' - path = os.path.join(kInputsDir, base) - - # Just in case. - if os.path.exists(path): - os.unlink(path) - + _, path = tempfile.mkstemp() tu.save(path) return path diff --git a/bindings/python/tests/cindex/util.py b/bindings/python/tests/cindex/util.py index 8614b02ad25..c53ba7c81bd 100644 --- a/bindings/python/tests/cindex/util.py +++ b/bindings/python/tests/cindex/util.py @@ -39,52 +39,34 @@ def get_cursor(source, spelling): If the cursor is not found, None is returned. """ - children = [] - if isinstance(source, Cursor): - children = source.get_children() - else: - # Assume TU - children = source.cursor.get_children() - - for cursor in children: + # Convenience for calling on a TU. + root_cursor = source if isinstance(source, Cursor) else source.cursor + + for cursor in root_cursor.walk_preorder(): if cursor.spelling == spelling: return cursor - # Recurse into children. - result = get_cursor(cursor, spelling) - if result is not None: - return result - return None - + def get_cursors(source, spelling): """Obtain all cursors from a source object with a specific spelling. - This provides a convenient search mechanism to find all cursors with specific - spelling within a source. The first argument can be either a + This provides a convenient search mechanism to find all cursors with + specific spelling within a source. The first argument can be either a TranslationUnit or Cursor instance. If no cursors are found, an empty list is returned. """ + # Convenience for calling on a TU. + root_cursor = source if isinstance(source, Cursor) else source.cursor + cursors = [] - children = [] - if isinstance(source, Cursor): - children = source.get_children() - else: - # Assume TU - children = source.cursor.get_children() - - for cursor in children: + for cursor in root_cursor.walk_preorder(): if cursor.spelling == spelling: cursors.append(cursor) - # Recurse into children. - cursors.extend(get_cursors(cursor, spelling)) - return cursors - - __all__ = [ 'get_cursor', diff --git a/bindings/xml/comment-xml-schema.rng b/bindings/xml/comment-xml-schema.rng index a8913a360b7..43f3e54c286 100644 --- a/bindings/xml/comment-xml-schema.rng +++ b/bindings/xml/comment-xml-schema.rng @@ -580,6 +580,14 @@ + + + + + + + .*\S.* diff --git a/docs/AddressSanitizer.rst b/docs/AddressSanitizer.rst index 4d5944d372a..93a6a0ebaa5 100644 --- a/docs/AddressSanitizer.rst +++ b/docs/AddressSanitizer.rst @@ -16,6 +16,7 @@ following types of bugs: * Use-after-free * Use-after-return (to some extent) * Double-free, invalid free +* Memory leaks (experimental) Typical slowdown introduced by AddressSanitizer is **2x**. @@ -60,14 +61,14 @@ or: % clang -g -fsanitize=address example_UseAfterFree.o If a bug is detected, the program will print an error message to stderr and -exit with a non-zero exit code. Currently, AddressSanitizer does not symbolize -its output, so you may need to use a separate script to symbolize the result -offline (this will be fixed in future). +exit with a non-zero exit code. To make AddressSanitizer symbolize its output +you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to +the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your +``$PATH``): .. code-block:: console - % ./a.out 2> log - % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt + % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 READ of size 4 at 0x7f7ddab8c084 thread T0 #0 0x403c8c in main example_UseAfterFree.cc:4 @@ -83,6 +84,23 @@ offline (this will be fixed in future). #2 0x7f7ddabcac4d in __libc_start_main ??:0 ==9442== ABORTING +If that does not work for you (e.g. your process is sandboxed), you can use a +separate script to symbolize the result offline (online symbolization can be +force disabled by setting ``ASAN_OPTIONS=symbolize=0``): + +.. code-block:: console + + % ASAN_OPTIONS=symbolize=0 ./a.out 2> log + % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt + ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 + READ of size 4 at 0x7f7ddab8c084 thread T0 + #0 0x403c8c in main example_UseAfterFree.cc:4 + #1 0x7f7ddabcac4d in __libc_start_main ??:0 + ... + +Note that on OS X you may need to run ``dsymutil`` on your binary to have the +file\:line info in the AddressSanitizer reports. + AddressSanitizer exits on the first detected error. This is by design. One reason: it makes the generated code smaller and faster (both by ~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind, @@ -155,16 +173,22 @@ problems happening in certain source files or with certain global variables. type:*BadInitClassSubstring*=init src:bad/init/files/*=init +Memory leak detection +--------------------- + +For the experimental memory leak detector in AddressSanitizer, see +:doc:`LeakSanitizer`. + Supported Platforms =================== AddressSanitizer is supported on -* Linux i386/x86\_64 (tested on Ubuntu 10.04 and 12.04); -* MacOS 10.6, 10.7 and 10.8 (i386/x86\_64). +* Linux i386/x86\_64 (tested on Ubuntu 12.04); +* MacOS 10.6 - 10.9 (i386/x86\_64). +* Android ARM -Support for Linux ARM (and Android ARM) is in progress (it may work, but -is not guaranteed too). +Ports to various other platforms are in progress. Limitations =========== diff --git a/docs/AttributeReference.rst b/docs/AttributeReference.rst new file mode 100644 index 00000000000..115a217c4c1 --- /dev/null +++ b/docs/AttributeReference.rst @@ -0,0 +1,1116 @@ +.. + ------------------------------------------------------------------- + NOTE: This file is automatically generated by running clang-tblgen + -gen-attr-docs. Do not edit this file by hand!! + ------------------------------------------------------------------- + +=================== +Attributes in Clang +=================== +.. contents:: + :local: + +Introduction +============ + +This page lists the attributes currently supported by Clang. + +Function Attributes +=================== + + +interrupt +--------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on +ARM targets. This attribute may be attached to a function definition and +instructs the backend to generate appropriate function entry/exit code so that +it can be used directly as an interrupt service routine. + +The parameter passed to the interrupt attribute is optional, but if +provided it must be a string literal with one of the following values: "IRQ", +"FIQ", "SWI", "ABORT", "UNDEF". + +The semantics are as follows: + +- If the function is AAPCS, Clang instructs the backend to realign the stack to + 8 bytes on entry. This is a general requirement of the AAPCS at public + interfaces, but may not hold when an exception is taken. Doing this allows + other AAPCS functions to be called. +- If the CPU is M-class this is all that needs to be done since the architecture + itself is designed in such a way that functions obeying the normal AAPCS ABI + constraints are valid exception handlers. +- If the CPU is not M-class, the prologue and epilogue are modified to save all + non-banked registers that are used, so that upon return the user-mode state + will not be corrupted. Note that to avoid unnecessary overhead, only + general-purpose (integer) registers are saved in this way. If VFP operations + are needed, that state must be saved manually. + + Specifically, interrupt kinds other than "FIQ" will save all core registers + except "lr" and "sp". "FIQ" interrupts will save r0-r7. +- If the CPU is not M-class, the return instruction is changed to one of the + canonical sequences permitted by the architecture for exception return. Where + possible the function itself will make the necessary "lr" adjustments so that + the "preferred return address" is selected. + + Unfortunately the compiler is unable to make this guarantee for an "UNDEF" + handler, where the offset from "lr" to the preferred return address depends on + the execution state of the code which generated the exception. In this case + a sequence equivalent to "movs pc, lr" will be used. + + +acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability) +----------------------------------------------------------------------------------------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +Marks a function as acquiring a capability. + + +assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability) +------------------------------------------------------------------------------------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +Marks a function that dynamically tests whether a capability is held, and halts +the program if it is not held. + + +availability +------------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +The ``availability`` attribute can be placed on declarations to describe the +lifecycle of that declaration relative to operating system versions. Consider +the function declaration for a hypothetical function ``f``: + +.. code-block:: c++ + + void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7))); + +The availability attribute states that ``f`` was introduced in Mac OS X 10.4, +deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information +is used by Clang to determine when it is safe to use ``f``: for example, if +Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()`` +succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call +succeeds but Clang emits a warning specifying that the function is deprecated. +Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call +fails because ``f()`` is no longer available. + +The availability attribute is a comma-separated list starting with the +platform name and then including clauses specifying important milestones in the +declaration's lifetime (in any order) along with additional information. Those +clauses can be: + +introduced=\ *version* + The first version in which this declaration was introduced. + +deprecated=\ *version* + The first version in which this declaration was deprecated, meaning that + users should migrate away from this API. + +obsoleted=\ *version* + The first version in which this declaration was obsoleted, meaning that it + was removed completely and can no longer be used. + +unavailable + This declaration is never available on this platform. + +message=\ *string-literal* + Additional message text that Clang will provide when emitting a warning or + error about use of a deprecated or obsoleted declaration. Useful to direct + users to replacement APIs. + +Multiple availability attributes can be placed on a declaration, which may +correspond to different platforms. Only the availability attribute with the +platform corresponding to the target platform will be used; any others will be +ignored. If no availability attribute specifies availability for the current +target platform, the availability attributes are ignored. Supported platforms +are: + +``ios`` + Apple's iOS operating system. The minimum deployment target is specified by + the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*`` + command-line arguments. + +``macosx`` + Apple's Mac OS X operating system. The minimum deployment target is + specified by the ``-mmacosx-version-min=*version*`` command-line argument. + +A declaration can be used even when deploying back to a platform version prior +to when the declaration was introduced. When this happens, the declaration is +`weakly linked +`_, +as if the ``weak_import`` attribute were added to the declaration. A +weakly-linked declaration may or may not be present a run-time, and a program +can determine whether the declaration is present by checking whether the +address of that declaration is non-NULL. + +If there are multiple declarations of the same entity, the availability +attributes must either match on a per-platform basis or later +declarations must not have availability attributes for that +platform. For example: + +.. code-block:: c + + void g(void) __attribute__((availability(macosx,introduced=10.4))); + void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches + void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform + void g(void); // okay, inherits both macosx and ios availability from above. + void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch + +When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,: + +.. code-block:: objc + + @interface A + - (id)method __attribute__((availability(macosx,introduced=10.4))); + - (id)method2 __attribute__((availability(macosx,introduced=10.4))); + @end + + @interface B : A + - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later + - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4 + @end + + +_Noreturn +--------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "","","","X" + +A function declared as ``_Noreturn`` shall not return to its caller. The +compiler will generate a diagnostic for a function declared as ``_Noreturn`` +that appears to be capable of returning to its caller. + + +noreturn +-------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "","X","","" + +A function declared as ``[[noreturn]]`` shall not return to its caller. The +compiler will generate a diagnostic for a function declared as ``[[noreturn]]`` +that appears to be capable of returning to its caller. + + +carries_dependency +------------------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +The ``carries_dependency`` attribute specifies dependency propagation into and +out of functions. + +When specified on a function or Objective-C method, the ``carries_dependency`` +attribute means that the return value carries a dependency out of the function, +so that the implementation need not constrain ordering upon return from that +function. Implementations of the function and its caller may choose to preserve +dependencies instead of emitting memory ordering instructions such as fences. + +Note, this attribute does not change the meaning of the program, but may result +in generation of more efficient code. + + +enable_if +--------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +.. Note:: Some features of this attribute are experimental. The meaning of + multiple enable_if attributes on a single declaration is subject to change in + a future version of clang. Also, the ABI is not standardized and the name + mangling may change in future versions. To avoid that, use asm labels. + +The ``enable_if`` attribute can be placed on function declarations to control +which overload is selected based on the values of the function's arguments. +When combined with the ``overloadable`` attribute, this feature is also +available in C. + +.. code-block:: c++ + + int isdigit(int c); + int isdigit(int c) __attribute__((enable_if(c <= -1 || c > 255, "chosen when 'c' is out of range"))) __attribute__((unavailable("'c' must have the value of an unsigned char or EOF"))); + + void foo(char c) { + isdigit(c); + isdigit(10); + isdigit(-10); // results in a compile-time error. + } + +The enable_if attribute takes two arguments, the first is an expression written +in terms of the function parameters, the second is a string explaining why this +overload candidate could not be selected to be displayed in diagnostics. The +expression is part of the function signature for the purposes of determining +whether it is a redeclaration (following the rules used when determining +whether a C++ template specialization is ODR-equivalent), but is not part of +the type. + +The enable_if expression is evaluated as if it were the body of a +bool-returning constexpr function declared with the arguments of the function +it is being applied to, then called with the parameters at the callsite. If the +result is false or could not be determined through constant expression +evaluation, then this overload will not be chosen and the provided string may +be used in a diagnostic if the compile fails as a result. + +Because the enable_if expression is an unevaluated context, there are no global +state changes, nor the ability to pass information from the enable_if +expression to the function body. For example, suppose we want calls to +strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of +strbuf) only if the size of strbuf can be determined: + +.. code-block:: c++ + + __attribute__((always_inline)) + static inline size_t strnlen(const char *s, size_t maxlen) + __attribute__((overloadable)) + __attribute__((enable_if(__builtin_object_size(s, 0) != -1))), + "chosen when the buffer size is known but 'maxlen' is not"))) + { + return strnlen_chk(s, maxlen, __builtin_object_size(s, 0)); + } + +Multiple enable_if attributes may be applied to a single declaration. In this +case, the enable_if expressions are evaluated from left to right in the +following manner. First, the candidates whose enable_if expressions evaluate to +false or cannot be evaluated are discarded. If the remaining candidates do not +share ODR-equivalent enable_if expressions, the overload resolution is +ambiguous. Otherwise, enable_if overload resolution continues with the next +enable_if attribute on the candidates that have not been discarded and have +remaining enable_if attributes. In this way, we pick the most specific +overload out of a number of viable overloads using enable_if. + +.. code-block:: c++ + + void f() __attribute__((enable_if(true, ""))); // #1 + void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2 + + void g(int i, int j) __attribute__((enable_if(i, ""))); // #1 + void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2 + +In this example, a call to f() is always resolved to #2, as the first enable_if +expression is ODR-equivalent for both declarations, but #1 does not have another +enable_if expression to continue evaluating, so the next round of evaluation has +only a single candidate. In a call to g(1, 1), the call is ambiguous even though +#2 has more enable_if attributes, because the first enable_if expressions are +not ODR-equivalent. + +Query for this feature with ``__has_attribute(enable_if)``. + + +flatten (gnu::flatten) +---------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +The ``flatten`` attribute causes calls within the attributed function to +be inlined unless it is impossible to do so, for example if the body of the +callee is unavailable or if the callee has the ``noinline`` attribute. + + +format (gnu::format) +-------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +Clang supports the ``format`` attribute, which indicates that the function +accepts a ``printf`` or ``scanf``-like format string and corresponding +arguments or a ``va_list`` that contains these arguments. + +Please see `GCC documentation about format attribute +`_ to find details +about attribute syntax. + +Clang implements two kinds of checks with this attribute. + +#. Clang checks that the function with the ``format`` attribute is called with + a format string that uses format specifiers that are allowed, and that + arguments match the format string. This is the ``-Wformat`` warning, it is + on by default. + +#. Clang checks that the format string argument is a literal string. This is + the ``-Wformat-nonliteral`` warning, it is off by default. + + Clang implements this mostly the same way as GCC, but there is a difference + for functions that accept a ``va_list`` argument (for example, ``vprintf``). + GCC does not emit ``-Wformat-nonliteral`` warning for calls to such + fuctions. Clang does not warn if the format string comes from a function + parameter, where the function is annotated with a compatible attribute, + otherwise it warns. For example: + + .. code-block:: c + + __attribute__((__format__ (__scanf__, 1, 3))) + void foo(const char* s, char *buf, ...) { + va_list ap; + va_start(ap, buf); + + vprintf(s, ap); // warning: format string is not a string literal + } + + In this case we warn because ``s`` contains a format string for a + ``scanf``-like function, but it is passed to a ``printf``-like function. + + If the attribute is removed, clang still warns, because the format string is + not a string literal. + + Another example: + + .. code-block:: c + + __attribute__((__format__ (__printf__, 1, 3))) + void foo(const char* s, char *buf, ...) { + va_list ap; + va_start(ap, buf); + + vprintf(s, ap); // warning + } + + In this case Clang does not warn because the format string ``s`` and + the corresponding arguments are annotated. If the arguments are + incorrect, the caller of ``foo`` will receive a warning. + + +noduplicate (clang::noduplicate) +-------------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +The ``noduplicate`` attribute can be placed on function declarations to control +whether function calls to this function can be duplicated or not as a result of +optimizations. This is required for the implementation of functions with +certain special requirements, like the OpenCL "barrier" function, that might +need to be run concurrently by all the threads that are executing in lockstep +on the hardware. For example this attribute applied on the function +"nodupfunc" in the code below avoids that: + +.. code-block:: c + + void nodupfunc() __attribute__((noduplicate)); + // Setting it as a C++11 attribute is also valid + // void nodupfunc() [[clang::noduplicate]]; + void foo(); + void bar(); + + nodupfunc(); + if (a > n) { + foo(); + } else { + bar(); + } + +gets possibly modified by some optimizations into code similar to this: + +.. code-block:: c + + if (a > n) { + nodupfunc(); + foo(); + } else { + nodupfunc(); + bar(); + } + +where the call to "nodupfunc" is duplicated and sunk into the two branches +of the condition. + + +no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address) +----------------------------------------------------------------------------------------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +.. _langext-address_sanitizer: + +Use ``__attribute__((no_sanitize_address))`` on a function declaration to +specify that address safety instrumentation (e.g. AddressSanitizer) should +not be applied to that function. + + +no_sanitize_memory +------------------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +.. _langext-memory_sanitizer: + +Use ``__attribute__((no_sanitize_memory))`` on a function declaration to +specify that checks for uninitialized memory should not be inserted +(e.g. by MemorySanitizer). The function may still be instrumented by the tool +to avoid false positives in other places. + + +no_sanitize_thread +------------------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +.. _langext-thread_sanitizer: + +Use ``__attribute__((no_sanitize_thread))`` on a function declaration to +specify that checks for data races on plain (non-atomic) memory accesses should +not be inserted by ThreadSanitizer. The function is still instrumented by the +tool to avoid false positives and provide meaningful stack traces. + + +no_split_stack (gnu::no_split_stack) +------------------------------------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +The ``no_split_stack`` attribute disables the emission of the split stack +preamble for a particular function. It has no effect if ``-fsplit-stack`` +is not specified. + + +objc_method_family +------------------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Many methods in Objective-C have conventional meanings determined by their +selectors. It is sometimes useful to be able to mark a method as having a +particular conventional meaning despite not having the right selector, or as +not having the conventional meaning that its selector would suggest. For these +use cases, we provide an attribute to specifically describe the "method family" +that a method belongs to. + +**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of +``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This +attribute can only be placed at the end of a method declaration: + +.. code-block:: objc + + - (NSString *)initMyStringValue __attribute__((objc_method_family(none))); + +Users who do not wish to change the conventional meaning of a method, and who +merely want to document its non-standard retain and release semantics, should +use the retaining behavior attributes (``ns_returns_retained``, +``ns_returns_not_retained``, etc). + +Query for this feature with ``__has_attribute(objc_method_family)``. + + +objc_requires_super +------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Some Objective-C classes allow a subclass to override a particular method in a +parent class but expect that the overriding method also calls the overridden +method in the parent class. For these cases, we provide an attribute to +designate that a method requires a "call to ``super``" in the overriding +method in the subclass. + +**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only +be placed at the end of a method declaration: + +.. code-block:: objc + + - (void)foo __attribute__((objc_requires_super)); + +This attribute can only be applied the method declarations within a class, and +not a protocol. Currently this attribute does not enforce any placement of +where the call occurs in the overriding method (such as in the case of +``-dealloc`` where the call must appear at the end). It checks only that it +exists. + +Note that on both OS X and iOS that the Foundation framework provides a +convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this +attribute: + +.. code-block:: objc + + - (void)foo NS_REQUIRES_SUPER; + +This macro is conditionally defined depending on the compiler's support for +this attribute. If the compiler does not support the attribute the macro +expands to nothing. + +Operationally, when a method has this annotation the compiler will warn if the +implementation of an override in a subclass does not call super. For example: + +.. code-block:: objc + + warning: method possibly missing a [super AnnotMeth] call + - (void) AnnotMeth{}; + ^ + + +optnone (clang::optnone) +------------------------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +The ``optnone`` attribute suppresses essentially all optimizations +on a function or method, regardless of the optimization level applied to +the compilation unit as a whole. This is particularly useful when you +need to debug a particular function, but it is infeasible to build the +entire application without optimization. Avoiding optimization on the +specified function can improve the quality of the debugging information +for that function. + +This attribute is incompatible with the ``always_inline`` attribute. + + +overloadable +------------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Clang provides support for C++ function overloading in C. Function overloading +in C is introduced using the ``overloadable`` attribute. For example, one +might provide several overloaded versions of a ``tgsin`` function that invokes +the appropriate standard function computing the sine of a value with ``float``, +``double``, or ``long double`` precision: + +.. code-block:: c + + #include + float __attribute__((overloadable)) tgsin(float x) { return sinf(x); } + double __attribute__((overloadable)) tgsin(double x) { return sin(x); } + long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); } + +Given these declarations, one can call ``tgsin`` with a ``float`` value to +receive a ``float`` result, with a ``double`` to receive a ``double`` result, +etc. Function overloading in C follows the rules of C++ function overloading +to pick the best overload given the call arguments, with a few C-specific +semantics: + +* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a + floating-point promotion (per C99) rather than as a floating-point conversion + (as in C++). + +* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is + considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are + compatible types. + +* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T`` + and ``U`` are compatible types. This conversion is given "conversion" rank. + +The declaration of ``overloadable`` functions is restricted to function +declarations and definitions. Most importantly, if any function with a given +name is given the ``overloadable`` attribute, then all function declarations +and definitions with that name (and in that scope) must have the +``overloadable`` attribute. This rule even applies to redeclarations of +functions whose original declaration had the ``overloadable`` attribute, e.g., + +.. code-block:: c + + int f(int) __attribute__((overloadable)); + float f(float); // error: declaration of "f" must have the "overloadable" attribute + + int g(int) __attribute__((overloadable)); + int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute + +Functions marked ``overloadable`` must have prototypes. Therefore, the +following code is ill-formed: + +.. code-block:: c + + int h() __attribute__((overloadable)); // error: h does not have a prototype + +However, ``overloadable`` functions are allowed to use a ellipsis even if there +are no named parameters (as is permitted in C++). This feature is particularly +useful when combined with the ``unavailable`` attribute: + +.. code-block:: c++ + + void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error + +Functions declared with the ``overloadable`` attribute have their names mangled +according to the same rules as C++ function names. For example, the three +``tgsin`` functions in our motivating example get the mangled names +``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two +caveats to this use of name mangling: + +* Future versions of Clang may change the name mangling of functions overloaded + in C, so you should not depend on an specific mangling. To be completely + safe, we strongly urge the use of ``static inline`` with ``overloadable`` + functions. + +* The ``overloadable`` attribute has almost no meaning when used in C++, + because names will already be mangled and functions are already overloadable. + However, when an ``overloadable`` function occurs within an ``extern "C"`` + linkage specification, it's name *will* be mangled in the same way as it + would in C. + +Query for this feature with ``__has_extension(attribute_overloadable)``. + + +pcs (gnu::pcs) +-------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +On ARM targets, this can attribute can be used to select calling conventions, +similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and +"aapcs-vfp". + + +release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability) +----------------------------------------------------------------------------------------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +Marks a function as releasing a capability. + + +try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability) +--------------------------------------------------------------------------------------------------------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +Marks a function that attempts to acquire a capability. This function may fail to +actually acquire the capability; they accept a Boolean value determining +whether acquiring the capability means success (true), or failing to acquire +the capability means success (false). + + +Variable Attributes +=================== + + +section (gnu::section, __declspec(allocate)) +-------------------------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","X","" + +The ``section`` attribute allows you to specify a specific section a +global variable or function should be in after translation. + + +tls_model (gnu::tls_model) +-------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","X","","" + +The ``tls_model`` attribute allows you to specify which thread-local storage +model to use. It accepts the following strings: + +* global-dynamic +* local-dynamic +* initial-exec +* local-exec + +TLS models are mutually exclusive. + + +thread +------ +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "","","X","" + +The ``__declspec(thread)`` attribute declares a variable with thread local +storage. It is available under the ``-fms-extensions`` flag for MSVC +compatibility. Documentation for the Visual C++ attribute is available on MSDN_. + +.. _MSDN: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx + +In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the +GNU ``__thread`` keyword. The variable must not have a destructor and must have +a constant initializer, if any. The attribute only applies to variables +declared with static storage duration, such as globals, class static data +members, and static locals. + + +Type Attributes +=============== + + +__single_inhertiance, __multiple_inheritance, __virtual_inheritance +------------------------------------------------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "","","","X" + +This collection of keywords is enabled under ``-fms-extensions`` and controls +the pointer-to-member representation used on ``*-*-win32`` targets. + +The ``*-*-win32`` targets utilize a pointer-to-member representation which +varies in size and alignment depending on the definition of the underlying +class. + +However, this is problematic when a forward declaration is only available and +no definition has been made yet. In such cases, Clang is forced to utilize the +most general representation that is available to it. + +These keywords make it possible to use a pointer-to-member representation other +than the most general one regardless of whether or not the definition will ever +be present in the current translation unit. + +This family of keywords belong between the ``class-key`` and ``class-name``: + +.. code-block:: c++ + + struct __single_inheritance S; + int S::*i; + struct S {}; + +This keyword can be applied to class templates but only has an effect when used +on full specializations: + +.. code-block:: c++ + + template struct __single_inheritance A; // warning: inheritance model ignored on primary template + template struct __multiple_inheritance A; // warning: inheritance model ignored on partial specialization + template <> struct __single_inheritance A; + +Note that choosing an inheritance model less general than strictly necessary is +an error: + +.. code-block:: c++ + + struct __multiple_inheritance S; // error: inheritance model does not match definition + int S::*i; + struct S {}; + + +Statement Attributes +==================== + + +fallthrough (clang::fallthrough) +-------------------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "","X","","" + +The ``clang::fallthrough`` attribute is used along with the +``-Wimplicit-fallthrough`` argument to annotate intentional fall-through +between switch labels. It can only be applied to a null statement placed at a +point of execution between any statement and the next switch label. It is +common to mark these places with a specific comment, but this attribute is +meant to replace comments with a more strict annotation, which can be checked +by the compiler. This attribute doesn't change semantics of the code and can +be used wherever an intended fall-through occurs. It is designed to mimic +control-flow statements like ``break;``, so it can be placed in most places +where ``break;`` can, but only if there are no statements on the execution path +between it and the next switch label. + +Here is an example: + +.. code-block:: c++ + + // compile with -Wimplicit-fallthrough + switch (n) { + case 22: + case 33: // no warning: no statements between case labels + f(); + case 44: // warning: unannotated fall-through + g(); + [[clang::fallthrough]]; + case 55: // no warning + if (x) { + h(); + break; + } + else { + i(); + [[clang::fallthrough]]; + } + case 66: // no warning + p(); + [[clang::fallthrough]]; // warning: fallthrough annotation does not + // directly precede case label + q(); + case 77: // warning: unannotated fall-through + r(); + } + + +Consumed Annotation Checking +============================ +Clang supports additional attributes for checking basic resource management +properties, specifically for unique objects that have a single owning reference. +The following attributes are currently supported, although **the implementation +for these annotations is currently in development and are subject to change.** + +callable_when +------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Use ``__attribute__((callable_when(...)))`` to indicate what states a method +may be called in. Valid states are unconsumed, consumed, or unknown. Each +argument to this attribute must be a quoted string. E.g.: + +``__attribute__((callable_when("unconsumed", "unknown")))`` + + +consumable +---------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Each ``class`` that uses any of the typestate annotations must first be marked +using the ``consumable`` attribute. Failure to do so will result in a warning. + +This attribute accepts a single parameter that must be one of the following: +``unknown``, ``consumed``, or ``unconsumed``. + + +param_typestate +--------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +This attribute specifies expectations about function parameters. Calls to an +function with annotated parameters will issue a warning if the corresponding +argument isn't in the expected state. The attribute is also used to set the +initial state of the parameter when analyzing the function's body. + + +return_typestate +---------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +The ``return_typestate`` attribute can be applied to functions or parameters. +When applied to a function the attribute specifies the state of the returned +value. The function's body is checked to ensure that it always returns a value +in the specified state. On the caller side, values returned by the annotated +function are initialized to the given state. + +When applied to a function parameter it modifies the state of an argument after +a call to the function returns. The function's body is checked to ensure that +the parameter is in the expected state before returning. + + +set_typestate +------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Annotate methods that transition an object into a new state with +``__attribute__((set_typestate(new_state)))``. The new new state must be +unconsumed, consumed, or unknown. + + +test_typestate +-------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method +returns true if the object is in the specified state.. + + +Type Safety Checking +==================== +Clang supports additional attributes to enable checking type safety properties +that can't be enforced by the C type system. Use cases include: + +* MPI library implementations, where these attributes enable checking that + the buffer type matches the passed ``MPI_Datatype``; +* for HDF5 library there is a similar use case to MPI; +* checking types of variadic functions' arguments for functions like + ``fcntl()`` and ``ioctl()``. + +You can detect support for these attributes with ``__has_attribute()``. For +example: + +.. code-block:: c++ + + #if defined(__has_attribute) + # if __has_attribute(argument_with_type_tag) && \ + __has_attribute(pointer_with_type_tag) && \ + __has_attribute(type_tag_for_datatype) + # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx))) + /* ... other macros ... */ + # endif + #endif + + #if !defined(ATTR_MPI_PWT) + # define ATTR_MPI_PWT(buffer_idx, type_idx) + #endif + + int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) + ATTR_MPI_PWT(1,3); + +argument_with_type_tag +---------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx, +type_tag_idx)))`` on a function declaration to specify that the function +accepts a type tag that determines the type of some other argument. +``arg_kind`` is an identifier that should be used when annotating all +applicable type tags. + +This attribute is primarily useful for checking arguments of variadic functions +(``pointer_with_type_tag`` can be used in most non-variadic cases). + +For example: + +.. code-block:: c++ + + int fcntl(int fd, int cmd, ...) + __attribute__(( argument_with_type_tag(fcntl,3,2) )); + + +pointer_with_type_tag +--------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))`` +on a function declaration to specify that the function accepts a type tag that +determines the pointee type of some other pointer argument. + +For example: + +.. code-block:: c++ + + int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) + __attribute__(( pointer_with_type_tag(mpi,1,3) )); + + +type_tag_for_datatype +--------------------- +.. csv-table:: Supported Syntaxes + :header: "GNU", "C++11", "__declspec", "Keyword" + + "X","","","" + +Clang supports annotating type tags of two forms. + +* **Type tag that is an expression containing a reference to some declared + identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a + declaration with that identifier: + + .. code-block:: c++ + + extern struct mpi_datatype mpi_datatype_int + __attribute__(( type_tag_for_datatype(mpi,int) )); + #define MPI_INT ((MPI_Datatype) &mpi_datatype_int) + +* **Type tag that is an integral literal.** Introduce a ``static const`` + variable with a corresponding initializer value and attach + ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration, + for example: + + .. code-block:: c++ + + #define MPI_INT ((MPI_Datatype) 42) + static const MPI_Datatype mpi_datatype_int + __attribute__(( type_tag_for_datatype(mpi,int) )) = 42 + +The attribute also accepts an optional third argument that determines how the +expression is compared to the type tag. There are two supported flags: + +* ``layout_compatible`` will cause types to be compared according to + layout-compatibility rules (C++11 [class.mem] p 17, 18). This is + implemented to support annotating types like ``MPI_DOUBLE_INT``. + + For example: + + .. code-block:: c++ + + /* In mpi.h */ + struct internal_mpi_double_int { double d; int i; }; + extern struct mpi_datatype mpi_datatype_double_int + __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) )); + + #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int) + + /* In user code */ + struct my_pair { double a; int b; }; + struct my_pair *buffer; + MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning + + struct my_int_pair { int a; int b; } + struct my_int_pair *buffer2; + MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element + // type 'struct my_int_pair' + // doesn't match specified MPI_Datatype + +* ``must_be_null`` specifies that the expression should be a null pointer + constant, for example: + + .. code-block:: c++ + + /* In mpi.h */ + extern struct mpi_datatype mpi_datatype_null + __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) )); + + #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null) + + /* In user code */ + MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL + // was specified but buffer + // is not a null pointer + + diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 8528c7af584..20a1396c487 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -22,6 +22,31 @@ if (LLVM_ENABLE_DOXYGEN) set(extra_search_mappings "") endif() + # If asked, configure doxygen for the creation of a Qt Compressed Help file. + if (LLVM_ENABLE_DOXYGEN_QT_HELP) + set(CLANG_DOXYGEN_QCH_FILENAME "org.llvm.clang.qch" CACHE STRING + "Filename of the Qt Compressed help file") + set(CLANG_DOXYGEN_QHP_NAMESPACE "org.llvm.clang" CACHE STRING + "Namespace under which the intermediate Qt Help Project file lives") + set(CLANG_DOXYGEN_QHP_CUST_FILTER_NAME "Clang ${CLANG_VERSION}" CACHE STRING + "See http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters") + set(CLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS "Clang,${CLANG_VERSION}" CACHE STRING + "See http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes") + set(clang_doxygen_generate_qhp "YES") + set(clang_doxygen_qch_filename "${CLANG_DOXYGEN_QCH_FILENAME}") + set(clang_doxygen_qhp_namespace "${CLANG_DOXYGEN_QHP_NAMESPACE}") + set(clang_doxygen_qhelpgenerator_path "${LLVM_DOXYGEN_QHELPGENERATOR_PATH}") + set(clang_doxygen_qhp_cust_filter_name "${CLANG_DOXYGEN_QHP_CUST_FILTER_NAME}") + set(clang_doxygen_qhp_cust_filter_attrs "${CLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS}") + else() + set(clang_doxygen_generate_qhp "NO") + set(clang_doxygen_qch_filename "") + set(clang_doxygen_qhp_namespace "") + set(clang_doxygen_qhelpgenerator_path "") + set(clang_doxygen_qhp_cust_filter_name "") + set(clang_doxygen_qhp_cust_filter_attrs "") + endif() + configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY) @@ -33,6 +58,12 @@ if (LLVM_ENABLE_DOXYGEN) set(enable_server_based_search) set(enable_external_search) set(extra_search_mappings) + set(clang_doxygen_generate_qhp) + set(clang_doxygen_qch_filename) + set(clang_doxygen_qhp_namespace) + set(clang_doxygen_qhelpgenerator_path) + set(clang_doxygen_qhp_cust_filter_name) + set(clang_doxygen_qhp_cust_filter_attrs) add_custom_target(doxygen-clang COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @@ -49,3 +80,12 @@ if (LLVM_ENABLE_DOXYGEN) endif() endif() endif() + +if (LLVM_ENABLE_SPHINX) + if (SPHINX_FOUND) + include(AddSphinxTarget) + if (${SPHINX_OUTPUT_HTML}) + add_sphinx_target(html clang) + endif() + endif() +endif() diff --git a/docs/ClangFormat.rst b/docs/ClangFormat.rst index bc6b8a2c41f..86c5ec5e587 100644 --- a/docs/ClangFormat.rst +++ b/docs/ClangFormat.rst @@ -146,7 +146,7 @@ shortcut in the BBEdit preferences, under Menus & Shortcuts. Visual Studio Integration ========================= -Download the latest Visual Studio plugin from the `alpha build site +Download the latest Visual Studio extension from the `alpha build site `_. The default key-binding is Ctrl-R,Ctrl-F. @@ -158,21 +158,30 @@ a unified diff and reformats all contained lines with :program:`clang-format`. .. code-block:: console - usage: clang-format-diff.py [-h] [-p P] [-style STYLE] + usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE] - Reformat changed lines in diff. + Reformat changed lines in diff. Without -i option just output the diff that + would be introduced. optional arguments: - -h, --help show this help message and exit - -p P strip the smallest prefix containing P slashes - -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla, - WebKit) + -h, --help show this help message and exit + -i apply edits to files instead of displaying a diff + -p NUM strip the smallest prefix containing P slashes + -regex PATTERN custom pattern selecting file paths to reformat + -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla, + WebKit) So to reformat all the lines in the latest :program:`git` commit, just do: .. code-block:: console - git diff -U0 HEAD^ | clang-format-diff.py -p1 + git diff -U0 HEAD^ | clang-format-diff.py -i -p1 + +In an SVN client, you can do: + +.. code-block:: console + + svn diff --diff-cmd=diff -x-U0 | clang-format-diff.py -i The :option:`-U0` will create a diff without context lines (the script would format those as well). diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst index d73801c7e73..07febaf3898 100644 --- a/docs/ClangFormatStyleOptions.rst +++ b/docs/ClangFormatStyleOptions.rst @@ -106,6 +106,25 @@ the configuration (without a prefix: ``Auto``). Allow putting all parameters of a function declaration onto the next line even if ``BinPackParameters`` is ``false``. +**AllowShortBlocksOnASingleLine** (``bool``) + Allows contracting simple braced statements to a single line. + + E.g., this allows ``if (a) { return; }`` to be put on a single line. + +**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) + Dependent on the value, ``int f() { return 0; }`` can be put + on a single line. + + Possible values: + + * ``SFS_None`` (in configuration: ``None``) + Never merge functions into a single line. + * ``SFS_Inline`` (in configuration: ``Inline``) + Only merge functions defined inside a class. + * ``SFS_All`` (in configuration: ``All``) + Merge all functions fitting on a single line. + + **AllowShortIfStatementsOnASingleLine** (``bool``) If ``true``, ``if (a) return;`` can be put on a single line. @@ -142,8 +161,15 @@ the configuration (without a prefix: ``Auto``). Like ``Attach``, but break before function definitions. * ``BS_Allman`` (in configuration: ``Allman``) Always break before braces. + * ``BS_GNU`` (in configuration: ``GNU``) + Always break before braces and add an extra level of indentation to + braces of control statements, not to those of class, function + or other definitions. +**BreakBeforeTernaryOperators** (``bool``) + If ``true``, ternary operators will be placed after line breaks. + **BreakConstructorInitializersBeforeComma** (``bool``) Always break constructor initializers before commas and align the commas with the colon. @@ -153,7 +179,11 @@ the configuration (without a prefix: ``Auto``). A column limit of ``0`` means that there is no column limit. In this case, clang-format will respect the input's line breaking decisions within - statements. + statements unless they contradict other rules. + +**CommentPragmas** (``std::string``) + A regular expression that describes comments with special meaning, + which should not be split into lines or otherwise changed. **ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``) If the constructor initializers don't fit on a line, put each @@ -163,6 +193,9 @@ the configuration (without a prefix: ``Auto``). The number of characters to use for indentation of constructor initializer lists. +**ContinuationIndentWidth** (``unsigned``) + Indent width for line continuations. + **Cpp11BracedListStyle** (``bool``) If ``true``, format braced lists as best suited for C++11 braced lists. @@ -178,8 +211,12 @@ the configuration (without a prefix: ``Auto``). the parentheses of a function call with that name. If there is no name, a zero-length name is assumed. -**DerivePointerBinding** (``bool``) - If ``true``, analyze the formatted file for the most common binding. +**DerivePointerAlignment** (``bool``) + If ``true``, analyze the formatted file for the most common + alignment of & and \*. ``PointerAlignment`` is then used only as fallback. + +**DisableFormat** (``bool``) + Disables formatting at all. **ExperimentalAutoDetectBinPacking** (``bool``) If ``true``, clang-format detects whether function calls and @@ -193,19 +230,50 @@ the configuration (without a prefix: ``Auto``). NOTE: This is an experimental flag, that might go away or be renamed. Do not use this in config files, etc. Use at your own risk. +**ForEachMacros** (``std::vector``) + A vector of macros that should be interpreted as foreach loops + instead of as function calls. + + These are expected to be macros of the form: + \code + FOREACH(, ...) + + \endcode + + For example: BOOST_FOREACH. + **IndentCaseLabels** (``bool``) Indent case labels one level from the switch statement. When ``false``, use the same indentation level as for the switch statement. Switch statement body is always indented one level more than case labels. -**IndentFunctionDeclarationAfterType** (``bool``) - If ``true``, indent when breaking function declarations which - are not also definitions after the type. - **IndentWidth** (``unsigned``) The number of columns to use for indentation. +**IndentWrappedFunctionNames** (``bool``) + Indent if a function definition or declaration is wrapped after the + type. + +**KeepEmptyLinesAtTheStartOfBlocks** (``bool``) + If true, empty lines at the start of blocks are kept. + +**Language** (``LanguageKind``) + Language, this format style is targeted at. + + Possible values: + + * ``LK_None`` (in configuration: ``None``) + Do not use. + * ``LK_Cpp`` (in configuration: ``Cpp``) + Should be used for C, C++, ObjectiveC, ObjectiveC++. + * ``LK_JavaScript`` (in configuration: ``JavaScript``) + Should be used for JavaScript. + * ``LK_Proto`` (in configuration: ``Proto``) + Should be used for Protocol Buffers + (https://developers.google.com/protocol-buffers/). + + **MaxEmptyLinesToKeep** (``unsigned``) The maximum number of consecutive empty lines to keep. @@ -222,10 +290,17 @@ the configuration (without a prefix: ``Auto``). Indent in all namespaces. +**ObjCSpaceAfterProperty** (``bool``) + Add a space after ``@property`` in Objective-C, i.e. use + ``\@property (readonly)`` instead of ``\@property(readonly)``. + **ObjCSpaceBeforeProtocolList** (``bool``) Add a space in front of an Objective-C protocol list, i.e. use ``Foo `` instead of ``Foo``. +**PenaltyBreakBeforeFirstCallParameter** (``unsigned``) + The penalty for breaking a function call after "call(". + **PenaltyBreakComment** (``unsigned``) The penalty for each line break introduced inside a comment. @@ -242,28 +317,62 @@ the configuration (without a prefix: ``Auto``). Penalty for putting the return type of a function onto its own line. -**PointerBindsToType** (``bool``) - Set whether & and * bind to the type as opposed to the variable. +**PointerAlignment** (``PointerAlignmentStyle``) + Pointer and reference alignment style. + + Possible values: + + * ``PAS_Left`` (in configuration: ``Left``) + Align pointer to the left. + * ``PAS_Right`` (in configuration: ``Right``) + Align pointer to the right. + * ``PAS_Middle`` (in configuration: ``Middle``) + Align pointer in the middle. -**SpaceAfterControlStatementKeyword** (``bool``) - If ``true``, spaces will be inserted between 'for'/'if'/'while'/... - and '('. **SpaceBeforeAssignmentOperators** (``bool``) If ``false``, spaces will be removed before assignment operators. +**SpaceBeforeParens** (``SpaceBeforeParensOptions``) + Defines in which cases to put a space before opening parentheses. + + Possible values: + + * ``SBPO_Never`` (in configuration: ``Never``) + Never put a space before opening parentheses. + * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``) + Put a space before opening parentheses only after control statement + keywords (``for/if/while...``). + * ``SBPO_Always`` (in configuration: ``Always``) + Always put a space before opening parentheses, except when it's + prohibited by the syntax rules (in function-like macro definitions) or + when determined by other style rules (after unary operators, opening + parentheses, etc.) + + **SpaceInEmptyParentheses** (``bool``) - If ``false``, spaces may be inserted into '()'. + If ``true``, spaces may be inserted into '()'. **SpacesBeforeTrailingComments** (``unsigned``) - The number of spaces to before trailing line comments. + The number of spaces before trailing line comments + (``//`` - comments). + + This does not affect trailing block comments (``/**/`` - comments) as those + commonly have different usage patterns and a number of special cases. + +**SpacesInAngles** (``bool``) + If ``true``, spaces will be inserted after '<' and before '>' in + template argument lists **SpacesInCStyleCastParentheses** (``bool``) - If ``false``, spaces may be inserted into C style casts. + If ``true``, spaces may be inserted into C style casts. + +**SpacesInContainerLiterals** (``bool``) + If ``true``, spaces are inserted inside container literals (e.g. + ObjC and Javascript array and dict literals). **SpacesInParentheses** (``bool``) - If ``true``, spaces will be inserted after every '(' and before - every ')'. + If ``true``, spaces will be inserted after '(' and before ')'. **Standard** (``LanguageStandard``) Format compatible with this standard, e.g. use diff --git a/docs/ClangPlugins.rst b/docs/ClangPlugins.rst index 7c5c65ccf1d..9a5bc142130 100644 --- a/docs/ClangPlugins.rst +++ b/docs/ClangPlugins.rst @@ -47,70 +47,10 @@ Putting it all together ======================= Let's look at an example plugin that prints top-level function names. This -example is also checked into the clang repository; please also take a look at -the latest `checked in version of PrintFunctionNames.cpp +example is checked into the clang repository; please take a look at +the `latest version of PrintFunctionNames.cpp `_. -.. code-block:: c++ - - #include "clang/Frontend/FrontendPluginRegistry.h" - #include "clang/AST/ASTConsumer.h" - #include "clang/AST/AST.h" - #include "clang/Frontend/CompilerInstance.h" - #include "llvm/Support/raw_ostream.h" - using namespace clang; - - namespace { - - class PrintFunctionsConsumer : public ASTConsumer { - public: - virtual bool HandleTopLevelDecl(DeclGroupRef DG) { - for (DeclGroupRef::iterator i = DG.begin(), e = DG.end(); i != e; ++i) { - const Decl *D = *i; - if (const NamedDecl *ND = dyn_cast(D)) - llvm::errs() << "top-level-decl: \"" << ND->getNameAsString() << "\"\n"; - } - - return true; - } - }; - - class PrintFunctionNamesAction : public PluginASTAction { - protected: - ASTConsumer *CreateASTConsumer(CompilerInstance &CI, llvm::StringRef) { - return new PrintFunctionsConsumer(); - } - - bool ParseArgs(const CompilerInstance &CI, - const std::vector& args) { - for (unsigned i = 0, e = args.size(); i != e; ++i) { - llvm::errs() << "PrintFunctionNames arg = " << args[i] << "\n"; - - // Example error handling. - if (args[i] == "-an-error") { - DiagnosticsEngine &D = CI.getDiagnostics(); - unsigned DiagID = D.getCustomDiagID( - DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'"); - D.Report(DiagID); - return false; - } - } - if (args.size() && args[0] == "help") - PrintHelp(llvm::errs()); - - return true; - } - void PrintHelp(llvm::raw_ostream& ros) { - ros << "Help for PrintFunctionNames plugin goes here\n"; - } - - }; - - } - - static FrontendPluginRegistry::Add - X("print-fns", "print function names"); - Running the plugin ================== diff --git a/docs/ClangTools.rst b/docs/ClangTools.rst index f8a7c366dba..8957541c250 100644 --- a/docs/ClangTools.rst +++ b/docs/ClangTools.rst @@ -93,9 +93,9 @@ as a user tool (ideally with powerful IDE integrations) and as part of other refactoring tools, e.g. to do a reformatting of all the lines changed during a renaming. -``cpp11-migrate`` -~~~~~~~~~~~~~~~~~ -``cpp11-migrate`` migrates C++ code to use C++11 features where appropriate. +``clang-modernize`` +~~~~~~~~~~~~~~~~~~~ +``clang-modernize`` migrates C++ code to use C++11 features where appropriate. Currently it can: * convert loops to range-based for loops; diff --git a/docs/CrossCompilation.rst b/docs/CrossCompilation.rst index e655d8920ad..89f8777ac07 100644 --- a/docs/CrossCompilation.rst +++ b/docs/CrossCompilation.rst @@ -190,7 +190,7 @@ Multilibs When you want to cross-compile to more than one configuration, for example hard-float-ARM and soft-float-ARM, you'll have to have multiple -copies of you libraries and (possibly) headers. +copies of your libraries and (possibly) headers. Some Linux distributions have support for Multilib, which handle that for you in an easier way, but if you're not careful and, for instance, diff --git a/docs/ExternalClangExamples.rst b/docs/ExternalClangExamples.rst index c7fd4c51faa..71d50c23fa1 100644 --- a/docs/ExternalClangExamples.rst +++ b/docs/ExternalClangExamples.rst @@ -78,3 +78,10 @@ List of projects and tools "cldoc is a Clang based documentation generator for C and C++. cldoc tries to solve the issue of writing C/C++ software documentation with a modern, non-intrusive and robust approach." + +``_ + "The simplest Clang plugin implementing a semantic check for Objective-C. + This example shows how to use the ``DiagnosticsEngine`` (emit warnings, + errors, fixit hints). See also ``_ for + step-by-step instructions." + diff --git a/docs/InternalsManual.rst b/docs/InternalsManual.rst index 6f5570263fc..8e047dbdae7 100644 --- a/docs/InternalsManual.rst +++ b/docs/InternalsManual.rst @@ -87,7 +87,8 @@ start with ``err_``, ``warn_``, ``ext_`` to encode the severity into the name. Since the enum is referenced in the C++ code that produces the diagnostic, it is somewhat useful for it to be reasonably short. -The severity of the diagnostic comes from the set {``NOTE``, ``WARNING``, +The severity of the diagnostic comes from the set {``NOTE``, ``REMARK``, +``WARNING``, ``EXTENSION``, ``EXTWARN``, ``ERROR``}. The ``ERROR`` severity is used for diagnostics indicating the program is never acceptable under any circumstances. When an error is emitted, the AST for the input code may not be fully built. @@ -97,11 +98,13 @@ represent them in the AST, but we produce diagnostics to tell the user their code is non-portable. The difference is that the former are ignored by default, and the later warn by default. The ``WARNING`` severity is used for constructs that are valid in the currently selected source language but that -are dubious in some way. The ``NOTE`` level is used to staple more information -onto previous diagnostics. +are dubious in some way. The ``REMARK`` severity provides generic information +about the compilation that is not necessarily related to any dubious code. The +``NOTE`` level is used to staple more information onto previous diagnostics. These *severities* are mapped into a smaller set (the ``Diagnostic::Level`` -enum, {``Ignored``, ``Note``, ``Warning``, ``Error``, ``Fatal``}) of output +enum, {``Ignored``, ``Note``, ``Remark``, ``Warning``, ``Error``, ``Fatal``}) of +output *levels* by the diagnostics subsystem based on various configuration options. Clang internally supports a fully fine grained mapping mechanism that allows you to map almost any diagnostic to the output level that you want. The only @@ -1588,47 +1591,171 @@ How to change Clang How to add an attribute ----------------------- -To add an attribute, you'll have to add it to the list of attributes, add it to -the parsing phase, and look for it in the AST scan. -`r124217 `_ -has a good example of adding a warning attribute. +Attribute Basics +^^^^^^^^^^^^^^^^ -(Beware that this hasn't been reviewed/fixed by the people who designed the -attributes system yet.) +Attributes in clang come in two forms: parsed form, and semantic form. Both +forms are represented via a tablegen definition of the attribute, specified in +Attr.td. ``include/clang/Basic/Attr.td`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -First, add your attribute to the `include/clang/Basic/Attr.td file -`_. +First, add your attribute to the `include/clang/Basic/Attr.td +`_ +file. Each attribute gets a ``def`` inheriting from ``Attr`` or one of its subclasses. ``InheritableAttr`` means that the attribute also applies to -subsequent declarations of the same name. +subsequent declarations of the same name. ``InheritableParamAttr`` is similar +to ``InheritableAttr``, except that the attribute is written on a parameter +instead of a declaration, type or statement. Attributes inheriting from +``TypeAttr`` are pure type attributes which generally are not given a +representation in the AST. Attributes inheriting from ``TargetSpecificAttr`` +are attributes specific to one or more target architectures. An attribute that +inherits from ``IgnoredAttr`` is parsed, but will generate an ignored attribute +diagnostic when used. The attribute type may be useful when an attribute is +supported by another vendor, but not supported by clang. ``Spellings`` lists the strings that can appear in ``__attribute__((here))`` or -``[[here]]``. All such strings will be synonymous. If you want to allow the -``[[]]`` C++11 syntax, you have to define a list of ``Namespaces``, which will -let users write ``[[namespace::spelling]]``. Using the empty string for a -namespace will allow users to write just the spelling with no "``::``". -Attributes which g++-4.8 accepts should also have a -``CXX11<"gnu", "spelling">`` spelling. +``[[here]]``. All such strings will be synonymous. Possible ``Spellings`` +are: ``GNU`` (for use with GNU-style __attribute__ spellings), ``Declspec`` +(for use with Microsoft Visual Studio-style __declspec spellings), ``CXX11` +(for use with C++11-style [[foo]] and [[foo::bar]] spellings), and ``Keyword`` +(for use with attributes that are implemented as keywords, like C++11's +``override`` or ``final``). If you want to allow the ``[[]]`` C++11 syntax, you +have to define a list of ``Namespaces``, which will let users write +``[[namespace::spelling]]``. Using the empty string for a namespace will allow +users to write just the spelling with no "``::``". Attributes which g++-4.8 +or later accepts should also have a ``CXX11<"gnu", "spelling">`` spelling. ``Subjects`` restricts what kinds of AST node to which this attribute can -appertain (roughly, attach). +appertain (roughly, attach). The subjects are specified via a ``SubjectList``, +which specify the list of subjects. Additionally, subject-related diagnostics +can be specified to be warnings or errors, with the default being a warning. +The diagnostics displayed to the user are automatically determined based on +the subjects in the list, but a custom diagnostic parameter can also be +specified in the ``SubjectList``. The diagnostics generated for subject list +violations are either ``diag::warn_attribute_wrong_decl_type`` or +``diag::err_attribute_wrong_decl_type``, and the parameter enumeration is +found in `include/clang/Sema/AttributeList.h +`_ +If you add new Decl nodes to the ``SubjectList``, you may need to update the +logic used to automatically determine the diagnostic parameter in `utils/TableGen/ClangAttrEmitter.cpp +`_. + +Diagnostic checking for attribute subject lists is automated except when +``HasCustomParsing`` is set to ``1``. + +By default, all subjects in the SubjectList must either be a Decl node defined +in ``DeclNodes.td``, or a statement node defined in ``StmtNodes.td``. However, +more complex subjects can be created by creating a ``SubsetSubject`` object. +Each such object has a base subject which it appertains to (which must be a +Decl or Stmt node, and not a SubsetSubject node), and some custom code which is +called when determining whether an attribute appertains to the subject. For +instance, a ``NonBitField`` SubsetSubject appertains to a ``FieldDecl``, and +tests whether the given FieldDecl is a bit field. When a SubsetSubject is +specified in a SubjectList, a custom diagnostic parameter must also be provided. ``Args`` names the arguments the attribute takes, in order. If ``Args`` is ``[StringArgument<"Arg1">, IntArgument<"Arg2">]`` then -``__attribute__((myattribute("Hello", 3)))`` will be a valid use. +``__attribute__((myattribute("Hello", 3)))`` will be a valid use. Attribute +arguments specify both the parsed form and the semantic form of the attribute. +The previous example shows an attribute which requires two attributes while +parsing, and the Attr subclass' constructor for the attribute will require a +string and integer argument. + +Diagnostic checking for argument counts is automated except when +``HasCustomParsing`` is set to ``1``, or when the attribute uses an optional or +variadic argument. Diagnostic checking for argument semantics is not automated. + +If the parsed form of the attribute is more complex, or differs from the +semantic form, the ``HasCustomParsing`` bit can be set to ``1`` for the class, +and the parsing code in `Parser::ParseGNUAttributeArgs +`_ +can be updated for the special case. Note that this only applies to arguments +with a GNU spelling -- attributes with a __declspec spelling currently ignore +this flag and are handled by ``Parser::ParseMicrosoftDeclSpec``. + +Custom accessors can be generated for an attribute based on the spelling list +for that attribute. For instance, if an attribute has two different spellings: +'Foo' and 'Bar', accessors can be created: +``[Accessor<"isFoo", [GNU<"Foo">]>, Accessor<"isBar", [GNU<"Bar">]>]`` +These accessors will be generated on the semantic form of the attribute, +accepting no arguments and returning a Boolean. + +Attributes which do not require an AST node should set the ``ASTNode`` field to +``0`` to avoid polluting the AST. Note that anything inheriting from +``TypeAttr`` or ``IgnoredAttr`` automatically do not generate an AST node. All +other attributes generate an AST node by default. The AST node is the semantic +representation of the attribute. + +Attributes which do not require custom semantic handling should set the +``SemaHandler`` field to ``0``. Note that anything inheriting from +``IgnoredAttr`` automatically do not get a semantic handler. All other +attributes are assumed to use a semantic handler by default. Attributes +without a semantic handler are not given a parsed attribute Kind enumeration. + +The ``LangOpts`` field can be used to specify a list of language options +required by the attribute. For instance, all of the CUDA-specific attributes +specify ``[CUDA]`` for the ``LangOpts`` field, and when the CUDA language +option is not enabled, an "attribute ignored" warning diagnostic is emitted. +Since language options are not table generated nodes, new language options must +be created manually and should specify the spelling used by ``LangOptions`` class. + +Target-specific attribute sometimes share a spelling with other attributes in +different targets. For instance, the ARM and MSP430 targets both have an +attribute spelled ``GNU<"interrupt">``, but with different parsing and semantic +requirements. To support this feature, an attribute inheriting from +``TargetSpecificAttribute`` make specify a ``ParseKind`` field. This field +should be the same value between all arguments sharing a spelling, and +corresponds to the parsed attribute's Kind enumeration. This allows attributes +to share a parsed attribute kind, but have distinct semantic attribute classes. +For instance, ``AttributeList::AT_Interrupt`` is the shared parsed attribute +kind, but ARMInterruptAttr and MSP430InterruptAttr are the semantic attributes +generated. + +By default, when declarations are merging attributes, an attribute will not be +duplicated. However, if an attribute can be duplicated during this merging +stage, set ``DuplicatesAllowedWhileMerging`` to ``1``, and the attribute will +be merged. + +By default, attribute arguments are parsed in an evaluated context. If the +arguments for an attribute should be parsed in an unevaluated context (akin to +the way the argument to a ``sizeof`` expression is parsed), you can set +``ParseArgumentsAsUnevaluated`` to ``1``. + +If additional functionality is desired for the semantic form of the attribute, +the ``AdditionalMembers`` field specifies code to be copied verbatim into the +semantic attribute class object. + +All attributes must have one or more form of documentation, which is provided +in the ``Documentation`` list. Generally, the documentation for an attribute +is a stand-alone definition in `include/clang/Basic/AttrDocs.td +`_ +that is named after the attribute being documented. Each documentation element +is given a ``Category`` (variable, function, or type) and ``Content``. A single +attribute may contain multiple documentation elements for distinct categories. +For instance, an attribute which can appertain to both function and types (such +as a calling convention attribute), should contain two documentation elements. +The ``Content`` for an attribute uses reStructuredText (RST) syntax. + +If an attribute is used internally by the compiler, but is not written by users +(such as attributes with an empty spelling list), it can use the +``Undocumented`` documentation element. Boilerplate ^^^^^^^^^^^ -Write a new ``HandleYourAttr()`` function in `lib/Sema/SemaDeclAttr.cpp -`_, -and add a case to the switch in ``ProcessNonInheritableDeclAttr()`` or -``ProcessInheritableDeclAttr()`` forwarding to it. +All semantic processing of declaration attributes happens in `lib/Sema/SemaDeclAttr.cpp +`_, +and generally starts in the ``ProcessDeclAttribute`` function. If your +attribute is a "simple" attribute -- meaning that it requires no custom +semantic processing aside from what is automatically provided for you, you can +add a call to ``handleSimpleAttribute(S, D, Attr);`` to the switch +statement. Otherwise, write a new ``handleYourAttr()`` function, and add that +to the switch statement. If your attribute causes extra warnings to fire, define a ``DiagGroup`` in `include/clang/Basic/DiagnosticGroups.td @@ -1638,6 +1765,10 @@ only defining one diagnostic, you can skip ``DiagnosticGroups.td`` and use ``InGroup>`` directly in `DiagnosticSemaKinds.td `_ +All semantic diagnostics generated for your attribute, including automatically- +generated ones (such as subjects and argument counts), should have a +corresponding test case. + The meat of your attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1721,13 +1852,14 @@ are similar. * Make sure that ``children()`` visits all of the subexpressions. This is important for a number of features (e.g., IDE support, C++ variadic templates). If you have sub-types, you'll also need to visit those - sub-types in the ``RecursiveASTVisitor``. - * Add printing support (``StmtPrinter.cpp``) and dumping support - (``StmtDumper.cpp``) for your expression. + sub-types in ``RecursiveASTVisitor`` and ``DataRecursiveASTVisitor``. + * Add printing support (``StmtPrinter.cpp``) for your expression. * Add profiling support (``StmtProfile.cpp``) for your AST node, noting the distinguishing (non-source location) characteristics of an instance of your expression. Omitting this step will lead to hard-to-diagnose failures regarding matching of template declarations. + * Add serialization support (``ASTReaderStmt.cpp``, ``ASTWriterStmt.cpp``) + for your AST node. #. Teach semantic analysis to build your AST node. At this point, you can wire up your ``Sema::BuildXXX`` function to actually create your AST. A few diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst index ca1b7ea364a..35f759f4cf9 100644 --- a/docs/LanguageExtensions.rst +++ b/docs/LanguageExtensions.rst @@ -12,7 +12,7 @@ Clang Language Extensions ObjectiveCLiterals BlockLanguageSpec Block-ABI-Apple - AutomaticReferenceCounting + AutomaticReferenceCounting Introduction ============ @@ -91,7 +91,7 @@ feature) or 0 if not. They can be used like this: .. _langext-has-feature-back-compat: -For backwards compatibility reasons, ``__has_feature`` can also be used to test +For backward compatibility, ``__has_feature`` can also be used to test for support for non-standardized features, i.e. features not prefixed ``c_``, ``cxx_`` or ``objc_``. @@ -113,8 +113,8 @@ of ``cxx_rvalue_references``. ------------------- This function-like macro takes a single identifier argument that is the name of -an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It -can be used like this: +an attribute. It evaluates to 1 if the attribute is supported by the current +compilation target, or 0 if not. It can be used like this: .. code-block:: c++ @@ -134,6 +134,27 @@ The attribute name can also be specified with a preceding and following ``__`` (double underscore) to avoid interference from a macro with the same name. For instance, ``__always_inline__`` can be used instead of ``always_inline``. +``__is_identifier`` +------------------- + +This function-like macro takes a single identifier argument that might be either +a reserved word or a regular identifier. It evaluates to 1 if the argument is just +a regular identifier and not a reserved word, in the sense that it can then be +used as the name of a user-defined function or variable. Otherwise it evaluates +to 0. It can be used like this: + +.. code-block:: c++ + + ... + #ifdef __is_identifier // Compatibility with non-clang compilers. + #if __is_identifier(__wchar_t) + typedef wchar_t __wchar_t; + #endif + #endif + + __wchar_t WideCharacter; + ... + Include File Checking Macros ============================ @@ -425,103 +446,6 @@ should be treated as a system framework, regardless of how it was found in the framework search path. For consistency, we recommend that such files never be included in installed versions of the framework. -Availability attribute -====================== - -Clang introduces the ``availability`` attribute, which can be placed on -declarations to describe the lifecycle of that declaration relative to -operating system versions. Consider the function declaration for a -hypothetical function ``f``: - -.. code-block:: c++ - - void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7))); - -The availability attribute states that ``f`` was introduced in Mac OS X 10.4, -deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information -is used by Clang to determine when it is safe to use ``f``: for example, if -Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()`` -succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call -succeeds but Clang emits a warning specifying that the function is deprecated. -Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call -fails because ``f()`` is no longer available. - -The availability attribute is a comma-separated list starting with the -platform name and then including clauses specifying important milestones in the -declaration's lifetime (in any order) along with additional information. Those -clauses can be: - -introduced=\ *version* - The first version in which this declaration was introduced. - -deprecated=\ *version* - The first version in which this declaration was deprecated, meaning that - users should migrate away from this API. - -obsoleted=\ *version* - The first version in which this declaration was obsoleted, meaning that it - was removed completely and can no longer be used. - -unavailable - This declaration is never available on this platform. - -message=\ *string-literal* - Additional message text that Clang will provide when emitting a warning or - error about use of a deprecated or obsoleted declaration. Useful to direct - users to replacement APIs. - -Multiple availability attributes can be placed on a declaration, which may -correspond to different platforms. Only the availability attribute with the -platform corresponding to the target platform will be used; any others will be -ignored. If no availability attribute specifies availability for the current -target platform, the availability attributes are ignored. Supported platforms -are: - -``ios`` - Apple's iOS operating system. The minimum deployment target is specified by - the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*`` - command-line arguments. - -``macosx`` - Apple's Mac OS X operating system. The minimum deployment target is - specified by the ``-mmacosx-version-min=*version*`` command-line argument. - -A declaration can be used even when deploying back to a platform version prior -to when the declaration was introduced. When this happens, the declaration is -`weakly linked -`_, -as if the ``weak_import`` attribute were added to the declaration. A -weakly-linked declaration may or may not be present a run-time, and a program -can determine whether the declaration is present by checking whether the -address of that declaration is non-NULL. - -If there are multiple declarations of the same entity, the availability -attributes must either match on a per-platform basis or later -declarations must not have availability attributes for that -platform. For example: - -.. code-block:: c - - void g(void) __attribute__((availability(macosx,introduced=10.4))); - void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches - void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform - void g(void); // okay, inherits both macosx and ios availability from above. - void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch - -When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,: - -.. code-block:: objc - - @interface A - - (id)method __attribute__((availability(macosx,introduced=10.4))); - - (id)method2 __attribute__((availability(macosx,introduced=10.4))); - @end - - @interface B : A - - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later - - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4 - @end - Checks for Standard Language Features ===================================== @@ -826,20 +750,18 @@ for default initializers in aggregate members is enabled. C++1y generalized lambda capture ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Use ``__has_feature(cxx_init_capture)`` or -``__has_extension(cxx_init_capture)`` to determine if support for +Use ``__has_feature(cxx_init_captures)`` or +``__has_extension(cxx_init_captures)`` to determine if support for lambda captures with explicit initializers is enabled (for instance, ``[n(0)] { return ++n; }``). -Clang does not yet support this feature. C++1y generic lambdas ^^^^^^^^^^^^^^^^^^^^^ -Use ``__has_feature(cxx_generic_lambda)`` or -``__has_extension(cxx_generic_lambda)`` to determine if support for generic +Use ``__has_feature(cxx_generic_lambdas)`` or +``__has_extension(cxx_generic_lambdas)`` to determine if support for generic (polymorphic) lambdas is enabled (for instance, ``[] (auto x) { return x + 1; }``). -Clang does not yet support this feature. C++1y relaxed constexpr ^^^^^^^^^^^^^^^^^^^^^^^ @@ -872,7 +794,6 @@ C++1y variable templates Use ``__has_feature(cxx_variable_templates)`` or ``__has_extension(cxx_variable_templates)`` to determine if support for templated variable declarations is enabled. -Clang does not yet support this feature. C11 --- @@ -924,15 +845,33 @@ C11 ``_Thread_local`` Use ``__has_feature(c_thread_local)`` or ``__has_extension(c_thread_local)`` to determine if support for ``_Thread_local`` variables is enabled. -Checks for Type Traits -====================== +Checks for Type Trait Primitives +================================ + +Type trait primitives are special builtin constant expressions that can be used +by the standard C++ library to facilitate or simplify the implementation of +user-facing type traits in the header. + +They are not intended to be used directly by user code because they are +implementation-defined and subject to change -- as such they're tied closely to +the supported set of system headers, currently: + +* LLVM's own libc++ +* GNU libstdc++ +* The Microsoft standard C++ library Clang supports the `GNU C++ type traits `_ and a subset of the `Microsoft Visual C++ Type traits -`_. For each -supported type trait ``__X``, ``__has_extension(X)`` indicates the presence of -the type trait. For example: +`_. + +Feature detection is supported only for some of the primitives at present. User +code should not use these checks because they bear no direct relation to the +actual set of type traits supported by the C++ standard library. + +For type trait ``__X``, ``__has_extension(X)`` indicates the presence of the +type trait primitive in the compiler. A simplistic usage example as might be +seen in standard C++ headers follows: .. code-block:: c++ @@ -942,10 +881,10 @@ the type trait. For example: static const bool value = __is_convertible_to(From, To); }; #else - // Emulate type trait + // Emulate type trait for compatibility with other compilers. #endif -The following type traits are supported by Clang: +The following type trait primitives are supported by Clang: * ``__has_nothrow_assign`` (GNU, Microsoft) * ``__has_nothrow_copy`` (GNU, Microsoft) @@ -980,6 +919,11 @@ The following type traits are supported by Clang: ``argtypes...`` such that no non-trivial functions are called as part of that initialization. This trait is required to implement the C++11 standard library. +* ``__is_destructible`` (MSVC 2013): partially implemented +* ``__is_nothrow_destructible`` (MSVC 2013): partially implemented +* ``__is_nothrow_assignable`` (MSVC 2013, clang) +* ``__is_constructible`` (MSVC 2013, clang) +* ``__is_nothrow_constructible`` (MSVC 2013, clang) Blocks ====== @@ -1174,77 +1118,6 @@ feature, clang provides default synthesis of those properties not declared ``__has_feature(objc_default_synthesize_properties)`` checks for availability of this feature in version of clang being used. -.. _langext-objc_method_family: - - -Objective-C requiring a call to ``super`` in an override --------------------------------------------------------- - -Some Objective-C classes allow a subclass to override a particular method in a -parent class but expect that the overriding method also calls the overridden -method in the parent class. For these cases, we provide an attribute to -designate that a method requires a "call to ``super``" in the overriding -method in the subclass. - -**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only -be placed at the end of a method declaration: - -.. code-block:: objc - - - (void)foo __attribute__((objc_requires_super)); - -This attribute can only be applied the method declarations within a class, and -not a protocol. Currently this attribute does not enforce any placement of -where the call occurs in the overriding method (such as in the case of -``-dealloc`` where the call must appear at the end). It checks only that it -exists. - -Note that on both OS X and iOS that the Foundation framework provides a -convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this -attribute: - -.. code-block:: objc - - - (void)foo NS_REQUIRES_SUPER; - -This macro is conditionally defined depending on the compiler's support for -this attribute. If the compiler does not support the attribute the macro -expands to nothing. - -Operationally, when a method has this annotation the compiler will warn if the -implementation of an override in a subclass does not call super. For example: - -.. code-block:: objc - - warning: method possibly missing a [super AnnotMeth] call - - (void) AnnotMeth{}; - ^ - -Objective-C Method Families ---------------------------- - -Many methods in Objective-C have conventional meanings determined by their -selectors. It is sometimes useful to be able to mark a method as having a -particular conventional meaning despite not having the right selector, or as -not having the conventional meaning that its selector would suggest. For these -use cases, we provide an attribute to specifically describe the "method family" -that a method belongs to. - -**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of -``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This -attribute can only be placed at the end of a method declaration: - -.. code-block:: objc - - - (NSString *)initMyStringValue __attribute__((objc_method_family(none))); - -Users who do not wish to change the conventional meaning of a method, and who -merely want to document its non-standard retain and release semantics, should -use the :ref:`retaining behavior attributes ` -described below. - -Query for this feature with ``__has_attribute(objc_method_family)``. - .. _langext-objc-retain-release: Objective-C retaining behavior attributes @@ -1257,8 +1130,7 @@ conventions for ownership of object arguments and return values. However, there are exceptions, and so Clang provides attributes to allow these exceptions to be documented. This are used by ARC and the `static analyzer `_ Some exceptions may be -better described using the :ref:`objc_method_family -` attribute instead. +better described using the ``objc_method_family`` attribute instead. **Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``, ``ns_returns_autoreleased``, ``cf_returns_retained``, and @@ -1315,87 +1187,7 @@ parameters of protocol-qualified type. Query the presence of this new mangling with ``__has_feature(objc_protocol_qualifier_mangling)``. -Function Overloading in C -========================= - -Clang provides support for C++ function overloading in C. Function overloading -in C is introduced using the ``overloadable`` attribute. For example, one -might provide several overloaded versions of a ``tgsin`` function that invokes -the appropriate standard function computing the sine of a value with ``float``, -``double``, or ``long double`` precision: - -.. code-block:: c - - #include - float __attribute__((overloadable)) tgsin(float x) { return sinf(x); } - double __attribute__((overloadable)) tgsin(double x) { return sin(x); } - long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); } - -Given these declarations, one can call ``tgsin`` with a ``float`` value to -receive a ``float`` result, with a ``double`` to receive a ``double`` result, -etc. Function overloading in C follows the rules of C++ function overloading -to pick the best overload given the call arguments, with a few C-specific -semantics: - -* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a - floating-point promotion (per C99) rather than as a floating-point conversion - (as in C++). - -* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is - considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are - compatible types. - -* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T`` - and ``U`` are compatible types. This conversion is given "conversion" rank. - -The declaration of ``overloadable`` functions is restricted to function -declarations and definitions. Most importantly, if any function with a given -name is given the ``overloadable`` attribute, then all function declarations -and definitions with that name (and in that scope) must have the -``overloadable`` attribute. This rule even applies to redeclarations of -functions whose original declaration had the ``overloadable`` attribute, e.g., - -.. code-block:: c - - int f(int) __attribute__((overloadable)); - float f(float); // error: declaration of "f" must have the "overloadable" attribute - - int g(int) __attribute__((overloadable)); - int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute - -Functions marked ``overloadable`` must have prototypes. Therefore, the -following code is ill-formed: - -.. code-block:: c - - int h() __attribute__((overloadable)); // error: h does not have a prototype - -However, ``overloadable`` functions are allowed to use a ellipsis even if there -are no named parameters (as is permitted in C++). This feature is particularly -useful when combined with the ``unavailable`` attribute: - -.. code-block:: c++ - - void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error - -Functions declared with the ``overloadable`` attribute have their names mangled -according to the same rules as C++ function names. For example, the three -``tgsin`` functions in our motivating example get the mangled names -``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two -caveats to this use of name mangling: - -* Future versions of Clang may change the name mangling of functions overloaded - in C, so you should not depend on an specific mangling. To be completely - safe, we strongly urge the use of ``static inline`` with ``overloadable`` - functions. - -* The ``overloadable`` attribute has almost no meaning when used in C++, - because names will already be mangled and functions are already overloadable. - However, when an ``overloadable`` function occurs within an ``extern "C"`` - linkage specification, it's name *will* be mangled in the same way as it - would in C. - -Query for this feature with ``__has_extension(attribute_overloadable)``. +.. _langext-overloading: Initializer lists for complex numbers in C ========================================== @@ -1654,6 +1446,24 @@ object that overloads ``operator&``. return __builtin_addressof(value); } +``__builtin_operator_new`` and ``__builtin_operator_delete`` +------------------------------------------------------------ + +``__builtin_operator_new`` allocates memory just like a non-placement non-class +*new-expression*. This is exactly like directly calling the normal +non-placement ``::operator new``, except that it allows certain optimizations +that the C++ standard does not permit for a direct function call to +``::operator new`` (in particular, removing ``new`` / ``delete`` pairs and +merging allocations). + +Likewise, ``__builtin_operator_delete`` deallocates memory just like a +non-class *delete-expression*, and is exactly like directly calling the normal +``::operator delete``, except that it permits optimizations. Only the unsized +form of ``__builtin_operator_delete`` is currently available. + +These builtins are intended for use in the implementation of ``std::allocator`` +and other similar allocation libraries, and are only available in C++. + Multiprecision Arithmetic Builtins ---------------------------------- @@ -1770,20 +1580,22 @@ instructions for implementing atomic operations. .. code-block:: c T __builtin_arm_ldrex(const volatile T *addr); + T __builtin_arm_ldaex(const volatile T *addr); int __builtin_arm_strex(T val, volatile T *addr); + int __builtin_arm_stlex(T val, volatile T *addr); void __builtin_arm_clrex(void); The types ``T`` currently supported are: -* Integer types with width at most 64 bits. +* Integer types with width at most 64 bits (or 128 bits on AArch64). * Floating-point types * Pointer types. Note that the compiler does not guarantee it will not insert stores which clear -the exclusive monitor in between an ``ldrex`` and its paired ``strex``. In -practice this is only usually a risk when the extra store is on the same cache -line as the variable being modified and Clang will only insert stack stores on -its own, so it is best not to use these operations on variables with automatic -storage duration. +the exclusive monitor in between an ``ldrex`` type operation and its paired +``strex``. In practice this is only usually a risk when the extra store is on +the same cache line as the variable being modified and Clang will only insert +stack stores on its own, so it is best not to use these operations on variables +with automatic storage duration. Also, loads and stores may be implicit in code written between the ``ldrex`` and ``strex``. Clang will not necessarily mitigate the effects of these either, so @@ -1798,55 +1610,7 @@ Non-standard C++11 Attributes Clang's non-standard C++11 attributes live in the ``clang`` attribute namespace. -The ``clang::fallthrough`` attribute ------------------------------------- - -The ``clang::fallthrough`` attribute is used along with the -``-Wimplicit-fallthrough`` argument to annotate intentional fall-through -between switch labels. It can only be applied to a null statement placed at a -point of execution between any statement and the next switch label. It is -common to mark these places with a specific comment, but this attribute is -meant to replace comments with a more strict annotation, which can be checked -by the compiler. This attribute doesn't change semantics of the code and can -be used wherever an intended fall-through occurs. It is designed to mimic -control-flow statements like ``break;``, so it can be placed in most places -where ``break;`` can, but only if there are no statements on the execution path -between it and the next switch label. - -Here is an example: - -.. code-block:: c++ - - // compile with -Wimplicit-fallthrough - switch (n) { - case 22: - case 33: // no warning: no statements between case labels - f(); - case 44: // warning: unannotated fall-through - g(); - [[clang::fallthrough]]; - case 55: // no warning - if (x) { - h(); - break; - } - else { - i(); - [[clang::fallthrough]]; - } - case 66: // no warning - p(); - [[clang::fallthrough]]; // warning: fallthrough annotation does not - // directly precede case label - q(); - case 77: // warning: unannotated fall-through - r(); - } - -``gnu::`` attributes --------------------- - -Clang also supports GCC's ``gnu`` attribute namespace. All GCC attributes which +Clang supports GCC's ``gnu`` attribute namespace. All GCC attributes which are accepted with the ``__attribute__((foo))`` syntax are also accepted as ``[[gnu::foo]]``. This only extends to attributes which are specified by GCC (see the list of `GCC function attributes @@ -1870,6 +1634,19 @@ Target-Specific Extensions Clang supports some language features conditionally on some targets. +ARM/AArch64 Language Extensions +------------------------------- + +Memory Barrier Intrinsics +^^^^^^^^^^^^^^^^^^^^^^^^^ +Clang implements the ``__dmb``, ``__dsb`` and ``__isb`` intrinsics as defined +in the `ARM C Language Extensions Release 2.0 +`_. +Note that these intrinsics are implemented as motion barriers that block +reordering of memory accesses and side effect instructions. Other instructions +like simple arithmatic may be reordered around the intrinsic. If you expect to +have no reordering at all, use inline assembly instead. + X86/X86-64 Language Extensions ------------------------------ @@ -1902,48 +1679,6 @@ Which compiles to (on X86-32): movl %gs:(%eax), %eax ret -ARM Language Extensions ------------------------ - -Interrupt attribute -^^^^^^^^^^^^^^^^^^^ - -Clang supports the GNU style ``__attribite__((interrupt("TYPE")))`` attribute on -ARM targets. This attribute may be attached to a function definiton and -instructs the backend to generate appropriate function entry/exit code so that -it can be used directly as an interrupt service routine. - - The parameter passed to the interrupt attribute is optional, but if -provided it must be a string literal with one of the following values: "IRQ", -"FIQ", "SWI", "ABORT", "UNDEF". - -The semantics are as follows: - -- If the function is AAPCS, Clang instructs the backend to realign the stack to - 8 bytes on entry. This is a general requirement of the AAPCS at public - interfaces, but may not hold when an exception is taken. Doing this allows - other AAPCS functions to be called. -- If the CPU is M-class this is all that needs to be done since the architecture - itself is designed in such a way that functions obeying the normal AAPCS ABI - constraints are valid exception handlers. -- If the CPU is not M-class, the prologue and epilogue are modified to save all - non-banked registers that are used, so that upon return the user-mode state - will not be corrupted. Note that to avoid unnecessary overhead, only - general-purpose (integer) registers are saved in this way. If VFP operations - are needed, that state must be saved manually. - - Specifically, interrupt kinds other than "FIQ" will save all core registers - except "lr" and "sp". "FIQ" interrupts will save r0-r7. -- If the CPU is not M-class, the return instruction is changed to one of the - canonical sequences permitted by the architecture for exception return. Where - possible the function itself will make the necessary "lr" adjustments so that - the "preferred return address" is selected. - - Unfortunately the compiler is unable to make this guarantee for an "UNDEF" - handler, where the offset from "lr" to the preferred return address depends on - the execution state of the code which generated the exception. In this case - a sequence equivalent to "movs pc, lr" will be used. - Extensions for Static Analysis ============================== @@ -1957,450 +1692,156 @@ in the analyzer's `list of source-level annotations Extensions for Dynamic Analysis =============================== -.. _langext-address_sanitizer: - -AddressSanitizer ----------------- - Use ``__has_feature(address_sanitizer)`` to check if the code is being built with :doc:`AddressSanitizer`. -Use ``__attribute__((no_sanitize_address))`` -on a function declaration -to specify that address safety instrumentation (e.g. AddressSanitizer) should -not be applied to that function. - -.. _langext-thread_sanitizer: - -ThreadSanitizer ----------------- - Use ``__has_feature(thread_sanitizer)`` to check if the code is being built with :doc:`ThreadSanitizer`. -Use ``__attribute__((no_sanitize_thread))`` on a function declaration -to specify that checks for data races on plain (non-atomic) memory accesses -should not be inserted by ThreadSanitizer. -The function is still instrumented by the tool to avoid false positives and -provide meaningful stack traces. - -.. _langext-memory_sanitizer: - -MemorySanitizer ----------------- Use ``__has_feature(memory_sanitizer)`` to check if the code is being built with :doc:`MemorySanitizer`. -Use ``__attribute__((no_sanitize_memory))`` on a function declaration -to specify that checks for uninitialized memory should not be inserted -(e.g. by MemorySanitizer). The function may still be instrumented by the tool -to avoid false positives in other places. - -Thread-Safety Annotation Checking -================================= +Extensions for selectively disabling optimization +================================================= -Clang supports additional attributes for checking basic locking policies in -multithreaded programs. Clang currently parses the following list of -attributes, although **the implementation for these annotations is currently in -development.** For more details, see the `GCC implementation -`_. +Clang provides a mechanism for selectively disabling optimizations in functions +and methods. -``no_thread_safety_analysis`` ------------------------------ +To disable optimizations in a single function definition, the GNU-style or C++11 +non-standard attribute ``optnone`` can be used. -Use ``__attribute__((no_thread_safety_analysis))`` on a function declaration to -specify that the thread safety analysis should not be run on that function. -This attribute provides an escape hatch (e.g. for situations when it is -difficult to annotate the locking policy). - -``lockable`` ------------- - -Use ``__attribute__((lockable))`` on a class definition to specify that it has -a lockable type (e.g. a Mutex class). This annotation is primarily used to -check consistency. - -``scoped_lockable`` -------------------- - -Use ``__attribute__((scoped_lockable))`` on a class definition to specify that -it has a "scoped" lockable type. Objects of this type will acquire the lock -upon construction and release it upon going out of scope. This annotation is -primarily used to check consistency. - -``guarded_var`` ---------------- - -Use ``__attribute__((guarded_var))`` on a variable declaration to specify that -the variable must be accessed while holding some lock. - -``pt_guarded_var`` ------------------- - -Use ``__attribute__((pt_guarded_var))`` on a pointer declaration to specify -that the pointer must be dereferenced while holding some lock. - -``guarded_by(l)`` ------------------ - -Use ``__attribute__((guarded_by(l)))`` on a variable declaration to specify -that the variable must be accessed while holding lock ``l``. - -``pt_guarded_by(l)`` --------------------- - -Use ``__attribute__((pt_guarded_by(l)))`` on a pointer declaration to specify -that the pointer must be dereferenced while holding lock ``l``. - -``acquired_before(...)`` ------------------------- - -Use ``__attribute__((acquired_before(...)))`` on a declaration of a lockable -variable to specify that the lock must be acquired before all attribute -arguments. Arguments must be lockable type, and there must be at least one -argument. - -``acquired_after(...)`` ------------------------ - -Use ``__attribute__((acquired_after(...)))`` on a declaration of a lockable -variable to specify that the lock must be acquired after all attribute -arguments. Arguments must be lockable type, and there must be at least one -argument. - -``exclusive_lock_function(...)`` --------------------------------- - -Use ``__attribute__((exclusive_lock_function(...)))`` on a function declaration -to specify that the function acquires all listed locks exclusively. This -attribute takes zero or more arguments: either of lockable type or integers -indexing into function parameters of lockable type. If no arguments are given, -the acquired lock is implicitly ``this`` of the enclosing object. - -``shared_lock_function(...)`` ------------------------------ - -Use ``__attribute__((shared_lock_function(...)))`` on a function declaration to -specify that the function acquires all listed locks, although the locks may be -shared (e.g. read locks). This attribute takes zero or more arguments: either -of lockable type or integers indexing into function parameters of lockable -type. If no arguments are given, the acquired lock is implicitly ``this`` of -the enclosing object. - -``exclusive_trylock_function(...)`` ------------------------------------ - -Use ``__attribute__((exclusive_lock_function(...)))`` on a function declaration -to specify that the function will try (without blocking) to acquire all listed -locks exclusively. This attribute takes one or more arguments. The first -argument is an integer or boolean value specifying the return value of a -successful lock acquisition. The remaining arugments are either of lockable -type or integers indexing into function parameters of lockable type. If only -one argument is given, the acquired lock is implicitly ``this`` of the -enclosing object. - -``shared_trylock_function(...)`` --------------------------------- - -Use ``__attribute__((shared_lock_function(...)))`` on a function declaration to -specify that the function will try (without blocking) to acquire all listed -locks, although the locks may be shared (e.g. read locks). This attribute -takes one or more arguments. The first argument is an integer or boolean value -specifying the return value of a successful lock acquisition. The remaining -arugments are either of lockable type or integers indexing into function -parameters of lockable type. If only one argument is given, the acquired lock -is implicitly ``this`` of the enclosing object. - -``unlock_function(...)`` ------------------------- - -Use ``__attribute__((unlock_function(...)))`` on a function declaration to -specify that the function release all listed locks. This attribute takes zero -or more arguments: either of lockable type or integers indexing into function -parameters of lockable type. If no arguments are given, the acquired lock is -implicitly ``this`` of the enclosing object. - -``lock_returned(l)`` --------------------- - -Use ``__attribute__((lock_returned(l)))`` on a function declaration to specify -that the function returns lock ``l`` (``l`` must be of lockable type). This -annotation is used to aid in resolving lock expressions. - -``locks_excluded(...)`` ------------------------ - -Use ``__attribute__((locks_excluded(...)))`` on a function declaration to -specify that the function must not be called with the listed locks. Arguments -must be lockable type, and there must be at least one argument. - -``exclusive_locks_required(...)`` ---------------------------------- - -Use ``__attribute__((exclusive_locks_required(...)))`` on a function -declaration to specify that the function must be called while holding the -listed exclusive locks. Arguments must be lockable type, and there must be at -least one argument. - -``shared_locks_required(...)`` ------------------------------- - -Use ``__attribute__((shared_locks_required(...)))`` on a function declaration -to specify that the function must be called while holding the listed shared -locks. Arguments must be lockable type, and there must be at least one -argument. - -Consumed Annotation Checking -============================ - -Clang supports additional attributes for checking basic resource management -properties, specifically for unique objects that have a single owning reference. -The following attributes are currently supported, although **the implementation -for these annotations is currently in development and are subject to change.** - -``consumable`` --------------- - -Each class that uses any of the following annotations must first be marked -using the consumable attribute. Failure to do so will result in a warning. - -``set_typestate(new_state)`` ----------------------------- - -Annotate methods that transition an object into a new state with -``__attribute__((set_typestate(new_state)))``. The new new state must be -unconsumed, consumed, or unknown. - -``callable_when(...)`` ----------------------- - -Use ``__attribute__((callable_when(...)))`` to indicate what states a method -may be called in. Valid states are unconsumed, consumed, or unknown. Each -argument to this attribute must be a quoted string. E.g.: - -``__attribute__((callable_when("unconsumed", "unknown")))`` - -``tests_typestate(tested_state)`` ---------------------------------- - -Use ``__attribute__((tests_typestate(tested_state)))`` to indicate that a method -returns true if the object is in the specified state.. - -``param_typestate(expected_state)`` ------------------------------------ - -This attribute specifies expectations about function parameters. Calls to an -function with annotated parameters will issue a warning if the corresponding -argument isn't in the expected state. The attribute is also used to set the -initial state of the parameter when analyzing the function's body. - -``return_typestate(ret_state)`` -------------------------------- - -The ``return_typestate`` attribute can be applied to functions or parameters. -When applied to a function the attribute specifies the state of the returned -value. The function's body is checked to ensure that it always returns a value -in the specified state. On the caller side, values returned by the annotated -function are initialized to the given state. - -If the attribute is applied to a function parameter it modifies the state of -an argument after a call to the function returns. The function's body is -checked to ensure that the parameter is in the expected state before returning. - -Type Safety Checking -==================== +.. code-block:: c++ -Clang supports additional attributes to enable checking type safety properties -that can't be enforced by the C type system. Use cases include: + // The following functions will not be optimized. + // GNU-style attribute + __attribute__((optnone)) int foo() { + // ... code + } + // C++11 attribute + [[clang::optnone]] int bar() { + // ... code + } -* MPI library implementations, where these attributes enable checking that - the buffer type matches the passed ``MPI_Datatype``; -* for HDF5 library there is a similar use case to MPI; -* checking types of variadic functions' arguments for functions like - ``fcntl()`` and ``ioctl()``. +To facilitate disabling optimization for a range of function definitions, a +range-based pragma is provided. Its syntax is ``#pragma clang optimize`` +followed by ``off`` or ``on``. -You can detect support for these attributes with ``__has_attribute()``. For -example: +All function definitions in the region between an ``off`` and the following +``on`` will be decorated with the ``optnone`` attribute unless doing so would +conflict with explicit attributes already present on the function (e.g. the +ones that control inlining). .. code-block:: c++ - #if defined(__has_attribute) - # if __has_attribute(argument_with_type_tag) && \ - __has_attribute(pointer_with_type_tag) && \ - __has_attribute(type_tag_for_datatype) - # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx))) - /* ... other macros ... */ - # endif - #endif - - #if !defined(ATTR_MPI_PWT) - # define ATTR_MPI_PWT(buffer_idx, type_idx) - #endif - - int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) - ATTR_MPI_PWT(1,3); + #pragma clang optimize off + // This function will be decorated with optnone. + int foo() { + // ... code + } -``argument_with_type_tag(...)`` -------------------------------- + // optnone conflicts with always_inline, so bar() will not be decorated. + __attribute__((always_inline)) int bar() { + // ... code + } + #pragma clang optimize on -Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx, -type_tag_idx)))`` on a function declaration to specify that the function -accepts a type tag that determines the type of some other argument. -``arg_kind`` is an identifier that should be used when annotating all -applicable type tags. +If no ``on`` is found to close an ``off`` region, the end of the region is the +end of the compilation unit. -This attribute is primarily useful for checking arguments of variadic functions -(``pointer_with_type_tag`` can be used in most non-variadic cases). +Note that a stray ``#pragma clang optimize on`` does not selectively enable +additional optimizations when compiling at low optimization levels. This feature +can only be used to selectively disable optimizations. -For example: +The pragma has an effect on functions only at the point of their definition; for +function templates, this means that the state of the pragma at the point of an +instantiation is not necessarily relevant. Consider the following example: .. code-block:: c++ - int fcntl(int fd, int cmd, ...) - __attribute__(( argument_with_type_tag(fcntl,3,2) )); - -``pointer_with_type_tag(...)`` ------------------------------- + template T twice(T t) { + return 2 * t; + } -Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))`` -on a function declaration to specify that the function accepts a type tag that -determines the pointee type of some other pointer argument. + #pragma clang optimize off + template T thrice(T t) { + return 3 * t; + } -For example: + int container(int a, int b) { + return twice(a) + thrice(b); + } + #pragma clang optimize on + +In this example, the definition of the template function ``twice`` is outside +the pragma region, whereas the definition of ``thrice`` is inside the region. +The ``container`` function is also in the region and will not be optimized, but +it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of +these two instantiations, ``twice`` will be optimized (because its definition +was outside the region) and ``thrice`` will not be optimized. + +.. _langext-pragma-loop: + +Extensions for loop hint optimizations +====================================== + +The ``#pragma clang loop`` directive is used to specify hints for optimizing the +subsequent for, while, do-while, or c++11 range-based for loop. The directive +provides options for vectorization and interleaving. Loop hints can be specified +before any loop and will be ignored if the optimization is not safe to apply. + +A vectorized loop performs multiple iterations of the original loop +in parallel using vector instructions. The instruction set of the target +processor determines which vector instructions are available and their vector +widths. This restricts the types of loops that can be vectorized. The vectorizer +automatically determines if the loop is safe and profitable to vectorize. A +vector instruction cost model is used to select the vector width. + +Interleaving multiple loop iterations allows modern processors to further +improve instruction-level parallelism (ILP) using advanced hardware features, +such as multiple execution units and out-of-order execution. The vectorizer uses +a cost model that depends on the register pressure and generated code size to +select the interleaving count. + +Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled +by ``interleave(enable)``. This is useful when compiling with ``-Os`` to +manually enable vectorization or interleaving. .. code-block:: c++ - int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) - __attribute__(( pointer_with_type_tag(mpi,1,3) )); - -``type_tag_for_datatype(...)`` ------------------------------- - -Clang supports annotating type tags of two forms. - -* **Type tag that is an expression containing a reference to some declared - identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a - declaration with that identifier: - - .. code-block:: c++ - - extern struct mpi_datatype mpi_datatype_int - __attribute__(( type_tag_for_datatype(mpi,int) )); - #define MPI_INT ((MPI_Datatype) &mpi_datatype_int) - -* **Type tag that is an integral literal.** Introduce a ``static const`` - variable with a corresponding initializer value and attach - ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration, - for example: - - .. code-block:: c++ - - #define MPI_INT ((MPI_Datatype) 42) - static const MPI_Datatype mpi_datatype_int - __attribute__(( type_tag_for_datatype(mpi,int) )) = 42 - -The attribute also accepts an optional third argument that determines how the -expression is compared to the type tag. There are two supported flags: - -* ``layout_compatible`` will cause types to be compared according to - layout-compatibility rules (C++11 [class.mem] p 17, 18). This is - implemented to support annotating types like ``MPI_DOUBLE_INT``. - - For example: - - .. code-block:: c++ - - /* In mpi.h */ - struct internal_mpi_double_int { double d; int i; }; - extern struct mpi_datatype mpi_datatype_double_int - __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) )); - - #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int) - - /* In user code */ - struct my_pair { double a; int b; }; - struct my_pair *buffer; - MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning - - struct my_int_pair { int a; int b; } - struct my_int_pair *buffer2; - MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element - // type 'struct my_int_pair' - // doesn't match specified MPI_Datatype - -* ``must_be_null`` specifies that the expression should be a null pointer - constant, for example: - - .. code-block:: c++ - - /* In mpi.h */ - extern struct mpi_datatype mpi_datatype_null - __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) )); - - #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null) - - /* In user code */ - MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL - // was specified but buffer - // is not a null pointer - -Format String Checking -====================== - -Clang supports the ``format`` attribute, which indicates that the function -accepts a ``printf`` or ``scanf``-like format string and corresponding -arguments or a ``va_list`` that contains these arguments. - -Please see `GCC documentation about format attribute -`_ to find details -about attribute syntax. - -Clang implements two kinds of checks with this attribute. - -#. Clang checks that the function with the ``format`` attribute is called with - a format string that uses format specifiers that are allowed, and that - arguments match the format string. This is the ``-Wformat`` warning, it is - on by default. - -#. Clang checks that the format string argument is a literal string. This is - the ``-Wformat-nonliteral`` warning, it is off by default. - - Clang implements this mostly the same way as GCC, but there is a difference - for functions that accept a ``va_list`` argument (for example, ``vprintf``). - GCC does not emit ``-Wformat-nonliteral`` warning for calls to such - fuctions. Clang does not warn if the format string comes from a function - parameter, where the function is annotated with a compatible attribute, - otherwise it warns. For example: - - .. code-block:: c - - __attribute__((__format__ (__scanf__, 1, 3))) - void foo(const char* s, char *buf, ...) { - va_list ap; - va_start(ap, buf); + #pragma clang loop vectorize(enable) + #pragma clang loop interleave(enable) + for(...) { + ... + } - vprintf(s, ap); // warning: format string is not a string literal - } +The vector width is specified by ``vectorize_width(_value_)`` and the interleave +count is specified by ``interleave_count(_value_)``, where +_value_ is a positive integer. This is useful for specifying the optimal +width/count of the set of target architectures supported by your application. - In this case we warn because ``s`` contains a format string for a - ``scanf``-like function, but it is passed to a ``printf``-like function. +.. code-block:: c++ - If the attribute is removed, clang still warns, because the format string is - not a string literal. + #pragma clang loop vectorize_width(2) + #pragma clang loop interleave_count(2) + for(...) { + ... + } - Another example: +Specifying a width/count of 1 disables the optimization, and is equivalent to +``vectorize(disable)`` or ``interleave(disable)``. - .. code-block:: c +For convenience multiple loop hints can be specified on a single line. - __attribute__((__format__ (__printf__, 1, 3))) - void foo(const char* s, char *buf, ...) { - va_list ap; - va_start(ap, buf); +.. code-block:: c++ - vprintf(s, ap); // warning - } + #pragma clang loop vectorize_width(4) interleave_count(8) + for(...) { + ... + } - In this case Clang does not warn because the format string ``s`` and - the corresponding arguments are annotated. If the arguments are - incorrect, the caller of ``foo`` will receive a warning. +If an optimization cannot be applied any hints that apply to it will be ignored. +For example, the hint ``vectorize_width(4)`` is ignored if the loop is not +proven safe to vectorize. To identify and diagnose optimization issues use +`-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the +user guide for details. diff --git a/docs/LeakSanitizer.rst b/docs/LeakSanitizer.rst index 09d02cfcd5d..b1071efd1aa 100644 --- a/docs/LeakSanitizer.rst +++ b/docs/LeakSanitizer.rst @@ -8,21 +8,25 @@ LeakSanitizer Introduction ============ -LeakSanitizer is a heap leak detector which is designed to be used on top of -:doc:`AddressSanitizer` / :doc:`MemorySanitizer`, or as a standalone library. -LeakSanitizer is a run-time tool which doesn't require compiler -instrumentation. +LeakSanitizer is a run-time memory leak detector. It can be combined with +:doc:`AddressSanitizer` to get both memory error and leak detection. +LeakSanitizer does not introduce any additional slowdown when used in this mode. +The LeakSanitizer runtime can also be linked in separately to get leak detection +only, at a minimal performance cost. Current status ============== -LeakSanitizer is a work in progress, currently under development for -x86\_64 Linux. +LeakSanitizer is experimental and supported only on x86\_64 Linux. + +The combined mode has been tested on fairly large software projects. The +stand-alone mode has received much less testing. + +There are plans to support LeakSanitizer in :doc:`MemorySanitizer` builds. More Information ================ -Design wiki: -`https://code.google.com/p/address-sanitizer/wiki/LeakSanitizerDesignDocument -`_ +`https://code.google.com/p/address-sanitizer/wiki/LeakSanitizer +`_ diff --git a/docs/LibASTMatchersReference.html b/docs/LibASTMatchersReference.html index 2c9b3aae0a8..49880539bc9 100644 --- a/docs/LibASTMatchersReference.html +++ b/docs/LibASTMatchersReference.html @@ -250,7 +250,7 @@

Node Matchers

Matches method declarations.
 
 Example matches y
-  class X { void y() };
+  class X { void y(); };
@@ -631,6 +631,15 @@

Node Matchers

+Matcher<Stmt>exprWithCleanupsMatcher<ExprWithCleanups>... +
Matches expressions that introduce cleanups to be run at the end
+of the sub-expression's evaluation.
+
+Example matches std::string()
+  const std::string str = std::string();
+
+ + Matcher<Stmt>floatLiteralMatcher<FloatingLiteral>... 
Matches float literals of all sizes encodings, e.g.
 1.0, 1.0f, 1.0L and 1e10.
@@ -1311,7 +1320,7 @@ 
Narrowing Matchers
-Matcher<*>unlessMatcher<*> InnerMatcher +Matcher<*>unlessMatcher<*> 
Matches if the provided matcher does not match.
 
 Example matches Y (matcher = recordDecl(unless(hasName("X"))))
@@ -1352,9 +1361,8 @@ 
Narrowing Matchers
-Matcher<CXXConstructorDecl>isImplicit -
Matches a constructor declaration that has been implicitly added
-by the compiler (eg. implicit defaultcopy constructors).
+Matcher<CXXConstructExpr>isListInitialization
+
Matches a constructor call expression which uses list initialization.
 

 
 
@@ -1422,6 +1430,18 @@ 
Narrowing Matchers
+Matcher<CXXMethodDecl>isPure +
Matches if the given method declaration is pure.
+
+Given
+  class A {
+   public:
+    virtual void x() = 0;
+  };
+  matches A::x
+
+ + Matcher<CXXMethodDecl>isVirtual 
Matches if the given method declaration is virtual.
 
@@ -1581,13 +1601,19 @@ 
Narrowing Matchers
-Matcher<Decl>equalsNodeDecl* Other +Matcher<Decl>equalsNodeDecl *Node 
Matches if a node equals another node.
 
 Decl has pointer identity in the AST.
+Matcher<Decl>isImplicit +
Matches a declaration that has been implicitly added
+by the compiler (eg. implicit defaultcopy constructors).
+
+ + Matcher<Decl>isPrivate 
Matches private C++ declarations.
 
@@ -1874,7 +1900,7 @@ 
Narrowing Matchers
-Matcher<Stmt>equalsNodeStmt* Other +Matcher<Stmt>equalsNodeStmt *Node 
Matches if a node equals another node.
 
 Stmt has pointer identity in the AST.
@@ -1940,6 +1966,31 @@ 
Narrowing Matchers
+Matcher<VarDecl>hasGlobalStorage +
Matches a variable declaration that does not have local storage.
+
+Example matches y and z (matcher = varDecl(hasGlobalStorage())
+void f() {
+  int x;
+  static int y;
+}
+int z;
+
+ + +Matcher<VarDecl>hasLocalStorage +
Matches a variable declaration that has function scope and is a
+non-static local variable.
+
+Example matches x (matcher = varDecl(hasLocalStorage())
+void f() {
+  int x;
+  static int y;
+}
+int z;
+
+ + Matcher<VarDecl>isDefinition 
Matches if a declaration has a body attached.
 
@@ -2026,24 +2077,6 @@ 
AST Traversal Matchers
-Matcher<*>forEachMatcher<*> -
Matches AST nodes that have child AST nodes that match the
-provided matcher.
-
-Example matches X, Y (matcher = recordDecl(forEach(recordDecl(hasName("X")))
-  class X {};  Matches X, because X::X is a class of name X inside X.
-  class Y { class X {}; };
-  class Z { class Y { class X {}; }; };  Does not match Z.
-
-ChildT must be an AST base type.
-
-As opposed to 'has', 'forEach' will cause a match for each result that
-matches instead of only on the first one.
-
-Usable as: Any Matcher
-
- - Matcher<*>forEachDescendantMatcher<*> 
Matches AST nodes that have descendant AST nodes that match the
 provided matcher.
@@ -2068,17 +2101,20 @@ 
AST Traversal Matchers
-Matcher<*>hasMatcher<*> -
Matches AST nodes that have child AST nodes that match the
+Matcher<*>forEachMatcher<*>
+
Matches AST nodes that have child AST nodes that match the
 provided matcher.
 
-Example matches X, Y (matcher = recordDecl(has(recordDecl(hasName("X")))
+Example matches X, Y (matcher = recordDecl(forEach(recordDecl(hasName("X")))
   class X {};  Matches X, because X::X is a class of name X inside X.
   class Y { class X {}; };
   class Z { class Y { class X {}; }; };  Does not match Z.
 
 ChildT must be an AST base type.
 
+As opposed to 'has', 'forEach' will cause a match for each result that
+matches instead of only on the first one.
+
 Usable as: Any Matcher
 

 
@@ -2112,6 +2148,21 @@ 
AST Traversal Matchers
+Matcher<*>hasMatcher<*> +
Matches AST nodes that have child AST nodes that match the
+provided matcher.
+
+Example matches X, Y (matcher = recordDecl(has(recordDecl(hasName("X")))
+  class X {};  Matches X, because X::X is a class of name X inside X.
+  class Y { class X {}; };
+  class Z { class Y { class X {}; }; };  Does not match Z.
+
+ChildT must be an AST base type.
+
+Usable as: Any Matcher
+
+ + Matcher<*>hasParentMatcher<*> 
Matches AST nodes that have a parent that matches the provided
 matcher.
@@ -2313,8 +2364,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -2378,6 +2427,43 @@ 
AST Traversal Matchers
+Matcher<CXXForRangeStmt>hasBodyMatcher<Stmt> InnerMatcher +
Matches a 'for', 'while', or 'do while' statement that has
+a given body.
+
+Given
+  for (;;) {}
+hasBody(compoundStmt())
+  matches 'for (;;) {}'
+with compoundStmt()
+  matching '{}'
+
+ + +Matcher<CXXForRangeStmt>hasLoopVariableMatcher<VarDecl> InnerMatcher +
Matches the initialization statement of a for loop.
+
+Example:
+    forStmt(hasLoopVariable(anything()))
+matches 'int x' in
+    for (int x : a) { }
+
+ + +Matcher<CXXForRangeStmt>hasRangeInitMatcher<Expr> InnerMatcher +
Matches the range initialization statement of a for loop.
+
+Example:
+    forStmt(hasRangeInit(anything()))
+matches 'a' in
+    for (int x : a) { }
+
+ + +Matcher<CXXMemberCallExpr>onImplicitObjectArgumentMatcher<Expr> InnerMatcher +

+
+
 Matcher<CXXMemberCallExpr>onMatcher<Expr> InnerMatcher
 
Matches on the implicit object argument of a member call expression.
 
@@ -2389,15 +2475,17 @@ 
AST Traversal Matchers

 

 
 
-Matcher<CXXMemberCallExpr>onImplicitObjectArgumentMatcher<Expr> InnerMatcher
-

-
-
 Matcher<CXXMemberCallExpr>thisPointerTypeMatcher<Decl> InnerMatcher
 
Overloaded to match the type's declaration.
 

 
 
+Matcher<CXXMemberCallExpr>thisPointerTypeMatcher<QualType> InnerMatcher
+
Matches if the expression's type either matches the specified
+matcher, or is a pointer to a type that matches the InnerMatcher.
+

+
+
 Matcher<CXXMethodDecl>ofClassMatcher<CXXRecordDecl> InnerMatcher
 
Matches the class declaration that the given method declaration
 belongs to.
@@ -2466,6 +2554,24 @@ 
AST Traversal Matchers

 

 
 
+Matcher<CallExpr>calleeMatcher<Stmt> InnerMatcher
+
Matches if the call expression's callee expression matches.
+
+Given
+  class Y { void x() { this->x(); x(); Y y; y.x(); } };
+  void f() { f(); }
+callExpr(callee(expr()))
+  matches this->x(), x(), y.x(), f()
+with callee(...)
+  matching this->x, x, y.x, f respectively
+
+Note: Callee cannot take the more general internal::Matcher<Expr>
+because this introduces ambiguous overloads with calls to Callee taking a
+internal::Matcher<Decl>, as the matcher hierarchy is purely
+implemented in terms of implicit casts.
+

+
+
 Matcher<CallExpr>hasAnyArgumentMatcher<Expr> InnerMatcher
 
Matches any argument of a call expression or a constructor call
 expression.
@@ -2506,8 +2612,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -2647,8 +2751,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -2813,8 +2915,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -2852,6 +2952,17 @@ 
AST Traversal Matchers

 

 
 
+Matcher<Expr>hasTypeMatcher<QualType> InnerMatcher
+
Matches if the expression's or declaration's type matches a type
+matcher.
+
+Example matches x (matcher = expr(hasType(recordDecl(hasName("X")))))
+            and z (matcher = varDecl(hasType(recordDecl(hasName("X")))))
+ class X {};
+ void y(X &x) { x; X z; }
+

+
+
 Matcher<Expr>ignoringImpCastsMatcher<Expr> InnerMatcher
 
Matches expressions that match InnerMatcher after any implicit casts
 are stripped off.
@@ -3014,6 +3125,24 @@ 
AST Traversal Matchers

 

 
 
+Matcher<IfStmt>hasElseMatcher<Stmt> InnerMatcher
+
Matches the else-statement of an if statement.
+
+Examples matches the if statement
+  (matcher = ifStmt(hasElse(boolLiteral(equals(true)))))
+  if (false) false; else true;
+

+
+
+Matcher<IfStmt>hasThenMatcher<Stmt> InnerMatcher
+
Matches the then-statement of an if statement.
+
+Examples matches the if statement
+  (matcher = ifStmt(hasThen(boolLiteral(equals(true)))))
+  if (false) true; else false;
+

+
+
 Matcher<ImplicitCastExpr>hasImplicitDestinationTypeMatcher<QualType> InnerMatcher
 
Matches implicit casts whose destination type matches a given
 matcher.
@@ -3034,8 +3163,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -3058,8 +3185,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -3082,8 +3207,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -3165,12 +3288,6 @@ 
AST Traversal Matchers

 

 
 
-Matcher<NestedNameSpecifierLoc>locMatcher<NestedNameSpecifier>  InnerMatcher
-
Matches NestedNameSpecifierLocs for which the given inner
-NestedNameSpecifier-matcher matches.
-

-
-
 Matcher<NestedNameSpecifierLoc>specifiesTypeLocMatcher<TypeLoc> InnerMatcher
 
Matches nested name specifier locs that specify a type matching the
 given TypeLoc.
@@ -3290,8 +3407,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -3307,11 +3422,36 @@ 
AST Traversal Matchers

 

 
 
+Matcher<QualType>pointsToMatcher<QualType> InnerMatcher
+
Matches if the matched type is a pointer type and the pointee type
+matches the specified matcher.
+
+Example matches y->x()
+    (matcher = callExpr(on(hasType(pointsTo(recordDecl(hasName("Y")))))))
+  class Y { public: void x(); };
+  void z() { Y *y; y->x(); }
+

+
+
 Matcher<QualType>referencesMatcher<Decl> InnerMatcher
 
Overloaded to match the referenced type's declaration.
 

 
 
+Matcher<QualType>referencesMatcher<QualType> InnerMatcher
+
Matches if the matched type is a reference type and the referenced
+type matches the specified matcher.
+
+Example matches X &x and const X &y
+    (matcher = varDecl(hasType(references(recordDecl(hasName("X"))))))
+  class X {
+    void a(X b) {
+      X &x = b;
+      const X &y = b;
+  };
+

+
+
 Matcher<RecordType>hasDeclarationMatcher<Decl>  InnerMatcher
 
Matches a node if the declaration associated with that node
 matches the given matcher.
@@ -3324,8 +3464,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -3405,8 +3543,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -3417,8 +3553,23 @@ 
AST Traversal Matchers

 

 
 
+Matcher<TemplateArgument>isExprMatcher<Expr> InnerMatcher
+
Matches a sugar TemplateArgument that refers to a certain expression.
+
+Given
+  template<typename T> struct A {};
+  struct B { B* next; };
+  A<&B::next> a;
+templateSpecializationType(hasAnyTemplateArgument(
+  isExpr(hasDescendant(declRefExpr(to(fieldDecl(hasName("next"))))))))
+  matches the specialization A<&B::next> with fieldDecl(...) matching
+    B::next
+

+
+
 Matcher<TemplateArgument>refersToDeclarationMatcher<Decl> InnerMatcher
-
Matches a TemplateArgument that refers to a certain declaration.
+
Matches a canonical TemplateArgument that refers to a certain
+declaration.
 
 Given
   template<typename T> struct A {};
@@ -3444,6 +3595,20 @@ 
AST Traversal Matchers

 

 
 
+Matcher<TemplateSpecializationType>hasAnyTemplateArgumentMatcher<TemplateArgument> InnerMatcher
+
Matches classTemplateSpecializations that have at least one
+TemplateArgument matching the given InnerMatcher.
+
+Given
+  template<typename T> class A {};
+  template<> class A<double> {};
+  A<int> a;
+classTemplateSpecializationDecl(hasAnyTemplateArgument(
+    refersToType(asString("int"))))
+  matches the specialization A<int>
+

+
+
 Matcher<TemplateSpecializationType>hasDeclarationMatcher<Decl>  InnerMatcher
 
Matches a node if the declaration associated with that node
 matches the given matcher.
@@ -3456,8 +3621,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -3468,6 +3631,20 @@ 
AST Traversal Matchers

 

 
 
+Matcher<TemplateSpecializationType>hasTemplateArgumentunsigned N, Matcher<TemplateArgument> InnerMatcher
+
Matches classTemplateSpecializations where the n'th TemplateArgument
+matches the given InnerMatcher.
+
+Given
+  template<typename T, typename U> class A {};
+  A<bool, int> b;
+  A<int, bool> c;
+classTemplateSpecializationDecl(hasTemplateArgument(
+    1, refersToType(asString("int"))))
+  matches the specialization A<bool, int>
+

+
+
 Matcher<TemplateTypeParmType>hasDeclarationMatcher<Decl>  InnerMatcher
 
Matches a node if the declaration associated with that node
 matches the given matcher.
@@ -3480,8 +3657,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -3507,12 +3682,6 @@ 
AST Traversal Matchers

 

 
 
-Matcher<TypeLoc>locMatcher<QualType>  InnerMatcher
-
Matches TypeLocs for which the given inner
-QualType-matcher matches.
-

-
-
 Matcher<TypedefType>hasDeclarationMatcher<Decl>  InnerMatcher
 
Matches a node if the declaration associated with that node
 matches the given matcher.
@@ -3525,8 +3694,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -3567,8 +3734,6 @@ 
AST Traversal Matchers

 
 Also usable as Matcher<T> for any T supporting the getDecl() member
 function. e.g. various subtypes of clang::Type and various expressions.
-FIXME: Add all node types for which this is matcher is usable due to
-getDecl().
 
 Usable as: Matcher<CallExpr>, Matcher<CXXConstructExpr>,
   Matcher<DeclRefExpr>, Matcher<EnumType>, Matcher<InjectedClassNameType>,
@@ -3620,6 +3785,17 @@ 
AST Traversal Matchers

 

 
 
+Matcher<ValueDecl>hasTypeMatcher<QualType> InnerMatcher
+
Matches if the expression's or declaration's type matches a type
+matcher.
+
+Example matches x (matcher = expr(hasType(recordDecl(hasName("X")))))
+            and z (matcher = varDecl(hasType(recordDecl(hasName("X")))))
+ class X {};
+ void y(X &x) { x; X z; }
+

+
+
 Matcher<VarDecl>hasInitializerMatcher<Expr> InnerMatcher
 
Matches a variable declaration that has an initializer expression
 that matches the given matcher.
@@ -3665,6 +3841,18 @@ 
AST Traversal Matchers

   if (true) {}
 

 
+
+Matcher<internal::BindableMatcher<NestedNameSpecifierLoc>>locMatcher<NestedNameSpecifier> InnerMatcher
+
Matches NestedNameSpecifierLocs for which the given inner
+NestedNameSpecifier-matcher matches.
+

+
+
+Matcher<internal::BindableMatcher<TypeLoc>>locMatcher<QualType> InnerMatcher
+
Matches TypeLocs for which the given inner
+QualType-matcher matches.
+

+
 
 
 
diff --git a/docs/LibASTMatchersTutorial.rst b/docs/LibASTMatchersTutorial.rst
index 5bd62a13364..1e88ec203c9 100644
--- a/docs/LibASTMatchersTutorial.rst
+++ b/docs/LibASTMatchersTutorial.rst
@@ -137,6 +137,10 @@ documentation `_.
       using namespace clang::tooling;
       using namespace llvm;
 
+      // Apply a custom category to all command-line options so that they are the
+      // only ones displayed.
+      static llvm::cl::OptionCategory MyToolCategory("my-tool options");
+
       // CommonOptionsParser declares HelpMessage with a description of the common
       // command-line options related to the compilation database and input files.
       // It's nice to have this help message in all tools.
@@ -146,10 +150,10 @@ documentation `_.
       static cl::extrahelp MoreHelp("\nMore help text...");
 
       int main(int argc, const char **argv) {
-        CommonOptionsParser OptionsParser(argc, argv);
+        CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
         ClangTool Tool(OptionsParser.getCompilations(),
                        OptionsParser.getSourcePathList());
-        return Tool.run(newFrontendActionFactory());
+        return Tool.run(newFrontendActionFactory().get());
       }
 
 And that's it! You can compile our new tool by running ninja from the
@@ -287,7 +291,7 @@ And change ``main()`` to:
 .. code-block:: c++
 
       int main(int argc, const char **argv) {
-        CommonOptionsParser OptionsParser(argc, argv);
+        CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
         ClangTool Tool(OptionsParser.getCompilations(),
                        OptionsParser.getSourcePathList());
 
@@ -295,7 +299,7 @@ And change ``main()`` to:
         MatchFinder Finder;
         Finder.addMatcher(LoopMatcher, &Printer);
 
-        return Tool.run(newFrontendActionFactory(&Finder));
+        return Tool.run(newFrontendActionFactory(&Finder).get());
       }
 
 Now, you should be able to recompile and run the code to discover for
diff --git a/docs/LibTooling.rst b/docs/LibTooling.rst
index a9c24c30454..75ef6a0fe7e 100644
--- a/docs/LibTooling.rst
+++ b/docs/LibTooling.rst
@@ -60,13 +60,18 @@ and automatic location of the compilation database using source files paths.
 .. code-block:: c++
 
   #include "clang/Tooling/CommonOptionsParser.h"
+  #include "llvm/Support/CommandLine.h"
 
   using namespace clang::tooling;
 
+  // Apply a custom category to all command-line options so that they are the
+  // only ones displayed.
+  static llvm::cl::OptionCategory MyToolCategory("my-tool options");
+
   int main(int argc, const char **argv) {
     // CommonOptionsParser constructor will parse arguments and create a
     // CompilationDatabase.  In case of error it will terminate the program.
-    CommonOptionsParser OptionsParser(argc, argv);
+    CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
 
     // Use OptionsParser.getCompilations() and OptionsParser.getSourcePathList()
     // to retrieve CompilationDatabase and the list of input file paths.
@@ -94,13 +99,13 @@ our ``FrontendAction`` over some code.  For example, to run the
   // on.  Thus, it takes a FrontendActionFactory as parameter.  To create a
   // FrontendActionFactory from a given FrontendAction type, we call
   // newFrontendActionFactory().
-  int result = Tool.run(newFrontendActionFactory());
+  int result = Tool.run(newFrontendActionFactory().get());
 
 Putting it together --- the first tool
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Now we combine the two previous steps into our first real tool.  This example
-tool is also checked into the clang tree at
+Now we combine the two previous steps into our first real tool.  A more advanced
+version of this example tool is also checked into the clang tree at
 ``tools/clang-check/ClangCheck.cpp``.
 
 .. code-block:: c++
@@ -115,6 +120,10 @@ tool is also checked into the clang tree at
   using namespace clang::tooling;
   using namespace llvm;
 
+  // Apply a custom category to all command-line options so that they are the
+  // only ones displayed.
+  static cl::OptionCategory MyToolCategory("my-tool options");
+
   // CommonOptionsParser declares HelpMessage with a description of the common
   // command-line options related to the compilation database and input files.
   // It's nice to have this help message in all tools.
@@ -124,10 +133,10 @@ tool is also checked into the clang tree at
   static cl::extrahelp MoreHelp("\nMore help text...");
 
   int main(int argc, const char **argv) {
-    CommonOptionsParser OptionsParser(argc, argv);
+    CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
     ClangTool Tool(OptionsParser.getCompilations(),
-    OptionsParser.getSourcePathList());
-    return Tool.run(newFrontendActionFactory());
+                   OptionsParser.getSourcePathList());
+    return Tool.run(newFrontendActionFactory().get());
   }
 
 Running the tool on some code
diff --git a/docs/MSVCCompatibility.rst b/docs/MSVCCompatibility.rst
new file mode 100644
index 00000000000..32efb76db25
--- /dev/null
+++ b/docs/MSVCCompatibility.rst
@@ -0,0 +1,141 @@
+.. raw:: html
+
+  
+
+.. role:: none
+.. role:: partial
+.. role:: good
+
+==================
+MSVC compatibility
+==================
+
+When Clang compiles C++ code for Windows, it attempts to be compatible with
+MSVC.  There are multiple dimensions to compatibility.
+
+First, Clang attempts to be ABI-compatible, meaning that Clang-compiled code
+should be able to link against MSVC-compiled code successfully.  However, C++
+ABIs are particularly large and complicated, and Clang's support for MSVC's C++
+ABI is a work in progress.  If you don't require MSVC ABI compatibility or don't
+want to use Microsoft's C and C++ runtimes, the mingw32 toolchain might be a
+better fit for your project.
+
+Second, Clang implements many MSVC language extensions, such as
+``__declspec(dllexport)`` and a handful of pragmas.  These are typically
+controlled by ``-fms-extensions``.
+
+Third, MSVC accepts some C++ code that Clang will typically diagnose as
+invalid.  When these constructs are present in widely included system headers,
+Clang attempts to recover and continue compiling the user's program.  Most
+parsing and semantic compatibility tweaks are controlled by
+``-fms-compatibility`` and ``-fdelayed-template-parsing``, and they are a work
+in progress.
+
+Finally, there is :ref:`clang-cl`, a driver program for clang that attempts to
+be compatible with MSVC's cl.exe.
+
+ABI features
+============
+
+The status of major ABI-impacting C++ features:
+
+* Record layout: :good:`Complete`.  We've tested this with a fuzzer and have
+  fixed all known bugs.
+
+* Class inheritance: :good:`Mostly complete`.  This covers all of the standard
+  OO features you would expect: virtual method inheritance, multiple
+  inheritance, and virtual inheritance.  Every so often we uncover a bug where
+  our tables are incompatible, but this is pretty well in hand.  This feature
+  has also been fuzz tested.
+
+* Name mangling: :good:`Ongoing`.  Every new C++ feature generally needs its own
+  mangling.  For example, member pointer template arguments have an interesting
+  and distinct mangling.  Fortunately, incorrect manglings usually do not result
+  in runtime errors.  Non-inline functions with incorrect manglings usually
+  result in link errors, which are relatively easy to diagnose.  Incorrect
+  manglings for inline functions and templates result in multiple copies in the
+  final image.  The C++ standard requires that those addresses be equal, but few
+  programs rely on this.
+
+* Member pointers: :good:`Mostly complete`.  Standard C++ member pointers are
+  fully implemented and should be ABI compatible.  Both `#pragma
+  pointers_to_members`_ and the `/vm`_ flags are supported. However, MSVC
+  supports an extension to allow creating a `pointer to a member of a virtual
+  base class`_.  Clang does not yet support this.
+
+.. _#pragma pointers_to_members:
+  http://msdn.microsoft.com/en-us/library/83cch5a6.aspx
+.. _/vm: http://msdn.microsoft.com/en-us/library/yad46a6z.aspx
+.. _pointer to a member of a virtual base class: http://llvm.org/PR15713
+
+* Debug info: :partial:`Minimal`.  Clang emits CodeView line tables into the
+  object file, similar to what MSVC emits when given the ``/Z7`` flag.
+  Microsoft's link.exe will read this information and use it to create a PDB,
+  enabling stack traces in all modern Windows debuggers.  Clang does not emit
+  any type info or description of variable layout.
+
+* RTTI: :good:`Complete`.  Generation of RTTI data structures has been
+  finished, along with support for the ``/GR`` flag.
+
+* Exceptions and SEH: :none:`Unstarted`.  Clang can parse both constructs, but
+  does not know how to emit compatible handlers.
+
+* Thread-safe initialization of local statics: :none:`Unstarted`.  We are ABI
+  compatible with MSVC 2013, which does not support thread-safe local statics.
+  MSVC "14" changed the ABI to make initialization of local statics thread safe,
+  and we have not yet implemented this.
+
+* Lambdas: :good:`Mostly complete`.  Clang is compatible with Microsoft's
+  implementation of lambdas except for providing overloads for conversion to
+  function pointer for different calling conventions.  However, Microsoft's
+  extension is non-conforming.
+
+Template instantiation and name lookup
+======================================
+
+MSVC allows many invalid constructs in class templates that Clang has
+historically rejected.  In order to parse widely distributed headers for
+libraries such as the Active Template Library (ATL) and Windows Runtime Library
+(WRL), some template rules have been relaxed or extended in Clang on Windows.
+
+The first major semantic difference is that MSVC appears to defer all parsing
+an analysis of inline method bodies in class templates until instantiation
+time.  By default on Windows, Clang attempts to follow suit.  This behavior is
+controlled by the ``-fdelayed-template-parsing`` flag.  While Clang delays
+parsing of method bodies, it still parses the bodies *before* template argument
+substitution, which is not what MSVC does.  The following compatibility tweaks
+are necessary to parse the the template in those cases.
+
+MSVC allows some name lookup into dependent base classes.  Even on other
+platforms, this has been a `frequently asked question`_ for Clang users.  A
+dependent base class is a base class that depends on the value of a template
+parameter.  Clang cannot see any of the names inside dependent bases while it
+is parsing your template, so the user is sometimes required to use the
+``typename`` keyword to assist the parser.  On Windows, Clang attempts to
+follow the normal lookup rules, but if lookup fails, it will assume that the
+user intended to find the name in a dependent base.  While parsing the
+following program, Clang will recover as if the user had written the
+commented-out code:
+
+.. _frequently asked question:
+  http://clang.llvm.org/compatibility.html#dep_lookup
+
+.. code-block:: c++
+
+  template 
+  struct Foo : T {
+    void f() {
+      /*typename*/ T::UnknownType x =  /*this->*/unknownMember;
+    }
+  };
+
+After recovery, Clang warns the user that this code is non-standard and issues
+a hint suggesting how to fix the problem.
+
+As of this writing, Clang is able to compile a simple ATL hello world
+application.  There are still issues parsing WRL headers for modern Windows 8
+apps, but they should be addressed soon.
diff --git a/docs/MemorySanitizer.rst b/docs/MemorySanitizer.rst
index 5fc7e745d19..9d6c22d8af0 100644
--- a/docs/MemorySanitizer.rst
+++ b/docs/MemorySanitizer.rst
@@ -56,12 +56,10 @@ future).
 
 .. code-block:: console
 
-    % ./a.out 2>log
-    % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
-    ==30106==  WARNING: MemorySanitizer: UMR (uninitialized-memory-read)
+    % ./a.out
+    WARNING: MemorySanitizer: use-of-uninitialized-value
         #0 0x7f45944b418a in main umr.cc:6
         #1 0x7f45938b676c in __libc_start_main libc-start.c:226
-    Exiting
 
 By default, MemorySanitizer exits on the first detected error.
 
@@ -101,6 +99,13 @@ checks for certain source files and functions. All "Use of uninitialized value"
 warnings will be suppressed and all values loaded from memory will be
 considered fully initialized.
 
+Report symbolization
+====================
+
+MemorySanitizer uses an external symbolizer to print files and line numbers in
+reports. Make sure that ``llvm-symbolizer`` binary is in ``PATH``,
+or set environment variable ``MSAN_SYMBOLIZER_PATH`` to point to it.
+
 Origin Tracking
 ===============
 
@@ -112,29 +117,59 @@ the example above,
 .. code-block:: console
 
     % clang -fsanitize=memory -fsanitize-memory-track-origins -fno-omit-frame-pointer -g -O2 umr.cc
-    % ./a.out 2>log
-    % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
-    ==14425==  WARNING: MemorySanitizer: UMR (uninitialized-memory-read)
-    ==14425== WARNING: Trying to symbolize code, but external symbolizer is not initialized!
-        #0 0x7f8bdda3824b in main umr.cc:6
-        #1 0x7f8bdce3a76c in __libc_start_main libc-start.c:226
-      raw origin id: 2030043137
-      ORIGIN: heap allocation:
-        #0 0x7f8bdda4034b in operator new[](unsigned long) msan_new_delete.cc:39
-        #1 0x7f8bdda3814d in main umr.cc:4
-        #2 0x7f8bdce3a76c in __libc_start_main libc-start.c:226
-    Exiting
-
-Origin tracking has proved to be very useful for debugging UMR
+    % ./a.out
+    WARNING: MemorySanitizer: use-of-uninitialized-value
+        #0 0x7f7893912f0b in main umr2.cc:6
+        #1 0x7f789249b76c in __libc_start_main libc-start.c:226
+
+      Uninitialized value was created by a heap allocation
+        #0 0x7f7893901cbd in operator new[](unsigned long) msan_new_delete.cc:44
+        #1 0x7f7893912e06 in main umr2.cc:4
+
+Origin tracking has proved to be very useful for debugging MemorySanitizer
 reports. It slows down program execution by a factor of 1.5x-2x on top
 of the usual MemorySanitizer slowdown.
 
+MemorySanitizer can provide even more information with
+``-fsanitize-memory-track-origins=2`` flag. In this mode reports
+include information about intermediate stores the uninitialized value went
+through.
+
+.. code-block:: console
+
+    % cat umr2.cc
+    #include 
+
+    int main(int argc, char** argv) {
+      int* a = new int[10];
+      a[5] = 0;
+      volatile int b = a[argc];
+      if (b)
+        printf("xx\n");
+      return 0;
+    }
+
+    % clang -fsanitize=memory -fsanitize-memory-track-origins=2 -fno-omit-frame-pointer -g -O2 umr2.cc
+    % ./a.out
+    WARNING: MemorySanitizer: use-of-uninitialized-value
+        #0 0x7f7893912f0b in main umr2.cc:7
+        #1 0x7f789249b76c in __libc_start_main libc-start.c:226
+
+      Uninitialized value was stored to memory at
+        #0 0x7f78938b5c25 in __msan_chain_origin msan.cc:484
+        #1 0x7f7893912ecd in main umr2.cc:6
+
+      Uninitialized value was created by a heap allocation
+        #0 0x7f7893901cbd in operator new[](unsigned long) msan_new_delete.cc:44
+        #1 0x7f7893912e06 in main umr2.cc:4
+
+
 Handling external code
 ============================
 
 MemorySanitizer requires that all program code is instrumented. This
 also includes any libraries that the program depends on, even libc.
-Failing to achieve this may result in false UMR reports.
+Failing to achieve this may result in false reports.
 
 Full MemorySanitizer instrumentation is very difficult to achieve. To
 make it easier, MemorySanitizer runtime library includes 70+
@@ -157,7 +192,7 @@ Supported Platforms
 
 MemorySanitizer is supported on
 
-* Linux x86\_64 (tested on Ubuntu 10.04 and 12.04);
+* Linux x86\_64 (tested on Ubuntu 12.04);
 
 Limitations
 ===========
diff --git a/docs/Modules.rst b/docs/Modules.rst
index 9fb4c774874..ce1e717bc2a 100644
--- a/docs/Modules.rst
+++ b/docs/Modules.rst
@@ -144,7 +144,7 @@ Module maps
 -----------
 The crucial link between modules and headers is described by a *module map*, which describes how a collection of existing headers maps on to the (logical) structure of a module. For example, one could imagine a module ``std`` covering the C standard library. Each of the C standard library headers (````, ````, ````, etc.) would contribute to the ``std`` module, by placing their respective APIs into the corresponding submodule (``std.io``, ``std.lib``, ``std.math``, etc.). Having a list of the headers that are part of the ``std`` module allows the compiler to build the ``std`` module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of ``#include`` directives to module imports.
 
-Module maps are specified as separate files (each named ``module.map``) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [#]_). The actual `Module map language`_ is described in a later section.
+Module maps are specified as separate files (each named ``module.modulemap``) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [#]_). The actual `Module map language`_ is described in a later section.
 
 .. note::
 
@@ -198,20 +198,63 @@ Command-line parameters
 ``-fmodule-map-file=``
   Load the given module map file if a header from its directory or one of its subdirectories is loaded.
 
+``-fmodules-search-all``
+  If a symbol is not found, search modules referenced in the current module maps but not imported for symbols, so the error message can reference the module by name.  Note that if the global module index has not been built before, this might take some time as it needs to build all the modules.  Note that this option doesn't apply in module builds, to avoid the recursion.
+
+Module Semantics
+================
+
+Modules are modeled as if each submodule were a separate translation unit, and a module import makes names from the other translation unit visible. Each submodule starts with a new preprocessor state and an empty translation unit.
+
+.. note::
+
+  This behavior is currently only approximated when building a module. Entities within a submodule that has already been built are visible when building later submodules in that module. This can lead to fragile modules that depend on the build order used for the submodules of the module, and should not be relied upon.
+
+As an example, in C, this implies that if two structs are defined in different submodules with the same name, those two types are distinct types (but may be *compatible* types if their definitions match. In C++, two structs defined with the same name in different submodules are the *same* type, and must be equivalent under C++'s One Definition Rule.
+
+.. note::
+
+  Clang currently only performs minimal checking for violations of the One Definition Rule.
+
+Macros
+------
+
+The C and C++ preprocessor assumes that the input text is a single linear buffer, but with modules this is not the case. It is possible to import two modules that have conflicting definitions for a macro (or where one ``#define``\s a macro and the other ``#undef``\ines it). The rules for handling macro definitions in the presence of modules are as follows:
+
+* Each definition and undefinition of a macro is considered to be a distinct entity.
+* Such entities are *visible* if they are from the current submodule or translation unit, or if they were exported from a submodule that has been imported.
+* A ``#define X`` or ``#undef X`` directive *overrides* all definitions of ``X`` that are visible at the point of the directive.
+* A ``#define`` or ``#undef`` directive is *active* if it is visible and no visible directive overrides it.
+* A set of macro directives is *consistent* if it consists of only ``#undef`` directives, or if all ``#define`` directives in the set define the macro name to the same sequence of tokens (following the usual rules for macro redefinitions).
+* If a macro name is used and the set of active directives is not consistent, the program is ill-formed. Otherwise, the (unique) meaning of the macro name is used.
+
+For example, suppose:
+
+* ```` defines a macro ``getc`` (and exports its ``#define``)
+* ```` imports the ```` module and undefines the macro (and exports its ``#undef``)
+  
+The ``#undef`` overrides the ``#define``, and a source file that imports both modules *in any order* will not see ``getc`` defined as a macro.
+
 Module Map Language
 ===================
 
 The module map language describes the mapping from header files to the
 logical structure of modules. To enable support for using a library as
-a module, one must write a ``module.map`` file for that library. The
-``module.map`` file is placed alongside the header files themselves,
+a module, one must write a ``module.modulemap`` file for that library. The
+``module.modulemap`` file is placed alongside the header files themselves,
 and is written in the module map language described below.
 
+.. note::
+    For compatibility with previous releases, if a module map file named
+    ``module.modulemap`` is not found, Clang will also search for a file named
+    ``module.map``. This behavior is deprecated and we plan to eventually
+    remove it.
+
 As an example, the module map file for the C standard library might look a bit like this:
 
 .. parsed-literal::
 
-  module std [system] {
+  module std [system] [extern_c] {
     module complex {
       header "complex.h"
       export *
@@ -285,13 +328,15 @@ The ``framework`` qualifier specifies that this module corresponds to a Darwin-s
 .. parsed-literal::
 
   Name.framework/
-    module.map                Module map for the framework
+    Modules/module.modulemap  Module map for the framework
     Headers/                  Subdirectory containing framework headers
     Frameworks/               Subdirectory containing embedded frameworks
     Resources/                Subdirectory containing additional resources
     Name                      Symbolic link to the shared library for the framework
 
-The ``system`` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's header will be considered system headers, which suppresses warnings. This is equivalent to placing ``#pragma GCC system_header`` in each of the module's headers. The form of attributes is described in the section Attributes_, below.
+The ``system`` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's headers will be considered system headers, which suppresses warnings. This is equivalent to placing ``#pragma GCC system_header`` in each of the module's headers. The form of attributes is described in the section Attributes_, below.
+
+The ``extern_c`` attribute specifies that the module contains C code that can be used from within C++. When such a module is built for use in C++ code, all of the module's headers will be treated as if they were contained within an implicit ``extern "C"`` block. An import for a module with this attribute can appear within an ``extern "C"`` block. No other restrictions are lifted, however: the module currently cannot be imported within an ``extern "C"`` block in a namespace.
 
 Modules can have a number of different kinds of members, each of which is described below:
 
@@ -573,7 +618,7 @@ A *use-declaration* specifies one of the other modules that the module is allowe
     use B
   }
 
-When compiling a source file that implements a module, use the option ``-fmodule-name=``module-id to indicate that the source file is logically part of that module.
+When compiling a source file that implements a module, use the option ``-fmodule-name=module-id`` to indicate that the source file is logically part of that module.
 
 The compiler at present only applies restrictions to the module directly being built.
 
@@ -691,6 +736,63 @@ Attributes are used in a number of places in the grammar to describe specific be
 
 Any *identifier* can be used as an attribute, and each declaration specifies what attributes can be applied to it.
 
+Private Module Map Files
+------------------------
+Module map files are typically named ``module.modulemap`` and live
+either alongside the headers they describe or in a parent directory of
+the headers they describe. These module maps typically describe all of
+the API for the library.
+
+However, in some cases, the presence or absence of particular headers
+is used to distinguish between the "public" and "private" APIs of a
+particular library. For example, a library may contain the headers
+``Foo.h`` and ``Foo_Private.h``, providing public and private APIs,
+respectively. Additionally, ``Foo_Private.h`` may only be available on
+some versions of library, and absent in others. One cannot easily
+express this with a single module map file in the library:
+
+.. parsed-literal::
+
+  module Foo {
+    header "Foo.h"
+    
+    explicit module Private {
+      header "Foo_Private.h"
+    }
+  }
+
+
+because the header ``Foo_Private.h`` won't always be available. The
+module map file could be customized based on whether
+``Foo_Private.h`` is available or not, but doing so requires custom
+build machinery.
+
+Private module map files, which are named ``module.private.modulemap``
+(or, for backward compatibility, ``module_private.map``), allow one to
+augment the primary module map file with an additional submodule. For
+example, we would split the module map file above into two module map
+files:
+
+.. code-block:: c
+
+  /* module.modulemap */
+  module Foo {
+    header "Foo.h"
+  }
+  
+  /* module.private.modulemap */
+  explicit module Foo.Private {
+    header "Foo_Private.h"
+  }
+
+
+When a ``module.private.modulemap`` file is found alongside a
+``module.modulemap`` file, it is loaded after the ``module.modulemap``
+file. In our example library, the ``module.private.modulemap`` file
+would be available when ``Foo_Private.h`` is available, making it
+easier to split a library's public and private APIs along header
+boundaries.
+
 Modularizing a Platform
 =======================
 To get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system's headers and the C standard library headers (in ``/usr/include``, for a Unix system). 
@@ -740,7 +842,7 @@ Where To Learn More About Modules
 =================================
 The Clang source code provides additional information about modules:
 
-``clang/lib/Headers/module.map``
+``clang/lib/Headers/module.modulemap``
   Module map for Clang's compiler-specific header files.
 
 ``clang/test/Modules/``
diff --git a/docs/ObjectiveCLiterals.rst b/docs/ObjectiveCLiterals.rst
index 8066d8f6bea..8907c1efc77 100644
--- a/docs/ObjectiveCLiterals.rst
+++ b/docs/ObjectiveCLiterals.rst
@@ -91,7 +91,7 @@ Previously, the ``BOOL`` type was simply a typedef for ``signed char``,
 and ``YES`` and ``NO`` were macros that expand to ``(BOOL)1`` and
 ``(BOOL)0`` respectively. To support ``@YES`` and ``@NO`` expressions,
 these macros are now defined using new language keywords in
-``<objc/objc.h>``:
+````:
 
 .. code-block:: objc
 
@@ -251,7 +251,7 @@ This creates an ``NSDictionary`` with 3 key/value pairs. Value
 sub-expressions of a dictionary literal must be Objective-C object
 pointer typed, as in array literals. Key sub-expressions must be of an
 Objective-C object pointer type that implements the
-``<NSCopying>`` protocol.
+```` protocol.
 
 Discussion
 ----------
diff --git a/docs/PTHInternals.rst b/docs/PTHInternals.rst
index 10dda6117b7..7401cf9b4d4 100644
--- a/docs/PTHInternals.rst
+++ b/docs/PTHInternals.rst
@@ -135,11 +135,11 @@ copy-on-write pages, the approach itself can fundamentally dominate at
 an algorithmic level, especially when one considers header files of
 arbitrary size.
 
-There are plans to potentially implement an complementary PCH
-implementation for Clang based on the lazy deserialization of ASTs. This
-approach would theoretically have the same constant-time algorithmic
-advantages just mentioned but would also retain some of the strengths of
-PTH such as reduced memory pressure (ideal for multi-core builds).
+There is also a PCH implementation for Clang based on the lazy
+deserialization of ASTs. This approach theoretically has the same
+constant-time algorithmic advantages just mentioned but also retains some
+of the strengths of PTH such as reduced memory pressure (ideal for
+multi-core builds).
 
 Internal PTH Optimizations
 --------------------------
diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst
index 597d48142f0..5ff136e5f6d 100644
--- a/docs/ReleaseNotes.rst
+++ b/docs/ReleaseNotes.rst
@@ -1,6 +1,6 @@
-=====================================
-Clang 3.4 (In-Progress) Release Notes
-=====================================
+=======================
+Clang 3.5 Release Notes
+=======================
 
 .. contents::
    :local:
@@ -8,17 +8,11 @@ Clang 3.4 (In-Progress) Release Notes
 
 Written by the `LLVM Team `_
 
-.. warning::
-
-   These are in-progress notes for the upcoming Clang 3.4 release. You may
-   prefer the `Clang 3.3 Release Notes
-   `_.
-
 Introduction
 ============
 
 This document contains the release notes for the Clang C/C++/Objective-C
-frontend, part of the LLVM Compiler Infrastructure, release 3.4. Here we
+frontend, part of the LLVM Compiler Infrastructure, release 3.5. Here we
 describe the status of Clang in some detail, including major
 improvements from the previous release and new feature work. For the
 general LLVM release notes, see `the LLVM
@@ -36,7 +30,7 @@ main Clang web page, this document applies to the *next* release, not
 the current one. To see the release notes for a specific release, please
 see the `releases page `_.
 
-What's New in Clang 3.4?
+What's New in Clang 3.5?
 ========================
 
 Some of the major new features and improvements to Clang are listed
@@ -44,128 +38,216 @@ here. Generic improvements to Clang as a whole or to its underlying
 infrastructure are described first, followed by language-specific
 sections with improvements to Clang's support for those languages.
 
-Last release which will build as C++98
---------------------------------------
-
-This is expected to be the last release of Clang which compiles using a C++98
-toolchain. We expect to start using some C++11 features in Clang starting after
-this release. That said, we are committed to supporting a reasonable set of
-modern C++ toolchains as the host compiler on all of the platforms. This will
-at least include Visual Studio 2012 on Windows, and Clang 3.1 or GCC 4.7.x on
-Mac and Linux. The final set of compilers (and the C++11 features they support)
-is not set in stone, but we wanted users of Clang to have a heads up that the
-next release will involve a substantial change in the host toolchain
-requirements.
-
-Note that this change is part of a change for the entire LLVM project, not just
-Clang.
-
 Major New Features
 ------------------
 
+- Clang uses the new MingW ABI
+  GCC 4.7 changed the mingw ABI. Clang 3.4 and older use the GCC 4.6
+  ABI. Clang 3.5 and newer use the GCC 4.7 abi.
+
+- The __has_attribute feature test is now target-aware. Older versions of Clang
+  would return true when the attribute spelling was known, regardless of whether
+  the attribute was available to the specific target. Clang now returns true
+  only when the attribute pertains to the current compilation target.
+  
+- Clang 3.5 now has parsing and semantic-analysis support for all OpenMP 3.1
+  pragmas (except atomics and ordered). LLVM's OpenMP runtime library,
+  originally developed by Intel, has been modified to work on ARM, PowerPC,
+  as well as X86. Code generation support is minimal at this point and will
+  continue to be developed for 3.6, along with the rest of OpenMP 3.1.
+  Support for OpenMP 4.0 features, such as SIMD and target accelerator
+  directives, is also in progress. Contributors to this work include AMD,
+  Argonne National Lab., IBM, Intel, Texas Instruments, University of Houston
+  and many others.
+
 Improvements to Clang's diagnostics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Clang's diagnostics are constantly being improved to catch more issues,
 explain them more clearly, and provide more accurate source information
-about them. The improvements since the 3.3 release include:
+about them. The improvements since the 3.4 release include:
+
+- GCC compatibility: Clang displays a warning on unsupported gcc
+  optimization flags instead of an error.
+
+- Remarks system: Clang supports `-R` flags for enabling remarks. These are
+  diagnostic messages that provide information about the compilation process,
+  but don't suggest that a problem has been detected. As such, they cannot
+  be upgraded to errors with `-Werror` or `-Rerror`. A `-Reverything` flag
+  is provided (paralleling `-Weverything`) to turn on all remarks.
+
+- New remark `-Rpass`: Clang provides information about decisions made by
+  optimization passes during compilation. See :ref:`opt_rpass`.
+
+- New warning `-Wabsolute-value`: Clang warns about incorrect or useless usage
+  of the absolute functions (`abs`, `fabsf`, etc).
+
+  .. code-block:: c
+
+    #include 
+    void foo() {
+     unsigned int i=0;
+     abs(i);
+    }
+
+  returns
+  `warning: taking the absolute value of unsigned type 'unsigned int' has no effect [-Wabsolute-value]`
+
+  or
+
+  .. code-block:: c
+
+    #include 
+    void plop() {
+      long long i=0;
+      abs(i);
+    }
+
+  returns
+  `warning: absolute value function 'abs' given an argument of type 'long long' but has parameter of type 'int' which may cause truncation of value [-Wabsolute-value] use function 'llabs' instead`
+
+- New warning `-Wtautological-pointer-compare`:
+
+  .. code-block:: c++
+
+    #include 
+    void foo() {
+     int arr[5];
+     int x;
+     // warn on these conditionals
+     if (foo);
+     if (arr);
+     if (&x);
+     if (foo == NULL);
+     if (arr == NULL);
+     if (&x == NULL);
+    }
+
+  returns
+  `warning: comparison of address of 'x' equal to a null pointer is always false [-Wtautological-pointer-compare]`
+
+- New warning `-Wtautological-undefined-compare`: 
+
+  .. code-block:: c++
+
+    #include 
+    void f(int &x) {
+       if (&x == nullptr) { }
+    }
+
+  returns
+  `warning: reference cannot be bound to dereferenced null pointer in well-defined C++ code; comparison may be assumed to always evaluate to false [-Wtautological-undefined-compare]`
 
 -  ...
 
 New Compiler Flags
 ------------------
 
-- Clang no longer special cases -O4 to enable lto. Explicitly pass -flto to
-  enable it.
-- Clang no longer fails on >= -O5. Uses -O3 instead.
-- Command line "clang -O3 -flto a.c -c" and "clang -emit-llvm a.c -c"
-  are no longer equivalent.
-- Clang now errors on unknown -m flags (``-munknown-to-clang``),
-  unknown -f flags (``-funknown-to-clang``) and unknown
-  options (``-what-is-this``).
+The integrated assembler is now turned on by default on ARM (and Thumb),
+so the use of the option `-fintegrated-as` is now redundant on those
+architectures. This is an important move to both *eat our own dog food*
+and to ease cross-compilation tremendously.
+
+We are aware of the problems that this may cause for code bases that
+rely on specific GNU syntax or extensions, and we're working towards
+getting them all fixed. Please, report bugs or feature requests if
+you find anything. In the meantime, use `-fno-integrated-as` to revert
+back the call to GNU assembler.
 
-C Language Changes in Clang
----------------------------
+In order to provide better diagnostics, the integrated assembler validates
+inline assembly when the integrated assembler is enabled.  Because this is
+considered a feature of the compiler, it is controlled via the `fintegrated-as`
+and `fno-integrated-as` flags which enable and disable the integrated assembler
+respectively.  `-integrated-as` and `-no-integrated-as` are now considered
+legacy flags (but are available as an alias to prevent breaking existing users),
+and users are encouraged to switch to the equivalent new feature flag.
 
-- Added new checked arithmetic builtins for security critical applications.
+Deprecated flags `-faddress-sanitizer`, `-fthread-sanitizer`,
+`-fcatch-undefined-behavior` and `-fbounds-checking` were removed in favor of
+`-fsanitize=` family of flags.
 
-C11 Feature Support
-^^^^^^^^^^^^^^^^^^^
+It is now possible to get optimization reports from the major transformation
+passes via three new flags: `-Rpass`, `-Rpass-missed` and `-Rpass-analysis`.
+These flags take a POSIX regular expression which indicates the name
+of the pass (or passes) that should emit optimization remarks.
 
-...
+Options `-u` and `-z` are forwarded to the linker on gnutools toolchains.
+
+
+New Pragmas in Clang
+-----------------------
+
+Loop optimization hints can be specified using the new `#pragma clang loop`
+directive just prior to the desired loop. The directive allows vectorization and
+interleaving to be enabled or disabled. Vector width as well as interleave count
+can be manually specified.  See :ref:`langext-pragma-loop` for details.
 
 C++ Language Changes in Clang
 -----------------------------
 
-- Fixed an ABI regression, introduced in Clang 3.2, which affected
-  member offsets for classes inheriting from certain classes with tail padding.
-  See PR16537.
+- Reference parameters and return values from functions are more aggressively
+  assumed to refer to valid objects when optimizing. Clang will attempt to
+  issue a warning by default if it sees null checks being performed on
+  references, and `-fsanitize=null` can be used to detect null references
+  being formed at runtime.
 
-- ...
-
-C++11 Feature Support
+C++17 Feature Support
 ^^^^^^^^^^^^^^^^^^^^^
 
-...
+Clang has experimental support for some proposed C++1z (tentatively, C++17)
+features. This support can be enabled using the `-std=c++1z` flag. The
+supported features are:
 
-Objective-C Language Changes in Clang
--------------------------------------
+- `static_assert(expr)` with no message
 
-...
+- `for (identifier : range)` as a synonym for `for (auto &&identifier : range)`
 
-OpenCL C Language Changes in Clang
-----------------------------------
+- `template typename>` as a synonym for `template class>`
+
+Additionally, trigraphs are not recognized by default in this mode.
+`-ftrigraphs` can be used if you need to parse legacy code that uses trigraphs.
+Note that these features may be changed or removed in future Clang releases
+without notice.
+
+OpenMP C/C++ Language Changes in Clang
+--------------------------------------
+
+- `Status of supported OpenMP constructs 
+  `_.
 
-- OpenCL C "long" now always has a size of 64 bit, and all OpenCL C
-  types are aligned as specified in the OpenCL C standard. Also,
-  "char" is now always signed.
 
 Internal API Changes
 --------------------
 
-These are major API changes that have happened since the 3.3 release of
+These are major API changes that have happened since the 3.4 release of
 Clang. If upgrading an external codebase that uses Clang as a library,
 this section should help get you past the largest hurdles of upgrading.
 
-Wide Character Types
-^^^^^^^^^^^^^^^^^^^^
-
-The ASTContext class now keeps track of two different types for wide character
-types: WCharTy and WideCharTy. WCharTy represents the built-in wchar_t type
-available in C++. WideCharTy is the type used for wide character literals; in
-C++ it is the same as WCharTy, but in C99, where wchar_t is a typedef, it is an
-integer type.
-
-...
-
-libclang
---------
-
-...
+- Clang uses `std::unique_ptr` in many places where it used to use
+  raw `T *` pointers.
 
 Static Analyzer
 ---------------
 
-The static analyzer (which contains additional code checking beyond compiler
-warnings) has improved significantly in both in the core analysis engine and 
-also in the kinds of issues it can find.
+Check for code testing a variable for 0 after using it as a denominator.
+This new checker, alpha.core.TestAfterDivZero, catches issues like this:
 
-Core Analysis Improvements
-==========================
+.. code-block:: c
 
-- ...
+  int sum = ...
+  int avg = sum / count; // potential division by zero...
+  if (count == 0) { ... } // ...caught here
 
-New Issues Found
-================
 
-- ...
+The `-analyzer-config` options are now passed from scan-build through to
+ccc-analyzer and then to Clang.
 
-Python Binding Changes
-----------------------
+With the option `-analyzer-config stable-report-filename=true`,
+instead of `report-XXXXXX.html`, scan-build/clang analyzer generate
+`report----.html`.
+(id = i++ for several issues found in the same function/method).
 
-The following methods have been added:
-
--  ...
+List the function/method name in the index page of scan-build.
 
 Significant Known Problems
 ==========================
diff --git a/docs/SanitizerSpecialCaseList.rst b/docs/SanitizerSpecialCaseList.rst
index 8f4727c2fbc..a4165b2521c 100644
--- a/docs/SanitizerSpecialCaseList.rst
+++ b/docs/SanitizerSpecialCaseList.rst
@@ -24,7 +24,7 @@ certain source-level entities to:
   thread stack, bypassing the frame boundaries);
 * ignore a known problem.
 
-To achieve this, user may create a file listing the entities he wants to
+To achieve this, user may create a file listing the entities they want to
 ignore, and pass it to clang at compile-time using
 ``-fsanitize-blacklist`` flag. See :doc:`UsersManual` for details.
 
diff --git a/docs/ThreadSafetyAnalysis.rst b/docs/ThreadSafetyAnalysis.rst
new file mode 100644
index 00000000000..dfef80b69fa
--- /dev/null
+++ b/docs/ThreadSafetyAnalysis.rst
@@ -0,0 +1,818 @@
+
+======================
+Thread Safety Analysis
+======================
+
+Introduction
+============
+
+Clang Thread Safety Analysis is a C++ language extension which warns about
+potential race conditions in code.  The analysis is completely static (i.e.
+compile-time); there is no run-time overhead.  The analysis is still
+under active development, but it is mature enough to be deployed in an
+industrial setting.  It being developed by Google, and is used extensively
+on their internal code base.
+
+Thread safety analysis works very much like a type system for multi-threaded
+programs.  In addition to declaring the *type* of data (e.g. ``int``, ``float``,
+etc.), the programmer can (optionally) declare how access to that data is
+controlled in a multi-threaded environment.  For example, if ``foo`` is
+*guarded by* the mutex ``mu``, then the analysis will issue a warning whenever
+a piece of code reads or writes to ``foo`` without first locking ``mu``.
+Similarly, if there are particular routines that should only be called by
+the GUI thread, then the analysis will warn if other threads call those
+routines. 
+
+Getting Started
+----------------
+
+.. code-block:: c++
+
+  #include "mutex.h"
+
+  class BankAccount {
+  private:
+    Mutex mu;
+    int   balance GUARDED_BY(mu);
+  
+    void depositImpl(int amount) {
+      balance += amount;       // WARNING! Cannot write balance without locking mu.
+    }
+  
+    void withdrawImpl(int amount) EXCLUSIVE_LOCKS_REQUIRED(mu) {
+      balance -= amount;       // OK. Caller must have locked mu.
+    }
+  
+  public:
+    void withdraw(int amount) {
+      mu.Lock();
+      withdrawImpl(amount);    // OK.  We've locked mu.
+    }                          // WARNING!  Failed to unlock mu.
+  
+    void transferFrom(BankAccount& b, int amount) {
+      mu.Lock();
+      b.withdrawImpl(amount);  // WARNING!  Calling withdrawImpl() requires locking b.mu.
+      depositImpl(amount);     // OK.  depositImpl() has no requirements.
+      mu.Unlock();
+    }
+  };
+
+This example demonstrates the basic concepts behind the analysis.  The
+``GUARDED_BY`` attribute declares that a thread must lock ``mu`` before it can
+read or write to ``balance``, thus ensuring that the increment and decrement
+operations are atomic.  Similarly, ``EXCLUSIVE_LOCKS_REQUIRED`` declares that
+the calling thread must lock ``mu`` before calling ``withdrawImpl``.
+Because the caller is assumed to have locked ``mu``, it is safe to modify
+``balance`` within the body of the method.
+
+The ``depositImpl()`` method does not have ``EXCLUSIVE_LOCKS_REQUIRED``, so the
+analysis issues a warning.  Thread safety analysis is not inter-procedural, so
+caller requirements must be explicitly declared.
+There is also a warning in ``transferFrom()``, because although the method
+locks ``this->mu``, it does not lock ``b.mu``.  The analysis understands
+that these are two separate mutexes, in two different objects.  
+
+Finally, there is a warning in the ``withdraw()`` method, because it fails to
+unlock ``mu``.  Every lock must have a corresponding unlock, and the analysis
+will detect both double locks, and double unlocks.  A function is allowed to
+acquire a lock without releasing it, (or vice versa), but it must be annotated
+as such (using ``LOCK``/``UNLOCK_FUNCTION``).
+
+
+Running The Analysis
+--------------------
+
+To run the analysis, simply compile with the ``-Wthread-safety`` flag, e.g.
+
+.. code-block:: bash
+
+  clang -c -Wthread-safety example.cpp
+
+Note that this example assumes the presence of a suitably annotated
+:ref:`mutexheader` that declares which methods perform locking,
+unlocking, and so on. 
+
+
+Basic Concepts: Capabilities
+============================
+
+Thread safety analysis provides a way of protecting *resources* with
+*capabilities*.  A resource is either a data member, or a function/method
+that provides access to some underlying resource.  The analysis ensures that
+the calling thread cannot access the *resource* (i.e. call the function, or
+read/write the data) unless it has the *capability* to do so.
+
+Capabilities are associated with named C++ objects which declare specific
+methods to acquire and release the capability.  The name of the object serves
+to identify the capability.  The most common example is a mutex.  For example,
+if ``mu`` is a mutex, then calling ``mu.Lock()`` causes the calling thread
+to acquire the capability to access data that is protected by ``mu``. Similarly, 
+calling ``mu.Unlock()`` releases that capability.
+
+A thread may hold a capability either *exclusively* or *shared*.  An exclusive
+capability can be held by only one thread at a time, while a shared capability
+can be held by many threads at the same time.  This mechanism enforces a
+multiple-reader, single-writer pattern.  Write operations to protected data
+require exclusive access, while read operations require only shared access.  
+
+At any given moment during program execution, a thread holds a specific set of
+capabilities (e.g. the set of mutexes that it has locked.)  These act like keys
+or tokens that allow the thread to access a given resource.  Just like physical
+security keys, a thread cannot make copy of a capability, nor can it destroy
+one.  A thread can only release a capability to another thread, or acquire one
+from another thread.  The annotations are deliberately agnostic about the
+exact mechanism used to acquire and release capabilities; it assumes that the 
+underlying implementation (e.g. the Mutex implementation) does the handoff in
+an appropriate manner.
+
+The set of capabilities that are actually held by a given thread at a given
+point in program execution is a run-time concept.  The static analysis works
+by calculating an approximation of that set, called the *capability
+environment*.  The capability environment is calculated for every program point,
+and describes the set of capabilities that are statically known to be held, or
+not held, at that particular point.  This environment is a conservative
+approximation of the full set of capabilities that will actually held by a
+thread at run-time.
+
+
+Reference Guide
+===============
+
+The thread safety analysis uses attributes to declare threading constraints.
+Attributes must be attached to named declarations, such as classes, methods,
+and data members. Users are *strongly advised* to define macros for the various
+attributes; example definitions can be found in :ref:`mutexheader`, below.
+The following documentation assumes the use of macros.
+
+
+GUARDED_BY(c) and PT_GUARDED_BY(c)
+----------------------------------
+
+``GUARDED_BY`` is an attribute on data members, which declares that the data
+member is protected by the given capability.  Read operations on the data
+require shared access, while write operations require exclusive access.
+
+``PT_GUARDED_BY`` is similar, but is intended for use on pointers and smart
+pointers. There is no constraint on the data member itself, but the *data that
+it points to* is protected by the given capability.  
+
+.. code-block:: c++
+
+  Mutex mu;
+  int *p1            GUARDED_BY(mu);
+  int *p2            PT_GUARDED_BY(mu);
+  unique_ptr p3 PT_GUARDED_BY(mu);
+  
+  void test() {
+    p1 = 0;             // Warning!
+  
+    p2 = new int;       // OK.
+    *p2 = 42;           // Warning!
+  
+    p3.reset(new int);  // OK.
+    *p3 = 42;           // Warning!
+  }
+
+
+EXCLUSIVE_LOCKS_REQUIRED(...), SHARED_LOCKS_REQUIRED(...)
+---------------------------------------------------------
+
+``EXCLUSIVE_LOCKS_REQUIRED`` is an attribute on functions or methods, which
+declares that the calling thread must have exclusive access to the given
+capabilities.  More than one capability may be specified.  The capabilities
+must be held on entry to the function, *and must still be held on exit*.  
+
+``SHARED_LOCKS_REQUIRED`` is similar, but requires only shared access.
+
+.. code-block:: c++
+
+  Mutex mu1, mu2;
+  int a GUARDED_BY(mu1);
+  int b GUARDED_BY(mu2);
+  
+  void foo() EXCLUSIVE_LOCKS_REQUIRED(mu1, mu2) {
+    a = 0;
+    b = 0;
+  }
+  
+  void test() {
+    mu1.Lock();
+    foo();         // Warning!  Requires mu2.
+    mu1.Unlock();
+  }
+
+
+EXCLUSIVE_LOCK_FUNCTION(...), SHARED_LOCK_FUNCTION(...), UNLOCK_FUNCTION(...)
+-----------------------------------------------------------------------------
+
+``EXCLUSIVE_LOCK_FUNCTION`` is an attribute on functions or methods, which
+declares that the function acquires a capability, but does not release it.  The
+caller must not hold the given capability on entry, and it will hold the
+capability on exit.  ``SHARED_LOCK_FUNCTION`` is similar. 
+
+``UNLOCK_FUNCTION`` declares that the function releases the given capability.
+The caller must hold the capability on entry, and will no longer hold it on
+exit. It does not matter whether the given capability is shared or exclusive.
+
+.. code-block:: c++
+
+  Mutex mu;
+  MyClass myObject GUARDED_BY(mu);
+  
+  void lockAndInit() EXCLUSIVE_LOCK_FUNCTION(mu) {
+    mu.Lock();
+    myObject.init();
+  }
+  
+  void cleanupAndUnlock() UNLOCK_FUNCTION(mu) {
+    myObject.cleanup();
+  }  // Warning!  Need to unlock mu.
+  
+  void test() {
+    lockAndInit();
+    myObject.doSomething();
+    cleanupAndUnlock();
+    myObject.doSomething();  // Warning, mu is not locked.
+  }
+
+If no argument is passed to ``(UN)LOCK_FUNCTION``, then the argument is assumed
+to be ``this``, and the analysis will not check the body of the function.  This
+pattern is intended for use by classes which hide locking details behind an
+abstract interface.  E.g.
+
+.. code-block:: c++
+
+  template 
+  class LOCKABLE Container {
+  private:
+    Mutex mu;
+    T* data;
+  
+  public:
+    // Hide mu from public interface.
+    void Lock() EXCLUSIVE_LOCK_FUNCTION() { mu.Lock(); }
+    void Unlock() UNLOCK_FUNCTION() { mu.Unlock(); }
+  
+    T& getElem(int i) { return data[i]; }
+  };
+  
+  void test() {
+    Container c;
+    c.Lock();
+    int i = c.getElem(0);
+    c.Unlock();
+  }
+
+
+LOCKS_EXCLUDED(...)
+-------------------
+
+``LOCKS_EXCLUDED`` is an attribute on functions or methods, which declares that
+the caller must *not* hold the given capabilities.  This annotation is
+used to prevent deadlock.  Many mutex implementations are not re-entrant, so
+deadlock can occur if the function in question acquires the mutex a second time.
+
+.. code-block:: c++
+
+  Mutex mu;
+  int a GUARDED_BY(mu);
+  
+  void clear() LOCKS_EXCLUDED(mu) {
+    mu.Lock();
+    a = 0;
+    mu.Unlock();
+  }
+  
+  void reset() {
+    mu.Lock();
+    clear();     // Warning!  Caller cannot hold 'mu'.
+    mu.Unlock();
+  }
+
+Unlike ``LOCKS_REQUIRED``, ``LOCKS_EXCLUDED`` is optional.  The analysis will
+not issue a warning if the attribute is missing.  See :ref:`limitations`.
+
+
+NO_THREAD_SAFETY_ANALYSIS
+-------------------------
+
+``NO_THREAD_SAFETY_ANALYSIS`` is an attribute on functions or methods, which
+turns off thread safety checking for that method.  It provides an escape hatch
+for functions which are either (1) deliberately thread-unsafe, or (2) are
+thread-safe, but too complicated for the analysis to understand.  Reasons for
+(2) will be described in the :ref:`limitations`, below.
+
+.. code-block:: c++
+
+  class Counter {
+    Mutex mu;
+    int a GUARDED_BY(mu);
+  
+    void unsafeIncrement() NO_THREAD_SAFETY_ANALYSIS { a++; }
+  };
+
+
+LOCK_RETURNED(c)
+----------------
+
+``LOCK_RETURNED`` is an attribute on functions or methods, which declares that
+the function returns a reference to the given capability.  It is used to
+annotate getter methods that return mutexes.
+
+.. code-block:: c++
+
+  class MyClass {
+  private:
+    Mutex mu;
+    int a GUARDED_BY(mu);
+  
+  public:
+    Mutex* getMu() LOCK_RETURNED(mu) { return μ }
+  
+    // analysis knows that getMu() == mu
+    void clear() EXCLUSIVE_LOCKS_REQUIRED(getMu()) { a = 0; }
+  };
+
+
+ACQUIRED_BEFORE(...), ACQUIRED_AFTER(...)
+-----------------------------------------
+
+``ACQUIRED_BEFORE`` and ``ACQUIRED_AFTER`` are attributes on member
+declarations, specifically declarations of mutexes or other capabilities.
+These declarations enforce a particular order in which the mutexes must be
+acquired, in order to prevent deadlock.
+
+.. code-block:: c++
+
+  Mutex m1;
+  Mutex m2 ACQUIRED_AFTER(m1);
+  
+  // Alternative declaration
+  // Mutex m2;
+  // Mutex m1 ACQUIRED_BEFORE(m2);
+  
+  void foo() {
+    m2.Lock();
+    m1.Lock();  // Warning!  m2 must be acquired after m1.
+    m1.Unlock();
+    m2.Unlock();
+  }
+
+
+LOCKABLE
+--------
+
+``LOCKABLE`` is an attribute on classes, which specifies that objects of the
+class can be used as a capability.  See the ``Container`` example given above,
+or the ``Mutex`` class in :ref:`mutexheader`.
+
+
+SCOPED_LOCKABLE
+---------------
+
+``SCOPED_LOCKABLE`` is an attribute on classes that implement RAII-style
+locking, in which a capability is acquired in the constructor, and released in
+the destructor.  Such classes require special handling because the constructor
+and destructor refer to the capability via different names; see the
+``MutexLocker`` class in :ref:`mutexheader`, below.
+
+
+EXCLUSIVE_TRYLOCK_FUNCTION(, ...), SHARED_TRYLOCK_FUNCTION(, ...)
+-----------------------------------------------------------------------------
+
+These are attributes on a function or method that tries to acquire the given
+capability, and returns a boolean value indicating success or failure.
+The first argument must be ``true`` or ``false``, to specify which return value
+indicates success, and the remaining arguments are interpreted in the same way
+as ``(UN)LOCK_FUNCTION``.  See :ref:`mutexheader`, below, for example uses.
+
+
+ASSERT_EXCLUSIVE_LOCK(...) and ASSERT_SHARED_LOCK(...)
+------------------------------------------------------
+
+These are attributes on a function or method that does a run-time test to see
+whether the calling thread holds the given capability.  The function is assumed
+to fail (no return) if the capability is not held.  See :ref:`mutexheader`,
+below, for example uses.
+
+
+GUARDED_VAR and PT_GUARDED_VAR
+------------------------------
+
+Use of these attributes has been deprecated.
+
+
+Warning flags
+-------------
+
+* ``-Wthread-safety``:  Umbrella flag which turns on the following three:
+
+  + ``-Wthread-safety-attributes``: Sanity checks on attribute syntax.
+  + ``-Wthread-safety-analysis``: The core analysis.
+  + ``-Wthread-safety-precise``: Requires that mutex expressions match precisely.
+    This warning can be disabled for code which has a lot of aliases.
+
+When new features and checks are added to the analysis, they can often introduce
+additional warnings.  Those warnings are initially released as *beta* warnings
+for a period of time, after which they are migrated to the standard analysis.  
+
+* ``-Wthread-safety-beta``:  New features.  Off by default. 
+
+
+.. _faq:
+
+Frequently Asked Questions
+==========================
+
+(Q) Should I put attributes in the header file, or in the .cc/.cpp/.cxx file?
+
+(A) Attributes should always go in the header.
+
+
+(Q) "*Mutex is not locked on every path through here?*"  What does that mean?
+
+(A) See :ref:`conditional_locks`, below.
+
+
+.. _limitations:
+
+Known Limitations 
+=================
+
+Lexical scope
+-------------
+
+Thread safety attributes contain ordinary C++ expressions, and thus follow
+ordinary C++ scoping rules.  In particular, this means that mutexes and other
+capabilities must be declared before they can be used in an attribute.
+Use-before-declaration is okay within a single class, because attributes are
+parsed at the same time as method bodies. (C++ delays parsing of method bodies
+until the end of the class.)  However, use-before-declaration is not allowed
+between classes, as illustrated below.  
+
+.. code-block:: c++
+
+  class Foo;
+
+  class Bar {
+    void bar(Foo* f) EXCLUSIVE_LOCKS_REQUIRED(f->mu);  // Error: mu undeclared.
+  };
+
+  class Foo {
+    Mutex mu;
+  };
+
+
+Private Mutexes
+---------------
+
+Good software engineering practice dictates that mutexes should be private
+members, because the locking mechanism used by a thread-safe class is part of
+its internal implementation.  However, private mutexes can sometimes leak into
+the public interface of a class.
+Thread safety attributes follow normal C++ access restrictions, so if ``mu``
+is a private member of ``c``, then it is an error to write ``c.mu`` in an
+attribute.
+
+One workround is to (ab)use the ``LOCK_RETURNED`` attribute to provide a public
+*name* for a private mutex, without actually exposing the underlying mutex.
+For example:
+
+.. code-block:: c++
+
+  class MyClass {
+  private:
+    Mutex mu;
+
+  public:
+    // For thread safety analysis only.  Does not actually return mu.
+    Mutex* getMu() LOCK_RETURNED(mu) { return 0; }
+
+    void doSomething() EXCLUSIVE_LOCKS_REQUIRED(mu); 
+  };
+
+  void doSomethingTwice(MyClass& c) EXCLUSIVE_LOCKS_REQUIRED(c.getMu()) {
+    // The analysis thinks that c.getMu() == c.mu
+    c.doSomething();
+    c.doSomething();
+  }
+
+In the above example, ``doSomethingTwice()`` is an external routine that
+requires ``c.mu`` to be locked, which cannot be declared directly because ``mu``
+is private.  This pattern is discouraged because it
+violates encapsulation, but it is sometimes necessary, especially when adding
+annotations to an existing code base.  The workaround is to define ``getMu()``
+as a fake getter method, which is provided only for the benefit of thread
+safety analysis.
+
+
+False negatives on pass by reference.
+-------------------------------------
+
+The current version of the analysis only checks operations which refer to
+guarded data members directly by name.  If the data members are accessed
+indirectly, via a pointer or reference, then no warning is generated.  Thus,
+no warnings will be generated for the following code:
+
+.. code-block:: c++
+
+  Mutex mu;
+  int a GUARDED_BY(mu);
+
+  void clear(int& ra) { ra = 0; }
+
+  void test() {
+    int *p = &a;
+    *p = 0;       // No warning.  *p is an alias to a.  
+       
+    clear(a);     // No warning.  'a' is passed by reference.
+  }
+
+This issue is by far the biggest source of false negatives in the current
+version of the analysis.  At a fundamental level, the
+false negatives are caused by the fact that annotations are attached to data
+members, rather than types.  The type of ``&a`` should really be
+``int GUARDED_BY(mu)*``, rather than ``int*``, and the statement ``p = &a``
+should thus generate a type error.  However, attaching attributes to types
+would be an invasive change to the C++ type system, with potential
+ramifications with respect to template instantation, function overloading,
+and so on.  Thus, a complete solution to this issue is simply not feasible.
+
+Future versions of the analysis will include better support for pointer
+alias analysis, along with limited checking of guarded types, in order to
+reduce the number of false negatives.
+
+
+.. _conditional_locks:
+
+No conditionally held locks.
+----------------------------
+
+The analysis must be able to determine whether a lock is held, or not held, at
+every program point.  Thus, sections of code where a lock *might be held* will
+generate spurious warnings (false positives).  For example:
+
+.. code-block:: c++
+
+  void foo() {
+    bool b = needsToLock();
+    if (b) mu.Lock();
+    ...  // Warning!  Mutex 'mu' is not held on every path through here. 
+    if (b) mu.Unlock();
+  }
+
+
+No checking inside constructors and destructors.
+------------------------------------------------
+
+The analysis currently does not do any checking inside constructors or
+destructors.  In other words, every constructor and destructor is treated as
+if it was annotated with ``NO_THREAD_SAFETY_ANALYSIS``.  
+The reason for this is that during initialization, only one thread typically
+has access to the object which is being initialized, and it is thus safe (and
+common practice) to initialize guarded members without acquiring any locks.
+The same is true of destructors.
+
+Ideally, the analysis would allow initialization of guarded members inside the
+object being initialized or destroyed, while still enforcing the usual access
+restrictions on everything else.  However, this is difficult to enforce in
+practice, because in complex pointer-based data structures, it is hard to
+determine what data is "owned by" the enclosing object.
+
+No inlining.
+------------
+
+Thread safety analysis is strictly intra-procedural, just like ordinary type
+checking.  It relies only on the declared attributes of a function, and will
+not attempt to "step inside", or inline any method calls.  As a result, code
+such as the following will not work:
+
+.. code-block:: c++
+
+  template
+  class AutoCleanup {
+    T* object;
+    void (T::*mp)();
+    
+  public:
+    AutoCleanup(T* obj, void (T::*imp)()) : object(obj), mp(imp) { }
+    ~AutoCleanup() { (object->*mp)(); }
+  };
+
+  Mutex mu;
+  void foo() {
+    mu.Lock();
+    AutoCleanup(&mu, &Mutex::Unlock); 
+    ...
+  }  // Warning, mu is not unlocked.
+
+In this case, the destructor of ``Autocleanup`` calls ``mu.Unlock()``, so
+the warning is bogus.  However,
+thread safety analysis cannot see the unlock, because it does not attempt to
+inline the destructor.  Moreover, there is no way to annotate the destructor,
+because the destructor is calling a function that is not statically known.
+This pattern is simply not supported. 
+
+
+LOCKS_EXCLUDED is not transitive.
+---------------------------------
+
+A function which calls a method marked with LOCKS_EXCLUDED is not required to
+put LOCKS_EXCLUDED in its own interface.  LOCKS_EXCLUDED behaves differently
+from LOCKS_REQUIRED in this respect, and it can result in false negatives:
+
+.. code-block:: c++
+
+  class Foo {
+    Mutex mu;
+    
+    void foo() {
+      mu.Lock();
+      bar();                // No warning
+      mu.Unlock();
+    }
+    
+    void bar() { baz(); }   // No warning.  (Should have LOCKS_EXCLUDED(mu).)
+    
+    void baz() LOCKS_EXCLUDED(mu);
+  };
+
+The lack of transitivity is due to the fact that LOCKS_EXCLUDED can easily
+break encapsulation; it would be a bad idea to require functions to list the
+names private locks which happen to be acquired internally.  
+
+
+No alias analysis.
+------------------
+
+The analysis currently does not track pointer aliases.  Thus, there can be
+false positives if two pointers both point to the same mutex.  
+
+
+.. code-block:: c++
+
+  class MutexUnlocker {
+    Mutex* mu;
+
+  public:
+    MutexUnlocker(Mutex* m) UNLOCK_FUNCTION(m) : mu(m)  { mu->Unlock(); }
+    ~MutexUnlocker() EXCLUSIVE_LOCK_FUNCTION(mu) { mu->Lock(); }
+  };
+
+  Mutex mutex;
+  void test() EXCLUSIVE_LOCKS_REQUIRED(mutex) {
+    { 
+      MutexUnlocker munl(&mutex);  // unlocks mutex
+      doSomeIO();
+    }                              // Warning: locks munl.mu
+  }
+
+The MutexUnlocker class is intended to be the dual of the MutexLocker class,
+defined in :ref:`mutexheader`.  However, it doesn't work because the analysis
+doesn't know that munl.mu == mutex.  The SCOPED_LOCKABLE attribute handles
+aliasing 
+
+
+ACQUIRED_BEFORE(...) and ACQUIRED_AFTER(...) are currently unimplemented.
+-------------------------------------------------------------------------
+
+To be fixed in a future update. 
+
+
+.. _mutexheader:
+
+mutex.h
+=======
+
+Thread safety analysis can be used with any threading library, but it does
+require that the threading API be wrapped in classes and methods which have the
+appropriate annotations.  The following code provides ``mutex.h`` as an example;
+these methods should be filled in to call the appropriate underlying
+implementation. 
+
+
+.. code-block:: c++
+
+  #ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H
+  #define THREAD_SAFETY_ANALYSIS_MUTEX_H
+  
+  // Enable thread safety attributes only with clang.
+  // The attributes can be safely erased when compiling with other compilers.
+  #if defined(__clang__) && (!defined(SWIG))
+  #define THREAD_ANNOTATION_ATTRIBUTE__(x)   __attribute__((x))
+  #else
+  #define THREAD_ANNOTATION_ATTRIBUTE__(x)   // no-op
+  #endif
+  
+  #define THREAD_ANNOTATION_ATTRIBUTE__(x)   __attribute__((x))
+  
+  #define GUARDED_BY(x) \
+    THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))
+  
+  #define GUARDED_VAR \
+    THREAD_ANNOTATION_ATTRIBUTE__(guarded)
+  
+  #define PT_GUARDED_BY(x) \
+    THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))
+  
+  #define PT_GUARDED_VAR \
+    THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded)
+  
+  #define ACQUIRED_AFTER(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))
+  
+  #define ACQUIRED_BEFORE(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))
+  
+  #define EXCLUSIVE_LOCKS_REQUIRED(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))
+  
+  #define SHARED_LOCKS_REQUIRED(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))
+  
+  #define LOCKS_EXCLUDED(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))
+  
+  #define LOCK_RETURNED(x) \
+    THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))
+  
+  #define LOCKABLE \
+    THREAD_ANNOTATION_ATTRIBUTE__(lockable)
+  
+  #define SCOPED_LOCKABLE \
+    THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)
+  
+  #define EXCLUSIVE_LOCK_FUNCTION(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))
+  
+  #define SHARED_LOCK_FUNCTION(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))
+  
+  #define ASSERT_EXCLUSIVE_LOCK(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))
+  
+  #define ASSERT_SHARED_LOCK(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))
+  
+  #define EXCLUSIVE_TRYLOCK_FUNCTION(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))
+  
+  #define SHARED_TRYLOCK_FUNCTION(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))
+  
+  #define UNLOCK_FUNCTION(...) \
+    THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))
+  
+  #define NO_THREAD_SAFETY_ANALYSIS \
+    THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
+  
+  
+  // Defines an annotated interface for mutexes.
+  // These methods can be implemented to use any internal mutex implementation.
+  class LOCKABLE Mutex {
+  public:
+    // Acquire/lock this mutex exclusively.  Only one thread can have exclusive
+    // access at any one time.  Write operations to guarded data require an
+    // exclusive lock.
+    void Lock() EXCLUSIVE_LOCK_FUNCTION();
+  
+    // Acquire/lock this mutex for read operations, which require only a shared
+    // lock.  This assumes a multiple-reader, single writer semantics.  Multiple
+    // threads may acquire the mutex simultaneously as readers, but a writer must
+    // wait for all of them to release the mutex before it can acquire it
+    // exclusively.  
+    void ReaderLock() SHARED_LOCK_FUNCTION();
+  
+    // Release/unlock the mutex, regardless of whether it is exclusive or shared.
+    void Unlock() UNLOCK_FUNCTION();
+  
+    // Try to acquire the mutex.  Returns true on success, and false on failure.
+    bool TryLock() EXCLUSIVE_TRYLOCK_FUNCTION(true);
+  
+    // Try to acquire the mutex for read operations.
+    bool ReaderTryLock() SHARED_TRYLOCK_FUNCTION(true);
+  
+    // Assert that this mutex is currently held by the calling thread.
+    void AssertHeld() ASSERT_EXCLUSIVE_LOCK();
+  
+    // Assert that is mutex is currently held for read operations. 
+    void AssertReaderHeld() ASSERT_SHARED_LOCK();
+  };
+  
+  
+  // MutexLocker is an RAII class that acquires a mutex in its constructor, and
+  // releases it in its destructor.  
+  class SCOPED_LOCKABLE MutexLocker {
+  private:
+    Mutex* mut;
+  
+  public:
+    MutexLocker(Mutex *mu) EXCLUSIVE_LOCK_FUNCTION(mu) : mut(mu) {
+      mu->Lock();
+    }  
+    ~MutexLocker() UNLOCK_FUNCTION() {
+      mut->Unlock();
+    }
+  };
+  
+  #endif  // THREAD_SAFETY_ANALYSIS_MUTEX_H
diff --git a/docs/ThreadSanitizer.rst b/docs/ThreadSanitizer.rst
index 194ad4a8efb..a1d81e9a9c2 100644
--- a/docs/ThreadSanitizer.rst
+++ b/docs/ThreadSanitizer.rst
@@ -18,9 +18,9 @@ supported.
 Supported Platforms
 -------------------
 
-ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04 and 12.04).
-Support for MacOS 10.7 (64-bit only) is planned for 2013.  Support for 32-bit
-platforms is problematic and not yet planned.
+ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04).
+Support for other 64-bit architectures is possible, contributions are welcome.
+Support for 32-bit platforms is problematic and is not planned.
 
 Usage
 -----
diff --git a/docs/UsersManual.rst b/docs/UsersManual.rst
index e0a68384ad3..90f16ee0d43 100644
--- a/docs/UsersManual.rst
+++ b/docs/UsersManual.rst
@@ -112,11 +112,11 @@ Options to Control Error and Warning Messages
 
 .. option:: -w
 
-  Disable all warnings.
+  Disable all diagnostics.
 
 .. option:: -Weverything
 
-  :ref:`Enable all warnings. `
+  :ref:`Enable all diagnostics. `
 
 .. option:: -pedantic
 
@@ -265,11 +265,6 @@ output format of the diagnostics that it generates.
 
            t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
 
-**-f[no-]diagnostics-show-name**
-   Enable the display of the diagnostic name.
-   This option, which defaults to off, controls whether or not Clang
-   prints the associated name.
-
 .. _opt_fdiagnostics-show-option:
 
 **-f[no-]diagnostics-show-option**
@@ -536,6 +531,67 @@ control the crash diagnostics.
 The -fno-crash-diagnostics flag can be helpful for speeding the process
 of generating a delta reduced test case.
 
+.. _opt_rpass:
+
+Options to Emit Optimization Reports
+------------------------------------
+
+Optimization reports trace, at a high-level, all the major decisions
+done by compiler transformations. For instance, when the inliner
+decides to inline function ``foo()`` into ``bar()``, or the loop unroller
+decides to unroll a loop N times, or the vectorizer decides to
+vectorize a loop body.
+
+Clang offers a family of flags which the optimizers can use to emit
+a diagnostic in three cases:
+
+1. When the pass makes a transformation (:option:`-Rpass`).
+
+2. When the pass fails to make a transformation (:option:`-Rpass-missed`).
+
+3. When the pass determines whether or not to make a transformation
+   (:option:`-Rpass-analysis`).
+
+NOTE: Although the discussion below focuses on :option:`-Rpass`, the exact
+same options apply to :option:`-Rpass-missed` and :option:`-Rpass-analysis`.
+
+Since there are dozens of passes inside the compiler, each of these flags
+take a regular expression that identifies the name of the pass which should
+emit the associated diagnostic. For example, to get a report from the inliner,
+compile the code with:
+
+.. code-block:: console
+
+   $ clang -O2 -Rpass=inline code.cc -o code
+   code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]
+   int bar(int j) { return foo(j, j - 2); }
+                           ^
+
+Note that remarks from the inliner are identified with `[-Rpass=inline]`.
+To request a report from every optimization pass, you should use
+:option:`-Rpass=.*` (in fact, you can use any valid POSIX regular
+expression). However, do not expect a report from every transformation
+made by the compiler. Optimization remarks do not really make sense
+outside of the major transformations (e.g., inlining, vectorization,
+loop optimizations) and not every optimization pass supports this
+feature.
+
+Current limitations
+^^^^^^^^^^^^^^^^^^^
+
+1. Optimization remarks that refer to function names will display the
+   mangled name of the function. Since these remarks are emitted by the
+   back end of the compiler, it does not know anything about the input
+   language, nor its mangling rules.
+
+2. Some source locations are not displayed correctly. The front end has
+   a more detailed source location tracking than the locations included
+   in the debug info (e.g., the front end can locate code inside macro
+   expansions). However, the locations used by :option:`-Rpass` are
+   translated from debug annotations. That translation can be lossy,
+   which results in some remarks having no location information.
+
+
 Language and Target-Independent Features
 ========================================
 
@@ -587,6 +643,7 @@ All diagnostics are mapped into one of these 5 classes:
 
 -  Ignored
 -  Note
+-  Remark
 -  Warning
 -  Error
 -  Fatal
@@ -704,17 +761,18 @@ the pragma onwards within the same file.
 
   char b = 'ab'; // no warning
 
-The :option:`-isystem-prefix` and :option:`-ino-system-prefix` command-line
-arguments can be used to override whether subsets of an include path are
-treated as system headers. When the name in a ``#include`` directive is
-found within a header search path and starts with a system prefix, the
+The :option:`--system-header-prefix=` and :option:`--no-system-header-prefix=`
+command-line arguments can be used to override whether subsets of an include
+path are treated as system headers. When the name in a ``#include`` directive
+is found within a header search path and starts with a system prefix, the
 header is treated as a system header. The last prefix on the
 command-line which matches the specified header name takes precedence.
 For instance:
 
 .. code-block:: console
 
-  $ clang -Ifoo -isystem bar -isystem-prefix x/ -ino-system-prefix x/y/
+  $ clang -Ifoo -isystem bar --system-header-prefix=x/ \
+      --no-system-header-prefix=x/y/
 
 Here, ``#include "x/a.h"`` is treated as including a system header, even
 if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
@@ -727,11 +785,12 @@ is treated as a system header.
 
 .. _diagnostics_enable_everything:
 
-Enabling All Warnings
-^^^^^^^^^^^^^^^^^^^^^
+Enabling All Diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In addition to the traditional ``-W`` flags, one can enable **all**
-warnings by passing :option:`-Weverything`. This works as expected with
+diagnostics by passing :option:`-Weverything`. This works as expected
+with
 :option:`-Werror`, and also includes the warnings from :option:`-pedantic`.
 
 Note that when combined with :option:`-w` (which disables all warnings), that
@@ -765,7 +824,7 @@ on-disk cache that contains the vital information necessary to reduce
 some of the work needed to process a corresponding header file. While
 details of precompiled headers vary between compilers, precompiled
 headers have been shown to be highly effective at speeding up program
-compilation on systems with very large system headers (e.g., Mac OS/X).
+compilation on systems with very large system headers (e.g., Mac OS X).
 
 Generating a PCH File
 ^^^^^^^^^^^^^^^^^^^^^
@@ -874,10 +933,6 @@ are listed below.
       ``-fsanitize=address``:
       :doc:`AddressSanitizer`, a memory error
       detector.
-   -  ``-fsanitize=init-order``: Make AddressSanitizer check for
-      dynamic initialization order problems. Implied by ``-fsanitize=address``.
-   -  ``-fsanitize=address-full``: AddressSanitizer with all the
-      experimental features listed below.
    -  ``-fsanitize=integer``: Enables checks for undefined or
       suspicious integer behavior.
    -  .. _opt_fsanitize_thread:
@@ -960,23 +1015,20 @@ are listed below.
    -  ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
       specified earlier in the command line.
 
-   Experimental features of AddressSanitizer (not ready for widespread
-   use, require explicit ``-fsanitize=address``):
-
-   -  ``-fsanitize=use-after-return``: Check for use-after-return
-      errors (accessing local variable after the function exit).
-   -  ``-fsanitize=use-after-scope``: Check for use-after-scope errors
-      (accesing local variable after it went out of scope).
-
    Extra features of MemorySanitizer (require explicit
    ``-fsanitize=memory``):
 
-   -  ``-fsanitize-memory-track-origins``: Enables origin tracking in
+   -  ``-fsanitize-memory-track-origins[=level]``: Enables origin tracking in
       MemorySanitizer. Adds a second section to MemorySanitizer
       reports pointing to the heap or stack allocation the
       uninitialized bits came from. Slows down execution by additional
       1.5x-2x.
 
+      Possible values for level are 0 (off), 1 (default), 2. Level 2 adds more
+      sections to MemorySanitizer reports describing the order of memory stores
+      the uninitialized value went through. Beware, this mode may use a lot of
+      extra memory.
+
    Extra features of UndefinedBehaviorSanitizer:
 
    -  ``-fno-sanitize-recover``: By default, after a sanitizer diagnoses
@@ -1002,18 +1054,6 @@ are listed below.
    program. The ``-fsanitize=undefined`` checks can be combined with other
    sanitizers.
 
-**-f[no-]address-sanitizer**
-   Deprecated synonym for :ref:`-f[no-]sanitize=address
-   `.
-**-f[no-]thread-sanitizer**
-   Deprecated synonym for :ref:`-f[no-]sanitize=thread
-   `.
-
-.. option:: -fcatch-undefined-behavior
-
-   Deprecated synonym for :ref:`-fsanitize=undefined
-   `.
-
 .. option:: -fno-assume-sane-operator-new
 
    Don't assume that the C++'s new operator is sane.
@@ -1066,6 +1106,240 @@ are listed below.
 
    CRC instructions are enabled by default on ARMv8.
 
+.. option:: -mgeneral-regs-only
+
+   Generate code which only uses the general purpose registers.
+
+   This option restricts the generated code to use general registers
+   only. This only applies to the AArch64 architecture.
+
+
+Profile Guided Optimization
+---------------------------
+
+Profile information enables better optimization. For example, knowing that a
+branch is taken very frequently helps the compiler make better decisions when
+ordering basic blocks. Knowing that a function ``foo`` is called more
+frequently than another function ``bar`` helps the inliner.
+
+Clang supports profile guided optimization with two different kinds of
+profiling. A sampling profiler can generate a profile with very low runtime
+overhead, or you can build an instrumented version of the code that collects
+more detailed profile information. Both kinds of profiles can provide execution
+counts for instructions in the code and information on branches taken and
+function invocation.
+
+Regardless of which kind of profiling you use, be careful to collect profiles
+by running your code with inputs that are representative of the typical
+behavior. Code that is not exercised in the profile will be optimized as if it
+is unimportant, and the compiler may make poor optimization choices for code
+that is disproportionately used while profiling.
+
+Using Sampling Profilers
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sampling profilers are used to collect runtime information, such as
+hardware counters, while your application executes. They are typically
+very efficient and do not incur a large runtime overhead. The
+sample data collected by the profiler can be used during compilation
+to determine what the most executed areas of the code are.
+
+Using the data from a sample profiler requires some changes in the way
+a program is built. Before the compiler can use profiling information,
+the code needs to execute under the profiler. The following is the
+usual build cycle when using sample profilers for optimization:
+
+1. Build the code with source line table information. You can use all the
+   usual build flags that you always build your application with. The only
+   requirement is that you add ``-gline-tables-only`` or ``-g`` to the
+   command line. This is important for the profiler to be able to map
+   instructions back to source line locations.
+
+   .. code-block:: console
+
+     $ clang++ -O2 -gline-tables-only code.cc -o code
+
+2. Run the executable under a sampling profiler. The specific profiler
+   you use does not really matter, as long as its output can be converted
+   into the format that the LLVM optimizer understands. Currently, there
+   exists a conversion tool for the Linux Perf profiler
+   (https://perf.wiki.kernel.org/), so these examples assume that you
+   are using Linux Perf to profile your code.
+
+   .. code-block:: console
+
+     $ perf record -b ./code
+
+   Note the use of the ``-b`` flag. This tells Perf to use the Last Branch
+   Record (LBR) to record call chains. While this is not strictly required,
+   it provides better call information, which improves the accuracy of
+   the profile data.
+
+3. Convert the collected profile data to LLVM's sample profile format.
+   This is currently supported via the AutoFDO converter ``create_llvm_prof``.
+   It is available at http://github.com/google/autofdo. Once built and
+   installed, you can convert the ``perf.data`` file to LLVM using
+   the command:
+
+   .. code-block:: console
+
+     $ create_llvm_prof --binary=./code --out=code.prof
+
+   This will read ``perf.data`` and the binary file ``./code`` and emit
+   the profile data in ``code.prof``. Note that if you ran ``perf``
+   without the ``-b`` flag, you need to use ``--use_lbr=false`` when
+   calling ``create_llvm_prof``.
+
+4. Build the code again using the collected profile. This step feeds
+   the profile back to the optimizers. This should result in a binary
+   that executes faster than the original one. Note that you are not
+   required to build the code with the exact same arguments that you
+   used in the first step. The only requirement is that you build the code
+   with ``-gline-tables-only`` and ``-fprofile-sample-use``.
+
+   .. code-block:: console
+
+     $ clang++ -O2 -gline-tables-only -fprofile-sample-use=code.prof code.cc -o code
+
+
+Sample Profile Format
+"""""""""""""""""""""
+
+If you are not using Linux Perf to collect profiles, you will need to
+write a conversion tool from your profiler to LLVM's format. This section
+explains the file format expected by the backend.
+
+Sample profiles are written as ASCII text. The file is divided into sections,
+which correspond to each of the functions executed at runtime. Each
+section has the following format (taken from
+https://github.com/google/autofdo/blob/master/profile_writer.h):
+
+.. code-block:: console
+
+    function1:total_samples:total_head_samples
+    offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
+    offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
+    ...
+    offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
+
+The file may contain blank lines between sections and within a
+section. However, the spacing within a single line is fixed. Additional
+spaces will result in an error while reading the file.
+
+Function names must be mangled in order for the profile loader to
+match them in the current translation unit. The two numbers in the
+function header specify how many total samples were accumulated in the
+function (first number), and the total number of samples accumulated
+in the prologue of the function (second number). This head sample
+count provides an indicator of how frequently the function is invoked.
+
+Each sampled line may contain several items. Some are optional (marked
+below):
+
+a. Source line offset. This number represents the line number
+   in the function where the sample was collected. The line number is
+   always relative to the line where symbol of the function is
+   defined. So, if the function has its header at line 280, the offset
+   13 is at line 293 in the file.
+
+   Note that this offset should never be a negative number. This could
+   happen in cases like macros. The debug machinery will register the
+   line number at the point of macro expansion. So, if the macro was
+   expanded in a line before the start of the function, the profile
+   converter should emit a 0 as the offset (this means that the optimizers
+   will not be able to associate a meaningful weight to the instructions
+   in the macro).
+
+b. [OPTIONAL] Discriminator. This is used if the sampled program
+   was compiled with DWARF discriminator support
+   (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
+   DWARF discriminators are unsigned integer values that allow the
+   compiler to distinguish between multiple execution paths on the
+   same source line location.
+
+   For example, consider the line of code ``if (cond) foo(); else bar();``.
+   If the predicate ``cond`` is true 80% of the time, then the edge
+   into function ``foo`` should be considered to be taken most of the
+   time. But both calls to ``foo`` and ``bar`` are at the same source
+   line, so a sample count at that line is not sufficient. The
+   compiler needs to know which part of that line is taken more
+   frequently.
+
+   This is what discriminators provide. In this case, the calls to
+   ``foo`` and ``bar`` will be at the same line, but will have
+   different discriminator values. This allows the compiler to correctly
+   set edge weights into ``foo`` and ``bar``.
+
+c. Number of samples. This is an integer quantity representing the
+   number of samples collected by the profiler at this source
+   location.
+
+d. [OPTIONAL] Potential call targets and samples. If present, this
+   line contains a call instruction. This models both direct and
+   number of samples. For example,
+
+   .. code-block:: console
+
+     130: 7  foo:3  bar:2  baz:7
+
+   The above means that at relative line offset 130 there is a call
+   instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
+   with ``baz()`` being the relatively more frequently called target.
+
+
+Profiling with Instrumentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clang also supports profiling via instrumentation. This requires building a
+special instrumented version of the code and has some runtime
+overhead during the profiling, but it provides more detailed results than a
+sampling profiler. It also provides reproducible results, at least to the
+extent that the code behaves consistently across runs.
+
+Here are the steps for using profile guided optimization with
+instrumentation:
+
+1. Build an instrumented version of the code by compiling and linking with the
+   ``-fprofile-instr-generate`` option.
+
+   .. code-block:: console
+
+     $ clang++ -O2 -fprofile-instr-generate code.cc -o code
+
+2. Run the instrumented executable with inputs that reflect the typical usage.
+   By default, the profile data will be written to a ``default.profraw`` file
+   in the current directory. You can override that default by setting the
+   ``LLVM_PROFILE_FILE`` environment variable to specify an alternate file.
+   Any instance of ``%p`` in that file name will be replaced by the process
+   ID, so that you can easily distinguish the profile output from multiple
+   runs.
+
+   .. code-block:: console
+
+     $ LLVM_PROFILE_FILE="code-%p.profraw" ./code
+
+3. Combine profiles from multiple runs and convert the "raw" profile format to
+   the input expected by clang. Use the ``merge`` command of the llvm-profdata
+   tool to do this.
+
+   .. code-block:: console
+
+     $ llvm-profdata merge -output=code.profdata code-*.profraw
+
+   Note that this step is necessary even when there is only one "raw" profile,
+   since the merge operation also changes the file format.
+
+4. Build the code again using the ``-fprofile-instr-use`` option to specify the
+   collected profile data.
+
+   .. code-block:: console
+
+     $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
+
+   You can repeat step 4 as often as you like without regenerating the
+   profile. As you make changes to your code, clang may no longer be able to
+   use the profile data. It will warn you when this happens.
+
 
 Controlling Size of Debug Information
 -------------------------------------
@@ -1086,23 +1360,70 @@ below. If multiple flags are present, the last one is used.
   doesn't contain any other data (e.g. description of local variables or
   function parameters).
 
+.. option:: -fstandalone-debug
+
+  Clang supports a number of optimizations to reduce the size of debug
+  information in the binary. They work based on the assumption that
+  the debug type information can be spread out over multiple
+  compilation units.  For instance, Clang will not emit type
+  definitions for types that are not needed by a module and could be
+  replaced with a forward declaration.  Further, Clang will only emit
+  type info for a dynamic C++ class in the module that contains the
+  vtable for the class.
+
+  The **-fstandalone-debug** option turns off these optimizations.
+  This is useful when working with 3rd-party libraries that don't come
+  with debug information.  Note that Clang will never emit type
+  information for types that are not referenced at all by the program.
+
+.. option:: -fno-standalone-debug
+
+   On Darwin **-fstandalone-debug** is enabled by default. The
+   **-fno-standalone-debug** option can be used to get to turn on the
+   vtable-based optimization described above.
+
 .. option:: -g
 
   Generate complete debug info.
 
 Comment Parsing Options
---------------------------
+-----------------------
 
 Clang parses Doxygen and non-Doxygen style documentation comments and attaches
 them to the appropriate declaration nodes.  By default, it only parses
 Doxygen-style comments and ignores ordinary comments starting with ``//`` and
 ``/*``.
 
+.. option:: -Wdocumentation
+
+  Emit warnings about use of documentation comments.  This warning group is off
+  by default.
+
+  This includes checking that ``\param`` commands name parameters that actually
+  present in the function signature, checking that ``\returns`` is used only on
+  functions that actually return a value etc.
+
+.. option:: -Wno-documentation-unknown-command
+
+  Don't warn when encountering an unknown Doxygen command.
+
 .. option:: -fparse-all-comments
 
   Parse all comments as documentation comments (including ordinary comments
   starting with ``//`` and ``/*``).
 
+.. option:: -fcomment-block-commands=[commands]
+
+  Define custom documentation commands as block commands.  This allows Clang to
+  construct the correct AST for these custom commands, and silences warnings
+  about unknown commands.  Several commands must be separated by a comma
+  *without trailing space*; e.g. ``-fcomment-block-commands=foo,bar`` defines
+  custom commands ``\foo`` and ``\bar``.
+
+  It is also possible to use ``-fcomment-block-commands`` several times; e.g.
+  ``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
+  as above.
+
 .. _c:
 
 C Language Features
@@ -1238,23 +1559,23 @@ Microsoft extensions
 --------------------
 
 clang has some experimental support for extensions from Microsoft Visual
-C++; to enable it, use the -fms-extensions command-line option. This is
+C++; to enable it, use the ``-fms-extensions`` command-line option. This is
 the default for Windows targets. Note that the support is incomplete.
-Some constructs such as dllexport on classes are ignored with a warning,
+Some constructs such as ``dllexport`` on classes are ignored with a warning,
 and others such as `Microsoft IDL annotations
 `_ are silently
 ignored.
 
-clang has a -fms-compatibility flag that makes clang accept enough
+clang has a ``-fms-compatibility`` flag that makes clang accept enough
 invalid C++ to be able to parse most Microsoft headers. For example, it
 allows `unqualified lookup of dependent base class members
 `_, which is
 a common compatibility issue with clang. This flag is enabled by default
 for Windows targets.
 
--fdelayed-template-parsing lets clang delay all template instantiation
-until the end of a translation unit. This flag is enabled by default for
-Windows targets.
+``-fdelayed-template-parsing`` lets clang delay parsing of function template
+definitions until the end of a translation unit. This flag is enabled by
+default for Windows targets.
 
 -  clang allows setting ``_MSC_VER`` with ``-fmsc-version=``. It defaults to
    1700 which is the same as Visual C/C++ 2012. Any number is supported
@@ -1280,8 +1601,8 @@ C++ Language Features
 =====================
 
 clang fully implements all of standard C++98 except for exported
-templates (which were removed in C++11), and `many C++11
-features `_ are also implemented.
+templates (which were removed in C++11), and all of standard C++11
+and the current draft standard for C++1y.
 
 Controlling implementation limits
 ---------------------------------
@@ -1329,14 +1650,21 @@ X86
 ^^^
 
 The support for X86 (both 32-bit and 64-bit) is considered stable on
-Darwin (Mac OS/X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
+Darwin (Mac OS X), Linux, FreeBSD, and Dragonfly BSD: it has been tested
 to correctly compile many large C, C++, Objective-C, and Objective-C++
 codebases.
 
-On ``x86_64-mingw32``, passing i128(by value) is incompatible to Microsoft
-x64 calling conversion. You might need to tweak
+On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
+Microsoft x64 calling convention. You might need to tweak
 ``WinX86_64ABIInfo::classify()`` in lib/CodeGen/TargetInfo.cpp.
 
+For the X86 target, clang supports the :option:`-m16` command line
+argument which enables 16-bit code output. This is broadly similar to
+using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
+and the ABI remains 32-bit but the assembler emits instructions
+appropriate for a CPU running in 16-bit mode, with address-size and
+operand-size prefixes to enable 32-bit addressing and operations.
+
 ARM
 ^^^
 
@@ -1377,15 +1705,16 @@ backend.
 Operating System Features and Limitations
 -----------------------------------------
 
-Darwin (Mac OS/X)
+Darwin (Mac OS X)
 ^^^^^^^^^^^^^^^^^
 
-None
+Thread Sanitizer is not supported.
 
 Windows
 ^^^^^^^
 
-Experimental supports are on Cygming.
+Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
+platforms.
 
 See also :ref:`Microsoft Extensions `.
 
@@ -1479,55 +1808,92 @@ Execute ``clang-cl /?`` to see a list of supported options:
 
   ::
 
-    /?                     Display available options
-    /c                     Compile only
-    /D      Define macro
-    /fallback              Fall back to cl.exe if clang-cl fails to compile
-    /FA                    Output assembly code file during compilation
-    /Fa Output assembly code to this file during compilation
-    /Fe Set output executable file or directory (ends in / or \)
-    /FI             Include file before parsing
-    /Fo Set output object file, or directory (ends in / or \)
-    /GF-                   Disable string pooling
-    /GR-                   Disable RTTI
-    /GR                    Enable RTTI
-    /help                  Display available options
-    /I                Add directory to include search path
-    /J                     Make char type unsigned
-    /LDd                   Create debug DLL
-    /LD                    Create DLL
-    /link         Forward options to the linker
-    /MDd                   Use DLL debug run-time
-    /MD                    Use DLL run-time
-    /MTd                   Use static debug run-time
-    /MT                    Use static run-time
-    /Ob0                   Disable inlining
-    /Od                    Disable optimization
-    /Oi-                   Disable use of builtin functions
-    /Oi                    Enable use of builtin functions
-    /Os                    Optimize for size
-    /Ot                    Optimize for speed
-    /Ox                    Maximum optimization
-    /Oy-                   Disable frame pointer omission
-    /Oy                    Enable frame pointer omission
-    /O                  Optimization level
-    /P                     Only run the preprocessor
-    /showIncludes          Print info about included files to stderr
-    /TC                    Treat all source files as C
-    /Tc          Specify a C source file
-    /TP                    Treat all source files as C++
-    /Tp          Specify a C++ source file
-    /U              Undefine macro
-    /W0                    Disable all warnings
-    /W1                    Enable -Wall
-    /W2                    Enable -Wall
-    /W3                    Enable -Wall
-    /W4                    Enable -Wall
-    /Wall                  Enable -Wall
-    /WX-                   Do not treat warnings as errors
-    /WX                    Treat warnings as errors
-    /w                     Disable all warnings
-    /Zs                    Syntax-check only
+    CL.EXE COMPATIBILITY OPTIONS:
+      /?                     Display available options
+      /arch:          Set architecture for code generation
+      /C                     Don't discard comments when preprocessing
+      /c                     Compile only
+      /D      Define macro
+      /EH             Exception handling model
+      /EP                    Disable linemarker output and preprocess to stdout
+      /E                     Preprocess to stdout
+      /fallback              Fall back to cl.exe if clang-cl fails to compile
+      /FA                    Output assembly code file during compilation
+      /Fa Output assembly code to this file during compilation
+      /Fe Set output executable file or directory (ends in / or \)
+      /FI             Include file before parsing
+      /Fi              Set preprocess output file name
+      /Fo Set output object file, or directory (ends in / or \)
+      /GF-                   Disable string pooling
+      /GR-                   Disable emission of RTTI data
+      /GR                    Enable emission of RTTI data
+      /Gw-                   Don't put each data item in its own section
+      /Gw                    Put each data item in its own section
+      /Gy-                   Don't put each function in its own section
+      /Gy                    Put each function in its own section
+      /help                  Display available options
+      /I                Add directory to include search path
+      /J                     Make char type unsigned
+      /LDd                   Create debug DLL
+      /LD                    Create DLL
+      /link         Forward options to the linker
+      /MDd                   Use DLL debug run-time
+      /MD                    Use DLL run-time
+      /MTd                   Use static debug run-time
+      /MT                    Use static run-time
+      /Ob0                   Disable inlining
+      /Od                    Disable optimization
+      /Oi-                   Disable use of builtin functions
+      /Oi                    Enable use of builtin functions
+      /Os                    Optimize for size
+      /Ot                    Optimize for speed
+      /Ox                    Maximum optimization
+      /Oy-                   Disable frame pointer omission
+      /Oy                    Enable frame pointer omission
+      /O                  Optimization level
+      /P                     Preprocess to file
+      /showIncludes          Print info about included files to stderr
+      /TC                    Treat all source files as C
+      /Tc          Specify a C source file
+      /TP                    Treat all source files as C++
+      /Tp          Specify a C++ source file
+      /U              Undefine macro
+      /vd             Control vtordisp placement
+      /vmb                   Use a best-case representation method for member pointers
+      /vmg                   Use a most-general representation for member pointers
+      /vmm                   Set the default most-general representation to multiple inheritance
+      /vms                   Set the default most-general representation to single inheritance
+      /vmv                   Set the default most-general representation to virtual inheritance
+      /W0                    Disable all warnings
+      /W1                    Enable -Wall
+      /W2                    Enable -Wall
+      /W3                    Enable -Wall
+      /W4                    Enable -Wall
+      /Wall                  Enable -Wall
+      /WX-                   Do not treat warnings as errors
+      /WX                    Treat warnings as errors
+      /w                     Disable all warnings
+      /Zi                    Enable debug information
+      /Zs                    Syntax-check only
+
+    OPTIONS:
+      -###                  Print (but do not run) the commands to run for this compilation
+      -fms-compatibility-version=
+                            Dot-separated value representing the Microsoft compiler version
+                            number to report in _MSC_VER (0 = don't define it (default))
+      -fmsc-version= Microsoft compiler version number to report in _MSC_VER (0 = don't
+                            define it (default))
+      -fsanitize-blacklist=
+                            Path to blacklist file for sanitizers
+      -fsanitize=    Enable runtime instrumentation for bug detection: address (memory
+                            errors) | thread (race detection) | undefined (miscellaneous
+                            undefined behavior)
+      -mllvm         Additional arguments to forward to LLVM's option processing
+      -Qunused-arguments    Don't emit warning for unused driver arguments
+      --target=      Generate code for the given target
+      -v                    Show commands to run and use verbose output
+      -W           Enable the specified warning
+      -Xclang          Pass  to the clang compiler
 
 The /fallback Option
 ^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/analyzer/conf.py b/docs/analyzer/conf.py
index 3690f936d33..1514708c0d5 100644
--- a/docs/analyzer/conf.py
+++ b/docs/analyzer/conf.py
@@ -41,7 +41,7 @@
 
 # General information about the project.
 project = u'Clang Static Analyzer'
-copyright = u'2013, Analyzer Team'
+copyright = u'2013-2014, Analyzer Team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
diff --git a/docs/conf.py b/docs/conf.py
index 183a285de24..1963a05385e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -41,16 +41,16 @@
 
 # General information about the project.
 project = u'Clang'
-copyright = u'2007-2013, The Clang Team'
+copyright = u'2007-2014, The Clang Team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '3.4'
+version = '3.5'
 # The full version, including alpha/beta/rc tags.
-release = '3.4'
+release = '3.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in
index 61c0bd847f8..2372e044cde 100644
--- a/docs/doxygen.cfg.in
+++ b/docs/doxygen.cfg.in
@@ -697,6 +697,59 @@ BINARY_TOC             = NO
 
 TOC_EXPAND             = NO
 
+# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and 
+# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated 
+# that can be used as input for Qt's qhelpgenerator to generate a 
+# Qt Compressed Help (.qch) of the generated HTML documentation.
+
+GENERATE_QHP           = @clang_doxygen_generate_qhp@
+
+# If the QHG_LOCATION tag is specified, the QCH_FILE tag can 
+# be used to specify the file name of the resulting .qch file. 
+# The path specified is relative to the HTML output folder.
+
+QCH_FILE               = @clang_doxygen_qch_filename@
+
+# The QHP_NAMESPACE tag specifies the namespace to use when generating 
+# Qt Help Project output. For more information please see 
+# http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace
+
+QHP_NAMESPACE          = @clang_doxygen_qhp_namespace@
+
+# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating 
+# Qt Help Project output. For more information please see 
+# http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual-folders
+
+QHP_VIRTUAL_FOLDER     = doc
+
+# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to 
+# add. For more information please see 
+# http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
+
+QHP_CUST_FILTER_NAME   = @clang_doxygen_qhp_cust_filter_name@
+
+# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the 
+# custom filter to add. For more information please see 
+#  
+# Qt Help Project / Custom Filters.
+
+QHP_CUST_FILTER_ATTRS  = @clang_doxygen_qhp_cust_filter_attrs@
+
+# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this 
+# project's 
+# filter section matches. 
+#  
+# Qt Help Project / Filter Attributes.
+
+QHP_SECT_FILTER_ATTRS  = 
+
+# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can 
+# be used to specify the location of Qt's qhelpgenerator. 
+# If non-empty doxygen will try to run qhelpgenerator on the generated 
+# .qhp file.
+
+QHG_LOCATION           = @clang_doxygen_qhelpgenerator_path@
+
 # The DISABLE_INDEX tag can be used to turn on/off the condensed index at 
 # top of each HTML page. The value NO (the default) enables the index and 
 # the value YES disables it.
diff --git a/docs/index.rst b/docs/index.rst
index d02686422b5..bf2de7ebfda 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,20 +18,19 @@ Using Clang as a Compiler
 
    UsersManual
    LanguageExtensions
+   AttributeReference
    CrossCompilation
+   ThreadSafetyAnalysis
    AddressSanitizer
    ThreadSanitizer
    MemorySanitizer
    DataFlowSanitizer
+   LeakSanitizer
    SanitizerSpecialCaseList
    Modules
+   MSVCCompatibility
    FAQ
 
-.. toctree::
-   :hidden:
-
-   LeakSanitizer
-
 Using Clang as a Library
 ========================
 
diff --git a/docs/tools/clang.pod b/docs/tools/clang.pod
index a58986c3a6b..f7d2eaf683c 100644
--- a/docs/tools/clang.pod
+++ b/docs/tools/clang.pod
@@ -237,7 +237,7 @@ Specify the architecture to build for.
 
 =item B<-mmacosx-version-min>=I
 
-When building for Mac OS/X, specify the minimum version supported by your
+When building for Mac OS X, specify the minimum version supported by your
 application.
 
 =item B<-miphoneos-version-min>
@@ -310,8 +310,23 @@ Currently equivalent to B<-O3>
 =item B<-g>
 
 Generate debug information.  Note that Clang debug information works best at
-B<-O0>.  At higher optimization levels, only line number information is
-currently available.
+B<-O0>.
+
+=item B<-fstandalone-debug> B<-fno-standalone-debug>
+
+Clang supports a number of optimizations to reduce the size of debug
+information in the binary. They work based on the assumption that the
+debug type information can be spread out over multiple compilation
+units.  For instance, Clang will not emit type definitions for types
+that are not needed by a module and could be replaced with a forward
+declaration.  Further, Clang will only emit type info for a dynamic
+C++ class in the module that contains the vtable for the class.
+
+The B<-fstandalone-debug> option turns off these optimizations.  This
+is useful when working with 3rd-party libraries that don't come with
+debug information.  This is the default on Darwin.  Note that Clang
+will never emit type information for types that are not referenced at
+all by the program.
 
 =item B<-fexceptions>
 
@@ -366,7 +381,7 @@ to the linker depending on the stage selection options).
 
 =item B<-###>
 
-Print the commands to run for this compilation.
+Print (but do not run) the commands to run for this compilation.
 
 =item B<--help>
 
diff --git a/docs/tools/dump_ast_matchers.py b/docs/tools/dump_ast_matchers.py
index 564dc380d64..4ece46ae34f 100644
--- a/docs/tools/dump_ast_matchers.py
+++ b/docs/tools/dump_ast_matchers.py
@@ -119,9 +119,9 @@ def add_matcher(result_type, name, args, comment, is_dyncast=False):
   # arguments.
   elif ('Matcher<' not in args or
         name in ['allOf', 'anyOf', 'anything', 'unless']):
-    narrowing_matchers[result_type + name] = matcher_html
+    narrowing_matchers[result_type + name + esc(args)] = matcher_html
   else:
-    traversal_matchers[result_type + name] = matcher_html
+    traversal_matchers[result_type + name + esc(args)] = matcher_html
 
 def act_on_decl(declaration, comment, allowed_types):
   """Parse the matcher out of the given declaration and comment.
@@ -204,6 +204,25 @@ def act_on_decl(declaration, comment, allowed_types):
         add_matcher(result_type, name, args, comment)
       return
 
+    m = re.match(r"""^\s*AST_MATCHER_FUNCTION(_P)?(.?)(?:_OVERLOAD)?\(
+                       (?:\s*([^\s,]+)\s*,)?
+                          \s*([^\s,]+)\s*
+                       (?:,\s*([^\s,]+)\s*
+                          ,\s*([^\s,]+)\s*)?
+                       (?:,\s*([^\s,]+)\s*
+                          ,\s*([^\s,]+)\s*)?
+                       (?:,\s*\d+\s*)?
+                      \)\s*{\s*$""", declaration, flags=re.X)
+    if m:
+      p, n, result, name = m.groups()[0:4]
+      args = m.groups()[4:]
+      if n not in ['', '2']:
+        raise Exception('Cannot parse "%s"' % declaration)
+      args = ', '.join('%s %s' % (args[i], args[i+1])
+                       for i in range(0, len(args), 2) if args[i])
+      add_matcher(result, name, args, comment)
+      return
+
     m = re.match(r"""^\s*AST_MATCHER(_P)?(.?)(?:_OVERLOAD)?\(
                        (?:\s*([^\s,]+)\s*,)?
                           \s*([^\s,]+)\s*
@@ -242,12 +261,17 @@ def act_on_decl(declaration, comment, allowed_types):
 
     # Parse Variadic operator matchers.
     m = re.match(
-        r"""^.*VariadicOperatorMatcherFunc\s*([a-zA-Z]*)\s*=\s*{.*};$""",
+        r"""^.*VariadicOperatorMatcherFunc\s*<\s*([^,]+),\s*([^\s>]+)\s*>\s*
+              ([a-zA-Z]*)\s*=\s*{.*};$""",
         declaration, flags=re.X)
     if m:
-      name = m.groups()[0]
-      add_matcher('*', name, 'Matcher<*>, ..., Matcher<*>', comment)
-      return
+      min_args, max_args, name = m.groups()[:3]
+      if max_args == '1':
+        add_matcher('*', name, 'Matcher<*>', comment)
+        return
+      elif max_args == 'UINT_MAX':
+        add_matcher('*', name, 'Matcher<*>, ..., Matcher<*>', comment)
+        return
 
 
     # Parse free standing matcher functions, like:
diff --git a/docs/tools/dump_format_style.py b/docs/tools/dump_format_style.py
old mode 100644
new mode 100755
index 0c8ca6d610f..66bad8bb4e7
--- a/docs/tools/dump_format_style.py
+++ b/docs/tools/dump_format_style.py
@@ -98,7 +98,7 @@ class State:
         enum = Enum(name, comment)
       elif line.endswith(';'):
         state = State.InStruct
-        field_type, field_name = re.match(r'(\w+)\s+(\w+);', line).groups()
+        field_type, field_name = re.match(r'([<>:\w]+)\s+(\w+);', line).groups()
         option = Option(str(field_name), str(field_type), comment)
         options.append(option)
       else:
@@ -122,7 +122,8 @@ class State:
     raise Exception('Not finished by the end of file')
 
   for option in options:
-    if not option.type in ['bool', 'unsigned', 'int']:
+    if not option.type in ['bool', 'unsigned', 'int', 'std::string',
+                           'std::vector']:
       if enums.has_key(option.type):
         option.enum = enums[option.type]
       else:
diff --git a/emscripten-version.txt b/emscripten-version.txt
index b7825b8d767..940f1321e44 100644
--- a/emscripten-version.txt
+++ b/emscripten-version.txt
@@ -1,2 +1,2 @@
-1.28.2
+1.29.1
 
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index 84a5d2cecbe..5d4b5fcdb0f 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -1,7 +1,10 @@
 if(NOT CLANG_BUILD_EXAMPLES)
   set_property(DIRECTORY PROPERTY EXCLUDE_FROM_ALL ON)
+  set(EXCLUDE_FROM_ALL ON)
 endif()
 
+if(CLANG_ENABLE_STATIC_ANALYZER)
 add_subdirectory(analyzer-plugin)
+endif()
 add_subdirectory(clang-interpreter)
 add_subdirectory(PrintFunctionNames)
diff --git a/examples/PrintFunctionNames/CMakeLists.txt b/examples/PrintFunctionNames/CMakeLists.txt
index ba6a350cd95..e700281ab48 100644
--- a/examples/PrintFunctionNames/CMakeLists.txt
+++ b/examples/PrintFunctionNames/CMakeLists.txt
@@ -1,24 +1,21 @@
-set(MODULE TRUE)
+# If we don't need RTTI or EH, there's no reason to export anything
+# from the plugin.
+if( NOT MSVC ) # MSVC mangles symbols differently, and
+                # PrintFunctionNames.export contains C++ symbols.
+  if( NOT LLVM_REQUIRES_RTTI )
+    if( NOT LLVM_REQUIRES_EH )
+      set(LLVM_EXPORTED_SYMBOL_FILE ${CMAKE_CURRENT_SOURCE_DIR}/PrintFunctionNames.exports)
+    endif()
+  endif()
+endif()
 
-set( LLVM_LINK_COMPONENTS support mc)
+add_llvm_loadable_module(PrintFunctionNames PrintFunctionNames.cpp)
 
-add_clang_library(PrintFunctionNames PrintFunctionNames.cpp)
-
-add_dependencies(PrintFunctionNames
-  ClangAttrClasses
-  ClangAttrList
-  ClangCommentNodes
-  ClangDeclNodes
-  ClangDiagnosticCommon
-  ClangStmtNodes
-  )
-
-target_link_libraries(PrintFunctionNames
-  clangFrontend
-  clangAST
-  )
-
-set_target_properties(PrintFunctionNames
-  PROPERTIES
-  LINKER_LANGUAGE CXX
-  PREFIX "")
+if(LLVM_ENABLE_PLUGINS AND (WIN32 OR CYGWIN))
+  target_link_libraries(PrintFunctionNames ${cmake_2_8_12_PRIVATE}
+    clangAST
+    clangBasic
+    clangFrontend
+    LLVMSupport
+    )
+endif()
diff --git a/examples/PrintFunctionNames/Makefile b/examples/PrintFunctionNames/Makefile
index 23a53054019..5865098bd30 100644
--- a/examples/PrintFunctionNames/Makefile
+++ b/examples/PrintFunctionNames/Makefile
@@ -19,7 +19,7 @@ endif
 endif
 
 LINK_LIBS_IN_SHARED = 0
-SHARED_LIBRARY = 1
+LOADABLE_MODULE = 1
 
 include $(CLANG_LEVEL)/Makefile
 
diff --git a/examples/PrintFunctionNames/PrintFunctionNames.cpp b/examples/PrintFunctionNames/PrintFunctionNames.cpp
index f6e75cc2d3a..3f18cd45e56 100644
--- a/examples/PrintFunctionNames/PrintFunctionNames.cpp
+++ b/examples/PrintFunctionNames/PrintFunctionNames.cpp
@@ -48,9 +48,9 @@ class PrintFunctionNamesAction : public PluginASTAction {
       // Example error handling.
       if (args[i] == "-an-error") {
         DiagnosticsEngine &D = CI.getDiagnostics();
-        unsigned DiagID = D.getCustomDiagID(
-          DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'");
-        D.Report(DiagID);
+        unsigned DiagID = D.getCustomDiagID(DiagnosticsEngine::Error,
+                                            "invalid argument '%0'");
+        D.Report(DiagID) << args[i];
         return false;
       }
     }
diff --git a/examples/PrintFunctionNames/PrintFunctionNames.exports b/examples/PrintFunctionNames/PrintFunctionNames.exports
index 0ff590d30d7..e69de29bb2d 100644
--- a/examples/PrintFunctionNames/PrintFunctionNames.exports
+++ b/examples/PrintFunctionNames/PrintFunctionNames.exports
@@ -1 +0,0 @@
-_ZN4llvm8Registry*
diff --git a/examples/analyzer-plugin/CMakeLists.txt b/examples/analyzer-plugin/CMakeLists.txt
index ba73030cc37..1788d6c5cac 100644
--- a/examples/analyzer-plugin/CMakeLists.txt
+++ b/examples/analyzer-plugin/CMakeLists.txt
@@ -1,23 +1,10 @@
-set(MODULE TRUE)
-
-set( LLVM_LINK_COMPONENTS support mc)
-
-add_clang_library(SampleAnalyzerPlugin MainCallChecker.cpp)
-
-add_dependencies(SampleAnalyzerPlugin
-  ClangAttrClasses
-  ClangAttrList
-  ClangCommentNodes
-  ClangDeclNodes
-  ClangDiagnosticCommon
-  ClangStmtNodes
-  )
-
-target_link_libraries(SampleAnalyzerPlugin
-  clangStaticAnalyzerCore
-  )
-
-set_target_properties(SampleAnalyzerPlugin
-  PROPERTIES
-  LINKER_LANGUAGE CXX
-  PREFIX "")
+add_llvm_loadable_module(SampleAnalyzerPlugin MainCallChecker.cpp)
+
+if(LLVM_ENABLE_PLUGINS AND (WIN32 OR CYGWIN))
+  target_link_libraries(SampleAnalyzerPlugin ${cmake_2_8_12_PRIVATE}
+    clangAnalysis
+    clangAST
+    clangStaticAnalyzerCore
+    LLVMSupport
+    )
+endif()
diff --git a/examples/analyzer-plugin/MainCallChecker.cpp b/examples/analyzer-plugin/MainCallChecker.cpp
index 8801f9a158f..2ad8c8416a5 100644
--- a/examples/analyzer-plugin/MainCallChecker.cpp
+++ b/examples/analyzer-plugin/MainCallChecker.cpp
@@ -8,7 +8,7 @@ using namespace ento;
 
 namespace {
 class MainCallChecker : public Checker < check::PreStmt > {
-  mutable OwningPtr BT;
+  mutable std::unique_ptr BT;
 
 public:
   void checkPreStmt(const CallExpr *CE, CheckerContext &C) const;
@@ -35,7 +35,7 @@ void MainCallChecker::checkPreStmt(const CallExpr *CE, CheckerContext &C) const
       return;
 
     if (!BT)
-      BT.reset(new BugType("call to main", "example analyzer plugin"));
+      BT.reset(new BugType(this, "call to main", "example analyzer plugin"));
 
     BugReport *report = new BugReport(*BT, BT->getName(), N);
     report->addRange(Callee->getSourceRange());
diff --git a/examples/clang-interpreter/CMakeLists.txt b/examples/clang-interpreter/CMakeLists.txt
index 451b4b86722..3c66881d026 100644
--- a/examples/clang-interpreter/CMakeLists.txt
+++ b/examples/clang-interpreter/CMakeLists.txt
@@ -1,15 +1,9 @@
 set(LLVM_LINK_COMPONENTS
-  jit
-  interpreter
-  nativecodegen
-  asmparser
-  bitreader
-  bitwriter
-  irreader
-  codegen
-  ipo
-  linker
-  selectiondag
+  Core
+  ExecutionEngine
+  JIT
+  Support
+  native
   )
 
 add_clang_executable(clang-interpreter
@@ -21,19 +15,8 @@ add_dependencies(clang-interpreter
   )
 
 target_link_libraries(clang-interpreter
-  clangFrontend
-  clangSerialization
-  clangDriver
-  clangCodeGen
-  clangSema
-  clangStaticAnalyzerFrontend
-  clangStaticAnalyzerCheckers
-  clangStaticAnalyzerCore
-  clangAnalysis
-  clangRewriteCore
-  clangRewriteFrontend
-  clangAST
-  clangParse
-  clangLex
   clangBasic
+  clangCodeGen
+  clangDriver
+  clangFrontend
   )
diff --git a/examples/clang-interpreter/Makefile b/examples/clang-interpreter/Makefile
index 55a8e6fb0f4..d571337735e 100644
--- a/examples/clang-interpreter/Makefile
+++ b/examples/clang-interpreter/Makefile
@@ -16,11 +16,11 @@ NO_INSTALL = 1
 TOOL_NO_EXPORTS = 1
 
 LINK_COMPONENTS := jit interpreter nativecodegen bitreader bitwriter irreader \
-	ipo linker selectiondag asmparser instrumentation option
+	ipo linker selectiondag asmparser instrumentation objcarcopts option
 USEDLIBS = clangFrontend.a clangSerialization.a clangDriver.a clangCodeGen.a \
            clangParse.a clangSema.a clangStaticAnalyzerFrontend.a \
            clangStaticAnalyzerCheckers.a clangStaticAnalyzerCore.a \
-           clangAnalysis.a clangRewriteCore.a clangRewriteFrontend.a \
+           clangAnalysis.a clangRewrite.a clangRewriteFrontend.a \
            clangEdit.a clangAST.a clangLex.a clangBasic.a
 
 include $(CLANG_LEVEL)/Makefile
diff --git a/examples/clang-interpreter/main.cpp b/examples/clang-interpreter/main.cpp
index e00583d1a1a..8b8ccfdf70a 100644
--- a/examples/clang-interpreter/main.cpp
+++ b/examples/clang-interpreter/main.cpp
@@ -16,7 +16,6 @@
 #include "clang/Frontend/CompilerInvocation.h"
 #include "clang/Frontend/FrontendDiagnostic.h"
 #include "clang/Frontend/TextDiagnosticPrinter.h"
-#include "llvm/ADT/OwningPtr.h"
 #include "llvm/ADT/SmallString.h"
 #include "llvm/ExecutionEngine/ExecutionEngine.h"
 #include "llvm/ExecutionEngine/JIT.h"
@@ -27,6 +26,7 @@
 #include "llvm/Support/Path.h"
 #include "llvm/Support/TargetSelect.h"
 #include "llvm/Support/raw_ostream.h"
+#include 
 using namespace clang;
 using namespace clang::driver;
 
@@ -46,8 +46,8 @@ static int Execute(llvm::Module *Mod, char * const *envp) {
   llvm::InitializeNativeTarget();
 
   std::string Error;
-  OwningPtr EE(
-    llvm::ExecutionEngine::createJIT(Mod, &Error));
+  std::unique_ptr EE(
+      llvm::ExecutionEngine::create(Mod, /*ForceInterpreter*/ false, &Error));
   if (!EE) {
     llvm::errs() << "unable to make execution engine: " << Error << "\n";
     return 255;
@@ -75,15 +75,16 @@ int main(int argc, const char **argv, char * const *envp) {
 
   IntrusiveRefCntPtr DiagID(new DiagnosticIDs());
   DiagnosticsEngine Diags(DiagID, &*DiagOpts, DiagClient);
-  Driver TheDriver(Path, llvm::sys::getProcessTriple(), "a.out", Diags);
+  Driver TheDriver(Path, llvm::sys::getProcessTriple(), Diags);
   TheDriver.setTitle("clang interpreter");
+  TheDriver.setCheckInputsExist(false);
 
   // FIXME: This is a hack to try to force the driver to do something we can
   // recognize. We need to extend the driver library to support this use model
   // (basically, exactly one input, and the operation mode is hard wired).
   SmallVector Args(argv, argv + argc);
   Args.push_back("-fsyntax-only");
-  OwningPtr C(TheDriver.BuildCompilation(Args));
+  std::unique_ptr C(TheDriver.BuildCompilation(Args));
   if (!C)
     return 0;
 
@@ -108,7 +109,7 @@ int main(int argc, const char **argv, char * const *envp) {
 
   // Initialize a compiler invocation object from the clang (-cc1) arguments.
   const driver::ArgStringList &CCArgs = Cmd->getArguments();
-  OwningPtr CI(new CompilerInvocation);
+  std::unique_ptr CI(new CompilerInvocation);
   CompilerInvocation::CreateFromArgs(*CI,
                                      const_cast(CCArgs.data()),
                                      const_cast(CCArgs.data()) +
@@ -126,7 +127,7 @@ int main(int argc, const char **argv, char * const *envp) {
 
   // Create a compiler instance to handle the actual work.
   CompilerInstance Clang;
-  Clang.setInvocation(CI.take());
+  Clang.setInvocation(CI.release());
 
   // Create the compilers actual diagnostics engine.
   Clang.createDiagnostics();
@@ -140,7 +141,7 @@ int main(int argc, const char **argv, char * const *envp) {
       CompilerInvocation::GetResourcesPath(argv[0], MainAddr);
 
   // Create and execute the frontend to generate an LLVM bitcode module.
-  OwningPtr Act(new EmitLLVMOnlyAction());
+  std::unique_ptr Act(new EmitLLVMOnlyAction());
   if (!Clang.ExecuteAction(*Act))
     return 1;
 
diff --git a/include/clang-c/BuildSystem.h b/include/clang-c/BuildSystem.h
new file mode 100644
index 00000000000..ed3e8d9a28b
--- /dev/null
+++ b/include/clang-c/BuildSystem.h
@@ -0,0 +1,148 @@
+/*==-- clang-c/BuildSystem.h - Utilities for use by build systems -*- C -*-===*\
+|*                                                                            *|
+|*                     The LLVM Compiler Infrastructure                       *|
+|*                                                                            *|
+|* This file is distributed under the University of Illinois Open Source      *|
+|* License. See LICENSE.TXT for details.                                      *|
+|*                                                                            *|
+|*===----------------------------------------------------------------------===*|
+|*                                                                            *|
+|* This header provides various utilities for use by build systems.           *|
+|*                                                                            *|
+\*===----------------------------------------------------------------------===*/
+
+#ifndef CLANG_C_BUILD_SYSTEM_H
+#define CLANG_C_BUILD_SYSTEM_H
+
+#include "clang-c/Platform.h"
+#include "clang-c/CXErrorCode.h"
+#include "clang-c/CXString.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \defgroup BUILD_SYSTEM Build system utilities
+ * @{
+ */
+
+/**
+ * \brief Return the timestamp for use with Clang's
+ * \c -fbuild-session-timestamp= option.
+ */
+CINDEX_LINKAGE unsigned long long clang_getBuildSessionTimestamp(void);
+
+/**
+ * \brief Object encapsulating information about overlaying virtual
+ * file/directories over the real file system.
+ */
+typedef struct CXVirtualFileOverlayImpl *CXVirtualFileOverlay;
+
+/**
+ * \brief Create a \c CXVirtualFileOverlay object.
+ * Must be disposed with \c clang_VirtualFileOverlay_dispose().
+ *
+ * \param options is reserved, always pass 0.
+ */
+CINDEX_LINKAGE CXVirtualFileOverlay
+clang_VirtualFileOverlay_create(unsigned options);
+
+/**
+ * \brief Map an absolute virtual file path to an absolute real one.
+ * The virtual path must be canonicalized (not contain "."/"..").
+ * \returns 0 for success, non-zero to indicate an error.
+ */
+CINDEX_LINKAGE enum CXErrorCode
+clang_VirtualFileOverlay_addFileMapping(CXVirtualFileOverlay,
+                                        const char *virtualPath,
+                                        const char *realPath);
+
+/**
+ * \brief Set the case sensitivity for the \c CXVirtualFileOverlay object.
+ * The \c CXVirtualFileOverlay object is case-sensitive by default, this
+ * option can be used to override the default.
+ * \returns 0 for success, non-zero to indicate an error.
+ */
+CINDEX_LINKAGE enum CXErrorCode
+clang_VirtualFileOverlay_setCaseSensitivity(CXVirtualFileOverlay,
+											int caseSensitive);
+
+/**
+ * \brief Write out the \c CXVirtualFileOverlay object to a char buffer.
+ *
+ * \param options is reserved, always pass 0.
+ * \param out_buffer_ptr pointer to receive the buffer pointer, which should be
+ * disposed using \c free().
+ * \param out_buffer_size pointer to receive the buffer size.
+ * \returns 0 for success, non-zero to indicate an error.
+ */
+CINDEX_LINKAGE enum CXErrorCode
+clang_VirtualFileOverlay_writeToBuffer(CXVirtualFileOverlay, unsigned options,
+                                       char **out_buffer_ptr,
+                                       unsigned *out_buffer_size);
+
+/**
+ * \brief Dispose a \c CXVirtualFileOverlay object.
+ */
+CINDEX_LINKAGE void clang_VirtualFileOverlay_dispose(CXVirtualFileOverlay);
+
+/**
+ * \brief Object encapsulating information about a module.map file.
+ */
+typedef struct CXModuleMapDescriptorImpl *CXModuleMapDescriptor;
+
+/**
+ * \brief Create a \c CXModuleMapDescriptor object.
+ * Must be disposed with \c clang_ModuleMapDescriptor_dispose().
+ *
+ * \param options is reserved, always pass 0.
+ */
+CINDEX_LINKAGE CXModuleMapDescriptor
+clang_ModuleMapDescriptor_create(unsigned options);
+
+/**
+ * \brief Sets the framework module name that the module.map describes.
+ * \returns 0 for success, non-zero to indicate an error.
+ */
+CINDEX_LINKAGE enum CXErrorCode
+clang_ModuleMapDescriptor_setFrameworkModuleName(CXModuleMapDescriptor,
+                                                 const char *name);
+
+/**
+ * \brief Sets the umbrealla header name that the module.map describes.
+ * \returns 0 for success, non-zero to indicate an error.
+ */
+CINDEX_LINKAGE enum CXErrorCode
+clang_ModuleMapDescriptor_setUmbrellaHeader(CXModuleMapDescriptor,
+                                            const char *name);
+
+/**
+ * \brief Write out the \c CXModuleMapDescriptor object to a char buffer.
+ *
+ * \param options is reserved, always pass 0.
+ * \param out_buffer_ptr pointer to receive the buffer pointer, which should be
+ * disposed using \c free().
+ * \param out_buffer_size pointer to receive the buffer size.
+ * \returns 0 for success, non-zero to indicate an error.
+ */
+CINDEX_LINKAGE enum CXErrorCode
+clang_ModuleMapDescriptor_writeToBuffer(CXModuleMapDescriptor, unsigned options,
+                                       char **out_buffer_ptr,
+                                       unsigned *out_buffer_size);
+
+/**
+ * \brief Dispose a \c CXModuleMapDescriptor object.
+ */
+CINDEX_LINKAGE void clang_ModuleMapDescriptor_dispose(CXModuleMapDescriptor);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CLANG_C_BUILD_SYSTEM_H */
+
diff --git a/include/clang-c/CXErrorCode.h b/include/clang-c/CXErrorCode.h
new file mode 100644
index 00000000000..a026c95a5bb
--- /dev/null
+++ b/include/clang-c/CXErrorCode.h
@@ -0,0 +1,64 @@
+/*===-- clang-c/CXErrorCode.h - C Index Error Codes  --------------*- C -*-===*\
+|*                                                                            *|
+|*                     The LLVM Compiler Infrastructure                       *|
+|*                                                                            *|
+|* This file is distributed under the University of Illinois Open Source      *|
+|* License. See LICENSE.TXT for details.                                      *|
+|*                                                                            *|
+|*===----------------------------------------------------------------------===*|
+|*                                                                            *|
+|* This header provides the CXErrorCode enumerators.                          *|
+|*                                                                            *|
+\*===----------------------------------------------------------------------===*/
+
+#ifndef CLANG_C_CXERRORCODE_H
+#define CLANG_C_CXERRORCODE_H
+
+#include "clang-c/Platform.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \brief Error codes returned by libclang routines.
+ *
+ * Zero (\c CXError_Success) is the only error code indicating success.  Other
+ * error codes, including not yet assigned non-zero values, indicate errors.
+ */
+enum CXErrorCode {
+  /**
+   * \brief No error.
+   */
+  CXError_Success = 0,
+
+  /**
+   * \brief A generic error code, no further details are available.
+   *
+   * Errors of this kind can get their own specific error codes in future
+   * libclang versions.
+   */
+  CXError_Failure = 1,
+
+  /**
+   * \brief libclang crashed while performing the requested operation.
+   */
+  CXError_Crashed = 2,
+
+  /**
+   * \brief The function detected that the arguments violate the function
+   * contract.
+   */
+  CXError_InvalidArguments = 3,
+
+  /**
+   * \brief An AST deserialization error has occurred.
+   */
+  CXError_ASTReadError = 4
+};
+
+#ifdef __cplusplus
+}
+#endif
+#endif
+
diff --git a/include/clang-c/CXString.h b/include/clang-c/CXString.h
index 592c4dc44e3..cf198cbf5d0 100644
--- a/include/clang-c/CXString.h
+++ b/include/clang-c/CXString.h
@@ -31,7 +31,7 @@ extern "C" {
  * \brief A character string.
  *
  * The \c CXString type is used to return strings from the interface when
- * the ownership of that string might different from one call to the next.
+ * the ownership of that string might differ from one call to the next.
  * Use \c clang_getCString() to retrieve the string data and, once finished
  * with the string data, call \c clang_disposeString() to free the string.
  */
diff --git a/include/clang-c/Documentation.h b/include/clang-c/Documentation.h
new file mode 100644
index 00000000000..ad2da077831
--- /dev/null
+++ b/include/clang-c/Documentation.h
@@ -0,0 +1,554 @@
+/*==-- clang-c/Documentation.h - Utilities for comment processing -*- C -*-===*\
+|*                                                                            *|
+|*                     The LLVM Compiler Infrastructure                       *|
+|*                                                                            *|
+|* This file is distributed under the University of Illinois Open Source      *|
+|* License. See LICENSE.TXT for details.                                      *|
+|*                                                                            *|
+|*===----------------------------------------------------------------------===*|
+|*                                                                            *|
+|* This header provides a supplementary interface for inspecting              *|
+|* documentation comments.                                                    *|
+|*                                                                            *|
+\*===----------------------------------------------------------------------===*/
+
+#ifndef CLANG_C_DOCUMENTATION_H
+#define CLANG_C_DOCUMENTATION_H
+
+#include "clang-c/Index.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \defgroup CINDEX_COMMENT Comment introspection
+ *
+ * The routines in this group provide access to information in documentation
+ * comments. These facilities are distinct from the core and may be subject to
+ * their own schedule of stability and deprecation.
+ *
+ * @{
+ */
+
+/**
+ * \brief A parsed comment.
+ */
+typedef struct {
+  const void *ASTNode;
+  CXTranslationUnit TranslationUnit;
+} CXComment;
+
+/**
+ * \brief Given a cursor that represents a documentable entity (e.g.,
+ * declaration), return the associated parsed comment as a
+ * \c CXComment_FullComment AST node.
+ */
+CINDEX_LINKAGE CXComment clang_Cursor_getParsedComment(CXCursor C);
+
+/**
+ * \brief Describes the type of the comment AST node (\c CXComment).  A comment
+ * node can be considered block content (e. g., paragraph), inline content
+ * (plain text) or neither (the root AST node).
+ */
+enum CXCommentKind {
+  /**
+   * \brief Null comment.  No AST node is constructed at the requested location
+   * because there is no text or a syntax error.
+   */
+  CXComment_Null = 0,
+
+  /**
+   * \brief Plain text.  Inline content.
+   */
+  CXComment_Text = 1,
+
+  /**
+   * \brief A command with word-like arguments that is considered inline content.
+   *
+   * For example: \\c command.
+   */
+  CXComment_InlineCommand = 2,
+
+  /**
+   * \brief HTML start tag with attributes (name-value pairs).  Considered
+   * inline content.
+   *
+   * For example:
+   * \verbatim
+   * 
 
 
+   * \endverbatim
+   */
+  CXComment_HTMLStartTag = 3,
+
+  /**
+   * \brief HTML end tag.  Considered inline content.
+   *
+   * For example:
+   * \verbatim
+   * 
+   * \endverbatim
+   */
+  CXComment_HTMLEndTag = 4,
+
+  /**
+   * \brief A paragraph, contains inline comment.  The paragraph itself is
+   * block content.
+   */
+  CXComment_Paragraph = 5,
+
+  /**
+   * \brief A command that has zero or more word-like arguments (number of
+   * word-like arguments depends on command name) and a paragraph as an
+   * argument.  Block command is block content.
+   *
+   * Paragraph argument is also a child of the block command.
+   *
+   * For example: \\brief has 0 word-like arguments and a paragraph argument.
+   *
+   * AST nodes of special kinds that parser knows about (e. g., \\param
+   * command) have their own node kinds.
+   */
+  CXComment_BlockCommand = 6,
+
+  /**
+   * \brief A \\param or \\arg command that describes the function parameter
+   * (name, passing direction, description).
+   *
+   * For example: \\param [in] ParamName description.
+   */
+  CXComment_ParamCommand = 7,
+
+  /**
+   * \brief A \\tparam command that describes a template parameter (name and
+   * description).
+   *
+   * For example: \\tparam T description.
+   */
+  CXComment_TParamCommand = 8,
+
+  /**
+   * \brief A verbatim block command (e. g., preformatted code).  Verbatim
+   * block has an opening and a closing command and contains multiple lines of
+   * text (\c CXComment_VerbatimBlockLine child nodes).
+   *
+   * For example:
+   * \\verbatim
+   * aaa
+   * \\endverbatim
+   */
+  CXComment_VerbatimBlockCommand = 9,
+
+  /**
+   * \brief A line of text that is contained within a
+   * CXComment_VerbatimBlockCommand node.
+   */
+  CXComment_VerbatimBlockLine = 10,
+
+  /**
+   * \brief A verbatim line command.  Verbatim line has an opening command,
+   * a single line of text (up to the newline after the opening command) and
+   * has no closing command.
+   */
+  CXComment_VerbatimLine = 11,
+
+  /**
+   * \brief A full comment attached to a declaration, contains block content.
+   */
+  CXComment_FullComment = 12
+};
+
+/**
+ * \brief The most appropriate rendering mode for an inline command, chosen on
+ * command semantics in Doxygen.
+ */
+enum CXCommentInlineCommandRenderKind {
+  /**
+   * \brief Command argument should be rendered in a normal font.
+   */
+  CXCommentInlineCommandRenderKind_Normal,
+
+  /**
+   * \brief Command argument should be rendered in a bold font.
+   */
+  CXCommentInlineCommandRenderKind_Bold,
+
+  /**
+   * \brief Command argument should be rendered in a monospaced font.
+   */
+  CXCommentInlineCommandRenderKind_Monospaced,
+
+  /**
+   * \brief Command argument should be rendered emphasized (typically italic
+   * font).
+   */
+  CXCommentInlineCommandRenderKind_Emphasized
+};
+
+/**
+ * \brief Describes parameter passing direction for \\param or \\arg command.
+ */
+enum CXCommentParamPassDirection {
+  /**
+   * \brief The parameter is an input parameter.
+   */
+  CXCommentParamPassDirection_In,
+
+  /**
+   * \brief The parameter is an output parameter.
+   */
+  CXCommentParamPassDirection_Out,
+
+  /**
+   * \brief The parameter is an input and output parameter.
+   */
+  CXCommentParamPassDirection_InOut
+};
+
+/**
+ * \param Comment AST node of any kind.
+ *
+ * \returns the type of the AST node.
+ */
+CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment);
+
+/**
+ * \param Comment AST node of any kind.
+ *
+ * \returns number of children of the AST node.
+ */
+CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment);
+
+/**
+ * \param Comment AST node of any kind.
+ *
+ * \param ChildIdx child index (zero-based).
+ *
+ * \returns the specified child of the AST node.
+ */
+CINDEX_LINKAGE
+CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx);
+
+/**
+ * \brief A \c CXComment_Paragraph node is considered whitespace if it contains
+ * only \c CXComment_Text nodes that are empty or whitespace.
+ *
+ * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are
+ * never considered whitespace.
+ *
+ * \returns non-zero if \c Comment is whitespace.
+ */
+CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment);
+
+/**
+ * \returns non-zero if \c Comment is inline content and has a newline
+ * immediately following it in the comment text.  Newlines between paragraphs
+ * do not count.
+ */
+CINDEX_LINKAGE
+unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_Text AST node.
+ *
+ * \returns text contained in the AST node.
+ */
+CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_InlineCommand AST node.
+ *
+ * \returns name of the inline command.
+ */
+CINDEX_LINKAGE
+CXString clang_InlineCommandComment_getCommandName(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_InlineCommand AST node.
+ *
+ * \returns the most appropriate rendering mode, chosen on command
+ * semantics in Doxygen.
+ */
+CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind
+clang_InlineCommandComment_getRenderKind(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_InlineCommand AST node.
+ *
+ * \returns number of command arguments.
+ */
+CINDEX_LINKAGE
+unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_InlineCommand AST node.
+ *
+ * \param ArgIdx argument index (zero-based).
+ *
+ * \returns text of the specified argument.
+ */
+CINDEX_LINKAGE
+CXString clang_InlineCommandComment_getArgText(CXComment Comment,
+                                               unsigned ArgIdx);
+
+/**
+ * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
+ * node.
+ *
+ * \returns HTML tag name.
+ */
+CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_HTMLStartTag AST node.
+ *
+ * \returns non-zero if tag is self-closing (for example, <br />).
+ */
+CINDEX_LINKAGE
+unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_HTMLStartTag AST node.
+ *
+ * \returns number of attributes (name-value pairs) attached to the start tag.
+ */
+CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_HTMLStartTag AST node.
+ *
+ * \param AttrIdx attribute index (zero-based).
+ *
+ * \returns name of the specified attribute.
+ */
+CINDEX_LINKAGE
+CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx);
+
+/**
+ * \param Comment a \c CXComment_HTMLStartTag AST node.
+ *
+ * \param AttrIdx attribute index (zero-based).
+ *
+ * \returns value of the specified attribute.
+ */
+CINDEX_LINKAGE
+CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx);
+
+/**
+ * \param Comment a \c CXComment_BlockCommand AST node.
+ *
+ * \returns name of the block command.
+ */
+CINDEX_LINKAGE
+CXString clang_BlockCommandComment_getCommandName(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_BlockCommand AST node.
+ *
+ * \returns number of word-like arguments.
+ */
+CINDEX_LINKAGE
+unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_BlockCommand AST node.
+ *
+ * \param ArgIdx argument index (zero-based).
+ *
+ * \returns text of the specified word-like argument.
+ */
+CINDEX_LINKAGE
+CXString clang_BlockCommandComment_getArgText(CXComment Comment,
+                                              unsigned ArgIdx);
+
+/**
+ * \param Comment a \c CXComment_BlockCommand or
+ * \c CXComment_VerbatimBlockCommand AST node.
+ *
+ * \returns paragraph argument of the block command.
+ */
+CINDEX_LINKAGE
+CXComment clang_BlockCommandComment_getParagraph(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_ParamCommand AST node.
+ *
+ * \returns parameter name.
+ */
+CINDEX_LINKAGE
+CXString clang_ParamCommandComment_getParamName(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_ParamCommand AST node.
+ *
+ * \returns non-zero if the parameter that this AST node represents was found
+ * in the function prototype and \c clang_ParamCommandComment_getParamIndex
+ * function will return a meaningful value.
+ */
+CINDEX_LINKAGE
+unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_ParamCommand AST node.
+ *
+ * \returns zero-based parameter index in function prototype.
+ */
+CINDEX_LINKAGE
+unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_ParamCommand AST node.
+ *
+ * \returns non-zero if parameter passing direction was specified explicitly in
+ * the comment.
+ */
+CINDEX_LINKAGE
+unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_ParamCommand AST node.
+ *
+ * \returns parameter passing direction.
+ */
+CINDEX_LINKAGE
+enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection(
+                                                            CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_TParamCommand AST node.
+ *
+ * \returns template parameter name.
+ */
+CINDEX_LINKAGE
+CXString clang_TParamCommandComment_getParamName(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_TParamCommand AST node.
+ *
+ * \returns non-zero if the parameter that this AST node represents was found
+ * in the template parameter list and
+ * \c clang_TParamCommandComment_getDepth and
+ * \c clang_TParamCommandComment_getIndex functions will return a meaningful
+ * value.
+ */
+CINDEX_LINKAGE
+unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_TParamCommand AST node.
+ *
+ * \returns zero-based nesting depth of this parameter in the template parameter list.
+ *
+ * For example,
+ * \verbatim
+ *     template class TT>
+ *     void test(TT aaa);
+ * \endverbatim
+ * for C and TT nesting depth is 0,
+ * for T nesting depth is 1.
+ */
+CINDEX_LINKAGE
+unsigned clang_TParamCommandComment_getDepth(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_TParamCommand AST node.
+ *
+ * \returns zero-based parameter index in the template parameter list at a
+ * given nesting depth.
+ *
+ * For example,
+ * \verbatim
+ *     template class TT>
+ *     void test(TT aaa);
+ * \endverbatim
+ * for C and TT nesting depth is 0, so we can ask for index at depth 0:
+ * at depth 0 C's index is 0, TT's index is 1.
+ *
+ * For T nesting depth is 1, so we can ask for index at depth 0 and 1:
+ * at depth 0 T's index is 1 (same as TT's),
+ * at depth 1 T's index is 0.
+ */
+CINDEX_LINKAGE
+unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth);
+
+/**
+ * \param Comment a \c CXComment_VerbatimBlockLine AST node.
+ *
+ * \returns text contained in the AST node.
+ */
+CINDEX_LINKAGE
+CXString clang_VerbatimBlockLineComment_getText(CXComment Comment);
+
+/**
+ * \param Comment a \c CXComment_VerbatimLine AST node.
+ *
+ * \returns text contained in the AST node.
+ */
+CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment);
+
+/**
+ * \brief Convert an HTML tag AST node to string.
+ *
+ * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
+ * node.
+ *
+ * \returns string containing an HTML tag.
+ */
+CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment);
+
+/**
+ * \brief Convert a given full parsed comment to an HTML fragment.
+ *
+ * Specific details of HTML layout are subject to change.  Don't try to parse
+ * this HTML back into an AST, use other APIs instead.
+ *
+ * Currently the following CSS classes are used:
+ * \li "para-brief" for \\brief paragraph and equivalent commands;
+ * \li "para-returns" for \\returns paragraph and equivalent commands;
+ * \li "word-returns" for the "Returns" word in \\returns paragraph.
+ *
+ * Function argument documentation is rendered as a \ list with arguments
+ * sorted in function prototype order.  CSS classes used:
+ * \li "param-name-index-NUMBER" for parameter name (\);
+ * \li "param-descr-index-NUMBER" for parameter description (\);
+ * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if
+ * parameter index is invalid.
+ *
+ * Template parameter documentation is rendered as a \ list with
+ * parameters sorted in template parameter list order.  CSS classes used:
+ * \li "tparam-name-index-NUMBER" for parameter name (\);
+ * \li "tparam-descr-index-NUMBER" for parameter description (\);
+ * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for
+ * names inside template template parameters;
+ * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if
+ * parameter position is invalid.
+ *
+ * \param Comment a \c CXComment_FullComment AST node.
+ *
+ * \returns string containing an HTML fragment.
+ */
+CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment);
+
+/**
+ * \brief Convert a given full parsed comment to an XML document.
+ *
+ * A Relax NG schema for the XML can be found in comment-xml-schema.rng file
+ * inside clang source tree.
+ *
+ * \param Comment a \c CXComment_FullComment AST node.
+ *
+ * \returns string containing an XML document.
+ */
+CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment);
+
+/**
+ * @}
+ */
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CLANG_C_DOCUMENTATION_H */
+
diff --git a/include/clang-c/Index.h b/include/clang-c/Index.h
index 95d54c279f0..f69f567c269 100644
--- a/include/clang-c/Index.h
+++ b/include/clang-c/Index.h
@@ -19,7 +19,9 @@
 #include 
 
 #include "clang-c/Platform.h"
+#include "clang-c/CXErrorCode.h"
 #include "clang-c/CXString.h"
+#include "clang-c/BuildSystem.h"
 
 /**
  * \brief The version constants for the libclang API.
@@ -30,7 +32,7 @@
  * compatible, thus CINDEX_VERSION_MAJOR is expected to remain stable.
  */
 #define CINDEX_VERSION_MAJOR 0
-#define CINDEX_VERSION_MINOR 20
+#define CINDEX_VERSION_MINOR 27
 
 #define CINDEX_VERSION_ENCODE(major, minor) ( \
       ((major) * 10000)                       \
@@ -598,6 +600,32 @@ CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range);
  */
 CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range);
 
+/**
+ * \brief Identifies an array of ranges.
+ */
+typedef struct {
+  /** \brief The number of ranges in the \c ranges array. */
+  unsigned count;
+  /**
+   * \brief An array of \c CXSourceRanges.
+   */
+  CXSourceRange *ranges;
+} CXSourceRangeList;
+
+/**
+ * \brief Retrieve all ranges that were skipped by the preprocessor.
+ *
+ * The preprocessor will skip lines when they are surrounded by an
+ * if/ifdef/ifndef directive whose condition does not evaluate to true.
+ */
+CINDEX_LINKAGE CXSourceRangeList *clang_getSkippedRanges(CXTranslationUnit tu,
+                                                         CXFile file);
+
+/**
+ * \brief Destroy the given \c CXSourceRangeList.
+ */
+CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges);
+
 /**
  * @}
  */
@@ -1050,10 +1078,27 @@ CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile(
                                          struct CXUnsavedFile *unsaved_files);
 
 /**
- * \brief Create a translation unit from an AST file (-emit-ast).
+ * \brief Same as \c clang_createTranslationUnit2, but returns
+ * the \c CXTranslationUnit instead of an error code.  In case of an error this
+ * routine returns a \c NULL \c CXTranslationUnit, without further detailed
+ * error codes.
  */
-CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex,
-                                             const char *ast_filename);
+CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(
+    CXIndex CIdx,
+    const char *ast_filename);
+
+/**
+ * \brief Create a translation unit from an AST file (\c -emit-ast).
+ *
+ * \param[out] out_TU A non-NULL pointer to store the created
+ * \c CXTranslationUnit.
+ *
+ * \returns Zero on success, otherwise returns an error code.
+ */
+CINDEX_LINKAGE enum CXErrorCode clang_createTranslationUnit2(
+    CXIndex CIdx,
+    const char *ast_filename,
+    CXTranslationUnit *out_TU);
 
 /**
  * \brief Flags that control the creation of translation units.
@@ -1167,7 +1212,22 @@ enum CXTranslationUnit_Flags {
  * set of optimizations enabled may change from one version to the next.
  */
 CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void);
-  
+
+/**
+ * \brief Same as \c clang_parseTranslationUnit2, but returns
+ * the \c CXTranslationUnit instead of an error code.  In case of an error this
+ * routine returns a \c NULL \c CXTranslationUnit, without further detailed
+ * error codes.
+ */
+CINDEX_LINKAGE CXTranslationUnit
+clang_parseTranslationUnit(CXIndex CIdx,
+                           const char *source_filename,
+                           const char *const *command_line_args,
+                           int num_command_line_args,
+                           struct CXUnsavedFile *unsaved_files,
+                           unsigned num_unsaved_files,
+                           unsigned options);
+
 /**
  * \brief Parse the given source file and the translation unit corresponding
  * to that file.
@@ -1182,7 +1242,7 @@ CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void);
  * associated.
  *
  * \param source_filename The name of the source file to load, or NULL if the
- * source file is included in \p command_line_args.
+ * source file is included in \c command_line_args.
  *
  * \param command_line_args The command-line arguments that would be
  * passed to the \c clang executable if it were being invoked out-of-process.
@@ -1191,7 +1251,7 @@ CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void);
  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \'.
  *
  * \param num_command_line_args The number of command-line arguments in
- * \p command_line_args.
+ * \c command_line_args.
  *
  * \param unsaved_files the files that have not yet been saved to disk
  * but may be required for parsing, including the contents of
@@ -1206,18 +1266,22 @@ CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void);
  * is managed but not its compilation. This should be a bitwise OR of the
  * CXTranslationUnit_XXX flags.
  *
- * \returns A new translation unit describing the parsed code and containing
- * any diagnostics produced by the compiler. If there is a failure from which
- * the compiler cannot recover, returns NULL.
+ * \param[out] out_TU A non-NULL pointer to store the created
+ * \c CXTranslationUnit, describing the parsed code and containing any
+ * diagnostics produced by the compiler.
+ *
+ * \returns Zero on success, otherwise returns an error code.
  */
-CINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(CXIndex CIdx,
-                                                    const char *source_filename,
-                                         const char * const *command_line_args,
-                                                      int num_command_line_args,
-                                            struct CXUnsavedFile *unsaved_files,
-                                                     unsigned num_unsaved_files,
-                                                            unsigned options);
-  
+CINDEX_LINKAGE enum CXErrorCode
+clang_parseTranslationUnit2(CXIndex CIdx,
+                            const char *source_filename,
+                            const char *const *command_line_args,
+                            int num_command_line_args,
+                            struct CXUnsavedFile *unsaved_files,
+                            unsigned num_unsaved_files,
+                            unsigned options,
+                            CXTranslationUnit *out_TU);
+
 /**
  * \brief Flags that control how translation units are saved.
  *
@@ -1369,10 +1433,11 @@ CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU);
  * The function \c clang_defaultReparseOptions() produces a default set of
  * options recommended for most uses, based on the translation unit.
  *
- * \returns 0 if the sources could be reparsed. A non-zero value will be
+ * \returns 0 if the sources could be reparsed.  A non-zero error code will be
  * returned if reparsing was impossible, such that the translation unit is
- * invalid. In such cases, the only valid call for \p TU is 
- * \c clang_disposeTranslationUnit(TU).
+ * invalid. In such cases, the only valid call for \c TU is
+ * \c clang_disposeTranslationUnit(TU).  The error codes returned by this
+ * routine are described by the \c CXErrorCode enum.
  */
 CINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU,
                                                 unsigned num_unsaved_files,
@@ -1669,7 +1734,7 @@ enum CXCursorKind {
 
   /**
    * \brief An expression that refers to some value declaration, such
-   * as a function, varible, or enumerator.
+   * as a function, variable, or enumerator.
    */
   CXCursor_DeclRefExpr                   = 101,
 
@@ -1907,7 +1972,7 @@ enum CXCursorKind {
    */
   CXCursor_ObjCBoolLiteralExpr           = 145,
 
-  /** \brief Represents the "self" expression in a ObjC method.
+  /** \brief Represents the "self" expression in an Objective-C method.
    */
   CXCursor_ObjCSelfExpr                  = 146,
 
@@ -2070,7 +2135,67 @@ enum CXCursorKind {
    */
   CXCursor_OMPParallelDirective          = 232,
 
-  CXCursor_LastStmt                      = CXCursor_OMPParallelDirective,
+  /** \brief OpenMP simd directive.
+   */
+  CXCursor_OMPSimdDirective              = 233,
+
+  /** \brief OpenMP for directive.
+   */
+  CXCursor_OMPForDirective               = 234,
+
+  /** \brief OpenMP sections directive.
+   */
+  CXCursor_OMPSectionsDirective          = 235,
+
+  /** \brief OpenMP section directive.
+   */
+  CXCursor_OMPSectionDirective           = 236,
+
+  /** \brief OpenMP single directive.
+   */
+  CXCursor_OMPSingleDirective            = 237,
+
+  /** \brief OpenMP parallel for directive.
+   */
+  CXCursor_OMPParallelForDirective       = 238,
+
+  /** \brief OpenMP parallel sections directive.
+   */
+  CXCursor_OMPParallelSectionsDirective  = 239,
+
+  /** \brief OpenMP task directive.
+   */
+  CXCursor_OMPTaskDirective              = 240,
+
+  /** \brief OpenMP master directive.
+   */
+  CXCursor_OMPMasterDirective            = 241,
+
+  /** \brief OpenMP critical directive.
+   */
+  CXCursor_OMPCriticalDirective          = 242,
+
+  /** \brief OpenMP taskyield directive.
+   */
+  CXCursor_OMPTaskyieldDirective         = 243,
+
+  /** \brief OpenMP barrier directive.
+   */
+  CXCursor_OMPBarrierDirective           = 244,
+
+  /** \brief OpenMP taskwait directive.
+   */
+  CXCursor_OMPTaskwaitDirective          = 245,
+
+  /** \brief OpenMP flush directive.
+   */
+  CXCursor_OMPFlushDirective             = 246,
+
+  /** \brief Windows Structured Exception Handling's leave statement.
+   */
+  CXCursor_SEHLeaveStmt                  = 247,
+
+  CXCursor_LastStmt                      = CXCursor_SEHLeaveStmt,
 
   /**
    * \brief Cursor that represents the translation unit itself.
@@ -2096,8 +2221,15 @@ enum CXCursorKind {
   CXCursor_AnnotateAttr                  = 406,
   CXCursor_AsmLabelAttr                  = 407,
   CXCursor_PackedAttr                    = 408,
-  CXCursor_LastAttr                      = CXCursor_PackedAttr,
-     
+  CXCursor_PureAttr                      = 409,
+  CXCursor_ConstAttr                     = 410,
+  CXCursor_NoDuplicateAttr               = 411,
+  CXCursor_CUDAConstantAttr              = 412,
+  CXCursor_CUDADeviceAttr                = 413,
+  CXCursor_CUDAGlobalAttr                = 414,
+  CXCursor_CUDAHostAttr                  = 415,
+  CXCursor_LastAttr                      = CXCursor_CUDAHostAttr,
+
   /* Preprocessing */
   CXCursor_PreprocessingDirective        = 500,
   CXCursor_MacroDefinition               = 501,
@@ -2140,14 +2272,6 @@ typedef struct {
   const void *data[3];
 } CXCursor;
 
-/**
- * \brief A comment AST node.
- */
-typedef struct {
-  const void *ASTNode;
-  CXTranslationUnit TranslationUnit;
-} CXComment;
-
 /**
  * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations
  *
@@ -2369,7 +2493,7 @@ clang_disposeCXPlatformAvailability(CXPlatformAvailability *availability);
 /**
  * \brief Describe the "language" of the entity referred to by a cursor.
  */
-CINDEX_LINKAGE enum CXLanguageKind {
+enum CXLanguageKind {
   CXLanguage_Invalid = 0,
   CXLanguage_C,
   CXLanguage_ObjC,
@@ -2435,10 +2559,10 @@ CINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset,
  * void C::f() { }
  * \endcode
  *
- * In the out-of-line definition of \c C::f, the semantic parent is the 
+ * In the out-of-line definition of \c C::f, the semantic parent is
  * the class \c C, of which this function is a member. The lexical parent is
  * the place where the declaration actually occurs in the source code; in this
- * case, the definition occurs in the translation unit. In general, the 
+ * case, the definition occurs in the translation unit. In general, the
  * lexical parent for a given entity can change without affecting the semantics
  * of the program, and the lexical parent of different declarations of the
  * same entity may be different. Changing the semantic parent of a declaration,
@@ -2470,10 +2594,10 @@ CINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor);
  * void C::f() { }
  * \endcode
  *
- * In the out-of-line definition of \c C::f, the semantic parent is the 
+ * In the out-of-line definition of \c C::f, the semantic parent is
  * the class \c C, of which this function is a member. The lexical parent is
  * the place where the declaration actually occurs in the source code; in this
- * case, the definition occurs in the translation unit. In general, the 
+ * case, the definition occurs in the translation unit. In general, the
  * lexical parent for a given entity can change without affecting the semantics
  * of the program, and the lexical parent of different declarations of the
  * same entity may be different. Changing the semantic parent of a declaration,
@@ -2598,7 +2722,7 @@ CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor);
  *
  * The extent of a cursor starts with the file/line/column pointing at the
  * first character within the source construct that the cursor refers to and
- * ends with the last character withinin that source construct. For a
+ * ends with the last character within that source construct. For a
  * declaration, the extent covers the declaration itself. For a reference,
  * the extent covers the location of the reference (e.g., where the referenced
  * entity was actually used).
@@ -2620,7 +2744,7 @@ CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor);
  */
 enum CXTypeKind {
   /**
-   * \brief Reprents an invalid type (e.g., where no type is available).
+   * \brief Represents an invalid type (e.g., where no type is available).
    */
   CXType_Invalid = 0,
 
@@ -2854,14 +2978,14 @@ CINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K);
 CINDEX_LINKAGE enum CXCallingConv clang_getFunctionTypeCallingConv(CXType T);
 
 /**
- * \brief Retrieve the result type associated with a function type.
+ * \brief Retrieve the return type associated with a function type.
  *
  * If a non-function type is passed in, an invalid type is returned.
  */
 CINDEX_LINKAGE CXType clang_getResultType(CXType T);
 
 /**
- * \brief Retrieve the number of non-variadic arguments associated with a
+ * \brief Retrieve the number of non-variadic parameters associated with a
  * function type.
  *
  * If a non-function type is passed in, -1 is returned.
@@ -2869,7 +2993,7 @@ CINDEX_LINKAGE CXType clang_getResultType(CXType T);
 CINDEX_LINKAGE int clang_getNumArgTypes(CXType T);
 
 /**
- * \brief Retrieve the type of an argument of a function type.
+ * \brief Retrieve the type of a parameter of a function type.
  *
  * If a non-function type is passed in or the function does not have enough
  * parameters, an invalid type is returned.
@@ -2882,7 +3006,7 @@ CINDEX_LINKAGE CXType clang_getArgType(CXType T, unsigned i);
 CINDEX_LINKAGE unsigned clang_isFunctionTypeVariadic(CXType T);
 
 /**
- * \brief Retrieve the result type associated with a given cursor.
+ * \brief Retrieve the return type associated with a given cursor.
  *
  * This only returns a valid type if the cursor refers to a function or method.
  */
@@ -3011,6 +3135,24 @@ enum CXRefQualifierKind {
   CXRefQualifier_RValue
 };
 
+/**
+ * \brief Returns the number of template arguments for given class template
+ * specialization, or -1 if type \c T is not a class template specialization.
+ *
+ * Variadic argument packs count as only one argument, and can not be inspected
+ * further.
+ */
+CINDEX_LINKAGE int clang_Type_getNumTemplateArguments(CXType T);
+
+/**
+ * \brief Returns the type template argument of a template class specialization
+ * at given index.
+ *
+ * This function only returns template type arguments and does not handle
+ * template template arguments or variadic packs.
+ */
+CINDEX_LINKAGE CXType clang_Type_getTemplateArgumentAsType(CXType T, unsigned i);
+
 /**
  * \brief Retrieve the ref-qualifier kind of a function or method.
  *
@@ -3274,8 +3416,8 @@ CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor);
 /**
  * \brief Retrieve a range for a piece that forms the cursors spelling name.
  * Most of the times there is only one range for the complete spelling but for
- * objc methods and objc message expressions, there are multiple pieces for each
- * selector identifier.
+ * Objective-C methods and Objective-C message expressions, there are multiple
+ * pieces for each selector identifier.
  * 
  * \param pieceIndex the index of the spelling name piece. If this is greater
  * than the actual number of pieces, it will return a NULL (invalid) range.
@@ -3371,25 +3513,25 @@ CINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor);
 
 
 /**
- * \brief If the cursor points to a selector identifier in a objc method or
- * message expression, this returns the selector index.
+ * \brief If the cursor points to a selector identifier in an Objective-C
+ * method or message expression, this returns the selector index.
  *
  * After getting a cursor with #clang_getCursor, this can be called to
  * determine if the location points to a selector identifier.
  *
- * \returns The selector index if the cursor is an objc method or message
+ * \returns The selector index if the cursor is an Objective-C method or message
  * expression and the cursor is pointing to a selector identifier, or -1
  * otherwise.
  */
 CINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex(CXCursor);
 
 /**
- * \brief Given a cursor pointing to a C++ method call or an ObjC message,
- * returns non-zero if the method/message is "dynamic", meaning:
+ * \brief Given a cursor pointing to a C++ method call or an Objective-C
+ * message, returns non-zero if the method/message is "dynamic", meaning:
  * 
  * For a C++ method: the call is virtual.
- * For an ObjC message: the receiver is an object instance, not 'super' or a
- * specific class.
+ * For an Objective-C message: the receiver is an object instance, not 'super'
+ * or a specific class.
  * 
  * If the method/message is "static" or the cursor does not point to a
  * method/message, it will return zero.
@@ -3397,8 +3539,8 @@ CINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex(CXCursor);
 CINDEX_LINKAGE int clang_Cursor_isDynamicCall(CXCursor C);
 
 /**
- * \brief Given a cursor pointing to an ObjC message, returns the CXType of the
- * receiver.
+ * \brief Given a cursor pointing to an Objective-C message, returns the CXType
+ * of the receiver.
  */
 CINDEX_LINKAGE CXType clang_Cursor_getReceiverType(CXCursor C);
 
@@ -3433,7 +3575,7 @@ CINDEX_LINKAGE unsigned clang_Cursor_getObjCPropertyAttributes(CXCursor C,
 
 /**
  * \brief 'Qualifiers' written next to the return and parameter types in
- * ObjC method declarations.
+ * Objective-C method declarations.
  */
 typedef enum {
   CXObjCDeclQualifier_None = 0x0,
@@ -3446,15 +3588,16 @@ typedef enum {
 } CXObjCDeclQualifierKind;
 
 /**
- * \brief Given a cursor that represents an ObjC method or parameter
- * declaration, return the associated ObjC qualifiers for the return type or the
- * parameter respectively. The bits are formed from CXObjCDeclQualifierKind.
+ * \brief Given a cursor that represents an Objective-C method or parameter
+ * declaration, return the associated Objective-C qualifiers for the return
+ * type or the parameter respectively. The bits are formed from
+ * CXObjCDeclQualifierKind.
  */
 CINDEX_LINKAGE unsigned clang_Cursor_getObjCDeclQualifiers(CXCursor C);
 
 /**
- * \brief Given a cursor that represents an ObjC method or property declaration,
- * return non-zero if the declaration was affected by "@optional".
+ * \brief Given a cursor that represents an Objective-C method or property
+ * declaration, return non-zero if the declaration was affected by "@optional".
  * Returns zero if the cursor is not such a declaration or it is "@required".
  */
 CINDEX_LINKAGE unsigned clang_Cursor_isObjCOptional(CXCursor C);
@@ -3484,13 +3627,6 @@ CINDEX_LINKAGE CXString clang_Cursor_getRawCommentText(CXCursor C);
  */
 CINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText(CXCursor C);
 
-/**
- * \brief Given a cursor that represents a documentable entity (e.g.,
- * declaration), return the associated parsed comment as a
- * \c CXComment_FullComment AST node.
- */
-CINDEX_LINKAGE CXComment clang_Cursor_getParsedComment(CXCursor C);
-
 /**
  * @}
  */
@@ -3510,6 +3646,12 @@ typedef void *CXModule;
  */
 CINDEX_LINKAGE CXModule clang_Cursor_getModule(CXCursor C);
 
+/**
+ * \brief Given a CXFile header file, return the module that contains it, if one
+ * exists.
+ */
+CINDEX_LINKAGE CXModule clang_getModuleForFile(CXTranslationUnit, CXFile);
+
 /**
  * \param Module a module object.
  *
@@ -3540,6 +3682,13 @@ CINDEX_LINKAGE CXString clang_Module_getName(CXModule Module);
  */
 CINDEX_LINKAGE CXString clang_Module_getFullName(CXModule Module);
 
+/**
+ * \param Module a module object.
+ *
+ * \returns non-zero if the module is a system one.
+ */
+CINDEX_LINKAGE int clang_Module_isSystem(CXModule Module);
+
 /**
  * \param Module a module object.
  *
@@ -3559,514 +3708,6 @@ CINDEX_LINKAGE
 CXFile clang_Module_getTopLevelHeader(CXTranslationUnit,
                                       CXModule Module, unsigned Index);
 
-/**
- * @}
- */
-
-/**
- * \defgroup CINDEX_COMMENT Comment AST introspection
- *
- * The routines in this group provide access to information in the
- * documentation comment ASTs.
- *
- * @{
- */
-
-/**
- * \brief Describes the type of the comment AST node (\c CXComment).  A comment
- * node can be considered block content (e. g., paragraph), inline content
- * (plain text) or neither (the root AST node).
- */
-enum CXCommentKind {
-  /**
-   * \brief Null comment.  No AST node is constructed at the requested location
-   * because there is no text or a syntax error.
-   */
-  CXComment_Null = 0,
-
-  /**
-   * \brief Plain text.  Inline content.
-   */
-  CXComment_Text = 1,
-
-  /**
-   * \brief A command with word-like arguments that is considered inline content.
-   *
-   * For example: \\c command.
-   */
-  CXComment_InlineCommand = 2,
-
-  /**
-   * \brief HTML start tag with attributes (name-value pairs).  Considered
-   * inline content.
-   *
-   * For example:
-   * \verbatim
-   * 
 
 
-   * \endverbatim
-   */
-  CXComment_HTMLStartTag = 3,
-
-  /**
-   * \brief HTML end tag.  Considered inline content.
-   *
-   * For example:
-   * \verbatim
-   * 
-   * \endverbatim
-   */
-  CXComment_HTMLEndTag = 4,
-
-  /**
-   * \brief A paragraph, contains inline comment.  The paragraph itself is
-   * block content.
-   */
-  CXComment_Paragraph = 5,
-
-  /**
-   * \brief A command that has zero or more word-like arguments (number of
-   * word-like arguments depends on command name) and a paragraph as an
-   * argument.  Block command is block content.
-   *
-   * Paragraph argument is also a child of the block command.
-   *
-   * For example: \\brief has 0 word-like arguments and a paragraph argument.
-   *
-   * AST nodes of special kinds that parser knows about (e. g., \\param
-   * command) have their own node kinds.
-   */
-  CXComment_BlockCommand = 6,
-
-  /**
-   * \brief A \\param or \\arg command that describes the function parameter
-   * (name, passing direction, description).
-   *
-   * For example: \\param [in] ParamName description.
-   */
-  CXComment_ParamCommand = 7,
-
-  /**
-   * \brief A \\tparam command that describes a template parameter (name and
-   * description).
-   *
-   * For example: \\tparam T description.
-   */
-  CXComment_TParamCommand = 8,
-
-  /**
-   * \brief A verbatim block command (e. g., preformatted code).  Verbatim
-   * block has an opening and a closing command and contains multiple lines of
-   * text (\c CXComment_VerbatimBlockLine child nodes).
-   *
-   * For example:
-   * \\verbatim
-   * aaa
-   * \\endverbatim
-   */
-  CXComment_VerbatimBlockCommand = 9,
-
-  /**
-   * \brief A line of text that is contained within a
-   * CXComment_VerbatimBlockCommand node.
-   */
-  CXComment_VerbatimBlockLine = 10,
-
-  /**
-   * \brief A verbatim line command.  Verbatim line has an opening command,
-   * a single line of text (up to the newline after the opening command) and
-   * has no closing command.
-   */
-  CXComment_VerbatimLine = 11,
-
-  /**
-   * \brief A full comment attached to a declaration, contains block content.
-   */
-  CXComment_FullComment = 12
-};
-
-/**
- * \brief The most appropriate rendering mode for an inline command, chosen on
- * command semantics in Doxygen.
- */
-enum CXCommentInlineCommandRenderKind {
-  /**
-   * \brief Command argument should be rendered in a normal font.
-   */
-  CXCommentInlineCommandRenderKind_Normal,
-
-  /**
-   * \brief Command argument should be rendered in a bold font.
-   */
-  CXCommentInlineCommandRenderKind_Bold,
-
-  /**
-   * \brief Command argument should be rendered in a monospaced font.
-   */
-  CXCommentInlineCommandRenderKind_Monospaced,
-
-  /**
-   * \brief Command argument should be rendered emphasized (typically italic
-   * font).
-   */
-  CXCommentInlineCommandRenderKind_Emphasized
-};
-
-/**
- * \brief Describes parameter passing direction for \\param or \\arg command.
- */
-enum CXCommentParamPassDirection {
-  /**
-   * \brief The parameter is an input parameter.
-   */
-  CXCommentParamPassDirection_In,
-
-  /**
-   * \brief The parameter is an output parameter.
-   */
-  CXCommentParamPassDirection_Out,
-
-  /**
-   * \brief The parameter is an input and output parameter.
-   */
-  CXCommentParamPassDirection_InOut
-};
-
-/**
- * \param Comment AST node of any kind.
- *
- * \returns the type of the AST node.
- */
-CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment);
-
-/**
- * \param Comment AST node of any kind.
- *
- * \returns number of children of the AST node.
- */
-CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment);
-
-/**
- * \param Comment AST node of any kind.
- *
- * \param ChildIdx child index (zero-based).
- *
- * \returns the specified child of the AST node.
- */
-CINDEX_LINKAGE
-CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx);
-
-/**
- * \brief A \c CXComment_Paragraph node is considered whitespace if it contains
- * only \c CXComment_Text nodes that are empty or whitespace.
- *
- * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are
- * never considered whitespace.
- *
- * \returns non-zero if \c Comment is whitespace.
- */
-CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment);
-
-/**
- * \returns non-zero if \c Comment is inline content and has a newline
- * immediately following it in the comment text.  Newlines between paragraphs
- * do not count.
- */
-CINDEX_LINKAGE
-unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_Text AST node.
- *
- * \returns text contained in the AST node.
- */
-CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_InlineCommand AST node.
- *
- * \returns name of the inline command.
- */
-CINDEX_LINKAGE
-CXString clang_InlineCommandComment_getCommandName(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_InlineCommand AST node.
- *
- * \returns the most appropriate rendering mode, chosen on command
- * semantics in Doxygen.
- */
-CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind
-clang_InlineCommandComment_getRenderKind(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_InlineCommand AST node.
- *
- * \returns number of command arguments.
- */
-CINDEX_LINKAGE
-unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_InlineCommand AST node.
- *
- * \param ArgIdx argument index (zero-based).
- *
- * \returns text of the specified argument.
- */
-CINDEX_LINKAGE
-CXString clang_InlineCommandComment_getArgText(CXComment Comment,
-                                               unsigned ArgIdx);
-
-/**
- * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
- * node.
- *
- * \returns HTML tag name.
- */
-CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_HTMLStartTag AST node.
- *
- * \returns non-zero if tag is self-closing (for example, <br />).
- */
-CINDEX_LINKAGE
-unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_HTMLStartTag AST node.
- *
- * \returns number of attributes (name-value pairs) attached to the start tag.
- */
-CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_HTMLStartTag AST node.
- *
- * \param AttrIdx attribute index (zero-based).
- *
- * \returns name of the specified attribute.
- */
-CINDEX_LINKAGE
-CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx);
-
-/**
- * \param Comment a \c CXComment_HTMLStartTag AST node.
- *
- * \param AttrIdx attribute index (zero-based).
- *
- * \returns value of the specified attribute.
- */
-CINDEX_LINKAGE
-CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx);
-
-/**
- * \param Comment a \c CXComment_BlockCommand AST node.
- *
- * \returns name of the block command.
- */
-CINDEX_LINKAGE
-CXString clang_BlockCommandComment_getCommandName(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_BlockCommand AST node.
- *
- * \returns number of word-like arguments.
- */
-CINDEX_LINKAGE
-unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_BlockCommand AST node.
- *
- * \param ArgIdx argument index (zero-based).
- *
- * \returns text of the specified word-like argument.
- */
-CINDEX_LINKAGE
-CXString clang_BlockCommandComment_getArgText(CXComment Comment,
-                                              unsigned ArgIdx);
-
-/**
- * \param Comment a \c CXComment_BlockCommand or
- * \c CXComment_VerbatimBlockCommand AST node.
- *
- * \returns paragraph argument of the block command.
- */
-CINDEX_LINKAGE
-CXComment clang_BlockCommandComment_getParagraph(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_ParamCommand AST node.
- *
- * \returns parameter name.
- */
-CINDEX_LINKAGE
-CXString clang_ParamCommandComment_getParamName(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_ParamCommand AST node.
- *
- * \returns non-zero if the parameter that this AST node represents was found
- * in the function prototype and \c clang_ParamCommandComment_getParamIndex
- * function will return a meaningful value.
- */
-CINDEX_LINKAGE
-unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_ParamCommand AST node.
- *
- * \returns zero-based parameter index in function prototype.
- */
-CINDEX_LINKAGE
-unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_ParamCommand AST node.
- *
- * \returns non-zero if parameter passing direction was specified explicitly in
- * the comment.
- */
-CINDEX_LINKAGE
-unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_ParamCommand AST node.
- *
- * \returns parameter passing direction.
- */
-CINDEX_LINKAGE
-enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection(
-                                                            CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_TParamCommand AST node.
- *
- * \returns template parameter name.
- */
-CINDEX_LINKAGE
-CXString clang_TParamCommandComment_getParamName(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_TParamCommand AST node.
- *
- * \returns non-zero if the parameter that this AST node represents was found
- * in the template parameter list and
- * \c clang_TParamCommandComment_getDepth and
- * \c clang_TParamCommandComment_getIndex functions will return a meaningful
- * value.
- */
-CINDEX_LINKAGE
-unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_TParamCommand AST node.
- *
- * \returns zero-based nesting depth of this parameter in the template parameter list.
- *
- * For example,
- * \verbatim
- *     template class TT>
- *     void test(TT aaa);
- * \endverbatim
- * for C and TT nesting depth is 0,
- * for T nesting depth is 1.
- */
-CINDEX_LINKAGE
-unsigned clang_TParamCommandComment_getDepth(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_TParamCommand AST node.
- *
- * \returns zero-based parameter index in the template parameter list at a
- * given nesting depth.
- *
- * For example,
- * \verbatim
- *     template class TT>
- *     void test(TT aaa);
- * \endverbatim
- * for C and TT nesting depth is 0, so we can ask for index at depth 0:
- * at depth 0 C's index is 0, TT's index is 1.
- *
- * For T nesting depth is 1, so we can ask for index at depth 0 and 1:
- * at depth 0 T's index is 1 (same as TT's),
- * at depth 1 T's index is 0.
- */
-CINDEX_LINKAGE
-unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth);
-
-/**
- * \param Comment a \c CXComment_VerbatimBlockLine AST node.
- *
- * \returns text contained in the AST node.
- */
-CINDEX_LINKAGE
-CXString clang_VerbatimBlockLineComment_getText(CXComment Comment);
-
-/**
- * \param Comment a \c CXComment_VerbatimLine AST node.
- *
- * \returns text contained in the AST node.
- */
-CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment);
-
-/**
- * \brief Convert an HTML tag AST node to string.
- *
- * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST
- * node.
- *
- * \returns string containing an HTML tag.
- */
-CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment);
-
-/**
- * \brief Convert a given full parsed comment to an HTML fragment.
- *
- * Specific details of HTML layout are subject to change.  Don't try to parse
- * this HTML back into an AST, use other APIs instead.
- *
- * Currently the following CSS classes are used:
- * \li "para-brief" for \\brief paragraph and equivalent commands;
- * \li "para-returns" for \\returns paragraph and equivalent commands;
- * \li "word-returns" for the "Returns" word in \\returns paragraph.
- *
- * Function argument documentation is rendered as a \ list with arguments
- * sorted in function prototype order.  CSS classes used:
- * \li "param-name-index-NUMBER" for parameter name (\);
- * \li "param-descr-index-NUMBER" for parameter description (\);
- * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if
- * parameter index is invalid.
- *
- * Template parameter documentation is rendered as a \ list with
- * parameters sorted in template parameter list order.  CSS classes used:
- * \li "tparam-name-index-NUMBER" for parameter name (\);
- * \li "tparam-descr-index-NUMBER" for parameter description (\);
- * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for
- * names inside template template parameters;
- * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if
- * parameter position is invalid.
- *
- * \param Comment a \c CXComment_FullComment AST node.
- *
- * \returns string containing an HTML fragment.
- */
-CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment);
-
-/**
- * \brief Convert a given full parsed comment to an XML document.
- *
- * A Relax NG schema for the XML can be found in comment-xml-schema.rng file
- * inside clang source tree.
- *
- * \param Comment a \c CXComment_FullComment AST node.
- *
- * \returns string containing an XML document.
- */
-CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment);
-
 /**
  * @}
  */
@@ -4099,6 +3740,12 @@ CINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C);
  */
 CINDEX_LINKAGE unsigned clang_CXXMethod_isVirtual(CXCursor C);
 
+/**
+ * \brief Determine if a C++ member function or member function template is
+ * declared 'const'.
+ */
+CINDEX_LINKAGE unsigned clang_CXXMethod_isConst(CXCursor C);
+
 /**
  * \brief Given a cursor that represents a template, determine
  * the cursor kind of the specializations would be generated by instantiating
@@ -4189,7 +3836,7 @@ enum CXNameRefFlags {
    * Non-contiguous names occur in Objective-C when a selector with two or more
    * parameters is used, or in C++ when using an operator:
    * \code
-   * [object doSomething:here withValue:there]; // ObjC
+   * [object doSomething:here withValue:there]; // Objective-C
    * return some_vector[1]; // C++
    * \endcode
    */
@@ -5022,7 +4669,7 @@ CXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results,
                                              unsigned Index);
 
 /**
- * \brief Determines what compeltions are appropriate for the context
+ * \brief Determines what completions are appropriate for the context
  * the given code completion.
  * 
  * \param Results the code completion results to query
@@ -5472,7 +5119,7 @@ typedef struct {
   const CXIdxContainerInfo *declAsContainer;
   /**
    * \brief Whether the declaration exists in code or was created implicitly
-   * by the compiler, e.g. implicit objc methods for properties.
+   * by the compiler, e.g. implicit Objective-C methods for properties.
    */
   int isImplicit;
   const CXIdxAttrInfo *const *attributes;
@@ -5545,8 +5192,8 @@ typedef enum {
    */
   CXIdxEntityRef_Direct = 1,
   /**
-   * \brief An implicit reference, e.g. a reference of an ObjC method via the
-   * dot syntax.
+   * \brief An implicit reference, e.g. a reference of an Objective-C method
+   * via the dot syntax.
    */
   CXIdxEntityRef_Implicit = 2
 } CXIdxEntityRefKind;
@@ -5740,7 +5387,7 @@ typedef enum {
 
   /**
    * \brief Skip a function/method body that was already parsed during an
-   * indexing session assosiated with a \c CXIndexAction object.
+   * indexing session associated with a \c CXIndexAction object.
    * Bodies in system headers are always skipped.
    */
   CXIndexOpt_SkipParsedBodiesInSession = 0x10
@@ -5763,11 +5410,12 @@ typedef enum {
  * \param index_options A bitmask of options that affects how indexing is
  * performed. This should be a bitwise OR of the CXIndexOpt_XXX flags.
  *
- * \param out_TU [out] pointer to store a CXTranslationUnit that can be reused
- * after indexing is finished. Set to NULL if you do not require it.
+ * \param[out] out_TU pointer to store a \c CXTranslationUnit that can be
+ * reused after indexing is finished. Set to \c NULL if you do not require it.
  *
- * \returns If there is a failure from which the there is no recovery, returns
- * non-zero, otherwise returns 0.
+ * \returns 0 on success or if there were errors from which the compiler could
+ * recover.  If there is a failure from which the there is no recovery, returns
+ * a non-zero \c CXErrorCode.
  *
  * The rest of the parameters are the same as #clang_parseTranslationUnit.
  */
@@ -5836,6 +5484,9 @@ CXSourceLocation clang_indexLoc_getCXSourceLocation(CXIdxLoc loc);
  * @}
  */
 
+/* Include the comment API for compatibility. This will eventually go away. */
+#include "clang-c/Documentation.h"
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/clang-c/module.modulemap b/include/clang-c/module.modulemap
new file mode 100644
index 00000000000..95a59d62344
--- /dev/null
+++ b/include/clang-c/module.modulemap
@@ -0,0 +1,4 @@
+module Clang_C {
+  umbrella "."
+  module * { export * }
+}
diff --git a/include/clang/ARCMigrate/ARCMT.h b/include/clang/ARCMigrate/ARCMT.h
index 196f6c0b731..ad4f23c604b 100644
--- a/include/clang/ARCMigrate/ARCMT.h
+++ b/include/clang/ARCMigrate/ARCMT.h
@@ -113,7 +113,7 @@ class MigrationProcess {
     virtual void remove(CharSourceRange range) { }
   };
 
-  bool applyTransform(TransformFn trans, RewriteListener *listener = 0);
+  bool applyTransform(TransformFn trans, RewriteListener *listener = nullptr);
 
   FileRemapper &getRemapper() { return Remapper; }
 };
diff --git a/include/clang/ARCMigrate/ARCMTActions.h b/include/clang/ARCMigrate/ARCMTActions.h
index 45c8b4ed1a3..b3e74b99667 100644
--- a/include/clang/ARCMigrate/ARCMTActions.h
+++ b/include/clang/ARCMigrate/ARCMTActions.h
@@ -12,14 +12,14 @@
 
 #include "clang/ARCMigrate/FileRemapper.h"
 #include "clang/Frontend/FrontendAction.h"
-#include "llvm/ADT/OwningPtr.h"
+#include 
 
 namespace clang {
 namespace arcmt {
 
 class CheckAction : public WrapperFrontendAction {
 protected:
-  virtual bool BeginInvocation(CompilerInstance &CI);
+  bool BeginInvocation(CompilerInstance &CI) override;
 
 public:
   CheckAction(FrontendAction *WrappedAction);
@@ -27,7 +27,7 @@ class CheckAction : public WrapperFrontendAction {
 
 class ModifyAction : public WrapperFrontendAction {
 protected:
-  virtual bool BeginInvocation(CompilerInstance &CI);
+  bool BeginInvocation(CompilerInstance &CI) override;
 
 public:
   ModifyAction(FrontendAction *WrappedAction);
@@ -36,9 +36,9 @@ class ModifyAction : public WrapperFrontendAction {
 class MigrateSourceAction : public ASTFrontendAction {
   FileRemapper Remapper;
 protected:
-  virtual bool BeginInvocation(CompilerInstance &CI);
-  virtual ASTConsumer *CreateASTConsumer(CompilerInstance &CI,
-                                         StringRef InFile);
+  bool BeginInvocation(CompilerInstance &CI) override;
+  ASTConsumer *CreateASTConsumer(CompilerInstance &CI,
+                                 StringRef InFile) override;
 };
 
 class MigrateAction : public WrapperFrontendAction {
@@ -46,7 +46,7 @@ class MigrateAction : public WrapperFrontendAction {
   std::string PlistOut;
   bool EmitPremigrationARCErros;
 protected:
-  virtual bool BeginInvocation(CompilerInstance &CI);
+  bool BeginInvocation(CompilerInstance &CI) override;
 
 public:
   MigrateAction(FrontendAction *WrappedAction, StringRef migrateDir,
@@ -65,8 +65,9 @@ class ObjCMigrateAction : public WrapperFrontendAction {
                     unsigned migrateAction);
 
 protected:
-  virtual ASTConsumer *CreateASTConsumer(CompilerInstance &CI,StringRef InFile);
-  virtual bool BeginInvocation(CompilerInstance &CI);
+  ASTConsumer *CreateASTConsumer(CompilerInstance &CI,
+                                 StringRef InFile) override;
+  bool BeginInvocation(CompilerInstance &CI) override;
 };
 
 }
diff --git a/include/clang/ARCMigrate/FileRemapper.h b/include/clang/ARCMigrate/FileRemapper.h
index f7677cc8620..e094301ae6c 100644
--- a/include/clang/ARCMigrate/FileRemapper.h
+++ b/include/clang/ARCMigrate/FileRemapper.h
@@ -12,9 +12,9 @@
 
 #include "clang/Basic/LLVM.h"
 #include "llvm/ADT/DenseMap.h"
-#include "llvm/ADT/OwningPtr.h"
 #include "llvm/ADT/PointerUnion.h"
 #include "llvm/ADT/StringRef.h"
+#include 
 
 namespace llvm {
   class MemoryBuffer;
@@ -30,7 +30,7 @@ namespace arcmt {
 
 class FileRemapper {
   // FIXME: Reuse the same FileManager for multiple ASTContexts.
-  OwningPtr FileMgr;
+  std::unique_ptr FileMgr;
 
   typedef llvm::PointerUnion Target;
   typedef llvm::DenseMap MappingsTy;
@@ -56,8 +56,6 @@ class FileRemapper {
 
   void applyMappings(PreprocessorOptions &PPOpts) const;
 
-  void transferMappingsAndClear(PreprocessorOptions &PPOpts);
-
   void clear(StringRef outputDir = StringRef());
 
 private:
diff --git a/include/clang/AST/APValue.h b/include/clang/AST/APValue.h
index b4fd2affa65..e58c21923f5 100644
--- a/include/clang/AST/APValue.h
+++ b/include/clang/AST/APValue.h
@@ -80,7 +80,7 @@ class APValue {
   struct Vec {
     APValue *Elts;
     unsigned NumElts;
-    Vec() : Elts(0), NumElts(0) {}
+    Vec() : Elts(nullptr), NumElts(0) {}
     ~Vec() { delete[] Elts; }
   };
   struct Arr {
@@ -108,34 +108,33 @@ class APValue {
   };
   struct MemberPointerData;
 
-  enum {
-    MaxSize = (sizeof(ComplexAPSInt) > sizeof(ComplexAPFloat) ?
-               sizeof(ComplexAPSInt) : sizeof(ComplexAPFloat))
-  };
+  // We ensure elsewhere that Data is big enough for LV and MemberPointerData.
+  typedef llvm::AlignedCharArrayUnion DataType;
+  static const size_t DataSize = sizeof(DataType);
 
-  union {
-    void *Aligner;
-    char Data[MaxSize];
-  };
+  DataType Data;
 
 public:
   APValue() : Kind(Uninitialized) {}
-  explicit APValue(const APSInt &I) : Kind(Uninitialized) {
-    MakeInt(); setInt(I);
+  explicit APValue(APSInt I) : Kind(Uninitialized) {
+    MakeInt(); setInt(std::move(I));
   }
-  explicit APValue(const APFloat &F) : Kind(Uninitialized) {
-    MakeFloat(); setFloat(F);
+  explicit APValue(APFloat F) : Kind(Uninitialized) {
+    MakeFloat(); setFloat(std::move(F));
   }
   explicit APValue(const APValue *E, unsigned N) : Kind(Uninitialized) {
     MakeVector(); setVector(E, N);
   }
-  APValue(const APSInt &R, const APSInt &I) : Kind(Uninitialized) {
-    MakeComplexInt(); setComplexInt(R, I);
+  APValue(APSInt R, APSInt I) : Kind(Uninitialized) {
+    MakeComplexInt(); setComplexInt(std::move(R), std::move(I));
   }
-  APValue(const APFloat &R, const APFloat &I) : Kind(Uninitialized) {
-    MakeComplexFloat(); setComplexFloat(R, I);
+  APValue(APFloat R, APFloat I) : Kind(Uninitialized) {
+    MakeComplexFloat(); setComplexFloat(std::move(R), std::move(I));
   }
   APValue(const APValue &RHS);
+  APValue(APValue &&RHS) : Kind(Uninitialized) { swap(RHS); }
   APValue(LValueBase B, const CharUnits &O, NoLValuePath N, unsigned CallIndex)
       : Kind(Uninitialized) {
     MakeLValue(); setLValue(B, O, N, CallIndex);
@@ -200,7 +199,7 @@ class APValue {
 
   APSInt &getInt() {
     assert(isInt() && "Invalid accessor");
-    return *(APSInt*)(char*)Data;
+    return *(APSInt*)(char*)Data.buffer;
   }
   const APSInt &getInt() const {
     return const_cast(this)->getInt();
@@ -208,7 +207,7 @@ class APValue {
 
   APFloat &getFloat() {
     assert(isFloat() && "Invalid accessor");
-    return *(APFloat*)(char*)Data;
+    return *(APFloat*)(char*)Data.buffer;
   }
   const APFloat &getFloat() const {
     return const_cast(this)->getFloat();
@@ -216,7 +215,7 @@ class APValue {
 
   APSInt &getComplexIntReal() {
     assert(isComplexInt() && "Invalid accessor");
-    return ((ComplexAPSInt*)(char*)Data)->Real;
+    return ((ComplexAPSInt*)(char*)Data.buffer)->Real;
   }
   const APSInt &getComplexIntReal() const {
     return const_cast(this)->getComplexIntReal();
@@ -224,7 +223,7 @@ class APValue {
 
   APSInt &getComplexIntImag() {
     assert(isComplexInt() && "Invalid accessor");
-    return ((ComplexAPSInt*)(char*)Data)->Imag;
+    return ((ComplexAPSInt*)(char*)Data.buffer)->Imag;
   }
   const APSInt &getComplexIntImag() const {
     return const_cast(this)->getComplexIntImag();
@@ -232,7 +231,7 @@ class APValue {
 
   APFloat &getComplexFloatReal() {
     assert(isComplexFloat() && "Invalid accessor");
-    return ((ComplexAPFloat*)(char*)Data)->Real;
+    return ((ComplexAPFloat*)(char*)Data.buffer)->Real;
   }
   const APFloat &getComplexFloatReal() const {
     return const_cast(this)->getComplexFloatReal();
@@ -240,7 +239,7 @@ class APValue {
 
   APFloat &getComplexFloatImag() {
     assert(isComplexFloat() && "Invalid accessor");
-    return ((ComplexAPFloat*)(char*)Data)->Imag;
+    return ((ComplexAPFloat*)(char*)Data.buffer)->Imag;
   }
   const APFloat &getComplexFloatImag() const {
     return const_cast(this)->getComplexFloatImag();
@@ -259,20 +258,20 @@ class APValue {
   APValue &getVectorElt(unsigned I) {
     assert(isVector() && "Invalid accessor");
     assert(I < getVectorLength() && "Index out of range");
-    return ((Vec*)(char*)Data)->Elts[I];
+    return ((Vec*)(char*)Data.buffer)->Elts[I];
   }
   const APValue &getVectorElt(unsigned I) const {
     return const_cast(this)->getVectorElt(I);
   }
   unsigned getVectorLength() const {
     assert(isVector() && "Invalid accessor");
-    return ((const Vec*)(const void *)Data)->NumElts;
+    return ((const Vec*)(const void *)Data.buffer)->NumElts;
   }
 
   APValue &getArrayInitializedElt(unsigned I) {
     assert(isArray() && "Invalid accessor");
     assert(I < getArrayInitializedElts() && "Index out of range");
-    return ((Arr*)(char*)Data)->Elts[I];
+    return ((Arr*)(char*)Data.buffer)->Elts[I];
   }
   const APValue &getArrayInitializedElt(unsigned I) const {
     return const_cast(this)->getArrayInitializedElt(I);
@@ -283,35 +282,35 @@ class APValue {
   APValue &getArrayFiller() {
     assert(isArray() && "Invalid accessor");
     assert(hasArrayFiller() && "No array filler");
-    return ((Arr*)(char*)Data)->Elts[getArrayInitializedElts()];
+    return ((Arr*)(char*)Data.buffer)->Elts[getArrayInitializedElts()];
   }
   const APValue &getArrayFiller() const {
     return const_cast(this)->getArrayFiller();
   }
   unsigned getArrayInitializedElts() const {
     assert(isArray() && "Invalid accessor");
-    return ((const Arr*)(const void *)Data)->NumElts;
+    return ((const Arr*)(const void *)Data.buffer)->NumElts;
   }
   unsigned getArraySize() const {
     assert(isArray() && "Invalid accessor");
-    return ((const Arr*)(const void *)Data)->ArrSize;
+    return ((const Arr*)(const void *)Data.buffer)->ArrSize;
   }
 
   unsigned getStructNumBases() const {
     assert(isStruct() && "Invalid accessor");
-    return ((const StructData*)(const char*)Data)->NumBases;
+    return ((const StructData*)(const char*)Data.buffer)->NumBases;
   }
   unsigned getStructNumFields() const {
     assert(isStruct() && "Invalid accessor");
-    return ((const StructData*)(const char*)Data)->NumFields;
+    return ((const StructData*)(const char*)Data.buffer)->NumFields;
   }
   APValue &getStructBase(unsigned i) {
     assert(isStruct() && "Invalid accessor");
-    return ((StructData*)(char*)Data)->Elts[i];
+    return ((StructData*)(char*)Data.buffer)->Elts[i];
   }
   APValue &getStructField(unsigned i) {
     assert(isStruct() && "Invalid accessor");
-    return ((StructData*)(char*)Data)->Elts[getStructNumBases() + i];
+    return ((StructData*)(char*)Data.buffer)->Elts[getStructNumBases() + i];
   }
   const APValue &getStructBase(unsigned i) const {
     return const_cast(this)->getStructBase(i);
@@ -322,11 +321,11 @@ class APValue {
 
   const FieldDecl *getUnionField() const {
     assert(isUnion() && "Invalid accessor");
-    return ((const UnionData*)(const char*)Data)->Field;
+    return ((const UnionData*)(const char*)Data.buffer)->Field;
   }
   APValue &getUnionValue() {
     assert(isUnion() && "Invalid accessor");
-    return *((UnionData*)(char*)Data)->Value;
+    return *((UnionData*)(char*)Data.buffer)->Value;
   }
   const APValue &getUnionValue() const {
     return const_cast(this)->getUnionValue();
@@ -338,41 +337,41 @@ class APValue {
 
   const AddrLabelExpr* getAddrLabelDiffLHS() const {
     assert(isAddrLabelDiff() && "Invalid accessor");
-    return ((const AddrLabelDiffData*)(const char*)Data)->LHSExpr;
+    return ((const AddrLabelDiffData*)(const char*)Data.buffer)->LHSExpr;
   }
   const AddrLabelExpr* getAddrLabelDiffRHS() const {
     assert(isAddrLabelDiff() && "Invalid accessor");
-    return ((const AddrLabelDiffData*)(const char*)Data)->RHSExpr;
+    return ((const AddrLabelDiffData*)(const char*)Data.buffer)->RHSExpr;
   }
 
-  void setInt(const APSInt &I) {
+  void setInt(APSInt I) {
     assert(isInt() && "Invalid accessor");
-    *(APSInt*)(char*)Data = I;
+    *(APSInt *)(char *)Data.buffer = std::move(I);
   }
-  void setFloat(const APFloat &F) {
+  void setFloat(APFloat F) {
     assert(isFloat() && "Invalid accessor");
-    *(APFloat*)(char*)Data = F;
+    *(APFloat *)(char *)Data.buffer = std::move(F);
   }
   void setVector(const APValue *E, unsigned N) {
     assert(isVector() && "Invalid accessor");
-    ((Vec*)(char*)Data)->Elts = new APValue[N];
-    ((Vec*)(char*)Data)->NumElts = N;
+    ((Vec*)(char*)Data.buffer)->Elts = new APValue[N];
+    ((Vec*)(char*)Data.buffer)->NumElts = N;
     for (unsigned i = 0; i != N; ++i)
-      ((Vec*)(char*)Data)->Elts[i] = E[i];
+      ((Vec*)(char*)Data.buffer)->Elts[i] = E[i];
   }
-  void setComplexInt(const APSInt &R, const APSInt &I) {
+  void setComplexInt(APSInt R, APSInt I) {
     assert(R.getBitWidth() == I.getBitWidth() &&
            "Invalid complex int (type mismatch).");
     assert(isComplexInt() && "Invalid accessor");
-    ((ComplexAPSInt*)(char*)Data)->Real = R;
-    ((ComplexAPSInt*)(char*)Data)->Imag = I;
+    ((ComplexAPSInt *)(char *)Data.buffer)->Real = std::move(R);
+    ((ComplexAPSInt *)(char *)Data.buffer)->Imag = std::move(I);
   }
-  void setComplexFloat(const APFloat &R, const APFloat &I) {
+  void setComplexFloat(APFloat R, APFloat I) {
     assert(&R.getSemantics() == &I.getSemantics() &&
            "Invalid complex float (type mismatch).");
     assert(isComplexFloat() && "Invalid accessor");
-    ((ComplexAPFloat*)(char*)Data)->Real = R;
-    ((ComplexAPFloat*)(char*)Data)->Imag = I;
+    ((ComplexAPFloat *)(char *)Data.buffer)->Real = std::move(R);
+    ((ComplexAPFloat *)(char *)Data.buffer)->Imag = std::move(I);
   }
   void setLValue(LValueBase B, const CharUnits &O, NoLValuePath,
                  unsigned CallIndex);
@@ -381,13 +380,13 @@ class APValue {
                  unsigned CallIndex);
   void setUnion(const FieldDecl *Field, const APValue &Value) {
     assert(isUnion() && "Invalid accessor");
-    ((UnionData*)(char*)Data)->Field = Field;
-    *((UnionData*)(char*)Data)->Value = Value;
+    ((UnionData*)(char*)Data.buffer)->Field = Field;
+    *((UnionData*)(char*)Data.buffer)->Value = Value;
   }
   void setAddrLabelDiff(const AddrLabelExpr* LHSExpr,
                         const AddrLabelExpr* RHSExpr) {
-    ((AddrLabelDiffData*)(char*)Data)->LHSExpr = LHSExpr;
-    ((AddrLabelDiffData*)(char*)Data)->RHSExpr = RHSExpr;
+    ((AddrLabelDiffData*)(char*)Data.buffer)->LHSExpr = LHSExpr;
+    ((AddrLabelDiffData*)(char*)Data.buffer)->RHSExpr = RHSExpr;
   }
 
   /// Assign by swapping from a copy of the RHS.
@@ -404,46 +403,46 @@ class APValue {
   }
   void MakeInt() {
     assert(isUninit() && "Bad state change");
-    new ((void*)Data) APSInt(1);
+    new ((void*)Data.buffer) APSInt(1);
     Kind = Int;
   }
   void MakeFloat() {
     assert(isUninit() && "Bad state change");
-    new ((void*)(char*)Data) APFloat(0.0);
+    new ((void*)(char*)Data.buffer) APFloat(0.0);
     Kind = Float;
   }
   void MakeVector() {
     assert(isUninit() && "Bad state change");
-    new ((void*)(char*)Data) Vec();
+    new ((void*)(char*)Data.buffer) Vec();
     Kind = Vector;
   }
   void MakeComplexInt() {
     assert(isUninit() && "Bad state change");
-    new ((void*)(char*)Data) ComplexAPSInt();
+    new ((void*)(char*)Data.buffer) ComplexAPSInt();
     Kind = ComplexInt;
   }
   void MakeComplexFloat() {
     assert(isUninit() && "Bad state change");
-    new ((void*)(char*)Data) ComplexAPFloat();
+    new ((void*)(char*)Data.buffer) ComplexAPFloat();
     Kind = ComplexFloat;
   }
   void MakeLValue();
   void MakeArray(unsigned InitElts, unsigned Size);
   void MakeStruct(unsigned B, unsigned M) {
     assert(isUninit() && "Bad state change");
-    new ((void*)(char*)Data) StructData(B, M);
+    new ((void*)(char*)Data.buffer) StructData(B, M);
     Kind = Struct;
   }
   void MakeUnion() {
     assert(isUninit() && "Bad state change");
-    new ((void*)(char*)Data) UnionData();
+    new ((void*)(char*)Data.buffer) UnionData();
     Kind = Union;
   }
   void MakeMemberPointer(const ValueDecl *Member, bool IsDerivedMember,
                          ArrayRef Path);
   void MakeAddrLabelDiff() {
     assert(isUninit() && "Bad state change");
-    new ((void*)(char*)Data) AddrLabelDiffData();
+    new ((void*)(char*)Data.buffer) AddrLabelDiffData();
     Kind = AddrLabelDiff;
   }
 };
diff --git a/include/clang/AST/ASTConsumer.h b/include/clang/AST/ASTConsumer.h
index 7b6fa94b204..736a10bec9b 100644
--- a/include/clang/AST/ASTConsumer.h
+++ b/include/clang/AST/ASTConsumer.h
@@ -18,10 +18,10 @@
 
 namespace clang {
   class ASTContext;
+  class CXXMethodDecl;
   class CXXRecordDecl;
   class Decl;
   class DeclGroupRef;
-  class HandleTagDeclDefinition;
   class ASTMutationListener;
   class ASTDeserializationListener; // layering violation because void* is ugly
   class SemaConsumer; // layering violation required for safe SemaConsumer
@@ -50,13 +50,15 @@ class ASTConsumer {
   virtual void Initialize(ASTContext &Context) {}
 
   /// HandleTopLevelDecl - Handle the specified top-level declaration.  This is
-  /// called by the parser to process every top-level Decl*. Note that D can be
-  /// the head of a chain of Decls (e.g. for `int a, b` the chain will have two
-  /// elements). Use Decl::getNextDeclarator() to walk the chain.
+  /// called by the parser to process every top-level Decl*.
   ///
   /// \returns true to continue parsing, or false to abort parsing.
   virtual bool HandleTopLevelDecl(DeclGroupRef D);
 
+  /// \brief This callback is invoked each time an inline method definition is
+  /// completed.
+  virtual void HandleInlineMethodDefinition(CXXMethodDecl *D) {}
+
   /// HandleInterestingDecl - Handle the specified interesting declaration. This
   /// is called by the AST reader when deserializing things that might interest
   /// the consumer. The default implementation forwards to HandleTopLevelDecl.
@@ -136,12 +138,12 @@ class ASTConsumer {
   /// \brief If the consumer is interested in entities getting modified after
   /// their initial creation, it should return a pointer to
   /// an ASTMutationListener here.
-  virtual ASTMutationListener *GetASTMutationListener() { return 0; }
+  virtual ASTMutationListener *GetASTMutationListener() { return nullptr; }
 
   /// \brief If the consumer is interested in entities being deserialized from
   /// AST files, it should return a pointer to a ASTDeserializationListener here
   virtual ASTDeserializationListener *GetASTDeserializationListener() {
-    return 0;
+    return nullptr;
   }
 
   /// PrintStats - If desired, print any statistics.
diff --git a/include/clang/AST/ASTContext.h b/include/clang/AST/ASTContext.h
index f420e85ee14..8134f6b080b 100644
--- a/include/clang/AST/ASTContext.h
+++ b/include/clang/AST/ASTContext.h
@@ -19,6 +19,7 @@
 #include "clang/AST/CanonicalType.h"
 #include "clang/AST/CommentCommandTraits.h"
 #include "clang/AST/Decl.h"
+#include "clang/AST/ExternalASTSource.h"
 #include "clang/AST/NestedNameSpecifier.h"
 #include "clang/AST/PrettyPrinter.h"
 #include "clang/AST/RawCommentList.h"
@@ -33,10 +34,10 @@
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/FoldingSet.h"
 #include "llvm/ADT/IntrusiveRefCntPtr.h"
-#include "llvm/ADT/OwningPtr.h"
 #include "llvm/ADT/SmallPtrSet.h"
 #include "llvm/ADT/TinyPtrVector.h"
 #include "llvm/Support/Allocator.h"
+#include 
 #include 
 
 namespace llvm {
@@ -51,7 +52,6 @@ namespace clang {
   class CharUnits;
   class DiagnosticsEngine;
   class Expr;
-  class ExternalASTSource;
   class ASTMutationListener;
   class IdentifierTable;
   class MaterializeTemporaryExpr;
@@ -66,6 +66,7 @@ namespace clang {
   class UnresolvedSetIterator;
   class UsingDecl;
   class UsingShadowDecl;
+  class VTableContextBase;
 
   namespace Builtin { class Context; }
 
@@ -82,7 +83,7 @@ class ASTContext : public RefCountedBase {
   mutable llvm::FoldingSet ExtQualNodes;
   mutable llvm::FoldingSet ComplexTypes;
   mutable llvm::FoldingSet PointerTypes;
-  mutable llvm::FoldingSet DecayedTypes;
+  mutable llvm::FoldingSet AdjustedTypes;
   mutable llvm::FoldingSet BlockPointerTypes;
   mutable llvm::FoldingSet LValueReferenceTypes;
   mutable llvm::FoldingSet RValueReferenceTypes;
@@ -364,6 +365,7 @@ class ASTContext : public RefCountedBase {
   /// \brief Side-table of mangling numbers for declarations which rarely
   /// need them (like static local vars).
   llvm::DenseMap MangleNumbers;
+  llvm::DenseMap StaticLocalNumbers;
 
   /// \brief Mapping that stores parameterIndex values for ParmVarDecls when
   /// that value exceeds the bitfield size of ParmVarDeclBits.ParameterIndex.
@@ -392,7 +394,7 @@ class ASTContext : public RefCountedBase {
   PartialDiagnostic::StorageAllocator DiagAllocator;
 
   /// \brief The current C++ ABI.
-  OwningPtr ABI;
+  std::unique_ptr ABI;
   CXXABI *createCXXABI(const TargetInfo &T);
 
   /// \brief The logical -> physical address space map.
@@ -415,14 +417,16 @@ class ASTContext : public RefCountedBase {
   SelectorTable &Selectors;
   Builtin::Context &BuiltinInfo;
   mutable DeclarationNameTable DeclarationNames;
-  OwningPtr ExternalSource;
+  IntrusiveRefCntPtr ExternalSource;
   ASTMutationListener *Listener;
 
   /// \brief Contains parents of a node.
-  typedef llvm::SmallVector ParentVector;
+  typedef llvm::SmallVector ParentVector;
 
   /// \brief Maps from a node to its parents.
-  typedef llvm::DenseMap ParentMap;
+  typedef llvm::DenseMap> ParentMap;
 
   /// \brief Returns the parents of the given node.
   ///
@@ -601,9 +605,9 @@ class ASTContext : public RefCountedBase {
   ///
   /// \param OriginalDecl if not NULL, is set to declaration AST node that had
   /// the comment, if the comment we found comes from a redeclaration.
-  const RawComment *getRawCommentForAnyRedecl(
-                                      const Decl *D,
-                                      const Decl **OriginalDecl = NULL) const;
+  const RawComment *
+  getRawCommentForAnyRedecl(const Decl *D,
+                            const Decl **OriginalDecl = nullptr) const;
 
   /// Return parsed documentation comment attached to a given declaration.
   /// Returns NULL if no comment is attached.
@@ -624,6 +628,43 @@ class ASTContext : public RefCountedBase {
 private:
   mutable comments::CommandTraits CommentCommandTraits;
 
+  /// \brief Iterator that visits import declarations.
+  class import_iterator {
+    ImportDecl *Import;
+
+  public:
+    typedef ImportDecl               *value_type;
+    typedef ImportDecl               *reference;
+    typedef ImportDecl               *pointer;
+    typedef int                       difference_type;
+    typedef std::forward_iterator_tag iterator_category;
+
+    import_iterator() : Import() {}
+    explicit import_iterator(ImportDecl *Import) : Import(Import) {}
+
+    reference operator*() const { return Import; }
+    pointer operator->() const { return Import; }
+
+    import_iterator &operator++() {
+      Import = ASTContext::getNextLocalImport(Import);
+      return *this;
+    }
+
+    import_iterator operator++(int) {
+      import_iterator Other(*this);
+      ++(*this);
+      return Other;
+    }
+
+    friend bool operator==(import_iterator X, import_iterator Y) {
+      return X.Import == Y.Import;
+    }
+
+    friend bool operator!=(import_iterator X, import_iterator Y) {
+      return X.Import != Y.Import;
+    }
+  };
+
 public:
   comments::CommandTraits &getCommentCommandTraits() const {
     return CommentCommandTraits;
@@ -710,47 +751,10 @@ class ASTContext : public RefCountedBase {
     return Import->NextLocalImport;
   }
   
-  /// \brief Iterator that visits import declarations.
-  class import_iterator {
-    ImportDecl *Import;
-    
-  public:
-    typedef ImportDecl               *value_type;
-    typedef ImportDecl               *reference;
-    typedef ImportDecl               *pointer;
-    typedef int                       difference_type;
-    typedef std::forward_iterator_tag iterator_category;
-    
-    import_iterator() : Import() { }
-    explicit import_iterator(ImportDecl *Import) : Import(Import) { }
-    
-    reference operator*() const { return Import; }
-    pointer operator->() const { return Import; }
-    
-    import_iterator &operator++() {
-      Import = ASTContext::getNextLocalImport(Import);
-      return *this;
-    }
-
-    import_iterator operator++(int) {
-      import_iterator Other(*this);
-      ++(*this);
-      return Other;
-    }
-    
-    friend bool operator==(import_iterator X, import_iterator Y) {
-      return X.Import == Y.Import;
-    }
-
-    friend bool operator!=(import_iterator X, import_iterator Y) {
-      return X.Import != Y.Import;
-    }
-  };
-  
-  import_iterator local_import_begin() const { 
-    return import_iterator(FirstLocalImport); 
+  typedef llvm::iterator_range import_range;
+  import_range local_imports() const {
+    return import_range(import_iterator(FirstLocalImport), import_iterator());
   }
-  import_iterator local_import_end() const { return import_iterator(); }
 
   Decl *getPrimaryMergedDecl(Decl *D) {
     Decl *Result = MergedDecls.lookup(D);
@@ -797,11 +801,8 @@ class ASTContext : public RefCountedBase {
   // The type is built when constructing 'BuiltinVaListDecl'.
   mutable QualType VaListTagTy;
 
-  ASTContext(LangOptions& LOpts, SourceManager &SM, const TargetInfo *t,
-             IdentifierTable &idents, SelectorTable &sels,
-             Builtin::Context &builtins,
-             unsigned size_reserve,
-             bool DelayInitialization = false);
+  ASTContext(LangOptions &LOpts, SourceManager &SM, IdentifierTable &idents,
+             SelectorTable &sels, Builtin::Context &builtins);
 
   ~ASTContext();
 
@@ -810,11 +811,13 @@ class ASTContext : public RefCountedBase {
   /// The external AST source provides the ability to load parts of
   /// the abstract syntax tree as needed from some external storage,
   /// e.g., a precompiled header.
-  void setExternalSource(OwningPtr &Source);
+  void setExternalSource(IntrusiveRefCntPtr Source);
 
   /// \brief Retrieve a pointer to the external AST source associated
   /// with this AST context, if any.
-  ExternalASTSource *getExternalSource() const { return ExternalSource.get(); }
+  ExternalASTSource *getExternalSource() const {
+    return ExternalSource.get();
+  }
 
   /// \brief Attach an AST mutation listener to the AST context.
   ///
@@ -832,6 +835,14 @@ class ASTContext : public RefCountedBase {
   void PrintStats() const;
   const SmallVectorImpl& getTypes() const { return Types; }
 
+  /// \brief Create a new implicit TU-level CXXRecordDecl or RecordDecl
+  /// declaration.
+  RecordDecl *buildImplicitRecord(StringRef Name,
+                                  RecordDecl::TagKind TK = TTK_Struct) const;
+
+  /// \brief Create a new implicit TU-level typedef declaration.
+  TypedefDecl *buildImplicitTypedef(QualType T, StringRef Name) const;
+
   /// \brief Retrieve the declaration for the 128-bit signed integer type.
   TypedefDecl *getInt128Decl() const;
 
@@ -840,7 +851,7 @@ class ASTContext : public RefCountedBase {
 
   /// \brief Retrieve the declaration for a 128-bit float stub type.
   TypeDecl *getFloat128StubType() const;
-  
+
   //===--------------------------------------------------------------------===//
   //                           Type Constructors
   //===--------------------------------------------------------------------===//
@@ -915,6 +926,14 @@ class ASTContext : public RefCountedBase {
     return CanQualType::CreateUnsafe(getPointerType((QualType) T));
   }
 
+  /// \brief Return the uniqued reference to a type adjusted from the original
+  /// type to a new type.
+  QualType getAdjustedType(QualType Orig, QualType New) const;
+  CanQualType getAdjustedType(CanQualType Orig, CanQualType New) const {
+    return CanQualType::CreateUnsafe(
+        getAdjustedType((QualType)Orig, (QualType)New));
+  }
+
   /// \brief Return the uniqued reference to the decayed version of the given
   /// type.  Can only be called on array and function types which decay to
   /// pointer types.
@@ -1041,7 +1060,7 @@ class ASTContext : public RefCountedBase {
   /// \brief Return the unique reference to the type for the specified type
   /// declaration.
   QualType getTypeDeclType(const TypeDecl *Decl,
-                           const TypeDecl *PrevDecl = 0) const {
+                           const TypeDecl *PrevDecl = nullptr) const {
     assert(Decl && "Passed null for Decl param");
     if (Decl->TypeForDecl) return QualType(Decl->TypeForDecl, 0);
 
@@ -1075,9 +1094,10 @@ class ASTContext : public RefCountedBase {
                                           const TemplateTypeParmType *Replaced,
                                             const TemplateArgument &ArgPack);
 
-  QualType getTemplateTypeParmType(unsigned Depth, unsigned Index,
-                                   bool ParameterPack,
-                                   TemplateTypeParmDecl *ParmDecl = 0) const;
+  QualType
+  getTemplateTypeParmType(unsigned Depth, unsigned Index,
+                          bool ParameterPack,
+                          TemplateTypeParmDecl *ParmDecl = nullptr) const;
 
   QualType getTemplateSpecializationType(TemplateName T,
                                          const TemplateArgument *Args,
@@ -1121,11 +1141,18 @@ class ASTContext : public RefCountedBase {
                                 Optional NumExpansions);
 
   QualType getObjCInterfaceType(const ObjCInterfaceDecl *Decl,
-                                ObjCInterfaceDecl *PrevDecl = 0) const;
+                                ObjCInterfaceDecl *PrevDecl = nullptr) const;
 
   QualType getObjCObjectType(QualType Base,
                              ObjCProtocolDecl * const *Protocols,
                              unsigned NumProtocols) const;
+  
+  bool ObjCObjectAdoptsQTypeProtocols(QualType QT, ObjCInterfaceDecl *Decl);
+  /// QIdProtocolsAdoptObjCObjectProtocols - Checks that protocols in
+  /// QT's qualified-id protocol list adopt all protocols in IDecl's list
+  /// of protocols.
+  bool QIdProtocolsAdoptObjCObjectProtocols(QualType QT,
+                                            ObjCInterfaceDecl *IDecl);
 
   /// \brief Return a ObjCObjectPointerType type for the given ObjCObjectType.
   QualType getObjCObjectPointerType(QualType OIT) const;
@@ -1344,7 +1371,11 @@ class ASTContext : public RefCountedBase {
   ///
   /// If \p Field is specified then record field names are also encoded.
   void getObjCEncodingForType(QualType T, std::string &S,
-                              const FieldDecl *Field=0) const;
+                              const FieldDecl *Field=nullptr) const;
+
+  /// \brief Emit the Objective-C property type encoding for the given
+  /// type \p T into \p S.
+  void getObjCEncodingForPropertyType(QualType T, std::string &S) const;
 
   void getLegacyIntegralTypeEncoding(QualType &t) const;
 
@@ -1382,6 +1413,10 @@ class ASTContext : public RefCountedBase {
 
   bool ProtocolCompatibleWithProtocol(ObjCProtocolDecl *lProto,
                                       ObjCProtocolDecl *rProto) const;
+  
+  ObjCPropertyImplDecl *getObjCPropertyImplDeclForPropertyDecl(
+                                                  const ObjCPropertyDecl *PD,
+                                                  const Decl *Container) const;
 
   /// \brief Return the size of type \p T for Objective-C encoding purpose,
   /// in characters.
@@ -1542,7 +1577,7 @@ class ASTContext : public RefCountedBase {
   /// arguments to the builtin that are required to be integer constant
   /// expressions.
   QualType GetBuiltinType(unsigned ID, GetBuiltinTypeError &Error,
-                          unsigned *IntegerConstantArgs = 0) const;
+                          unsigned *IntegerConstantArgs = nullptr) const;
 
 private:
   CanQualType getFromTargetType(unsigned Type) const;
@@ -1704,6 +1739,8 @@ class ASTContext : public RefCountedBase {
 
   bool isNearlyEmpty(const CXXRecordDecl *RD) const;
 
+  VTableContextBase *getVTableContext();
+
   MangleContext *createMangleContext();
   
   void DeepCollectObjCIvars(const ObjCInterfaceDecl *OI, bool leafClass,
@@ -1745,6 +1782,10 @@ class ASTContext : public RefCountedBase {
     return getCanonicalType(T1) == getCanonicalType(T2);
   }
 
+  bool hasSameType(const Type *T1, const Type *T2) const {
+    return getCanonicalType(T1) == getCanonicalType(T2);
+  }
+
   /// \brief Return this type as a completely-unqualified array type,
   /// capturing the qualifiers in \p Quals.
   ///
@@ -1994,9 +2035,9 @@ class ASTContext : public RefCountedBase {
                       bool Unqualified = false, bool BlockReturnType = false);
   QualType mergeFunctionTypes(QualType, QualType, bool OfBlockPointer=false,
                               bool Unqualified = false);
-  QualType mergeFunctionArgumentTypes(QualType, QualType,
-                                      bool OfBlockPointer=false,
-                                      bool Unqualified = false);
+  QualType mergeFunctionParameterTypes(QualType, QualType,
+                                       bool OfBlockPointer = false,
+                                       bool Unqualified = false);
   QualType mergeTransparentUnionType(QualType, QualType,
                                      bool OfBlockPointer=false,
                                      bool Unqualified = false);
@@ -2008,7 +2049,7 @@ class ASTContext : public RefCountedBase {
          const FunctionProtoType *ToFunctionType);
 
   void ResetObjCLayout(const ObjCContainerDecl *CD) {
-    ObjCLayouts[CD] = 0;
+    ObjCLayouts[CD] = nullptr;
   }
 
   //===--------------------------------------------------------------------===//
@@ -2027,14 +2068,12 @@ class ASTContext : public RefCountedBase {
   //===--------------------------------------------------------------------===//
   //                    Type Iterators.
   //===--------------------------------------------------------------------===//
+  typedef llvm::iterator_range::const_iterator>
+    type_const_range;
 
-  typedef SmallVectorImpl::iterator       type_iterator;
-  typedef SmallVectorImpl::const_iterator const_type_iterator;
-
-  type_iterator types_begin() { return Types.begin(); }
-  type_iterator types_end() { return Types.end(); }
-  const_type_iterator types_begin() const { return Types.begin(); }
-  const_type_iterator types_end() const { return Types.end(); }
+  type_const_range types() const {
+    return type_const_range(Types.begin(), Types.end());
+  }
 
   //===--------------------------------------------------------------------===//
   //                    Integer Values
@@ -2125,7 +2164,7 @@ class ASTContext : public RefCountedBase {
   /// when it is called.
   void AddDeallocation(void (*Callback)(void*), void *Data);
 
-  GVALinkage GetGVALinkageForFunction(const FunctionDecl *FD);
+  GVALinkage GetGVALinkageForFunction(const FunctionDecl *FD) const;
   GVALinkage GetGVALinkageForVariable(const VarDecl *VD);
 
   /// \brief Determines if the decl can be CodeGen'ed or deserialized from PCH
@@ -2139,6 +2178,9 @@ class ASTContext : public RefCountedBase {
   void setManglingNumber(const NamedDecl *ND, unsigned Number);
   unsigned getManglingNumber(const NamedDecl *ND) const;
 
+  void setStaticLocalNumber(const VarDecl *VD, unsigned Number);
+  unsigned getStaticLocalNumber(const VarDecl *VD) const;
+
   /// \brief Retrieve the context for computing mangling numbers in the given
   /// DeclContext.
   MangleNumberingContext &getManglingNumberContext(const DeclContext *DC);
@@ -2212,9 +2254,7 @@ class ASTContext : public RefCountedBase {
   /// \brief Initialize built-in types.
   ///
   /// This routine may only be invoked once for a given ASTContext object.
-  /// It is normally invoked by the ASTContext constructor. However, the
-  /// constructor can be asked to delay initialization, which places the burden
-  /// of calling this function on the user of that object.
+  /// It is normally invoked after ASTContext construction.
   ///
   /// \param Target The target 
   void InitBuiltinTypes(const TargetInfo &Target);
@@ -2238,17 +2278,21 @@ class ASTContext : public RefCountedBase {
   void getObjCEncodingForStructureImpl(RecordDecl *RD, std::string &S,
                                        const FieldDecl *Field,
                                        bool includeVBases = true) const;
-
+public:
   // Adds the encoding of a method parameter or return type.
   void getObjCEncodingForMethodParameter(Decl::ObjCDeclQualifier QT,
                                          QualType T, std::string& S,
                                          bool Extended) const;
 
+  /// \brief Returns true if this is an inline-initialized static data member
+  /// which is treated as a definition for MSVC compatibility.
+  bool isMSStaticDataMemberInlineDefinition(const VarDecl *VD) const;
+  
+private:
   const ASTRecordLayout &
   getObjCLayout(const ObjCInterfaceDecl *D,
                 const ObjCImplementationDecl *Impl) const;
 
-private:
   /// \brief A set of deallocations that should be performed when the
   /// ASTContext is destroyed.
   typedef llvm::SmallDenseMap >
@@ -2263,8 +2307,11 @@ class ASTContext : public RefCountedBase {
   friend class DeclContext;
   friend class DeclarationNameTable;
   void ReleaseDeclContextMaps();
+  void ReleaseParentMapEntries();
 
-  llvm::OwningPtr AllParents;
+  std::unique_ptr AllParents;
+
+  std::unique_ptr VTContext;
 };
 
 /// \brief Utility function for constructing a nullary selector.
@@ -2363,4 +2410,18 @@ inline void operator delete[](void *Ptr, const clang::ASTContext &C, size_t) {
   C.Deallocate(Ptr);
 }
 
+/// \brief Create the representation of a LazyGenerationalUpdatePtr.
+template 
+typename clang::LazyGenerationalUpdatePtr::ValueType
+    clang::LazyGenerationalUpdatePtr::makeValue(
+        const clang::ASTContext &Ctx, T Value) {
+  // Note, this is implemented here so that ExternalASTSource.h doesn't need to
+  // include ASTContext.h. We explicitly instantiate it for all relevant types
+  // in ASTContext.cpp.
+  if (auto *Source = Ctx.getExternalSource())
+    return new (Ctx) LazyData(Source, Value);
+  return Value;
+}
+
 #endif
diff --git a/include/clang/AST/ASTDiagnostic.h b/include/clang/AST/ASTDiagnostic.h
index 1635511984d..484ca4cb863 100644
--- a/include/clang/AST/ASTDiagnostic.h
+++ b/include/clang/AST/ASTDiagnostic.h
@@ -36,12 +36,9 @@ namespace clang {
   void FormatASTNodeDiagnosticArgument(
       DiagnosticsEngine::ArgumentKind Kind,
       intptr_t Val,
-      const char *Modifier,
-      unsigned ModLen,
-      const char *Argument,
-      unsigned ArgLen,
-      const DiagnosticsEngine::ArgumentValue *PrevArgs,
-      unsigned NumPrevArgs,
+      StringRef Modifier,
+      StringRef Argument,
+      ArrayRef PrevArgs,
       SmallVectorImpl &Output,
       void *Cookie,
       ArrayRef QualTypeVals);
diff --git a/include/clang/AST/ASTImporter.h b/include/clang/AST/ASTImporter.h
index b74c8ee1bf4..a335f980e6c 100644
--- a/include/clang/AST/ASTImporter.h
+++ b/include/clang/AST/ASTImporter.h
@@ -278,7 +278,7 @@ namespace clang {
     /// happens especially for anonymous structs.  If the original of the second
     /// RecordDecl can be found, we can complete it without the need for
     /// importation, eliminating this loop.
-    virtual Decl *GetOriginalDecl(Decl *To) { return NULL; }
+    virtual Decl *GetOriginalDecl(Decl *To) { return nullptr; }
     
     /// \brief Determine whether the given types are structurally
     /// equivalent.
diff --git a/include/clang/AST/ASTLambda.h b/include/clang/AST/ASTLambda.h
index 358ac7131e4..9af016b13d4 100644
--- a/include/clang/AST/ASTLambda.h
+++ b/include/clang/AST/ASTLambda.h
@@ -36,9 +36,9 @@ inline bool isLambdaCallOperator(const DeclContext *DC) {
   return isLambdaCallOperator(cast(DC));
 }
 
-inline bool isGenericLambdaCallOperatorSpecialization(CXXMethodDecl *MD) {
+inline bool isGenericLambdaCallOperatorSpecialization(const CXXMethodDecl *MD) {
   if (!MD) return false;
-  CXXRecordDecl *LambdaClass = MD->getParent();
+  const CXXRecordDecl *LambdaClass = MD->getParent();
   if (LambdaClass && LambdaClass->isGenericLambda())
     return isLambdaCallOperator(MD) && 
                     MD->isFunctionTemplateSpecialization();
diff --git a/include/clang/AST/ASTMutationListener.h b/include/clang/AST/ASTMutationListener.h
index 6d12a92c61b..a89bfed53fb 100644
--- a/include/clang/AST/ASTMutationListener.h
+++ b/include/clang/AST/ASTMutationListener.h
@@ -65,6 +65,10 @@ class ASTMutationListener {
   virtual void AddedCXXTemplateSpecialization(const FunctionTemplateDecl *TD,
                                               const FunctionDecl *D) {}
 
+  /// \brief A function's exception specification has been evaluated or
+  /// instantiated.
+  virtual void ResolvedExceptionSpec(const FunctionDecl *FD) {}
+
   /// \brief A function's return type has been deduced.
   virtual void DeducedReturnType(const FunctionDecl *FD, QualType ReturnType);
 
@@ -74,6 +78,9 @@ class ASTMutationListener {
   /// \brief A static data member was implicitly instantiated.
   virtual void StaticDataMemberInstantiated(const VarDecl *D) {}
 
+  /// \brief A function template's definition was instantiated.
+  virtual void FunctionDefinitionInstantiated(const FunctionDecl *D) {}
+
   /// \brief A new objc category class was added for an interface.
   virtual void AddedObjCCategoryToInterface(const ObjCCategoryDecl *CatD,
                                             const ObjCInterfaceDecl *IFD) {}
diff --git a/include/clang/AST/ASTTypeTraits.h b/include/clang/AST/ASTTypeTraits.h
index 087ad560900..0e06e26e6d8 100644
--- a/include/clang/AST/ASTTypeTraits.h
+++ b/include/clang/AST/ASTTypeTraits.h
@@ -57,11 +57,18 @@ class ASTNodeKind {
   bool isSame(ASTNodeKind Other) const;
 
   /// \brief Returns \c true if \c this is a base kind of (or same as) \c Other.
-  bool isBaseOf(ASTNodeKind Other) const;
+  /// \param Distance If non-null, used to return the distance between \c this
+  /// and \c Other in the class hierarchy.
+  bool isBaseOf(ASTNodeKind Other, unsigned *Distance = nullptr) const;
 
   /// \brief String representation of the kind.
   StringRef asStringRef() const;
 
+  /// \brief Strict weak ordering for ASTNodeKind.
+  bool operator<(const ASTNodeKind &Other) const {
+    return KindId < Other.KindId;
+  }
+
 private:
   /// \brief Kind ids.
   ///
@@ -91,7 +98,9 @@ class ASTNodeKind {
 
   /// \brief Returns \c true if \c Base is a base kind of (or same as) \c
   ///   Derived.
-  static bool isBaseOf(NodeKindId Base, NodeKindId Derived);
+  /// \param Distance If non-null, used to return the distance between \c Base
+  /// and \c Derived in the class hierarchy.
+  static bool isBaseOf(NodeKindId Base, NodeKindId Derived, unsigned *Distance);
 
   /// \brief Helper meta-function to convert a kind T to its enum value.
   ///
@@ -133,6 +142,11 @@ KIND_TO_KIND_ID(Type)
 #include "clang/AST/TypeNodes.def"
 #undef KIND_TO_KIND_ID
 
+inline raw_ostream &operator<<(raw_ostream &OS, ASTNodeKind K) {
+  OS << K.asStringRef();
+  return OS;
+}
+
 /// \brief A dynamically typed AST node container.
 ///
 /// Stores an AST node in a type safe way. This allows writing code that
@@ -198,8 +212,8 @@ class DynTypedNode {
     return getMemoizationData() < Other.getMemoizationData();
   }
   bool operator==(const DynTypedNode &Other) const {
-    // Nodes with different types cannot be equal.
-    if (!NodeKind.isSame(Other.NodeKind))
+    if (!NodeKind.isBaseOf(Other.NodeKind) &&
+        !Other.NodeKind.isBaseOf(NodeKind))
       return false;
 
     // FIXME: Implement for other types.
@@ -223,7 +237,7 @@ class DynTypedNode {
     static const T *get(ASTNodeKind NodeKind, const char Storage[]) {
       if (ASTNodeKind::getFromNodeKind().isBaseOf(NodeKind))
         return dyn_cast(*reinterpret_cast(Storage));
-      return NULL;
+      return nullptr;
     }
     static DynTypedNode create(const BaseT &Node) {
       DynTypedNode Result;
@@ -238,7 +252,7 @@ class DynTypedNode {
     static const T *get(ASTNodeKind NodeKind, const char Storage[]) {
       if (ASTNodeKind::getFromNodeKind().isSame(NodeKind))
         return *reinterpret_cast(Storage);
-      return NULL;
+      return nullptr;
     }
     static DynTypedNode create(const T &Node) {
       DynTypedNode Result;
@@ -253,7 +267,7 @@ class DynTypedNode {
     static const T *get(ASTNodeKind NodeKind, const char Storage[]) {
       if (ASTNodeKind::getFromNodeKind().isSame(NodeKind))
         return reinterpret_cast(Storage);
-      return NULL;
+      return nullptr;
     }
     static DynTypedNode create(const T &Node) {
       DynTypedNode Result;
@@ -283,18 +297,18 @@ class DynTypedNode {
 
 template 
 struct DynTypedNode::BaseConverter<
-    T, typename llvm::enable_if >::type> : public DynCastPtrConverter {};
+    T, typename std::enable_if::value>::type>
+    : public DynCastPtrConverter {};
 
 template 
 struct DynTypedNode::BaseConverter<
-    T, typename llvm::enable_if >::type> : public DynCastPtrConverter {};
+    T, typename std::enable_if::value>::type>
+    : public DynCastPtrConverter {};
 
 template 
 struct DynTypedNode::BaseConverter<
-    T, typename llvm::enable_if >::type> : public DynCastPtrConverter {};
+    T, typename std::enable_if::value>::type>
+    : public DynCastPtrConverter {};
 
 template <>
 struct DynTypedNode::BaseConverter<
@@ -341,7 +355,7 @@ inline const void *DynTypedNode::getMemoizationData() const {
   } else if (ASTNodeKind::getFromNodeKind().isBaseOf(NodeKind)) {
     return BaseConverter::get(NodeKind, Storage.buffer);
   }
-  return NULL;
+  return nullptr;
 }
 
 } // end namespace ast_type_traits
diff --git a/include/clang/AST/ASTUnresolvedSet.h b/include/clang/AST/ASTUnresolvedSet.h
index e8be67006c5..84b0842492a 100644
--- a/include/clang/AST/ASTUnresolvedSet.h
+++ b/include/clang/AST/ASTUnresolvedSet.h
@@ -32,9 +32,6 @@ class ASTUnresolvedSet {
 
   DeclsTy Decls;
 
-  ASTUnresolvedSet(const ASTUnresolvedSet &) LLVM_DELETED_FUNCTION;
-  void operator=(const ASTUnresolvedSet &) LLVM_DELETED_FUNCTION;
-
   friend class LazyASTUnresolvedSet;
 
 public:
diff --git a/include/clang/AST/ASTVector.h b/include/clang/AST/ASTVector.h
index 6db918eaa63..d92167e9599 100644
--- a/include/clang/AST/ASTVector.h
+++ b/include/clang/AST/ASTVector.h
@@ -26,30 +26,6 @@
 #include 
 #include 
 
-#ifdef _MSC_VER
-namespace std {
-#if _MSC_VER <= 1310
-  // Work around flawed VC++ implementation of std::uninitialized_copy.  Define
-  // additional overloads so that elements with pointer types are recognized as
-  // scalars and not objects, causing bizarre type conversion errors.
-  template
-  inline _Scalar_ptr_iterator_tag _Ptr_cat(T1 **, T2 **) {
-    _Scalar_ptr_iterator_tag _Cat;
-    return _Cat;
-  }
-
-  template
-  inline _Scalar_ptr_iterator_tag _Ptr_cat(T1* const *, T2 **) {
-    _Scalar_ptr_iterator_tag _Cat;
-    return _Cat;
-  }
-#else
-  // FIXME: It is not clear if the problem is fixed in VS 2005.  What is clear
-  // is that the above hack won't work if it wasn't fixed.
-#endif
-}
-#endif
-
 namespace clang {
   class ASTContext;
 
@@ -69,15 +45,30 @@ class ASTVector {
 
 public:
   // Default ctor - Initialize to empty.
-  ASTVector() : Begin(0), End(0), Capacity(0, false) {}
+  ASTVector() : Begin(nullptr), End(nullptr), Capacity(nullptr, false) {}
+
+  ASTVector(ASTVector &&O) : Begin(O.Begin), End(O.End), Capacity(O.Capacity) {
+    O.Begin = O.End = nullptr;
+    O.Capacity.setPointer(nullptr);
+    O.Capacity.setInt(false);
+  }
 
   ASTVector(const ASTContext &C, unsigned N)
-      : Begin(0), End(0), Capacity(0, false) {
+      : Begin(nullptr), End(nullptr), Capacity(nullptr, false) {
     reserve(C, N);
   }
 
+  ASTVector &operator=(ASTVector &&RHS) {
+    ASTVector O(std::move(RHS));
+    using std::swap;
+    swap(Begin, O.Begin);
+    swap(End, O.End);
+    swap(Capacity, O.Capacity);
+    return *this;
+  }
+
   ~ASTVector() {
-    if (llvm::is_class::value) {
+    if (std::is_class::value) {
       // Destroy the constructed elements in the vector.
       destroy_range(Begin, End);
     }
@@ -147,7 +138,7 @@ class ASTVector {
   }
 
   void clear() {
-    if (llvm::is_class::value) {
+    if (std::is_class::value) {
       destroy_range(Begin, End);
     }
     End = Begin;
@@ -392,7 +383,7 @@ void ASTVector::grow(const ASTContext &C, size_t MinSize) {
   T *NewElts = new (C, llvm::alignOf()) T[NewCapacity];
 
   // Copy the elements over.
-  if (llvm::is_class::value) {
+  if (std::is_class::value) {
     std::uninitialized_copy(Begin, End, NewElts);
     // Destroy the original elements.
     destroy_range(Begin, End);
diff --git a/include/clang/AST/Attr.h b/include/clang/AST/Attr.h
index 7dbf41350a0..fc4881619bc 100644
--- a/include/clang/AST/Attr.h
+++ b/include/clang/AST/Attr.h
@@ -26,8 +26,8 @@
 #include "llvm/ADT/StringSwitch.h"
 #include "llvm/Support/ErrorHandling.h"
 #include "llvm/Support/raw_ostream.h"
+#include 
 #include 
-#include 
 
 namespace clang {
   class ASTContext;
@@ -48,10 +48,9 @@ class Attr {
   /// An index into the spelling list of an
   /// attribute defined in Attr.td file.
   unsigned SpellingListIndex : 4;
-
   bool Inherited : 1;
-
   bool IsPackExpansion : 1;
+  bool Implicit : 1;
 
   virtual ~Attr();
 
@@ -76,7 +75,7 @@ class Attr {
 protected:
   Attr(attr::Kind AK, SourceRange R, unsigned SpellingListIndex = 0)
     : Range(R), AttrKind(AK), SpellingListIndex(SpellingListIndex),
-      Inherited(false), IsPackExpansion(false) {}
+      Inherited(false), IsPackExpansion(false), Implicit(false) {}
 
 public:
 
@@ -85,6 +84,7 @@ class Attr {
   }
   
   unsigned getSpellingListIndex() const { return SpellingListIndex; }
+  virtual const char *getSpelling() const = 0;
 
   SourceLocation getLocation() const { return Range.getBegin(); }
   SourceRange getRange() const { return Range; }
@@ -92,6 +92,11 @@ class Attr {
 
   bool isInherited() const { return Inherited; }
 
+  /// \brief Returns true if the attribute has been implicitly created instead
+  /// of explicitly written by the user.
+  bool isImplicit() const { return Implicit; }
+  void setImplicit(bool I) { Implicit = I; }
+
   void setPackExpansion(bool PE) { IsPackExpansion = PE; }
   bool isPackExpansion() const { return IsPackExpansion; }
 
@@ -103,6 +108,11 @@ class Attr {
   // Pretty print this attribute.
   virtual void printPretty(raw_ostream &OS,
                            const PrintingPolicy &Policy) const = 0;
+
+  /// \brief By default, attributes cannot be duplicated when being merged;
+  /// however, an attribute can override this. Returns true if the attribute
+  /// can be duplicated when merging.
+  virtual bool duplicatesAllowed() const { return false; }
 };
 
 class InheritableAttr : public Attr {
@@ -121,7 +131,7 @@ class InheritableAttr : public Attr {
 };
 
 class InheritableParamAttr : public InheritableAttr {
-  virtual void anchor();
+  void anchor() override;
 protected:
   InheritableParamAttr(attr::Kind AK, SourceRange R,
                        unsigned SpellingListIndex = 0)
@@ -136,23 +146,21 @@ class InheritableParamAttr : public InheritableAttr {
   }
 };
 
-class MSInheritanceAttr : public InheritableAttr {
-  virtual void anchor();
-protected:
-  MSInheritanceAttr(attr::Kind AK, SourceRange R, unsigned SpellingListIndex = 0)
-    : InheritableAttr(AK, R, SpellingListIndex) {}
-
-public:
-  // Implement isa/cast/dyncast/etc.
-  static bool classof(const Attr *A) {
-    // Relies on relative order of enum emission with respect to param attrs.
-    return (A->getKind() <= attr::LAST_MS_INHERITANCE &&
-            A->getKind() > attr::LAST_INHERITABLE_PARAM);
-  }
-};
-
 #include "clang/AST/Attrs.inc"
 
+inline const DiagnosticBuilder &operator<<(const DiagnosticBuilder &DB,
+                                           const Attr *At) {
+  DB.AddTaggedVal(reinterpret_cast(At),
+                  DiagnosticsEngine::ak_attr);
+  return DB;
+}
+
+inline const PartialDiagnostic &operator<<(const PartialDiagnostic &PD,
+                                           const Attr *At) {
+  PD.AddTaggedVal(reinterpret_cast(At),
+                  DiagnosticsEngine::ak_attr);
+  return PD;
+}
 }  // end namespace clang
 
 #endif
diff --git a/include/clang/AST/AttrIterator.h b/include/clang/AST/AttrIterator.h
index 8bd8fbec895..39ee81f1201 100644
--- a/include/clang/AST/AttrIterator.h
+++ b/include/clang/AST/AttrIterator.h
@@ -43,7 +43,7 @@ typedef SmallVector AttrVec;
 typedef SmallVector ConstAttrVec;
 
 /// specific_attr_iterator - Iterates over a subrange of an AttrVec, only
-/// providing attributes that are of a specifc type.
+/// providing attributes that are of a specific type.
 template 
 class specific_attr_iterator {
   typedef typename Container::const_iterator Iterator;
@@ -53,7 +53,7 @@ class specific_attr_iterator {
   /// specifically requested, we don't necessarily advance this all the
   /// way. Instead, we advance it when an operation is requested; if the
   /// operation is acting on what should be a past-the-end iterator,
-  /// then we offer no guarantees, but this way we do not dererence a
+  /// then we offer no guarantees, but this way we do not dereference a
   /// past-the-end iterator when we move to a past-the-end position.
   mutable Iterator Current;
 
@@ -98,7 +98,7 @@ class specific_attr_iterator {
 
   friend bool operator==(specific_attr_iterator Left,
                          specific_attr_iterator Right) {
-    assert((Left.Current == 0) == (Right.Current == 0));
+    assert((Left.Current == nullptr) == (Right.Current == nullptr));
     if (Left.Current < Right.Current)
       Left.AdvanceToNext(Right.Current); 
     else
@@ -134,7 +134,7 @@ inline SpecificAttr *getSpecificAttr(const Container& container) {
   if (i != specific_attr_end(container))
     return *i;
   else
-    return 0;
+    return nullptr;
 }
 
 }  // end namespace clang
diff --git a/include/clang/AST/CMakeLists.txt b/include/clang/AST/CMakeLists.txt
index ba54fa2aa92..260734f2200 100644
--- a/include/clang/AST/CMakeLists.txt
+++ b/include/clang/AST/CMakeLists.txt
@@ -13,6 +13,11 @@ clang_tablegen(AttrDump.inc -gen-clang-attr-dump
   SOURCE ../Basic/Attr.td
   TARGET ClangAttrDump)
 
+clang_tablegen(AttrVisitor.inc -gen-clang-attr-ast-visitor
+  -I ${CMAKE_CURRENT_SOURCE_DIR}/../../
+  SOURCE ../Basic/Attr.td
+  TARGET ClangAttrVisitor)
+
 clang_tablegen(StmtNodes.inc -gen-clang-stmt-nodes
   SOURCE ../Basic/StmtNodes.td
   TARGET ClangStmtNodes)
diff --git a/include/clang/AST/CXXInheritance.h b/include/clang/AST/CXXInheritance.h
index dbe4ad0f5a1..37f6748ace9 100644
--- a/include/clang/AST/CXXInheritance.h
+++ b/include/clang/AST/CXXInheritance.h
@@ -177,8 +177,8 @@ class CXXBasePaths {
                         bool RecordPaths = true,
                         bool DetectVirtual = true)
     : FindAmbiguities(FindAmbiguities), RecordPaths(RecordPaths),
-      DetectVirtual(DetectVirtual), DetectedVirtual(0), DeclsFound(0),
-      NumDeclsFound(0) { }
+      DetectVirtual(DetectVirtual), DetectedVirtual(nullptr),
+      DeclsFound(nullptr), NumDeclsFound(0) { }
   
   ~CXXBasePaths() { delete [] DeclsFound; }
   
@@ -190,8 +190,8 @@ class CXXBasePaths {
   CXXBasePath&       front()       { return Paths.front(); }
   const CXXBasePath& front() const { return Paths.front(); }
   
-  decl_iterator found_decls_begin();
-  decl_iterator found_decls_end();
+  typedef llvm::iterator_range decl_range;
+  decl_range found_decls();
   
   /// \brief Determine whether the path from the most-derived type to the
   /// given base type is ambiguous (i.e., it refers to multiple subobjects of
@@ -232,7 +232,8 @@ class CXXBasePaths {
 /// \brief Uniquely identifies a virtual method within a class
 /// hierarchy by the method itself and a class subobject number.
 struct UniqueVirtualMethod {
-  UniqueVirtualMethod() : Method(0), Subobject(0), InVirtualSubobject(0) { }
+  UniqueVirtualMethod()
+    : Method(nullptr), Subobject(0), InVirtualSubobject(nullptr) { }
 
   UniqueVirtualMethod(CXXMethodDecl *Method, unsigned Subobject,
                       const CXXRecordDecl *InVirtualSubobject)
diff --git a/include/clang/AST/CanonicalType.h b/include/clang/AST/CanonicalType.h
index 9c699b7e0ae..7cccef69ddf 100644
--- a/include/clang/AST/CanonicalType.h
+++ b/include/clang/AST/CanonicalType.h
@@ -17,7 +17,6 @@
 
 #include "clang/AST/Type.h"
 #include "llvm/Support/Casting.h"
-#include "llvm/Support/type_traits.h"
 #include 
 
 namespace clang {
@@ -60,9 +59,9 @@ class CanQual {
 
   /// \brief Converting constructor that permits implicit upcasting of
   /// canonical type pointers.
-  template
-  CanQual(const CanQual& Other,
-          typename llvm::enable_if, int>::type = 0);
+  template 
+  CanQual(const CanQual &Other,
+          typename std::enable_if::value, int>::type = 0);
 
   /// \brief Retrieve the underlying type pointer, which refers to a
   /// canonical type.
@@ -541,39 +540,39 @@ struct CanProxyAdaptor : public CanProxyBase {
 
 template<>
 struct CanProxyAdaptor : public CanProxyBase {
-  LLVM_CLANG_CANPROXY_TYPE_ACCESSOR(getResultType)
+  LLVM_CLANG_CANPROXY_TYPE_ACCESSOR(getReturnType)
   LLVM_CLANG_CANPROXY_SIMPLE_ACCESSOR(FunctionType::ExtInfo, getExtInfo)
 };
 
 template<>
 struct CanProxyAdaptor
   : public CanProxyBase {
-  LLVM_CLANG_CANPROXY_TYPE_ACCESSOR(getResultType)
+  LLVM_CLANG_CANPROXY_TYPE_ACCESSOR(getReturnType)
   LLVM_CLANG_CANPROXY_SIMPLE_ACCESSOR(FunctionType::ExtInfo, getExtInfo)
 };
 
 template<>
 struct CanProxyAdaptor
   : public CanProxyBase {
-  LLVM_CLANG_CANPROXY_TYPE_ACCESSOR(getResultType)
+  LLVM_CLANG_CANPROXY_TYPE_ACCESSOR(getReturnType)
   LLVM_CLANG_CANPROXY_SIMPLE_ACCESSOR(FunctionType::ExtInfo, getExtInfo)
-  LLVM_CLANG_CANPROXY_SIMPLE_ACCESSOR(unsigned, getNumArgs)
-  CanQualType getArgType(unsigned i) const {
-    return CanQualType::CreateUnsafe(this->getTypePtr()->getArgType(i));
+  LLVM_CLANG_CANPROXY_SIMPLE_ACCESSOR(unsigned, getNumParams)
+  CanQualType getParamType(unsigned i) const {
+    return CanQualType::CreateUnsafe(this->getTypePtr()->getParamType(i));
   }
 
   LLVM_CLANG_CANPROXY_SIMPLE_ACCESSOR(bool, isVariadic)
   LLVM_CLANG_CANPROXY_SIMPLE_ACCESSOR(unsigned, getTypeQuals)
 
-  typedef CanTypeIterator
-    arg_type_iterator;
+  typedef CanTypeIterator
+  param_type_iterator;
 
-  arg_type_iterator arg_type_begin() const {
-    return arg_type_iterator(this->getTypePtr()->arg_type_begin());
+  param_type_iterator param_type_begin() const {
+    return param_type_iterator(this->getTypePtr()->param_type_begin());
   }
 
-  arg_type_iterator arg_type_end() const {
-    return arg_type_iterator(this->getTypePtr()->arg_type_end());
+  param_type_iterator param_type_end() const {
+    return param_type_iterator(this->getTypePtr()->param_type_end());
   }
 
   // Note: canonical function types never have exception specifications
diff --git a/include/clang/AST/CharUnits.h b/include/clang/AST/CharUnits.h
index 09ff6828ef5..72ca9f5cd67 100644
--- a/include/clang/AST/CharUnits.h
+++ b/include/clang/AST/CharUnits.h
@@ -165,7 +165,7 @@ namespace clang {
       /// RoundUpToAlignment - Returns the next integer (mod 2**64) that is
       /// greater than or equal to this quantity and is a multiple of \p Align.
       /// Align must be non-zero.
-      CharUnits RoundUpToAlignment(const CharUnits &Align) {
+      CharUnits RoundUpToAlignment(const CharUnits &Align) const {
         return CharUnits(llvm::RoundUpToAlignment(Quantity, 
                                                   Align.Quantity));
       }
@@ -173,12 +173,7 @@ namespace clang {
       /// Given that this is a non-zero alignment value, what is the
       /// alignment at the given offset?
       CharUnits alignmentAtOffset(CharUnits offset) {
-        // alignment: 0010000
-        // offset:    1011100
-        // lowBits:   0001011
-        // result:    0000100
-        QuantityType lowBits = (Quantity-1) & (offset.Quantity-1);
-        return CharUnits((lowBits + 1) & ~lowBits);
+        return CharUnits(llvm::MinAlign(Quantity, offset.Quantity));
       }
 
 
diff --git a/include/clang/AST/Comment.h b/include/clang/AST/Comment.h
index 28849f58a8e..e18fe9ab86a 100644
--- a/include/clang/AST/Comment.h
+++ b/include/clang/AST/Comment.h
@@ -100,16 +100,26 @@ class Comment {
   };
   enum { NumInlineCommandCommentBits = NumInlineContentCommentBits + 10 };
 
+  class HTMLTagCommentBitfields {
+    friend class HTMLTagComment;
+
+    unsigned : NumInlineContentCommentBits;
+
+    /// True if we found that this tag is malformed in some way.
+    unsigned IsMalformed : 1;
+  };
+  enum { NumHTMLTagCommentBits = NumInlineContentCommentBits + 1 };
+
   class HTMLStartTagCommentBitfields {
     friend class HTMLStartTagComment;
 
-    unsigned : NumInlineContentCommentBits;
+    unsigned : NumHTMLTagCommentBits;
 
     /// True if this tag is self-closing (e. g., 
).  This is based on tag
     /// spelling in comment (plain 
 would not set this flag).
     unsigned IsSelfClosing : 1;
   };
-  enum { NumHTMLStartTagCommentBits = NumInlineContentCommentBits + 1 };
+  enum { NumHTMLStartTagCommentBits = NumHTMLTagCommentBits + 1 };
 
   class ParagraphCommentBitfields {
     friend class ParagraphComment;
@@ -155,6 +165,7 @@ class Comment {
     InlineContentCommentBitfields InlineContentCommentBits;
     TextCommentBitfields TextCommentBits;
     InlineCommandCommentBitfields InlineCommandCommentBits;
+    HTMLTagCommentBitfields HTMLTagCommentBits;
     HTMLStartTagCommentBitfields HTMLStartTagCommentBits;
     ParagraphCommentBitfields ParagraphCommentBits;
     BlockCommandCommentBitfields BlockCommandCommentBits;
@@ -194,9 +205,9 @@ class Comment {
 
   const char *getCommentKindName() const;
 
-  LLVM_ATTRIBUTE_USED void dump() const;
-  LLVM_ATTRIBUTE_USED void dumpColor() const;
-  LLVM_ATTRIBUTE_USED void dump(const ASTContext &Context) const;
+  void dump() const;
+  void dumpColor() const;
+  void dump(const ASTContext &Context) const;
   void dump(raw_ostream &OS, const CommandTraits *Traits,
             const SourceManager *SM) const;
 
@@ -267,9 +278,9 @@ class TextComment : public InlineContentComment {
     return C->getCommentKind() == TextCommentKind;
   }
 
-  child_iterator child_begin() const { return NULL; }
+  child_iterator child_begin() const { return nullptr; }
 
-  child_iterator child_end() const { return NULL; }
+  child_iterator child_end() const { return nullptr; }
 
   StringRef getText() const LLVM_READONLY { return Text; }
 
@@ -325,9 +336,9 @@ class InlineCommandComment : public InlineContentComment {
     return C->getCommentKind() == InlineCommandCommentKind;
   }
 
-  child_iterator child_begin() const { return NULL; }
+  child_iterator child_begin() const { return nullptr; }
 
-  child_iterator child_end() const { return NULL; }
+  child_iterator child_end() const { return nullptr; }
 
   unsigned getCommandID() const {
     return InlineCommandCommentBits.CommandID;
@@ -360,8 +371,7 @@ class InlineCommandComment : public InlineContentComment {
 };
 
 /// Abstract class for opening and closing HTML tags.  HTML tags are always
-/// treated as inline content (regardless HTML semantics); opening and closing
-/// tags are not matched.
+/// treated as inline content (regardless HTML semantics).
 class HTMLTagComment : public InlineContentComment {
 protected:
   StringRef TagName;
@@ -377,6 +387,7 @@ class HTMLTagComment : public InlineContentComment {
       TagName(TagName),
       TagNameRange(TagNameBegin, TagNameEnd) {
     setLocation(TagNameBegin);
+    HTMLTagCommentBits.IsMalformed = 0;
   }
 
 public:
@@ -392,6 +403,14 @@ class HTMLTagComment : public InlineContentComment {
     return SourceRange(L.getLocWithOffset(1),
                        L.getLocWithOffset(1 + TagName.size()));
   }
+
+  bool isMalformed() const {
+    return HTMLTagCommentBits.IsMalformed;
+  }
+
+  void setIsMalformed() {
+    HTMLTagCommentBits.IsMalformed = 1;
+  }
 };
 
 /// An opening HTML tag with attributes.
@@ -450,9 +469,9 @@ class HTMLStartTagComment : public HTMLTagComment {
     return C->getCommentKind() == HTMLStartTagCommentKind;
   }
 
-  child_iterator child_begin() const { return NULL; }
+  child_iterator child_begin() const { return nullptr; }
 
-  child_iterator child_end() const { return NULL; }
+  child_iterator child_end() const { return nullptr; }
 
   unsigned getNumAttrs() const {
     return Attributes.size();
@@ -505,9 +524,9 @@ class HTMLEndTagComment : public HTMLTagComment {
     return C->getCommentKind() == HTMLEndTagCommentKind;
   }
 
-  child_iterator child_begin() const { return NULL; }
+  child_iterator child_begin() const { return nullptr; }
 
-  child_iterator child_end() const { return NULL; }
+  child_iterator child_end() const { return nullptr; }
 };
 
 /// Block content (contains inline content).
@@ -601,7 +620,7 @@ class BlockCommandComment : public BlockContentComment {
                       unsigned CommandID,
                       CommandMarkerKind CommandMarker) :
       BlockContentComment(K, LocBegin, LocEnd),
-      Paragraph(NULL) {
+      Paragraph(nullptr) {
     setLocation(getCommandNameBeginLoc());
     BlockCommandCommentBits.CommandID = CommandID;
     BlockCommandCommentBits.CommandMarker = CommandMarker;
@@ -613,7 +632,7 @@ class BlockCommandComment : public BlockContentComment {
                       unsigned CommandID,
                       CommandMarkerKind CommandMarker) :
       BlockContentComment(BlockCommandCommentKind, LocBegin, LocEnd),
-      Paragraph(NULL) {
+      Paragraph(nullptr) {
     setLocation(getCommandNameBeginLoc());
     BlockCommandCommentBits.CommandID = CommandID;
     BlockCommandCommentBits.CommandMarker = CommandMarker;
@@ -699,7 +718,7 @@ class ParamCommandComment : public BlockCommandComment {
   unsigned ParamIndex;
 
 public:
-  enum LLVM_ENUM_INT_TYPE(unsigned) {
+  enum : unsigned {
     InvalidParamIndex = ~0U,
     VarArgParamIndex = ~0U/*InvalidParamIndex*/ - 1U
   };
@@ -861,9 +880,9 @@ class VerbatimBlockLineComment : public Comment {
     return C->getCommentKind() == VerbatimBlockLineCommentKind;
   }
 
-  child_iterator child_begin() const { return NULL; }
+  child_iterator child_begin() const { return nullptr; }
 
-  child_iterator child_end() const { return NULL; }
+  child_iterator child_end() const { return nullptr; }
 
   StringRef getText() const LLVM_READONLY {
     return Text;
@@ -948,9 +967,9 @@ class VerbatimLineComment : public BlockCommandComment {
     return C->getCommentKind() == VerbatimLineCommentKind;
   }
 
-  child_iterator child_begin() const { return NULL; }
+  child_iterator child_begin() const { return nullptr; }
 
-  child_iterator child_end() const { return NULL; }
+  child_iterator child_end() const { return nullptr; }
 
   StringRef getText() const {
     return Text;
@@ -981,9 +1000,9 @@ struct DeclInfo {
   /// that we consider a "function".
   ArrayRef ParamVars;
 
-  /// Function result type if \c CommentDecl is something that we consider
+  /// Function return type if \c CommentDecl is something that we consider
   /// a "function".
-  QualType ResultType;
+  QualType ReturnType;
 
   /// Template parameters that can be referenced by \\tparam if \c CommentDecl is
   /// a template (\c IsTemplateDecl or \c IsTemplatePartialSpecialization is
diff --git a/include/clang/AST/CommentCommands.td b/include/clang/AST/CommentCommands.td
index ed323daa9f8..958ee032e71 100644
--- a/include/clang/AST/CommentCommands.td
+++ b/include/clang/AST/CommentCommands.td
@@ -146,7 +146,7 @@ def Todo       : BlockCommand<"todo">;
 def Version    : BlockCommand<"version">;
 def Warning    : BlockCommand<"warning">;
 // HeaderDoc commands
-def Abstract      : BlockCommand<"abstract">;
+def Abstract      : BlockCommand<"abstract"> { let IsBriefCommand = 1; }
 def ClassDesign   : RecordLikeDetailCommand<"classdesign">;
 def CoClass       : RecordLikeDetailCommand<"coclass">;
 def Dependency    : RecordLikeDetailCommand<"dependency">;
diff --git a/include/clang/AST/CommentHTMLTags.td b/include/clang/AST/CommentHTMLTags.td
index f98e32ddca4..25149009494 100644
--- a/include/clang/AST/CommentHTMLTags.td
+++ b/include/clang/AST/CommentHTMLTags.td
@@ -52,3 +52,16 @@ def Tr      : Tag<"tr"> { let EndTagOptional = 1; }
 def Th      : Tag<"th"> { let EndTagOptional = 1; }
 def Td      : Tag<"td"> { let EndTagOptional = 1; }
 
+// Define a blacklist of attributes that are not safe to pass through to HTML
+// output if the input is untrusted.
+//
+// FIXME: this should be a whitelist.  When changing this to a whitelist, don't
+// forget to change the default in the TableGen backend.
+class Attribute {
+  string Spelling = spelling;
+  bit IsSafeToPassThrough = 1;
+}
+class EventHandlerContentAttribute : Attribute {
+  let IsSafeToPassThrough = 0;
+}
+
diff --git a/include/clang/AST/CommentLexer.h b/include/clang/AST/CommentLexer.h
index f152c778c9a..a6e3ed89b27 100644
--- a/include/clang/AST/CommentLexer.h
+++ b/include/clang/AST/CommentLexer.h
@@ -14,8 +14,8 @@
 #ifndef LLVM_CLANG_AST_COMMENT_LEXER_H
 #define LLVM_CLANG_AST_COMMENT_LEXER_H
 
-#include "clang/Basic/SourceManager.h"
 #include "clang/Basic/Diagnostic.h"
+#include "clang/Basic/SourceManager.h"
 #include "llvm/ADT/SmallString.h"
 #include "llvm/ADT/SmallVector.h"
 #include "llvm/ADT/StringRef.h"
@@ -293,17 +293,7 @@ class Lexer {
   StringRef resolveHTMLHexCharacterReference(StringRef Name) const;
 
   void formTokenWithChars(Token &Result, const char *TokEnd,
-                          tok::TokenKind Kind) {
-    const unsigned TokLen = TokEnd - BufferPtr;
-    Result.setLocation(getSourceLocation(BufferPtr));
-    Result.setKind(Kind);
-    Result.setLength(TokLen);
-#ifndef NDEBUG
-    Result.TextPtr = "";
-    Result.IntVal = 7;
-#endif
-    BufferPtr = TokEnd;
-  }
+                          tok::TokenKind Kind);
 
   void formTextToken(Token &Result, const char *TokEnd) {
     StringRef Text(BufferPtr, TokEnd - BufferPtr);
@@ -362,7 +352,7 @@ class Lexer {
 
   StringRef getSpelling(const Token &Tok,
                         const SourceManager &SourceMgr,
-                        bool *Invalid = NULL) const;
+                        bool *Invalid = nullptr) const;
 };
 
 } // end namespace comments
diff --git a/include/clang/AST/CommentSema.h b/include/clang/AST/CommentSema.h
index 39109602b14..027c3b929df 100644
--- a/include/clang/AST/CommentSema.h
+++ b/include/clang/AST/CommentSema.h
@@ -84,8 +84,8 @@ class Sema {
       T *Mem = Allocator.Allocate(Size);
       std::uninitialized_copy(Source.begin(), Source.end(), Mem);
       return llvm::makeArrayRef(Mem, Size);
-    } else
-      return llvm::makeArrayRef(static_cast(NULL), 0);
+    }
+    return ArrayRef();
   }
 
   ParagraphComment *actOnParagraphComment(
diff --git a/include/clang/AST/DataRecursiveASTVisitor.h b/include/clang/AST/DataRecursiveASTVisitor.h
new file mode 100644
index 00000000000..9ef008717b1
--- /dev/null
+++ b/include/clang/AST/DataRecursiveASTVisitor.h
@@ -0,0 +1,2519 @@
+//===--- DataRecursiveASTVisitor.h - Data-Recursive AST Visitor -*- C++ -*-===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
+//  This file defines the DataRecursiveASTVisitor interface, which recursively
+//  traverses the entire AST, using data recursion for Stmts/Exprs.
+//
+//===----------------------------------------------------------------------===//
+#ifndef LLVM_CLANG_AST_DATARECURSIVEASTVISITOR_H
+#define LLVM_CLANG_AST_DATARECURSIVEASTVISITOR_H
+
+#include "clang/AST/Attr.h"
+#include "clang/AST/Decl.h"
+#include "clang/AST/DeclCXX.h"
+#include "clang/AST/DeclFriend.h"
+#include "clang/AST/DeclObjC.h"
+#include "clang/AST/DeclOpenMP.h"
+#include "clang/AST/DeclTemplate.h"
+#include "clang/AST/Expr.h"
+#include "clang/AST/ExprCXX.h"
+#include "clang/AST/ExprObjC.h"
+#include "clang/AST/NestedNameSpecifier.h"
+#include "clang/AST/Stmt.h"
+#include "clang/AST/StmtCXX.h"
+#include "clang/AST/StmtObjC.h"
+#include "clang/AST/StmtOpenMP.h"
+#include "clang/AST/TemplateBase.h"
+#include "clang/AST/TemplateName.h"
+#include "clang/AST/Type.h"
+#include "clang/AST/TypeLoc.h"
+
+// The following three macros are used for meta programming.  The code
+// using them is responsible for defining macro OPERATOR().
+
+// All unary operators.
+#define UNARYOP_LIST()                                                         \
+  OPERATOR(PostInc) OPERATOR(PostDec) OPERATOR(PreInc) OPERATOR(PreDec)        \
+      OPERATOR(AddrOf) OPERATOR(Deref) OPERATOR(Plus) OPERATOR(Minus)          \
+      OPERATOR(Not) OPERATOR(LNot) OPERATOR(Real) OPERATOR(Imag)               \
+      OPERATOR(Extension)
+
+// All binary operators (excluding compound assign operators).
+#define BINOP_LIST()                                                           \
+  OPERATOR(PtrMemD) OPERATOR(PtrMemI) OPERATOR(Mul) OPERATOR(Div)              \
+      OPERATOR(Rem) OPERATOR(Add) OPERATOR(Sub) OPERATOR(Shl) OPERATOR(Shr)    \
+      OPERATOR(LT) OPERATOR(GT) OPERATOR(LE) OPERATOR(GE) OPERATOR(EQ)         \
+      OPERATOR(NE) OPERATOR(And) OPERATOR(Xor) OPERATOR(Or) OPERATOR(LAnd)     \
+      OPERATOR(LOr) OPERATOR(Assign) OPERATOR(Comma)
+
+// All compound assign operators.
+#define CAO_LIST()                                                             \
+  OPERATOR(Mul) OPERATOR(Div) OPERATOR(Rem) OPERATOR(Add) OPERATOR(Sub)        \
+      OPERATOR(Shl) OPERATOR(Shr) OPERATOR(And) OPERATOR(Or) OPERATOR(Xor)
+
+namespace clang {
+
+// Reduce the diff between RecursiveASTVisitor / DataRecursiveASTVisitor to
+// make it easier to track changes and keep the two in sync.
+#define RecursiveASTVisitor DataRecursiveASTVisitor
+
+// A helper macro to implement short-circuiting when recursing.  It
+// invokes CALL_EXPR, which must be a method call, on the derived
+// object (s.t. a user of RecursiveASTVisitor can override the method
+// in CALL_EXPR).
+#define TRY_TO(CALL_EXPR)                                                      \
+  do {                                                                         \
+    if (!getDerived().CALL_EXPR)                                               \
+      return false;                                                            \
+  } while (0)
+
+/// \brief A class that does preorder depth-first traversal on the
+/// entire Clang AST and visits each node.
+///
+/// This class performs three distinct tasks:
+///   1. traverse the AST (i.e. go to each node);
+///   2. at a given node, walk up the class hierarchy, starting from
+///      the node's dynamic type, until the top-most class (e.g. Stmt,
+///      Decl, or Type) is reached.
+///   3. given a (node, class) combination, where 'class' is some base
+///      class of the dynamic type of 'node', call a user-overridable
+///      function to actually visit the node.
+///
+/// These tasks are done by three groups of methods, respectively:
+///   1. TraverseDecl(Decl *x) does task #1.  It is the entry point
+///      for traversing an AST rooted at x.  This method simply
+///      dispatches (i.e. forwards) to TraverseFoo(Foo *x) where Foo
+///      is the dynamic type of *x, which calls WalkUpFromFoo(x) and
+///      then recursively visits the child nodes of x.
+///      TraverseStmt(Stmt *x) and TraverseType(QualType x) work
+///      similarly.
+///   2. WalkUpFromFoo(Foo *x) does task #2.  It does not try to visit
+///      any child node of x.  Instead, it first calls WalkUpFromBar(x)
+///      where Bar is the direct parent class of Foo (unless Foo has
+///      no parent), and then calls VisitFoo(x) (see the next list item).
+///   3. VisitFoo(Foo *x) does task #3.
+///
+/// These three method groups are tiered (Traverse* > WalkUpFrom* >
+/// Visit*).  A method (e.g. Traverse*) may call methods from the same
+/// tier (e.g. other Traverse*) or one tier lower (e.g. WalkUpFrom*).
+/// It may not call methods from a higher tier.
+///
+/// Note that since WalkUpFromFoo() calls WalkUpFromBar() (where Bar
+/// is Foo's super class) before calling VisitFoo(), the result is
+/// that the Visit*() methods for a given node are called in the
+/// top-down order (e.g. for a node of type NamespaceDecl, the order will
+/// be VisitDecl(), VisitNamedDecl(), and then VisitNamespaceDecl()).
+///
+/// This scheme guarantees that all Visit*() calls for the same AST
+/// node are grouped together.  In other words, Visit*() methods for
+/// different nodes are never interleaved.
+///
+/// Stmts are traversed internally using a data queue to avoid a stack overflow
+/// with hugely nested ASTs.
+///
+/// Clients of this visitor should subclass the visitor (providing
+/// themselves as the template argument, using the curiously recurring
+/// template pattern) and override any of the Traverse*, WalkUpFrom*,
+/// and Visit* methods for declarations, types, statements,
+/// expressions, or other AST nodes where the visitor should customize
+/// behavior.  Most users only need to override Visit*.  Advanced
+/// users may override Traverse* and WalkUpFrom* to implement custom
+/// traversal strategies.  Returning false from one of these overridden
+/// functions will abort the entire traversal.
+///
+/// By default, this visitor tries to visit every part of the explicit
+/// source code exactly once.  The default policy towards templates
+/// is to descend into the 'pattern' class or function body, not any
+/// explicit or implicit instantiations.  Explicit specializations
+/// are still visited, and the patterns of partial specializations
+/// are visited separately.  This behavior can be changed by
+/// overriding shouldVisitTemplateInstantiations() in the derived class
+/// to return true, in which case all known implicit and explicit
+/// instantiations will be visited at the same time as the pattern
+/// from which they were produced.
+template  class RecursiveASTVisitor {
+public:
+  /// \brief Return a reference to the derived class.
+  Derived &getDerived() { return *static_cast(this); }
+
+  /// \brief Return whether this visitor should recurse into
+  /// template instantiations.
+  bool shouldVisitTemplateInstantiations() const { return false; }
+
+  /// \brief Return whether this visitor should recurse into the types of
+  /// TypeLocs.
+  bool shouldWalkTypesOfTypeLocs() const { return true; }
+
+  /// \brief Recursively visit a statement or expression, by
+  /// dispatching to Traverse*() based on the argument's dynamic type.
+  ///
+  /// \returns false if the visitation was terminated early, true
+  /// otherwise (including when the argument is NULL).
+  bool TraverseStmt(Stmt *S);
+
+  /// \brief Recursively visit a type, by dispatching to
+  /// Traverse*Type() based on the argument's getTypeClass() property.
+  ///
+  /// \returns false if the visitation was terminated early, true
+  /// otherwise (including when the argument is a Null type).
+  bool TraverseType(QualType T);
+
+  /// \brief Recursively visit a type with location, by dispatching to
+  /// Traverse*TypeLoc() based on the argument type's getTypeClass() property.
+  ///
+  /// \returns false if the visitation was terminated early, true
+  /// otherwise (including when the argument is a Null type location).
+  bool TraverseTypeLoc(TypeLoc TL);
+
+  /// \brief Recursively visit an attribute, by dispatching to
+  /// Traverse*Attr() based on the argument's dynamic type.
+  ///
+  /// \returns false if the visitation was terminated early, true
+  /// otherwise (including when the argument is a Null type location).
+  bool TraverseAttr(Attr *At);
+
+  /// \brief Recursively visit a declaration, by dispatching to
+  /// Traverse*Decl() based on the argument's dynamic type.
+  ///
+  /// \returns false if the visitation was terminated early, true
+  /// otherwise (including when the argument is NULL).
+  bool TraverseDecl(Decl *D);
+
+  /// \brief Recursively visit a C++ nested-name-specifier.
+  ///
+  /// \returns false if the visitation was terminated early, true otherwise.
+  bool TraverseNestedNameSpecifier(NestedNameSpecifier *NNS);
+
+  /// \brief Recursively visit a C++ nested-name-specifier with location
+  /// information.
+  ///
+  /// \returns false if the visitation was terminated early, true otherwise.
+  bool TraverseNestedNameSpecifierLoc(NestedNameSpecifierLoc NNS);
+
+  /// \brief Recursively visit a name with its location information.
+  ///
+  /// \returns false if the visitation was terminated early, true otherwise.
+  bool TraverseDeclarationNameInfo(DeclarationNameInfo NameInfo);
+
+  /// \brief Recursively visit a template name and dispatch to the
+  /// appropriate method.
+  ///
+  /// \returns false if the visitation was terminated early, true otherwise.
+  bool TraverseTemplateName(TemplateName Template);
+
+  /// \brief Recursively visit a template argument and dispatch to the
+  /// appropriate method for the argument type.
+  ///
+  /// \returns false if the visitation was terminated early, true otherwise.
+  // FIXME: migrate callers to TemplateArgumentLoc instead.
+  bool TraverseTemplateArgument(const TemplateArgument &Arg);
+
+  /// \brief Recursively visit a template argument location and dispatch to the
+  /// appropriate method for the argument type.
+  ///
+  /// \returns false if the visitation was terminated early, true otherwise.
+  bool TraverseTemplateArgumentLoc(const TemplateArgumentLoc &ArgLoc);
+
+  /// \brief Recursively visit a set of template arguments.
+  /// This can be overridden by a subclass, but it's not expected that
+  /// will be needed -- this visitor always dispatches to another.
+  ///
+  /// \returns false if the visitation was terminated early, true otherwise.
+  // FIXME: take a TemplateArgumentLoc* (or TemplateArgumentListInfo) instead.
+  bool TraverseTemplateArguments(const TemplateArgument *Args,
+                                 unsigned NumArgs);
+
+  /// \brief Recursively visit a constructor initializer.  This
+  /// automatically dispatches to another visitor for the initializer
+  /// expression, but not for the name of the initializer, so may
+  /// be overridden for clients that need access to the name.
+  ///
+  /// \returns false if the visitation was terminated early, true otherwise.
+  bool TraverseConstructorInitializer(CXXCtorInitializer *Init);
+
+  /// \brief Recursively visit a lambda capture.
+  ///
+  /// \returns false if the visitation was terminated early, true otherwise.
+  bool TraverseLambdaCapture(LambdaExpr *LE, const LambdaCapture *C);
+
+  /// \brief Recursively visit the body of a lambda expression.
+  ///
+  /// This provides a hook for visitors that need more context when visiting
+  /// \c LE->getBody().
+  ///
+  /// \returns false if the visitation was terminated early, true otherwise.
+  bool TraverseLambdaBody(LambdaExpr *LE);
+
+  // ---- Methods on Attrs ----
+
+  // \brief Visit an attribute.
+  bool VisitAttr(Attr *A) { return true; }
+
+// Declare Traverse* and empty Visit* for all Attr classes.
+#define ATTR_VISITOR_DECLS_ONLY
+#include "clang/AST/AttrVisitor.inc"
+#undef ATTR_VISITOR_DECLS_ONLY
+
+// ---- Methods on Stmts ----
+
+// Declare Traverse*() for all concrete Stmt classes.
+#define ABSTRACT_STMT(STMT)
+#define STMT(CLASS, PARENT) bool Traverse##CLASS(CLASS *S);
+#include "clang/AST/StmtNodes.inc"
+  // The above header #undefs ABSTRACT_STMT and STMT upon exit.
+
+  // Define WalkUpFrom*() and empty Visit*() for all Stmt classes.
+  bool WalkUpFromStmt(Stmt *S) { return getDerived().VisitStmt(S); }
+  bool VisitStmt(Stmt *S) { return true; }
+#define STMT(CLASS, PARENT)                                                    \
+  bool WalkUpFrom##CLASS(CLASS *S) {                                           \
+    TRY_TO(WalkUpFrom##PARENT(S));                                             \
+    TRY_TO(Visit##CLASS(S));                                                   \
+    return true;                                                               \
+  }                                                                            \
+  bool Visit##CLASS(CLASS *S) { return true; }
+#include "clang/AST/StmtNodes.inc"
+
+// Define Traverse*(), WalkUpFrom*(), and Visit*() for unary
+// operator methods.  Unary operators are not classes in themselves
+// (they're all opcodes in UnaryOperator) but do have visitors.
+#define OPERATOR(NAME)                                                         \
+  bool TraverseUnary##NAME(UnaryOperator *S) {                                 \
+    TRY_TO(WalkUpFromUnary##NAME(S));                                          \
+    StmtQueueAction StmtQueue(*this);                                          \
+    StmtQueue.queue(S->getSubExpr());                                          \
+    return true;                                                               \
+  }                                                                            \
+  bool WalkUpFromUnary##NAME(UnaryOperator *S) {                               \
+    TRY_TO(WalkUpFromUnaryOperator(S));                                        \
+    TRY_TO(VisitUnary##NAME(S));                                               \
+    return true;                                                               \
+  }                                                                            \
+  bool VisitUnary##NAME(UnaryOperator *S) { return true; }
+
+  UNARYOP_LIST()
+#undef OPERATOR
+
+// Define Traverse*(), WalkUpFrom*(), and Visit*() for binary
+// operator methods.  Binary operators are not classes in themselves
+// (they're all opcodes in BinaryOperator) but do have visitors.
+#define GENERAL_BINOP_FALLBACK(NAME, BINOP_TYPE)                               \
+  bool TraverseBin##NAME(BINOP_TYPE *S) {                                      \
+    TRY_TO(WalkUpFromBin##NAME(S));                                            \
+    StmtQueueAction StmtQueue(*this);                                          \
+    StmtQueue.queue(S->getLHS());                                              \
+    StmtQueue.queue(S->getRHS());                                              \
+    return true;                                                               \
+  }                                                                            \
+  bool WalkUpFromBin##NAME(BINOP_TYPE *S) {                                    \
+    TRY_TO(WalkUpFrom##BINOP_TYPE(S));                                         \
+    TRY_TO(VisitBin##NAME(S));                                                 \
+    return true;                                                               \
+  }                                                                            \
+  bool VisitBin##NAME(BINOP_TYPE *S) { return true; }
+
+#define OPERATOR(NAME) GENERAL_BINOP_FALLBACK(NAME, BinaryOperator)
+  BINOP_LIST()
+#undef OPERATOR
+
+// Define Traverse*(), WalkUpFrom*(), and Visit*() for compound
+// assignment methods.  Compound assignment operators are not
+// classes in themselves (they're all opcodes in
+// CompoundAssignOperator) but do have visitors.
+#define OPERATOR(NAME)                                                         \
+  GENERAL_BINOP_FALLBACK(NAME##Assign, CompoundAssignOperator)
+
+  CAO_LIST()
+#undef OPERATOR
+#undef GENERAL_BINOP_FALLBACK
+
+// ---- Methods on Types ----
+// FIXME: revamp to take TypeLoc's rather than Types.
+
+// Declare Traverse*() for all concrete Type classes.
+#define ABSTRACT_TYPE(CLASS, BASE)
+#define TYPE(CLASS, BASE) bool Traverse##CLASS##Type(CLASS##Type *T);
+#include "clang/AST/TypeNodes.def"
+  // The above header #undefs ABSTRACT_TYPE and TYPE upon exit.
+
+  // Define WalkUpFrom*() and empty Visit*() for all Type classes.
+  bool WalkUpFromType(Type *T) { return getDerived().VisitType(T); }
+  bool VisitType(Type *T) { return true; }
+#define TYPE(CLASS, BASE)                                                      \
+  bool WalkUpFrom##CLASS##Type(CLASS##Type *T) {                               \
+    TRY_TO(WalkUpFrom##BASE(T));                                               \
+    TRY_TO(Visit##CLASS##Type(T));                                             \
+    return true;                                                               \
+  }                                                                            \
+  bool Visit##CLASS##Type(CLASS##Type *T) { return true; }
+#include "clang/AST/TypeNodes.def"
+
+// ---- Methods on TypeLocs ----
+// FIXME: this currently just calls the matching Type methods
+
+// Declare Traverse*() for all concrete TypeLoc classes.
+#define ABSTRACT_TYPELOC(CLASS, BASE)
+#define TYPELOC(CLASS, BASE) bool Traverse##CLASS##TypeLoc(CLASS##TypeLoc TL);
+#include "clang/AST/TypeLocNodes.def"
+  // The above header #undefs ABSTRACT_TYPELOC and TYPELOC upon exit.
+
+  // Define WalkUpFrom*() and empty Visit*() for all TypeLoc classes.
+  bool WalkUpFromTypeLoc(TypeLoc TL) { return getDerived().VisitTypeLoc(TL); }
+  bool VisitTypeLoc(TypeLoc TL) { return true; }
+
+  // QualifiedTypeLoc and UnqualTypeLoc are not declared in
+  // TypeNodes.def and thus need to be handled specially.
+  bool WalkUpFromQualifiedTypeLoc(QualifiedTypeLoc TL) {
+    return getDerived().VisitUnqualTypeLoc(TL.getUnqualifiedLoc());
+  }
+  bool VisitQualifiedTypeLoc(QualifiedTypeLoc TL) { return true; }
+  bool WalkUpFromUnqualTypeLoc(UnqualTypeLoc TL) {
+    return getDerived().VisitUnqualTypeLoc(TL.getUnqualifiedLoc());
+  }
+  bool VisitUnqualTypeLoc(UnqualTypeLoc TL) { return true; }
+
+// Note that BASE includes trailing 'Type' which CLASS doesn't.
+#define TYPE(CLASS, BASE)                                                      \
+  bool WalkUpFrom##CLASS##TypeLoc(CLASS##TypeLoc TL) {                         \
+    TRY_TO(WalkUpFrom##BASE##Loc(TL));                                         \
+    TRY_TO(Visit##CLASS##TypeLoc(TL));                                         \
+    return true;                                                               \
+  }                                                                            \
+  bool Visit##CLASS##TypeLoc(CLASS##TypeLoc TL) { return true; }
+#include "clang/AST/TypeNodes.def"
+
+// ---- Methods on Decls ----
+
+// Declare Traverse*() for all concrete Decl classes.
+#define ABSTRACT_DECL(DECL)
+#define DECL(CLASS, BASE) bool Traverse##CLASS##Decl(CLASS##Decl *D);
+#include "clang/AST/DeclNodes.inc"
+  // The above header #undefs ABSTRACT_DECL and DECL upon exit.
+
+  // Define WalkUpFrom*() and empty Visit*() for all Decl classes.
+  bool WalkUpFromDecl(Decl *D) { return getDerived().VisitDecl(D); }
+  bool VisitDecl(Decl *D) { return true; }
+#define DECL(CLASS, BASE)                                                      \
+  bool WalkUpFrom##CLASS##Decl(CLASS##Decl *D) {                               \
+    TRY_TO(WalkUpFrom##BASE(D));                                               \
+    TRY_TO(Visit##CLASS##Decl(D));                                             \
+    return true;                                                               \
+  }                                                                            \
+  bool Visit##CLASS##Decl(CLASS##Decl *D) { return true; }
+#include "clang/AST/DeclNodes.inc"
+
+private:
+  // These are helper methods used by more than one Traverse* method.
+  bool TraverseTemplateParameterListHelper(TemplateParameterList *TPL);
+  bool TraverseClassInstantiations(ClassTemplateDecl *D);
+  bool TraverseVariableInstantiations(VarTemplateDecl *D);
+  bool TraverseFunctionInstantiations(FunctionTemplateDecl *D);
+  bool TraverseTemplateArgumentLocsHelper(const TemplateArgumentLoc *TAL,
+                                          unsigned Count);
+  bool TraverseArrayTypeLocHelper(ArrayTypeLoc TL);
+  bool TraverseRecordHelper(RecordDecl *D);
+  bool TraverseCXXRecordHelper(CXXRecordDecl *D);
+  bool TraverseDeclaratorHelper(DeclaratorDecl *D);
+  bool TraverseDeclContextHelper(DeclContext *DC);
+  bool TraverseFunctionHelper(FunctionDecl *D);
+  bool TraverseVarHelper(VarDecl *D);
+  bool TraverseOMPExecutableDirective(OMPExecutableDirective *S);
+  bool TraverseOMPClause(OMPClause *C);
+#define OPENMP_CLAUSE(Name, Class) bool Visit##Class(Class *C);
+#include "clang/Basic/OpenMPKinds.def"
+  /// \brief Process clauses with list of variables.
+  template  bool VisitOMPClauseList(T *Node);
+
+  typedef SmallVector StmtsTy;
+  typedef SmallVector QueuesTy;
+
+  QueuesTy Queues;
+
+  class NewQueueRAII {
+    RecursiveASTVisitor &RAV;
+
+  public:
+    NewQueueRAII(StmtsTy &queue, RecursiveASTVisitor &RAV) : RAV(RAV) {
+      RAV.Queues.push_back(&queue);
+    }
+    ~NewQueueRAII() { RAV.Queues.pop_back(); }
+  };
+
+  StmtsTy &getCurrentQueue() {
+    assert(!Queues.empty() && "base TraverseStmt was never called?");
+    return *Queues.back();
+  }
+
+public:
+  class StmtQueueAction {
+    StmtsTy &CurrQueue;
+
+  public:
+    explicit StmtQueueAction(RecursiveASTVisitor &RAV)
+        : CurrQueue(RAV.getCurrentQueue()) {}
+
+    void queue(Stmt *S) { CurrQueue.push_back(S); }
+  };
+};
+
+#define DISPATCH(NAME, CLASS, VAR)                                             \
+  return getDerived().Traverse##NAME(static_cast(VAR))
+
+template 
+bool RecursiveASTVisitor::TraverseStmt(Stmt *S) {
+  if (!S)
+    return true;
+
+  StmtsTy Queue, StmtsToEnqueue;
+  Queue.push_back(S);
+  NewQueueRAII NQ(StmtsToEnqueue, *this);
+
+  while (!Queue.empty()) {
+    S = Queue.pop_back_val();
+    if (!S)
+      continue;
+
+    StmtsToEnqueue.clear();
+
+#define DISPATCH_STMT(NAME, CLASS, VAR)                                        \
+  TRY_TO(Traverse##NAME(static_cast(VAR)));                           \
+  break
+
+    // If we have a binary expr, dispatch to the subcode of the binop.  A smart
+    // optimizer (e.g. LLVM) will fold this comparison into the switch stmt
+    // below.
+    if (BinaryOperator *BinOp = dyn_cast(S)) {
+      switch (BinOp->getOpcode()) {
+#define OPERATOR(NAME)                                                         \
+  case BO_##NAME:                                                              \
+    DISPATCH_STMT(Bin##NAME, BinaryOperator, S);
+
+        BINOP_LIST()
+#undef OPERATOR
+#undef BINOP_LIST
+
+#define OPERATOR(NAME)                                                         \
+  case BO_##NAME##Assign:                                                      \
+    DISPATCH_STMT(Bin##NAME##Assign, CompoundAssignOperator, S);
+
+        CAO_LIST()
+#undef OPERATOR
+#undef CAO_LIST
+      }
+    } else if (UnaryOperator *UnOp = dyn_cast(S)) {
+      switch (UnOp->getOpcode()) {
+#define OPERATOR(NAME)                                                         \
+  case UO_##NAME:                                                              \
+    DISPATCH_STMT(Unary##NAME, UnaryOperator, S);
+
+        UNARYOP_LIST()
+#undef OPERATOR
+#undef UNARYOP_LIST
+      }
+    } else {
+
+      // Top switch stmt: dispatch to TraverseFooStmt for each concrete FooStmt.
+      switch (S->getStmtClass()) {
+      case Stmt::NoStmtClass:
+        break;
+#define ABSTRACT_STMT(STMT)
+#define STMT(CLASS, PARENT)                                                    \
+  case Stmt::CLASS##Class:                                                     \
+    DISPATCH_STMT(CLASS, CLASS, S);
+#include "clang/AST/StmtNodes.inc"
+      }
+    }
+
+    for (SmallVectorImpl::reverse_iterator RI = StmtsToEnqueue.rbegin(),
+                                                   RE = StmtsToEnqueue.rend();
+         RI != RE; ++RI)
+      Queue.push_back(*RI);
+  }
+
+  return true;
+}
+
+#undef DISPATCH_STMT
+
+template 
+bool RecursiveASTVisitor::TraverseType(QualType T) {
+  if (T.isNull())
+    return true;
+
+  switch (T->getTypeClass()) {
+#define ABSTRACT_TYPE(CLASS, BASE)
+#define TYPE(CLASS, BASE)                                                      \
+  case Type::CLASS:                                                            \
+    DISPATCH(CLASS##Type, CLASS##Type, const_cast(T.getTypePtr()));
+#include "clang/AST/TypeNodes.def"
+  }
+
+  return true;
+}
+
+template 
+bool RecursiveASTVisitor::TraverseTypeLoc(TypeLoc TL) {
+  if (TL.isNull())
+    return true;
+
+  switch (TL.getTypeLocClass()) {
+#define ABSTRACT_TYPELOC(CLASS, BASE)
+#define TYPELOC(CLASS, BASE)                                                   \
+  case TypeLoc::CLASS:                                                         \
+    return getDerived().Traverse##CLASS##TypeLoc(TL.castAs());
+#include "clang/AST/TypeLocNodes.def"
+  }
+
+  return true;
+}
+
+// Define the Traverse*Attr(Attr* A) methods
+#define VISITORCLASS RecursiveASTVisitor
+#include "clang/AST/AttrVisitor.inc"
+#undef VISITORCLASS
+
+template 
+bool RecursiveASTVisitor::TraverseDecl(Decl *D) {
+  if (!D)
+    return true;
+
+  // As a syntax visitor, we want to ignore declarations for
+  // implicitly-defined declarations (ones not typed explicitly by the
+  // user).
+  if (D->isImplicit())
+    return true;
+
+  switch (D->getKind()) {
+#define ABSTRACT_DECL(DECL)
+#define DECL(CLASS, BASE)                                                      \
+  case Decl::CLASS:                                                            \
+    if (!getDerived().Traverse##CLASS##Decl(static_cast(D)))    \
+      return false;                                                            \
+    break;
+#include "clang/AST/DeclNodes.inc"
+  }
+
+  // Visit any attributes attached to this declaration.
+  for (auto *I : D->attrs()) {
+    if (!getDerived().TraverseAttr(I))
+      return false;
+  }
+  return true;
+}
+
+#undef DISPATCH
+
+template 
+bool RecursiveASTVisitor::TraverseNestedNameSpecifier(
+    NestedNameSpecifier *NNS) {
+  if (!NNS)
+    return true;
+
+  if (NNS->getPrefix())
+    TRY_TO(TraverseNestedNameSpecifier(NNS->getPrefix()));
+
+  switch (NNS->getKind()) {
+  case NestedNameSpecifier::Identifier:
+  case NestedNameSpecifier::Namespace:
+  case NestedNameSpecifier::NamespaceAlias:
+  case NestedNameSpecifier::Global:
+    return true;
+
+  case NestedNameSpecifier::TypeSpec:
+  case NestedNameSpecifier::TypeSpecWithTemplate:
+    TRY_TO(TraverseType(QualType(NNS->getAsType(), 0)));
+  }
+
+  return true;
+}
+
+template 
+bool RecursiveASTVisitor::TraverseNestedNameSpecifierLoc(
+    NestedNameSpecifierLoc NNS) {
+  if (!NNS)
+    return true;
+
+  if (NestedNameSpecifierLoc Prefix = NNS.getPrefix())
+    TRY_TO(TraverseNestedNameSpecifierLoc(Prefix));
+
+  switch (NNS.getNestedNameSpecifier()->getKind()) {
+  case NestedNameSpecifier::Identifier:
+  case NestedNameSpecifier::Namespace:
+  case NestedNameSpecifier::NamespaceAlias:
+  case NestedNameSpecifier::Global:
+    return true;
+
+  case NestedNameSpecifier::TypeSpec:
+  case NestedNameSpecifier::TypeSpecWithTemplate:
+    TRY_TO(TraverseTypeLoc(NNS.getTypeLoc()));
+    break;
+  }
+
+  return true;
+}
+
+template 
+bool RecursiveASTVisitor::TraverseDeclarationNameInfo(
+    DeclarationNameInfo NameInfo) {
+  switch (NameInfo.getName().getNameKind()) {
+  case DeclarationName::CXXConstructorName:
+  case DeclarationName::CXXDestructorName:
+  case DeclarationName::CXXConversionFunctionName:
+    if (TypeSourceInfo *TSInfo = NameInfo.getNamedTypeInfo())
+      TRY_TO(TraverseTypeLoc(TSInfo->getTypeLoc()));
+
+    break;
+
+  case DeclarationName::Identifier:
+  case DeclarationName::ObjCZeroArgSelector:
+  case DeclarationName::ObjCOneArgSelector:
+  case DeclarationName::ObjCMultiArgSelector:
+  case DeclarationName::CXXOperatorName:
+  case DeclarationName::CXXLiteralOperatorName:
+  case DeclarationName::CXXUsingDirective:
+    break;
+  }
+
+  return true;
+}
+
+template 
+bool RecursiveASTVisitor::TraverseTemplateName(TemplateName Template) {
+  if (DependentTemplateName *DTN = Template.getAsDependentTemplateName())
+    TRY_TO(TraverseNestedNameSpecifier(DTN->getQualifier()));
+  else if (QualifiedTemplateName *QTN = Template.getAsQualifiedTemplateName())
+    TRY_TO(TraverseNestedNameSpecifier(QTN->getQualifier()));
+
+  return true;
+}
+
+template 
+bool RecursiveASTVisitor::TraverseTemplateArgument(
+    const TemplateArgument &Arg) {
+  switch (Arg.getKind()) {
+  case TemplateArgument::Null:
+  case TemplateArgument::Declaration:
+  case TemplateArgument::Integral:
+  case TemplateArgument::NullPtr:
+    return true;
+
+  case TemplateArgument::Type:
+    return getDerived().TraverseType(Arg.getAsType());
+
+  case TemplateArgument::Template:
+  case TemplateArgument::TemplateExpansion:
+    return getDerived().TraverseTemplateName(
+        Arg.getAsTemplateOrTemplatePattern());
+
+  case TemplateArgument::Expression:
+    return getDerived().TraverseStmt(Arg.getAsExpr());
+
+  case TemplateArgument::Pack:
+    return getDerived().TraverseTemplateArguments(Arg.pack_begin(),
+                                                  Arg.pack_size());
+  }
+
+  return true;
+}
+
+// FIXME: no template name location?
+// FIXME: no source locations for a template argument pack?
+template 
+bool RecursiveASTVisitor::TraverseTemplateArgumentLoc(
+    const TemplateArgumentLoc &ArgLoc) {
+  const TemplateArgument &Arg = ArgLoc.getArgument();
+
+  switch (Arg.getKind()) {
+  case TemplateArgument::Null:
+  case TemplateArgument::Declaration:
+  case TemplateArgument::Integral:
+  case TemplateArgument::NullPtr:
+    return true;
+
+  case TemplateArgument::Type: {
+    // FIXME: how can TSI ever be NULL?
+    if (TypeSourceInfo *TSI = ArgLoc.getTypeSourceInfo())
+      return getDerived().TraverseTypeLoc(TSI->getTypeLoc());
+    else
+      return getDerived().TraverseType(Arg.getAsType());
+  }
+
+  case TemplateArgument::Template:
+  case TemplateArgument::TemplateExpansion:
+    if (ArgLoc.getTemplateQualifierLoc())
+      TRY_TO(getDerived().TraverseNestedNameSpecifierLoc(
+          ArgLoc.getTemplateQualifierLoc()));
+    return getDerived().TraverseTemplateName(
+        Arg.getAsTemplateOrTemplatePattern());
+
+  case TemplateArgument::Expression:
+    return getDerived().TraverseStmt(ArgLoc.getSourceExpression());
+
+  case TemplateArgument::Pack:
+    return getDerived().TraverseTemplateArguments(Arg.pack_begin(),
+                                                  Arg.pack_size());
+  }
+
+  return true;
+}
+
+template 
+bool RecursiveASTVisitor::TraverseTemplateArguments(
+    const TemplateArgument *Args, unsigned NumArgs) {
+  for (unsigned I = 0; I != NumArgs; ++I) {
+    TRY_TO(TraverseTemplateArgument(Args[I]));
+  }
+
+  return true;
+}
+
+template 
+bool RecursiveASTVisitor::TraverseConstructorInitializer(
+    CXXCtorInitializer *Init) {
+  if (TypeSourceInfo *TInfo = Init->getTypeSourceInfo())
+    TRY_TO(TraverseTypeLoc(TInfo->getTypeLoc()));
+
+  if (Init->isWritten())
+    TRY_TO(TraverseStmt(Init->getInit()));
+  return true;
+}
+
+template 
+bool
+RecursiveASTVisitor::TraverseLambdaCapture(LambdaExpr *LE,
+                                                    const LambdaCapture *C) {
+  if (C->isInitCapture())
+    TRY_TO(TraverseDecl(C->getCapturedVar()));
+  return true;
+}
+
+template 
+bool RecursiveASTVisitor::TraverseLambdaBody(LambdaExpr *LE) {
+  StmtQueueAction StmtQueue(*this);
+  StmtQueue.queue(LE->getBody());
+  return true;
+}
+
+// ----------------- Type traversal -----------------
+
+// This macro makes available a variable T, the passed-in type.
+#define DEF_TRAVERSE_TYPE(TYPE, CODE)                                          \
+  template                                                   \
+  bool RecursiveASTVisitor::Traverse##TYPE(TYPE *T) {                 \
+    TRY_TO(WalkUpFrom##TYPE(T));                                               \
+    { CODE; }                                                                  \
+    return true;                                                               \
+  }
+
+DEF_TRAVERSE_TYPE(BuiltinType, {})
+
+DEF_TRAVERSE_TYPE(ComplexType, { TRY_TO(TraverseType(T->getElementType())); })
+
+DEF_TRAVERSE_TYPE(PointerType, { TRY_TO(TraverseType(T->getPointeeType())); })
+
+DEF_TRAVERSE_TYPE(BlockPointerType,
+                  { TRY_TO(TraverseType(T->getPointeeType())); })
+
+DEF_TRAVERSE_TYPE(LValueReferenceType,
+                  { TRY_TO(TraverseType(T->getPointeeType())); })
+
+DEF_TRAVERSE_TYPE(RValueReferenceType,
+                  { TRY_TO(TraverseType(T->getPointeeType())); })
+
+DEF_TRAVERSE_TYPE(MemberPointerType, {
+  TRY_TO(TraverseType(QualType(T->getClass(), 0)));
+  TRY_TO(TraverseType(T->getPointeeType()));
+})
+
+DEF_TRAVERSE_TYPE(AdjustedType, { TRY_TO(TraverseType(T->getOriginalType())); })
+
+DEF_TRAVERSE_TYPE(DecayedType, { TRY_TO(TraverseType(T->getOriginalType())); })
+
+DEF_TRAVERSE_TYPE(ConstantArrayType,
+                  { TRY_TO(TraverseType(T->getElementType())); })
+
+DEF_TRAVERSE_TYPE(IncompleteArrayType,
+                  { TRY_TO(TraverseType(T->getElementType())); })
+
+DEF_TRAVERSE_TYPE(VariableArrayType, {
+  TRY_TO(TraverseType(T->getElementType()));
+  TRY_TO(TraverseStmt(T->getSizeExpr()));
+})
+
+DEF_TRAVERSE_TYPE(DependentSizedArrayType, {
+  TRY_TO(TraverseType(T->getElementType()));
+  if (T->getSizeExpr())
+    TRY_TO(TraverseStmt(T->getSizeExpr()));
+})
+
+DEF_TRAVERSE_TYPE(DependentSizedExtVectorType, {
+  if (T->getSizeExpr())
+    TRY_TO(TraverseStmt(T->getSizeExpr()));
+  TRY_TO(TraverseType(T->getElementType()));
+})
+
+DEF_TRAVERSE_TYPE(VectorType, { TRY_TO(TraverseType(T->getElementType())); })
+
+DEF_TRAVERSE_TYPE(ExtVectorType, { TRY_TO(TraverseType(T->getElementType())); })
+
+DEF_TRAVERSE_TYPE(FunctionNoProtoType,
+                  { TRY_TO(TraverseType(T->getReturnType())); })
+
+DEF_TRAVERSE_TYPE(FunctionProtoType, {
+  TRY_TO(TraverseType(T->getReturnType()));
+
+  for (const auto &A : T->param_types()) {
+    TRY_TO(TraverseType(A));
+  }
+
+  for (const auto &E : T->exceptions()) {
+    TRY_TO(TraverseType(E));
+  }
+})
+
+DEF_TRAVERSE_TYPE(UnresolvedUsingType, {})
+DEF_TRAVERSE_TYPE(TypedefType, {})
+
+DEF_TRAVERSE_TYPE(TypeOfExprType,
+                  { TRY_TO(TraverseStmt(T->getUnderlyingExpr())); })
+
+DEF_TRAVERSE_TYPE(TypeOfType, { TRY_TO(TraverseType(T->getUnderlyingType())); })
+
+DEF_TRAVERSE_TYPE(DecltypeType,
+                  { TRY_TO(TraverseStmt(T->getUnderlyingExpr())); })
+
+DEF_TRAVERSE_TYPE(UnaryTransformType, {
+  TRY_TO(TraverseType(T->getBaseType()));
+  TRY_TO(TraverseType(T->getUnderlyingType()));
+})
+
+DEF_TRAVERSE_TYPE(AutoType, { TRY_TO(TraverseType(T->getDeducedType())); })
+
+DEF_TRAVERSE_TYPE(RecordType, {})
+DEF_TRAVERSE_TYPE(EnumType, {})
+DEF_TRAVERSE_TYPE(TemplateTypeParmType, {})
+DEF_TRAVERSE_TYPE(SubstTemplateTypeParmType, {})
+DEF_TRAVERSE_TYPE(SubstTemplateTypeParmPackType, {})
+
+DEF_TRAVERSE_TYPE(TemplateSpecializationType, {
+  TRY_TO(TraverseTemplateName(T->getTemplateName()));
+  TRY_TO(TraverseTemplateArguments(T->getArgs(), T->getNumArgs()));
+})
+
+DEF_TRAVERSE_TYPE(InjectedClassNameType, {})
+
+DEF_TRAVERSE_TYPE(AttributedType,
+                  { TRY_TO(TraverseType(T->getModifiedType())); })
+
+DEF_TRAVERSE_TYPE(ParenType, { TRY_TO(TraverseType(T->getInnerType())); })
+
+DEF_TRAVERSE_TYPE(ElaboratedType, {
+  if (T->getQualifier()) {
+    TRY_TO(TraverseNestedNameSpecifier(T->getQualifier()));
+  }
+  TRY_TO(TraverseType(T->getNamedType()));
+})
+
+DEF_TRAVERSE_TYPE(DependentNameType,
+                  { TRY_TO(TraverseNestedNameSpecifier(T->getQualifier())); })
+
+DEF_TRAVERSE_TYPE(DependentTemplateSpecializationType, {
+  TRY_TO(TraverseNestedNameSpecifier(T->getQualifier()));
+  TRY_TO(TraverseTemplateArguments(T->getArgs(), T->getNumArgs()));
+})
+
+DEF_TRAVERSE_TYPE(PackExpansionType, { TRY_TO(TraverseType(T->getPattern())); })
+
+DEF_TRAVERSE_TYPE(ObjCInterfaceType, {})
+
+DEF_TRAVERSE_TYPE(ObjCObjectType, {
+  // We have to watch out here because an ObjCInterfaceType's base
+  // type is itself.
+  if (T->getBaseType().getTypePtr() != T)
+    TRY_TO(TraverseType(T->getBaseType()));
+})
+
+DEF_TRAVERSE_TYPE(ObjCObjectPointerType,
+                  { TRY_TO(TraverseType(T->getPointeeType())); })
+
+DEF_TRAVERSE_TYPE(AtomicType, { TRY_TO(TraverseType(T->getValueType())); })
+
+#undef DEF_TRAVERSE_TYPE
+
+// ----------------- TypeLoc traversal -----------------
+
+// This macro makes available a variable TL, the passed-in TypeLoc.
+// If requested, it calls WalkUpFrom* for the Type in the given TypeLoc,
+// in addition to WalkUpFrom* for the TypeLoc itself, such that existing
+// clients that override the WalkUpFrom*Type() and/or Visit*Type() methods
+// continue to work.
+#define DEF_TRAVERSE_TYPELOC(TYPE, CODE)                                       \
+  template                                                   \
+  bool RecursiveASTVisitor::Traverse##TYPE##Loc(TYPE##Loc TL) {       \
+    if (getDerived().shouldWalkTypesOfTypeLocs())                              \
+      TRY_TO(WalkUpFrom##TYPE(const_cast(TL.getTypePtr())));           \
+    TRY_TO(WalkUpFrom##TYPE##Loc(TL));                                         \
+    { CODE; }                                                                  \
+    return true;                                                               \
+  }
+
+template 
+bool
+RecursiveASTVisitor::TraverseQualifiedTypeLoc(QualifiedTypeLoc TL) {
+  // Move this over to the 'main' typeloc tree.  Note that this is a
+  // move -- we pretend that we were really looking at the unqualified
+  // typeloc all along -- rather than a recursion, so we don't follow
+  // the normal CRTP plan of going through
+  // getDerived().TraverseTypeLoc.  If we did, we'd be traversing
+  // twice for the same type (once as a QualifiedTypeLoc version of
+  // the type, once as an UnqualifiedTypeLoc version of the type),
+  // which in effect means we'd call VisitTypeLoc twice with the
+  // 'same' type.  This solves that problem, at the cost of never
+  // seeing the qualified version of the type (unless the client
+  // subclasses TraverseQualifiedTypeLoc themselves).  It's not a
+  // perfect solution.  A perfect solution probably requires making
+  // QualifiedTypeLoc a wrapper around TypeLoc -- like QualType is a
+  // wrapper around Type* -- rather than being its own class in the
+  // type hierarchy.
+  return TraverseTypeLoc(TL.getUnqualifiedLoc());
+}
+
+DEF_TRAVERSE_TYPELOC(BuiltinType, {})
+
+// FIXME: ComplexTypeLoc is unfinished
+DEF_TRAVERSE_TYPELOC(ComplexType, {
+  TRY_TO(TraverseType(TL.getTypePtr()->getElementType()));
+})
+
+DEF_TRAVERSE_TYPELOC(PointerType,
+                     { TRY_TO(TraverseTypeLoc(TL.getPointeeLoc())); })
+
+DEF_TRAVERSE_TYPELOC(BlockPointerType,
+                     { TRY_TO(TraverseTypeLoc(TL.getPointeeLoc())); })
+
+DEF_TRAVERSE_TYPELOC(LValueReferenceType,
+                     { TRY_TO(TraverseTypeLoc(TL.getPointeeLoc())); })
+
+DEF_TRAVERSE_TYPELOC(RValueReferenceType,
+                     { TRY_TO(TraverseTypeLoc(TL.getPointeeLoc())); })
+
+// FIXME: location of base class?
+// We traverse this in the type case as well, but how is it not reached through
+// the pointee type?
+DEF_TRAVERSE_TYPELOC(MemberPointerType, {
+  TRY_TO(TraverseType(QualType(TL.getTypePtr()->getClass(), 0)));
+  TRY_TO(TraverseTypeLoc(TL.getPointeeLoc()));
+})
+
+DEF_TRAVERSE_TYPELOC(AdjustedType,
+                     { TRY_TO(TraverseTypeLoc(TL.getOriginalLoc())); })
+
+DEF_TRAVERSE_TYPELOC(DecayedType,
+                     { TRY_TO(TraverseTypeLoc(TL.getOriginalLoc())); })
+
+template 
+bool RecursiveASTVisitor::TraverseArrayTypeLocHelper(ArrayTypeLoc TL) {
+  // This isn't available for ArrayType, but is for the ArrayTypeLoc.
+  TRY_TO(TraverseStmt(TL.getSizeExpr()));
+  return true;
+}
+
+DEF_TRAVERSE_TYPELOC(ConstantArrayType, {
+  TRY_TO(TraverseTypeLoc(TL.getElementLoc()));
+  return TraverseArrayTypeLocHelper(TL);
+})
+
+DEF_TRAVERSE_TYPELOC(IncompleteArrayType, {
+  TRY_TO(TraverseTypeLoc(TL.getElementLoc()));
+  return TraverseArrayTypeLocHelper(TL);
+})
+
+DEF_TRAVERSE_TYPELOC(VariableArrayType, {
+  TRY_TO(TraverseTypeLoc(TL.getElementLoc()));
+  return TraverseArrayTypeLocHelper(TL);
+})
+
+DEF_TRAVERSE_TYPELOC(DependentSizedArrayType, {
+  TRY_TO(TraverseTypeLoc(TL.getElementLoc()));
+  return TraverseArrayTypeLocHelper(TL);
+})
+
+// FIXME: order? why not size expr first?
+// FIXME: base VectorTypeLoc is unfinished
+DEF_TRAVERSE_TYPELOC(DependentSizedExtVectorType, {
+  if (TL.getTypePtr()->getSizeExpr())
+    TRY_TO(TraverseStmt(TL.getTypePtr()->getSizeExpr()));
+  TRY_TO(TraverseType(TL.getTypePtr()->getElementType()));
+})
+
+// FIXME: VectorTypeLoc is unfinished
+DEF_TRAVERSE_TYPELOC(VectorType, {
+  TRY_TO(TraverseType(TL.getTypePtr()->getElementType()));
+})
+
+// FIXME: size and attributes
+// FIXME: base VectorTypeLoc is unfinished
+DEF_TRAVERSE_TYPELOC(ExtVectorType, {
+  TRY_TO(TraverseType(TL.getTypePtr()->getElementType()));
+})
+
+DEF_TRAVERSE_TYPELOC(FunctionNoProtoType,
+                     { TRY_TO(TraverseTypeLoc(TL.getReturnLoc())); })
+
+// FIXME: location of exception specifications (attributes?)
+DEF_TRAVERSE_TYPELOC(FunctionProtoType, {
+  TRY_TO(TraverseTypeLoc(TL.getReturnLoc()));
+
+  const FunctionProtoType *T = TL.getTypePtr();
+
+  for (unsigned I = 0, E = TL.getNumParams(); I != E; ++I) {
+    if (TL.getParam(I)) {
+      TRY_TO(TraverseDecl(TL.getParam(I)));
+    } else if (I < T->getNumParams()) {
+      TRY_TO(TraverseType(T->getParamType(I)));
+    }
+  }
+
+  for (const auto &E : T->exceptions()) {
+    TRY_TO(TraverseType(E));
+  }
+})
+
+DEF_TRAVERSE_TYPELOC(UnresolvedUsingType, {})
+DEF_TRAVERSE_TYPELOC(TypedefType, {})
+
+DEF_TRAVERSE_TYPELOC(TypeOfExprType,
+                     { TRY_TO(TraverseStmt(TL.getUnderlyingExpr())); })
+
+DEF_TRAVERSE_TYPELOC(TypeOfType, {
+  TRY_TO(TraverseTypeLoc(TL.getUnderlyingTInfo()->getTypeLoc()));
+})
+
+// FIXME: location of underlying expr
+DEF_TRAVERSE_TYPELOC(DecltypeType, {
+  TRY_TO(TraverseStmt(TL.getTypePtr()->getUnderlyingExpr()));
+})
+
+DEF_TRAVERSE_TYPELOC(UnaryTransformType, {
+  TRY_TO(TraverseTypeLoc(TL.getUnderlyingTInfo()->getTypeLoc()));
+})
+
+DEF_TRAVERSE_TYPELOC(AutoType, {
+  TRY_TO(TraverseType(TL.getTypePtr()->getDeducedType()));
+})
+
+DEF_TRAVERSE_TYPELOC(RecordType, {})
+DEF_TRAVERSE_TYPELOC(EnumType, {})
+DEF_TRAVERSE_TYPELOC(TemplateTypeParmType, {})
+DEF_TRAVERSE_TYPELOC(SubstTemplateTypeParmType, {})
+DEF_TRAVERSE_TYPELOC(SubstTemplateTypeParmPackType, {})
+
+// FIXME: use the loc for the template name?
+DEF_TRAVERSE_TYPELOC(TemplateSpecializationType, {
+  TRY_TO(TraverseTemplateName(TL.getTypePtr()->getTemplateName()));
+  for (unsigned I = 0, E = TL.getNumArgs(); I != E; ++I) {
+    TRY_TO(TraverseTemplateArgumentLoc(TL.getArgLoc(I)));
+  }
+})
+
+DEF_TRAVERSE_TYPELOC(InjectedClassNameType, {})
+
+DEF_TRAVERSE_TYPELOC(ParenType, { TRY_TO(TraverseTypeLoc(TL.getInnerLoc())); })
+
+DEF_TRAVERSE_TYPELOC(AttributedType,
+                     { TRY_TO(TraverseTypeLoc(TL.getModifiedLoc())); })
+
+DEF_TRAVERSE_TYPELOC(ElaboratedType, {
+  if (TL.getQualifierLoc()) {
+    TRY_TO(TraverseNestedNameSpecifierLoc(TL.getQualifierLoc()));
+  }
+  TRY_TO(TraverseTypeLoc(TL.getNamedTypeLoc()));
+})
+
+DEF_TRAVERSE_TYPELOC(DependentNameType, {
+  TRY_TO(TraverseNestedNameSpecifierLoc(TL.getQualifierLoc()));
+})
+
+DEF_TRAVERSE_TYPELOC(DependentTemplateSpecializationType, {
+  if (TL.getQualifierLoc()) {
+    TRY_TO(TraverseNestedNameSpecifierLoc(TL.getQualifierLoc()));
+  }
+
+  for (unsigned I = 0, E = TL.getNumArgs(); I != E; ++I) {
+    TRY_TO(TraverseTemplateArgumentLoc(TL.getArgLoc(I)));
+  }
+})
+
+DEF_TRAVERSE_TYPELOC(PackExpansionType,
+                     { TRY_TO(TraverseTypeLoc(TL.getPatternLoc())); })
+
+DEF_TRAVERSE_TYPELOC(ObjCInterfaceType, {})
+
+DEF_TRAVERSE_TYPELOC(ObjCObjectType, {
+  // We have to watch out here because an ObjCInterfaceType's base
+  // type is itself.
+  if (TL.getTypePtr()->getBaseType().getTypePtr() != TL.getTypePtr())
+    TRY_TO(TraverseTypeLoc(TL.getBaseLoc()));
+})
+
+DEF_TRAVERSE_TYPELOC(ObjCObjectPointerType,
+                     { TRY_TO(TraverseTypeLoc(TL.getPointeeLoc())); })
+
+DEF_TRAVERSE_TYPELOC(AtomicType, { TRY_TO(TraverseTypeLoc(TL.getValueLoc())); })
+
+#undef DEF_TRAVERSE_TYPELOC
+
+// ----------------- Decl traversal -----------------
+//
+// For a Decl, we automate (in the DEF_TRAVERSE_DECL macro) traversing
+// the children that come from the DeclContext associated with it.
+// Therefore each Traverse* only needs to worry about children other
+// than those.
+
+template 
+bool RecursiveASTVisitor::TraverseDeclContextHelper(DeclContext *DC) {
+  if (!DC)
+    return true;
+
+  for (auto *Child : DC->decls()) {
+    // BlockDecls and CapturedDecls are traversed through BlockExprs and
+    // CapturedStmts respectively.
+    if (!isa(Child) && !isa(Child))
+      TRY_TO(TraverseDecl(Child));
+  }
+
+  return true;
+}
+
+// This macro makes available a variable D, the passed-in decl.
+#define DEF_TRAVERSE_DECL(DECL, CODE)                                          \
+  template                                                   \
+  bool RecursiveASTVisitor::Traverse##DECL(DECL *D) {                 \
+    TRY_TO(WalkUpFrom##DECL(D));                                               \
+    { CODE; }                                                                  \
+    TRY_TO(TraverseDeclContextHelper(dyn_cast(D)));               \
+    return true;                                                               \
+  }
+
+DEF_TRAVERSE_DECL(AccessSpecDecl, {})
+
+DEF_TRAVERSE_DECL(BlockDecl, {
+  if (TypeSourceInfo *TInfo = D->getSignatureAsWritten())
+    TRY_TO(TraverseTypeLoc(TInfo->getTypeLoc()));
+  TRY_TO(TraverseStmt(D->getBody()));
+  for (const auto &I : D->captures()) {
+    if (I.hasCopyExpr()) {
+      TRY_TO(TraverseStmt(I.getCopyExpr()));
+    }
+  }
+  // This return statement makes sure the traversal of nodes in
+  // decls_begin()/decls_end() (done in the DEF_TRAVERSE_DECL macro)
+  // is skipped - don't remove it.
+  return true;
+})
+
+DEF_TRAVERSE_DECL(CapturedDecl, {
+  TRY_TO(TraverseStmt(D->getBody()));
+  // This return statement makes sure the traversal of nodes in
+  // decls_begin()/decls_end() (done in the DEF_TRAVERSE_DECL macro)
+  // is skipped - don't remove it.
+  return true;
+})
+
+DEF_TRAVERSE_DECL(EmptyDecl, {})
+
+DEF_TRAVERSE_DECL(FileScopeAsmDecl,
+                  { TRY_TO(TraverseStmt(D->getAsmString())); })
+
+DEF_TRAVERSE_DECL(ImportDecl, {})
+
+DEF_TRAVERSE_DECL(FriendDecl, {
+  // Friend is either decl or a type.
+  if (D->getFriendType())
+    TRY_TO(TraverseTypeLoc(D->getFriendType()->getTypeLoc()));
+  else
+    TRY_TO(TraverseDecl(D->getFriendDecl()));
+})
+
+DEF_TRAVERSE_DECL(FriendTemplateDecl, {
+  if (D->getFriendType())
+    TRY_TO(TraverseTypeLoc(D->getFriendType()->getTypeLoc()));
+  else
+    TRY_TO(TraverseDecl(D->getFriendDecl()));
+  for (unsigned I = 0, E = D->getNumTemplateParameters(); I < E; ++I) {
+    TemplateParameterList *TPL = D->getTemplateParameterList(I);
+    for (TemplateParameterList::iterator ITPL = TPL->begin(), ETPL = TPL->end();
+         ITPL != ETPL; ++ITPL) {
+      TRY_TO(TraverseDecl(*ITPL));
+    }
+  }
+})
+
+DEF_TRAVERSE_DECL(ClassScopeFunctionSpecializationDecl,
+                  { TRY_TO(TraverseDecl(D->getSpecialization())); })
+
+DEF_TRAVERSE_DECL(LinkageSpecDecl, {})
+
+DEF_TRAVERSE_DECL(ObjCPropertyImplDecl, {// FIXME: implement this
+                                        })
+
+DEF_TRAVERSE_DECL(StaticAssertDecl, {
+  TRY_TO(TraverseStmt(D->getAssertExpr()));
+  TRY_TO(TraverseStmt(D->getMessage()));
+})
+
+DEF_TRAVERSE_DECL(
+    TranslationUnitDecl,
+    {// Code in an unnamed namespace shows up automatically in
+     // decls_begin()/decls_end().  Thus we don't need to recurse on
+     // D->getAnonymousNamespace().
+    })
+
+DEF_TRAVERSE_DECL(NamespaceAliasDecl, {
+  // We shouldn't traverse an aliased namespace, since it will be
+  // defined (and, therefore, traversed) somewhere else.
+  //
+  // This return statement makes sure the traversal of nodes in
+  // decls_begin()/decls_end() (done in the DEF_TRAVERSE_DECL macro)
+  // is skipped - don't remove it.
+  return true;
+})
+
+DEF_TRAVERSE_DECL(LabelDecl, {// There is no code in a LabelDecl.
+                             })
+
+DEF_TRAVERSE_DECL(
+    NamespaceDecl,
+    {// Code in an unnamed namespace shows up automatically in
+     // decls_begin()/decls_end().  Thus we don't need to recurse on
+     // D->getAnonymousNamespace().
+    })
+
+DEF_TRAVERSE_DECL(ObjCCompatibleAliasDecl, {// FIXME: implement
+                                           })
+
+DEF_TRAVERSE_DECL(ObjCCategoryDecl, {// FIXME: implement
+                                    })
+
+DEF_TRAVERSE_DECL(ObjCCategoryImplDecl, {// FIXME: implement
+                                        })
+
+DEF_TRAVERSE_DECL(ObjCImplementationDecl, {// FIXME: implement
+                                          })
+
+DEF_TRAVERSE_DECL(ObjCInterfaceDecl, {// FIXME: implement
+                                     })
+
+DEF_TRAVERSE_DECL(ObjCProtocolDecl, {// FIXME: implement
+                                    })
+
+DEF_TRAVERSE_DECL(ObjCMethodDecl, {
+  if (D->getReturnTypeSourceInfo()) {
+    TRY_TO(TraverseTypeLoc(D->getReturnTypeSourceInfo()->getTypeLoc()));
+  }
+  for (ObjCMethodDecl::param_iterator I = D->param_begin(), E = D->param_end();
+       I != E; ++I) {
+    TRY_TO(TraverseDecl(*I));
+  }
+  if (D->isThisDeclarationADefinition()) {
+    TRY_TO(TraverseStmt(D->getBody()));
+  }
+  return true;
+})
+
+DEF_TRAVERSE_DECL(ObjCPropertyDecl, {
+  if (D->getTypeSourceInfo())
+    TRY_TO(TraverseTypeLoc(D->getTypeSourceInfo()->getTypeLoc()));
+  else
+    TRY_TO(TraverseType(D->getType()));
+  return true;
+})
+
+DEF_TRAVERSE_DECL(UsingDecl, {
+  TRY_TO(TraverseNestedNameSpecifierLoc(D->getQualifierLoc()));
+  TRY_TO(TraverseDeclarationNameInfo(D->getNameInfo()));
+})
+
+DEF_TRAVERSE_DECL(UsingDirectiveDecl, {
+  TRY_TO(TraverseNestedNameSpecifierLoc(D->getQualifierLoc()));
+})
+
+DEF_TRAVERSE_DECL(UsingShadowDecl, {})
+
+DEF_TRAVERSE_DECL(OMPThreadPrivateDecl, {
+  for (auto *I : D->varlists()) {
+    TRY_TO(TraverseStmt(I));
+  }
+})
+
+// A helper method for TemplateDecl's children.
+template 
+bool RecursiveASTVisitor::TraverseTemplateParameterListHelper(
+    TemplateParameterList *TPL) {
+  if (TPL) {
+    for (TemplateParameterList::iterator I = TPL->begin(), E = TPL->end();
+         I != E; ++I) {
+      TRY_TO(TraverseDecl(*I));
+    }
+  }
+  return true;
+}
+
+// A helper method for traversing the implicit instantiations of a
+// class template.
+template 
+bool RecursiveASTVisitor::TraverseClassInstantiations(
+    ClassTemplateDecl *D) {
+  for (auto *SD : D->specializations()) {
+    for (auto *RD : SD->redecls()) {
+      // We don't want to visit injected-class-names in this traversal.
+      if (cast(RD)->isInjectedClassName())
+        continue;
+
+      switch (
+          cast(RD)->getSpecializationKind()) {
+      // Visit the implicit instantiations with the requested pattern.
+      case TSK_Undeclared:
+      case TSK_ImplicitInstantiation:
+        TRY_TO(TraverseDecl(RD));
+        break;
+
+      // We don't need to do anything on an explicit instantiation
+      // or explicit specialization because there will be an explicit
+      // node for it elsewhere.
+      case TSK_ExplicitInstantiationDeclaration:
+      case TSK_ExplicitInstantiationDefinition:
+      case TSK_ExplicitSpecialization:
+        break;
+      }
+    }
+  }
+
+  return true;
+}
+
+DEF_TRAVERSE_DECL(ClassTemplateDecl, {
+  CXXRecordDecl *TempDecl = D->getTemplatedDecl();
+  TRY_TO(TraverseDecl(TempDecl));
+  TRY_TO(TraverseTemplateParameterListHelper(D->getTemplateParameters()));
+
+  // By default, we do not traverse the instantiations of
+  // class templates since they do not appear in the user code. The
+  // following code optionally traverses them.
+  //
+  // We only traverse the class instantiations when we see the canonical
+  // declaration of the template, to ensure we only visit them once.
+  if (getDerived().shouldVisitTemplateInstantiations() &&
+      D == D->getCanonicalDecl())
+    TRY_TO(TraverseClassInstantiations(D));
+
+  // Note that getInstantiatedFromMemberTemplate() is just a link
+  // from a template instantiation back to the template from which
+  // it was instantiated, and thus should not be traversed.
+})
+
+// A helper method for traversing the implicit instantiations of a
+// class template.
+template 
+bool RecursiveASTVisitor::TraverseVariableInstantiations(
+    VarTemplateDecl *D) {
+  for (auto *SD : D->specializations()) {
+    for (auto *RD : SD->redecls()) {
+      switch (
+          cast(RD)->getSpecializationKind()) {
+      // Visit the implicit instantiations with the requested pattern.
+      case TSK_Undeclared:
+      case TSK_ImplicitInstantiation:
+        TRY_TO(TraverseDecl(RD));
+        break;
+
+      // We don't need to do anything on an explicit instantiation
+      // or explicit specialization because there will be an explicit
+      // node for it elsewhere.
+      case TSK_ExplicitInstantiationDeclaration:
+      case TSK_ExplicitInstantiationDefinition:
+      case TSK_ExplicitSpecialization:
+        break;
+      }
+    }
+  }
+
+  return true;
+}
+
+DEF_TRAVERSE_DECL(VarTemplateDecl, {
+  VarDecl *TempDecl = D->getTemplatedDecl();
+  TRY_TO(TraverseDecl(TempDecl));
+  TRY_TO(TraverseTemplateParameterListHelper(D->getTemplateParameters()));
+
+  // By default, we do not traverse the instantiations of
+  // variable templates since they do not appear in the user code. The
+  // following code optionally traverses them.
+  //
+  // We only traverse the variable instantiations when we see the canonical
+  // declaration of the template, to ensure we only visit them once.
+  if (getDerived().shouldVisitTemplateInstantiations() &&
+      D == D->getCanonicalDecl())
+    TRY_TO(TraverseVariableInstantiations(D));
+
+  // Note that getInstantiatedFromMemberTemplate() is just a link
+  // from a template instantiation back to the template from which
+  // it was instantiated, and thus should not be traversed.
+})
+
+// A helper method for traversing the instantiations of a
+// function while skipping its specializations.
+template 
+bool RecursiveASTVisitor::TraverseFunctionInstantiations(
+    FunctionTemplateDecl *D) {
+  for (auto *FD : D->specializations()) {
+    for (auto *RD : FD->redecls()) {
+      switch (RD->getTemplateSpecializationKind()) {
+      case TSK_Undeclared:
+      case TSK_ImplicitInstantiation:
+        // We don't know what kind of FunctionDecl this is.
+        TRY_TO(TraverseDecl(RD));
+        break;
+
+      // No need to visit explicit instantiations, we'll find the node
+      // eventually.
+      // FIXME: This is incorrect; there is no other node for an explicit
+      // instantiation of a function template specialization.
+      case TSK_ExplicitInstantiationDeclaration:
+      case TSK_ExplicitInstantiationDefinition:
+        break;
+
+      case TSK_ExplicitSpecialization:
+        break;
+      }
+    }
+  }
+
+  return true;
+}
+
+DEF_TRAVERSE_DECL(FunctionTemplateDecl, {
+  TRY_TO(TraverseDecl(D->getTemplatedDecl()));
+  TRY_TO(TraverseTemplateParameterListHelper(D->getTemplateParameters()));
+
+  // By default, we do not traverse the instantiations of
+  // function templates since they do not appear in the user code. The
+  // following code optionally traverses them.
+  //
+  // We only traverse the function instantiations when we see the canonical
+  // declaration of the template, to ensure we only visit them once.
+  if (getDerived().shouldVisitTemplateInstantiations() &&
+      D == D->getCanonicalDecl())
+    TRY_TO(TraverseFunctionInstantiations(D));
+})
+
+DEF_TRAVERSE_DECL(TemplateTemplateParmDecl, {
+  // D is the "T" in something like
+  //   template