Merge branch 'master' of https://github.com/llvm-mirror/clang

.clang-tidy

@@ -1,4 +1,9 @@
-Checks: '-*,clang-diagnostic-*,llvm-*,misc-*,-misc-unused-parameters,readability-identifier-naming'
+Checks: '-*,clang-diagnostic-*,llvm-*,misc-*,-misc-unused-parameters,-misc-non-private-member-variables-in-classes,-readability-identifier-naming'
+# Note that the readability-identifier-naming check is disabled, there are too
+# many violations in the codebase and they create too much noise in clang-tidy
+# results.
+# Naming settings are kept for documentation purposes and allowing to run the
+# check if the users would override this file, e.g. via a command-line arg.
 CheckOptions:
   - key:             readability-identifier-naming.ClassCase
     value:           CamelCase

.gitignore

@@ -1,9 +1,6 @@
 #==============================================================================#
 # This file specifies intentionally untracked files that git should ignore.
 # See: http://www.kernel.org/pub/software/scm/git/docs/gitignore.html
-#
-# This file is intentionally different from the output of `git svn show-ignore`,
-# as most of those are useless.
 #==============================================================================#
 
 #==============================================================================#
@@ -24,6 +21,7 @@
 #==============================================================================#
 cscope.files
 cscope.out
+/tags
 
 #==============================================================================#
 # Directories to ignore (do not add trailing '/'s, they skip symlinks).
@@ -35,3 +33,8 @@ docs/_build
 docs/analyzer/_build
 # debug info testsuite
 test/debuginfo-tests
+
+# VS2017 and VSCode config files.
+.vscode
+.vs
+

CMakeLists.txt

@@ -1,5 +1,9 @@
 cmake_minimum_required(VERSION 3.4.3)
 
+if(POLICY CMP0075)
+  cmake_policy(SET CMP0075 NEW)
+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 )
@@ -7,9 +11,14 @@ if( CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR )
 
   # Rely on llvm-config.
   set(CONFIG_OUTPUT)
-  find_program(LLVM_CONFIG "llvm-config")
   if(LLVM_CONFIG)
+    set (LLVM_CONFIG_FOUND 1)
     message(STATUS "Found LLVM_CONFIG as ${LLVM_CONFIG}")
+    message(DEPRECATION "Using llvm-config to detect the LLVM installation is \
+          deprecated.  The installed cmake files should be used \
+          instead.  CMake should be able to detect your LLVM install \
+          automatically, but you can also use LLVM_DIR to specify \
+          the path containing LLVMConfig.cmake.")
     set(CONFIG_COMMAND ${LLVM_CONFIG}
       "--assertion-mode"
       "--bindir"
@@ -32,17 +41,20 @@ if( CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR )
       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}")
+
+    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)
+    list(GET CONFIG_OUTPUT 6 LLVM_CONFIG_CMAKE_PATH)
+
+    # Normalize LLVM_CMAKE_PATH. --cmakedir might contain backslashes.
+    # CMake assumes slashes as PATH.
+    file(TO_CMAKE_PATH ${LLVM_CONFIG_CMAKE_PATH} LLVM_CMAKE_PATH)
   endif()
 
-  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)
-  list(GET CONFIG_OUTPUT 6 LLVM_CONFIG_CMAKE_PATH)
 
   if(NOT MSVC_IDE)
     set(LLVM_ENABLE_ASSERTIONS ${ENABLE_ASSERTIONS}
@@ -51,27 +63,34 @@ if( CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR )
     mark_as_advanced(LLVM_ENABLE_ASSERTIONS)
   endif()
 
+  find_package(LLVM REQUIRED HINTS "${LLVM_CMAKE_PATH}")
+  list(APPEND CMAKE_MODULE_PATH ${LLVM_DIR})
+
+  # We can't check LLVM_CONFIG here, because find_package(LLVM ...) also sets
+  # LLVM_CONFIG.
+  if (NOT LLVM_CONFIG_FOUND)
+    # Pull values from LLVMConfig.cmake.  We can drop this once the llvm-config
+    # path is removed.
+    set(TOOLS_BINARY_DIR ${LLVM_TOOLS_BINARY_DIR})
+    set(LIBRARY_DIR ${LLVM_LIBRARY_DIR})
+    set(INCLUDE_DIR ${LLVM_INCLUDE_DIR})
+    set(LLVM_OBJ_DIR ${LLVM_BINARY_DIR})
+    # The LLVM_CMAKE_PATH variable is set when doing non-standalone builds and
+    # used in this project, so we need to make sure we set this value.
+    # FIXME: LLVM_CMAKE_DIR comes from LLVMConfig.cmake.  We should rename
+    # LLVM_CMAKE_PATH to LLVM_CMAKE_DIR throughout the project.
+    set(LLVM_CMAKE_PATH ${LLVM_CMAKE_DIR})
+  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")
 
-  # Normalize LLVM_CMAKE_PATH. --cmakedir might contain backslashes.
-  # CMake assumes slashes as PATH.
-  file(TO_CMAKE_PATH ${LLVM_CONFIG_CMAKE_PATH} LLVM_CMAKE_PATH)
-
   find_program(LLVM_TABLEGEN_EXE "llvm-tblgen" ${LLVM_TOOLS_BINARY_DIR}
     NO_DEFAULT_PATH)
 
-  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 "Not found: ${LLVMCONFIG_FILE}")
-  endif()
-
   # 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${LLVM_LIBDIR_SUFFIX})
@@ -89,11 +108,13 @@ if( CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR )
   option(LLVM_FORCE_USE_OLD_HOST_TOOLCHAIN
     "Set to ON to force using an old, unsupported host toolchain." OFF)
   option(CLANG_ENABLE_BOOTSTRAP "Generate the clang bootstrap target" OFF)
+  option(LLVM_ENABLE_LIBXML2 "Use libxml2 if available." ON)
 
   include(AddLLVM)
   include(TableGen)
   include(HandleLLVMOptions)
   include(VersionFromVCS)
+  include(LLVMDistributionSupport)
 
   set(PACKAGE_VERSION "${LLVM_PACKAGE_VERSION}")
 
@@ -109,7 +130,6 @@ if( CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR )
   set( CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib${LLVM_LIBDIR_SUFFIX} )
 
   if(LLVM_INCLUDE_TESTS)
-    set(Python_ADDITIONAL_VERSIONS 2.7)
     include(FindPythonInterp)
     if(NOT PYTHONINTERP_FOUND)
       message(FATAL_ERROR
@@ -184,13 +204,15 @@ endif()
 # we can include cmake files from this directory.
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules")
 
-# Don't look for libxml if we're using MSan, since uninstrumented third party
-# code may call MSan interceptors like strlen, leading to false positives.
-if(NOT LLVM_USE_SANITIZER MATCHES "Memory.*")
-  set (LIBXML2_FOUND 0)
-  find_package(LibXml2 2.5.3 QUIET)
-  if (LIBXML2_FOUND)
-    set(CLANG_HAVE_LIBXML 1)
+if(LLVM_ENABLE_LIBXML2)
+  # Don't look for libxml if we're using MSan, since uninstrumented third party
+  # code may call MSan interceptors like strlen, leading to false positives.
+  if(NOT LLVM_USE_SANITIZER MATCHES "Memory.*")
+    set (LIBXML2_FOUND 0)
+    find_package(LibXml2 2.5.3 QUIET)
+    if (LIBXML2_FOUND)
+      set(CLANG_HAVE_LIBXML 1)
+    endif()
   endif()
 endif()
 
@@ -244,6 +266,25 @@ if (NOT(CLANG_DEFAULT_RTLIB STREQUAL "" OR
     "Default runtime library to use (\"libgcc\" or \"compiler-rt\", empty for platform default)" FORCE)
 endif()
 
+set(CLANG_DEFAULT_UNWINDLIB "" CACHE STRING
+  "Default unwind library to use (\"none\" \"libgcc\" or \"libunwind\", empty to match runtime library.)")
+if (CLANG_DEFAULT_UNWINDLIB STREQUAL "")
+  if (CLANG_DEFAULT_RTLIB STREQUAL "libgcc")
+    set (CLANG_DEFAULT_UNWINDLIB "libgcc" CACHE STRING "" FORCE)
+  elseif (CLANG_DEFAULT_RTLIBS STREQUAL "libunwind")
+    set (CLANG_DEFAULT_UNWINDLIB "none" CACHE STRING "" FORCE)
+  endif()
+endif()
+
+if (NOT(CLANG_DEFAULT_UNWINDLIB STREQUAL "" OR
+        CLANG_DEFAULT_UNWINDLIB STREQUAL "none" OR
+        CLANG_DEFAULT_UNWINDLIB STREQUAL "libgcc" OR
+        CLANG_DEFAULT_UNWINDLIB STREQUAL "libunwind"))
+  message(WARNING "Resetting default unwindlib to use platform default")
+  set(CLANG_DEFAULT_UNWINDLIB "" CACHE STRING
+    "Default unwind library to use (\"none\" \"libgcc\" or \"libunwind\", empty for none)" FORCE)
+endif()
+
 set(CLANG_DEFAULT_OBJCOPY "objcopy" CACHE STRING
   "Default objcopy executable to use.")
 
@@ -279,6 +320,17 @@ endif()
 set(CLANG_VENDOR_UTI "org.llvm.clang" CACHE STRING
   "Vendor-specific uti.")
 
+set(CLANG_PYTHON_BINDINGS_VERSIONS "" CACHE STRING
+    "Python versions to install libclang python bindings for")
+
+set(CLANG_LINK_CLANG_DYLIB ${LLVM_LINK_LLVM_DYLIB} CACHE BOOL
+    "Link tools against libclang-cpp.so")
+
+if (NOT LLVM_LINK_LLVM_DYLIB AND CLANG_LINK_CLANG_DYLIB)
+  message(FATAL_ERROR "Cannot set CLANG_LINK_CLANG_DYLIB=ON when "
+                      "LLVM_LINK_LLVM_DYLIB=OFF")
+endif()
+
 # The libdir suffix must exactly match whatever LLVM's configuration used.
 set(CLANG_LIBDIR_SUFFIX "${LLVM_LIBDIR_SUFFIX}")
 
@@ -286,25 +338,13 @@ set(CLANG_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
 set(CLANG_BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR})
 
 if( CMAKE_SOURCE_DIR STREQUAL CMAKE_BINARY_DIR AND NOT MSVC_IDE )
-  message(FATAL_ERROR "In-source builds are not allowed. CMake would overwrite "
-"the makefiles distributed with LLVM. Please create a directory and run cmake "
+  message(FATAL_ERROR "In-source builds are not allowed. "
+"Please create a directory and run cmake "
 "from there, passing the path to this source directory as the last argument. "
 "This process created the file `CMakeCache.txt' and the directory "
 "`CMakeFiles'. Please delete them.")
 endif()
 
-if( NOT CMAKE_SOURCE_DIR STREQUAL CMAKE_BINARY_DIR )
-  file(GLOB_RECURSE
-    tablegenned_files_on_include_dir
-    "${CLANG_SOURCE_DIR}/include/clang/*.inc")
-  if( tablegenned_files_on_include_dir )
-    message(FATAL_ERROR "Apparently there is a previous in-source build, "
-"probably as the result of running `configure' and `make' on "
-"${CLANG_SOURCE_DIR}. This may cause problems. The suspicious files are:\n"
-"${tablegenned_files_on_include_dir}\nPlease clean the source directory.")
-  endif()
-endif()
-
 # If CLANG_VERSION_* is specified, use it, if not use LLVM_VERSION_*.
 if(NOT DEFINED CLANG_VERSION_MAJOR)
   set(CLANG_VERSION_MAJOR ${LLVM_VERSION_MAJOR})
@@ -375,6 +415,7 @@ include_directories(BEFORE
 if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
   install(DIRECTORY include/clang include/clang-c
     DESTINATION include
+    COMPONENT clang-headers
     FILES_MATCHING
     PATTERN "*.def"
     PATTERN "*.h"
@@ -384,15 +425,32 @@ if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
 
   install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/include/clang
     DESTINATION include
+    COMPONENT clang-headers
     FILES_MATCHING
     PATTERN "CMakeFiles" EXCLUDE
     PATTERN "*.inc"
     PATTERN "*.h"
     )
 
+  # Installing the headers needs to depend on generating any public
+  # tablegen'd headers.
+  add_custom_target(clang-headers DEPENDS clang-tablegen-targets)
+  set_target_properties(clang-headers PROPERTIES FOLDER "Misc")
+  if(NOT LLVM_ENABLE_IDE)
+    add_llvm_install_targets(install-clang-headers
+                             DEPENDS clang-headers
+                             COMPONENT clang-headers)
+  endif()
+
+  add_custom_target(bash-autocomplete DEPENDS utils/bash-autocomplete.sh)
   install(PROGRAMS utils/bash-autocomplete.sh
-    DESTINATION share/clang
-    )
+          DESTINATION share/clang
+          COMPONENT bash-autocomplete)
+  if(NOT LLVM_ENABLE_IDE)
+    add_llvm_install_targets(install-bash-autocomplete
+                             DEPENDS bash-autocomplete
+                             COMPONENT bash-autocomplete)
+  endif()
 endif()
 
 add_definitions( -D_GNU_SOURCE )
@@ -403,24 +461,12 @@ option(CLANG_BUILD_TOOLS
 option(CLANG_ENABLE_ARCMT "Build ARCMT." ON)
 option(CLANG_ENABLE_STATIC_ANALYZER "Build static analyzer." ON)
 
-option(CLANG_ANALYZER_BUILD_Z3
-  "Build the static analyzer with the Z3 constraint manager." OFF)
-
 option(CLANG_ENABLE_PROTO_FUZZER "Build Clang protobuf fuzzer." OFF)
 
-if(NOT CLANG_ENABLE_STATIC_ANALYZER AND (CLANG_ENABLE_ARCMT OR CLANG_ANALYZER_BUILD_Z3))
+if(NOT CLANG_ENABLE_STATIC_ANALYZER AND CLANG_ENABLE_ARCMT)
   message(FATAL_ERROR "Cannot disable static analyzer while enabling ARCMT or Z3")
 endif()
 
-if(CLANG_ANALYZER_BUILD_Z3)
-  find_package(Z3 4.5)
-  if(Z3_FOUND)
-    set(CLANG_ANALYZER_WITH_Z3 1)
-  else()
-    message(FATAL_ERROR "Cannot find Z3 header file or shared library")
-  endif()
-endif()
-
 if(CLANG_ENABLE_ARCMT)
   set(CLANG_ENABLE_OBJC_REWRITER ON)
 endif()
@@ -494,6 +540,7 @@ if( CLANG_INCLUDE_TESTS )
       )
   endif()
   add_subdirectory(test)
+  add_subdirectory(bindings/python/tests)
 
   if(CLANG_BUILT_STANDALONE)
     # Add a global check rule now that all subdirectories have been traversed
@@ -502,11 +549,13 @@ if( CLANG_INCLUDE_TESTS )
     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)
+    get_property(LLVM_ADDITIONAL_TEST_TARGETS
+                 GLOBAL PROPERTY LLVM_ADDITIONAL_TEST_TARGETS)
     add_lit_target(check-all
       "Running all regression tests"
       ${LLVM_LIT_TESTSUITES}
       PARAMS ${LLVM_LIT_PARAMS}
-      DEPENDS ${LLVM_LIT_DEPENDS}
+      DEPENDS ${LLVM_LIT_DEPENDS} ${LLVM_ADDITIONAL_TEST_TARGETS}
       ARGS ${LLVM_LIT_EXTRA_ARGS}
       )
   endif()
@@ -519,6 +568,27 @@ if( CLANG_INCLUDE_DOCS )
   add_subdirectory(docs)
 endif()
 
+# Custom target to install all clang libraries.
+add_custom_target(clang-libraries)
+set_target_properties(clang-libraries PROPERTIES FOLDER "Misc")
+
+if(NOT LLVM_ENABLE_IDE)
+  add_llvm_install_targets(install-clang-libraries
+                           DEPENDS clang-libraries
+                           COMPONENT clang-libraries)
+endif()
+
+get_property(CLANG_LIBS GLOBAL PROPERTY CLANG_LIBS)
+if(CLANG_LIBS)
+  list(REMOVE_DUPLICATES CLANG_LIBS)
+  foreach(lib ${CLANG_LIBS})
+    add_dependencies(clang-libraries ${lib})
+    if(NOT LLVM_ENABLE_IDE)
+      add_dependencies(install-clang-libraries install-${lib})
+    endif()
+  endforeach()
+endif()
+
 add_subdirectory(cmake/modules)
 
 if(CLANG_STAGE)
@@ -578,11 +648,15 @@ if (CLANG_ENABLE_BOOTSTRAP)
       if(NOT BOOTSTRAP_LLVM_ENABLE_LLD AND LLVM_BINUTILS_INCDIR)
         add_dependencies(clang-bootstrap-deps LLVMgold)
       endif()
-      set(LTO_AR -DCMAKE_AR=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-ar)
-      set(LTO_RANLIB -DCMAKE_RANLIB=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-ranlib)
+      set(${CLANG_STAGE}_AR -DCMAKE_AR=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-ar)
+      set(${CLANG_STAGE}_RANLIB -DCMAKE_RANLIB=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-ranlib)
     endif()
   endif()
 
+  if(CLANG_BOOTSTRAP_EXTRA_DEPS)
+    add_dependencies(clang-bootstrap-deps ${CLANG_BOOTSTRAP_EXTRA_DEPS})
+  endif()
+
   add_custom_target(${NEXT_CLANG_STAGE}-clear
     DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${NEXT_CLANG_STAGE}-cleared
     )
@@ -612,15 +686,22 @@ if (CLANG_ENABLE_BOOTSTRAP)
     LLVM_VERSION_SUFFIX
     LLVM_BINUTILS_INCDIR
     CLANG_REPOSITORY_STRING
+    CMAKE_C_COMPILER_LAUNCHER
+    CMAKE_CXX_COMPILER_LAUNCHER
     CMAKE_MAKE_PROGRAM
     CMAKE_OSX_ARCHITECTURES
     LLVM_ENABLE_PROJECTS
     LLVM_ENABLE_RUNTIMES)
 
-  # We don't need to depend on compiler-rt if we're building instrumented
+  # We don't need to depend on compiler-rt/libcxx if we're building instrumented
   # because the next stage will use the same compiler used to build this stage.
-  if(TARGET compiler-rt AND NOT LLVM_BUILD_INSTRUMENTED)
-    add_dependencies(clang-bootstrap-deps compiler-rt)
+  if(NOT LLVM_BUILD_INSTRUMENTED)
+    if(TARGET compiler-rt)
+      add_dependencies(clang-bootstrap-deps compiler-rt)
+    endif()
+    if(TARGET cxx-headers)
+      add_dependencies(clang-bootstrap-deps cxx-headers)
+    endif()
   endif()
 
   set(C_COMPILER "clang")
@@ -636,6 +717,26 @@ if (CLANG_ENABLE_BOOTSTRAP)
     -DCMAKE_ASM_COMPILER=${LLVM_RUNTIME_OUTPUT_INTDIR}/${C_COMPILER}
     -DCMAKE_ASM_COMPILER_ID=Clang)
 
+  if(BOOTSTRAP_CMAKE_SYSTEM_NAME)
+    set(${CLANG_STAGE}_CONFIG -DLLVM_CONFIG_PATH=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-config)
+    set(${CLANG_STAGE}_TABLEGEN
+      -DLLVM_TABLEGEN=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-tblgen
+      -DCLANG_TABLEGEN=${LLVM_RUNTIME_OUTPUT_INTDIR}/clang-tblgen)
+    if(BOOTSTRAP_CMAKE_SYSTEM_NAME STREQUAL "Linux")
+      if(BOOTSTRAP_LLVM_ENABLE_LLD)
+        set(${CLANG_STAGE}_LINKER -DCMAKE_LINKER=${LLVM_RUNTIME_OUTPUT_INTDIR}/ld.lld)
+      endif()
+      if(NOT BOOTSTRAP_LLVM_ENABLE_LTO)
+        add_dependencies(clang-bootstrap-deps llvm-ar llvm-ranlib)
+        set(${CLANG_STAGE}_AR -DCMAKE_AR=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-ar)
+        set(${CLANG_STAGE}_RANLIB -DCMAKE_RANLIB=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-ranlib)
+      endif()
+      add_dependencies(clang-bootstrap-deps llvm-objcopy llvm-strip)
+      set(${CLANG_STAGE}_OBJCOPY -DCMAKE_OBJCOPY=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-objcopy)
+      set(${CLANG_STAGE}_STRIP -DCMAKE_STRIP=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-strip)
+    endif()
+  endif()
+
   if(BOOTSTRAP_LLVM_BUILD_INSTRUMENTED)
     add_dependencies(clang-bootstrap-deps llvm-profdata)
     set(PGO_OPT -DLLVM_PROFDATA=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-profdata)
@@ -704,7 +805,14 @@ if (CLANG_ENABLE_BOOTSTRAP)
                 ${PASSTHROUGH_VARIABLES}
                  -DCLANG_STAGE=${NEXT_CLANG_STAGE}
                 ${COMPILER_OPTIONS}
-                ${LTO_LIBRARY} ${LTO_AR} ${LTO_RANLIB} ${verbose} ${PGO_OPT}
+                ${${CLANG_STAGE}_CONFIG}
+                ${${CLANG_STAGE}_TABLEGEN}
+                ${LTO_LIBRARY} ${verbose} ${PGO_OPT}
+                ${${CLANG_STAGE}_LINKER}
+                ${${CLANG_STAGE}_AR}
+                ${${CLANG_STAGE}_RANLIB}
+                ${${CLANG_STAGE}_OBJCOPY}
+                ${${CLANG_STAGE}_STRIP}
     INSTALL_COMMAND ""
     STEP_TARGETS configure build
     USES_TERMINAL_CONFIGURE 1
@@ -749,6 +857,11 @@ endif()
 if (LLVM_ADD_NATIVE_VISUALIZERS_TO_SOLUTION)
   add_subdirectory(utils/ClangVisualizers)
 endif()
+add_subdirectory(utils/hmaptool)
+
+if(CLANG_BUILT_STANDALONE)
+  llvm_distribution_add_targets()
+endif()
 
 configure_file(
   ${CLANG_SOURCE_DIR}/include/clang/Config/config.h.cmake

CODE_OWNERS.TXT

@@ -49,6 +49,10 @@ N: John McCall
 E: rjmccall@apple.com
 D: Clang LLVM IR generation
 
+N: Brad Smith
+E: brad@comstyle.com
+D: OpenBSD driver
+
 N: Richard Smith
 E: richard@metafoo.co.uk
 D: All parts of Clang not covered by someone else

LICENSE.TXT

@@ -1,10 +1,245 @@
 ==============================================================================
-LLVM Release License
+The LLVM Project is under the Apache License v2.0 with LLVM Exceptions:
+==============================================================================
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+    1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+    2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+    3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+    4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+    5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+    6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+    7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+    8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+    9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+    END OF TERMS AND CONDITIONS
+
+    APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+    Copyright [yyyy] [name of copyright owner]
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+
+---- LLVM Exceptions to the Apache 2.0 License ----
+
+As an exception, if, as a result of your compiling your source code, portions
+of this Software are embedded into an Object form of such source code, you
+may redistribute such embedded portions in such Object form without complying
+with the conditions of Sections 4(a), 4(b) and 4(d) of the License.
+
+In addition, if you combine or link compiled forms of this Software with
+software that is licensed under the GPLv2 ("Combined Software") and if a
+court of competent jurisdiction determines that the patent provision (Section
+3), the indemnity provision (Section 9) or other Section of the License
+conflicts with the conditions of the GPLv2, you may retroactively and
+prospectively choose to deem waived or otherwise exclude such Section(s) of
+the License, but only in their entirety and only with respect to the Combined
+Software.
+
+==============================================================================
+Software from third parties included in the LLVM Project:
+==============================================================================
+The LLVM Project contains third party software which is under different license
+terms. All such code will be identified clearly using at least one of two
+mechanisms:
+1) It will be in a separate directory tree with its own `LICENSE.txt` or
+   `LICENSE` file at the top containing the specific license and restrictions
+   which apply to that software, or
+2) It will contain specific license and restriction terms at the top of every
+   file.
+
+==============================================================================
+Legacy LLVM License (https://llvm.org/docs/DeveloperPolicy.html#legacy):
 ==============================================================================
 University of Illinois/NCSA
 Open Source License
 
-Copyright (c) 2007-2016 University of Illinois at Urbana-Champaign.
+Copyright (c) 2007-2019 University of Illinois at Urbana-Champaign.
 All rights reserved.
 
 Developed by:
@@ -41,23 +276,3 @@ CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE
 SOFTWARE.
-
-==============================================================================
-The LLVM software contains code written by third parties.  Such software will
-have its own individual LICENSE.TXT file in the directory in which it appears.
-This file will describe the copyrights, license, and restrictions which apply
-to that code.
-
-The disclaimer of warranty in the University of Illinois Open Source License
-applies to all code in the LLVM Distribution, and nothing in any of the
-other licenses gives permission to use the names of the LLVM Team or the
-University of Illinois to endorse or promote products derived from this
-Software.
-
-The following pieces of software have additional or alternate copyrights,
-licenses, and/or restrictions:
-
-Program             Directory
--------             ---------
-<none yet>
-

NOTES.txt

@@ -8,13 +8,6 @@ To time GCC preprocessing speed without output, use:
    "time gcc -MM file"
 This is similar to -Eonly.
 
-//===---------------------------------------------------------------------===//
-
-Creating and using a PTH file for performance measurement (use a release build).
-
-$ clang -ccc-pch-is-pth -x objective-c-header INPUTS/Cocoa_h.m -o /tmp/tokencache
-$ clang -cc1 -token-cache /tmp/tokencache INPUTS/Cocoa_h.m
-
 //===---------------------------------------------------------------------===//
 
   C++ Template Instantiation benchmark:

README.txt

@@ -24,4 +24,3 @@ on the Clang development mailing list:
 
 If you find a bug in Clang, please file it in the LLVM bug tracker:
   http://llvm.org/bugs/
-

bindings/python/README.txt

@@ -4,12 +4,12 @@
 
 This directory implements Python bindings for Clang.
 
-You may need to alter LD_LIBRARY_PATH so that the Clang library can be
+You may need to set CLANG_LIBRARY_PATH so that the Clang library can be
 found. The unit tests are designed to be run with any standard test
 runner. For example:
 --
 $ env PYTHONPATH=$(echo ~/llvm/tools/clang/bindings/python/) \
-      LD_LIBRARY_PATH=$(llvm-config --libdir) \
+      CLANG_LIBRARY_PATH=$(llvm-config --libdir) \
   python -m unittest discover -v
 tests.cindex.test_index.test_create ... ok
 ...

bindings/python/clang/__init__.py

@@ -1,9 +1,8 @@
 #===- __init__.py - Clang Python Bindings --------------------*- python -*--===#
 #
-#                     The LLVM Compiler Infrastructure
-#
-# This file is distributed under the University of Illinois Open Source
-# License. See LICENSE.TXT for details.
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 

bindings/python/clang/cindex.py

@@ -1,9 +1,8 @@
 #===- cindex.py - Python Indexing Library Bindings -----------*- python -*--===#
 #
-#                     The LLVM Compiler Infrastructure
-#
-# This file is distributed under the University of Illinois Open Source
-# License. See LICENSE.TXT for details.
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 
@@ -44,6 +43,7 @@ The major indexing objects are:
 Most object information is exposed using properties, when the underlying API
 call is efficient.
 """
+from __future__ import absolute_import, division, print_function
 
 # TODO
 # ====
@@ -63,10 +63,10 @@ call is efficient.
 # o implement additional SourceLocation, SourceRange, and File methods.
 
 from ctypes import *
-import collections
 
 import clang.enumerations
 
+import os
 import sys
 if sys.version_info[0] == 3:
     # Python 3 strings are unicode, translate them to/from utf8 for C-interop.
@@ -108,8 +108,6 @@ if sys.version_info[0] == 3:
             return x
         return x.encode('utf8')
 
-    xrange = range
-
 elif sys.version_info[0] == 2:
     # Python 2 strings are utf8 byte strings, no translation is needed for
     # C-interop.
@@ -123,6 +121,22 @@ elif sys.version_info[0] == 2:
     def b(x):
         return x
 
+# Importing ABC-s directly from collections is deprecated since Python 3.7,
+# will stop working in Python 3.8.
+# See: https://docs.python.org/dev/whatsnew/3.7.html#id3
+if sys.version_info[:2] >= (3, 7):
+    from collections import abc as collections_abc
+else:
+    import collections as collections_abc
+
+# We only support PathLike objects on Python version with os.fspath present
+# to be consistent with the Python standard library. On older Python versions
+# we only support strings and we have dummy fspath to just pass them through.
+try:
+    fspath = os.fspath
+except AttributeError:
+    def fspath(x):
+        return x
 
 # ctypes doesn't implicitly convert c_void_p to the appropriate wrapper
 # object. This is a problem, because it means that from_parameter will see an
@@ -391,7 +405,7 @@ class Diagnostic(object):
 
     @property
     def ranges(self):
-        class RangeIterator:
+        class RangeIterator(object):
             def __init__(self, diag):
                 self.diag = diag
 
@@ -407,7 +421,7 @@ class Diagnostic(object):
 
     @property
     def fixits(self):
-        class FixItIterator:
+        class FixItIterator(object):
             def __init__(self, diag):
                 self.diag = diag
 
@@ -427,7 +441,7 @@ class Diagnostic(object):
 
     @property
     def children(self):
-        class ChildDiagnosticsIterator:
+        class ChildDiagnosticsIterator(object):
             def __init__(self, diag):
                 self.diag_set = conf.lib.clang_getChildDiagnostics(diag)
 
@@ -547,7 +561,7 @@ class TokenGroup(object):
 
         token_group = TokenGroup(tu, tokens_memory, tokens_count)
 
-        for i in xrange(0, count):
+        for i in range(0, count):
             token = Token()
             token.int_data = tokens_array[i].int_data
             token.ptr_data = tokens_array[i].ptr_data
@@ -1328,6 +1342,10 @@ CursorKind.VISIBILITY_ATTR = CursorKind(417)
 
 CursorKind.DLLEXPORT_ATTR = CursorKind(418)
 CursorKind.DLLIMPORT_ATTR = CursorKind(419)
+CursorKind.CONVERGENT_ATTR = CursorKind(438)
+CursorKind.WARN_UNUSED_ATTR = CursorKind(439)
+CursorKind.WARN_UNUSED_RESULT_ATTR = CursorKind(440)
+CursorKind.ALIGNED_ATTR = CursorKind(441)
 
 ###
 # Preprocessing
@@ -1511,6 +1529,12 @@ class Cursor(Structure):
         another translation unit."""
         return conf.lib.clang_getCursorUSR(self)
 
+    def get_included_file(self):
+        """Returns the File that is included by the current inclusion cursor."""
+        assert self.kind == CursorKind.INCLUSION_DIRECTIVE
+
+        return conf.lib.clang_getIncludedFile(self)
+
     @property
     def kind(self):
         """Return the kind of this cursor."""
@@ -2097,6 +2121,8 @@ TypeKind.OCLEVENT = TypeKind(158)
 TypeKind.OCLQUEUE = TypeKind(159)
 TypeKind.OCLRESERVEID = TypeKind(160)
 
+TypeKind.EXTVECTOR = TypeKind(176)
+
 class RefQualifierKind(BaseEnumeration):
     """Describes a specific ref-qualifier of a type."""
 
@@ -2167,7 +2193,7 @@ class Type(Structure):
         The returned object is iterable and indexable. Each item in the
         container is a Type instance.
         """
-        class ArgumentsIterator(collections.Sequence):
+        class ArgumentsIterator(collections_abc.Sequence):
             def __init__(self, parent):
                 self.parent = parent
                 self.length = None
@@ -2248,6 +2274,12 @@ class Type(Structure):
 
         return res
 
+    def get_num_template_arguments(self):
+        return conf.lib.clang_Type_getNumTemplateArguments(self)
+
+    def get_template_argument_type(self, num):
+        return conf.lib.clang_Type_getTemplateArgumentAsType(self, num)
+
     def get_canonical(self):
         """
         Return the canonical type for a Type.
@@ -2454,8 +2486,8 @@ SpellingCache = {
             # 20: CompletionChunk.Kind("VerticalSpace")
 }
 
-class CompletionChunk:
-    class Kind:
+class CompletionChunk(object):
+    class Kind(object):
         def __init__(self, name):
             self.name = name
 
@@ -2542,7 +2574,7 @@ completionChunkKindMap = {
             20: CompletionChunk.Kind("VerticalSpace")}
 
 class CompletionString(ClangObject):
-    class Availability:
+    class Availability(object):
         def __init__(self, name):
             self.name = name
 
@@ -2635,7 +2667,7 @@ class CodeCompletionResults(ClangObject):
 
     @property
     def diagnostics(self):
-        class DiagnosticsItr:
+        class DiagnosticsItr(object):
             def __init__(self, ccr):
                 self.ccr= ccr
 
@@ -2740,11 +2772,11 @@ class TranslationUnit(ClangObject):
         etc. e.g. ["-Wall", "-I/path/to/include"].
 
         In-memory file content can be provided via unsaved_files. This is an
-        iterable of 2-tuples. The first element is the str filename. The
-        second element defines the content. Content can be provided as str
-        source code or as file objects (anything with a read() method). If
-        a file object is being used, content will be read until EOF and the
-        read cursor will not be reset to its original position.
+        iterable of 2-tuples. The first element is the filename (str or
+        PathLike). The second element defines the content. Content can be
+        provided as str source code or as file objects (anything with a read()
+        method). If a file object is being used, content will be read until EOF
+        and the read cursor will not be reset to its original position.
 
         options is a bitwise or of TranslationUnit.PARSE_XXX flags which will
         control parsing behavior.
@@ -2788,12 +2820,14 @@ class TranslationUnit(ClangObject):
             for i, (name, contents) in enumerate(unsaved_files):
                 if hasattr(contents, "read"):
                     contents = contents.read()
-
-                unsaved_array[i].name = b(name)
-                unsaved_array[i].contents = b(contents)
+                contents = b(contents)
+                unsaved_array[i].name = b(fspath(name))
+                unsaved_array[i].contents = contents
                 unsaved_array[i].length = len(contents)
 
-        ptr = conf.lib.clang_parseTranslationUnit(index, filename, args_array,
+        ptr = conf.lib.clang_parseTranslationUnit(index,
+                                    fspath(filename) if filename is not None else None,
+                                    args_array,
                                     len(args), unsaved_array,
                                     len(unsaved_files), options)
 
@@ -2814,11 +2848,13 @@ class TranslationUnit(ClangObject):
 
         index is optional and is the Index instance to use. If not provided,
         a default Index will be created.
+
+        filename can be str or PathLike.
         """
         if index is None:
             index = Index.create()
 
-        ptr = conf.lib.clang_createTranslationUnit(index, filename)
+        ptr = conf.lib.clang_createTranslationUnit(index, fspath(filename))
         if not ptr:
             raise TranslationUnitLoadError(filename)
 
@@ -2933,7 +2969,7 @@ class TranslationUnit(ClangObject):
         """
         Return an iterable (and indexable) object containing the diagnostics.
         """
-        class DiagIterator:
+        class DiagIterator(object):
             def __init__(self, tu):
                 self.tu = tu
 
@@ -2963,17 +2999,13 @@ class TranslationUnit(ClangObject):
         unsaved_files_array = 0
         if len(unsaved_files):
             unsaved_files_array = (_CXUnsavedFile * len(unsaved_files))()
-            for i,(name,value) in enumerate(unsaved_files):
-                if not isinstance(value, str):
-                    # FIXME: It would be great to support an efficient version
-                    # of this, one day.
-                    value = value.read()
-                    print(value)
-                if not isinstance(value, str):
-                    raise TypeError('Unexpected unsaved file contents.')
-                unsaved_files_array[i].name = name
-                unsaved_files_array[i].contents = value
-                unsaved_files_array[i].length = len(value)
+            for i,(name,contents) in enumerate(unsaved_files):
+                if hasattr(contents, "read"):
+                    contents = contents.read()
+                contents = b(contents)
+                unsaved_files_array[i].name = b(fspath(name))
+                unsaved_files_array[i].contents = contents
+                unsaved_files_array[i].length = len(contents)
         ptr = conf.lib.clang_reparseTranslationUnit(self, len(unsaved_files),
                 unsaved_files_array, options)
 
@@ -2990,10 +3022,10 @@ class TranslationUnit(ClangObject):
         case, the reason(s) why should be available via
         TranslationUnit.diagnostics().
 
-        filename -- The path to save the translation unit to.
+        filename -- The path to save the translation unit to (str or PathLike).
         """
         options = conf.lib.clang_defaultSaveOptions(self)
-        result = int(conf.lib.clang_saveTranslationUnit(self, filename,
+        result = int(conf.lib.clang_saveTranslationUnit(self, fspath(filename),
                                                         options))
         if result != 0:
             raise TranslationUnitSaveError(result,
@@ -3027,18 +3059,14 @@ class TranslationUnit(ClangObject):
         unsaved_files_array = 0
         if len(unsaved_files):
             unsaved_files_array = (_CXUnsavedFile * len(unsaved_files))()
-            for i,(name,value) in enumerate(unsaved_files):
-                if not isinstance(value, str):
-                    # FIXME: It would be great to support an efficient version
-                    # of this, one day.
-                    value = value.read()
-                    print(value)
-                if not isinstance(value, str):
-                    raise TypeError('Unexpected unsaved file contents.')
-                unsaved_files_array[i].name = b(name)
-                unsaved_files_array[i].contents = b(value)
-                unsaved_files_array[i].length = len(value)
-        ptr = conf.lib.clang_codeCompleteAt(self, path, line, column,
+            for i,(name,contents) in enumerate(unsaved_files):
+                if hasattr(contents, "read"):
+                    contents = contents.read()
+                contents = b(contents)
+                unsaved_files_array[i].name = b(fspath(name))
+                unsaved_files_array[i].contents = contents
+                unsaved_files_array[i].length = len(contents)
+        ptr = conf.lib.clang_codeCompleteAt(self, fspath(path), line, column,
                 unsaved_files_array, len(unsaved_files), options)
         if ptr:
             return CodeCompletionResults(ptr)
@@ -3066,7 +3094,7 @@ class File(ClangObject):
     @staticmethod
     def from_name(translation_unit, file_name):
         """Retrieve a file handle within the given translation unit."""
-        return File(conf.lib.clang_getFile(translation_unit, file_name))
+        return File(conf.lib.clang_getFile(translation_unit, fspath(file_name)))
 
     @property
     def name(self):
@@ -3085,8 +3113,9 @@ class File(ClangObject):
         return "<File: %s>" % (self.name)
 
     @staticmethod
-    def from_cursor_result(res, fn, args):
-        assert isinstance(res, File)
+    def from_result(res, fn, args):
+        assert isinstance(res, c_object_p)
+        res = File(res)
 
         # Copy a reference to the TranslationUnit to prevent premature GC.
         res._tu = args[0]._tu
@@ -3164,7 +3193,7 @@ class CompileCommand(object):
         Invariant : the first argument is the compiler executable
         """
         length = conf.lib.clang_CompileCommand_getNumArgs(self.cmd)
-        for i in xrange(length):
+        for i in range(length):
             yield conf.lib.clang_CompileCommand_getArg(self.cmd, i)
 
 class CompileCommands(object):
@@ -3216,7 +3245,7 @@ class CompilationDatabase(ClangObject):
         """Builds a CompilationDatabase from the database found in buildDir"""
         errorCode = c_uint()
         try:
-            cdb = conf.lib.clang_CompilationDatabase_fromDirectory(buildDir,
+            cdb = conf.lib.clang_CompilationDatabase_fromDirectory(fspath(buildDir),
                 byref(errorCode))
         except CompilationDatabaseError as e:
             raise CompilationDatabaseError(int(errorCode.value),
@@ -3229,7 +3258,7 @@ class CompilationDatabase(ClangObject):
         build filename. Returns None if filename is not found in the database.
         """
         return conf.lib.clang_CompilationDatabase_getCompileCommands(self,
-                                                                     filename)
+                                                                     fspath(filename))
 
     def getAllCompileCommands(self):
         """
@@ -3701,8 +3730,8 @@ functionList = [
 
   ("clang_getIncludedFile",
    [Cursor],
-   File,
-   File.from_cursor_result),
+   c_object_p,
+   File.from_result),
 
   ("clang_getInclusions",
    [TranslationUnit, callbacks['translation_unit_includes'], py_object]),
@@ -3992,6 +4021,15 @@ functionList = [
    Type,
    Type.from_result),
 
+  ("clang_Type_getNumTemplateArguments",
+   [Type],
+   c_int),
+
+  ("clang_Type_getTemplateArgumentAsType",
+   [Type, c_uint],
+   Type,
+   Type.from_result),
+
   ("clang_Type_getOffsetOf",
    [Type, c_interop_string],
    c_longlong),
@@ -4055,7 +4093,7 @@ def register_functions(lib, ignore_errors):
     for f in functionList:
         register(f)
 
-class Config:
+class Config(object):
     library_path = None
     library_file = None
     compatibility_check = True
@@ -4068,7 +4106,7 @@ class Config:
             raise Exception("library path must be set before before using " \
                             "any other functionalities in libclang.")
 
-        Config.library_path = path
+        Config.library_path = fspath(path)
 
     @staticmethod
     def set_library_file(filename):
@@ -4077,7 +4115,7 @@ class Config:
             raise Exception("library file must be set before before using " \
                             "any other functionalities in libclang.")
 
-        Config.library_file = filename
+        Config.library_file = fspath(filename)
 
     @staticmethod
     def set_compatibility_check(check_status):

bindings/python/clang/enumerations.py

@@ -1,9 +1,8 @@
 #===- enumerations.py - Python Enumerations ------------------*- python -*--===#
 #
-#                     The LLVM Compiler Infrastructure
-#
-# This file is distributed under the University of Illinois Open Source
-# License. See LICENSE.TXT for details.
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 

bindings/python/examples/cindex/cindex-dump.py

@@ -2,10 +2,9 @@
 
 #===- cindex-dump.py - cindex/Python Source Dump -------------*- python -*--===#
 #
-#                     The LLVM Compiler Infrastructure
-#
-# This file is distributed under the University of Illinois Open Source
-# License. See LICENSE.TXT for details.
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 
@@ -79,7 +78,7 @@ def main():
     if not tu:
         parser.error("unable to load input")
 
-    pprint(('diags', map(get_diag_info, tu.diagnostics)))
+    pprint(('diags', [get_diag_info(d) for d in  tu.diagnostics]))
     pprint(('nodes', get_info(tu.cursor)))
 
 if __name__ == '__main__':

bindings/python/examples/cindex/cindex-includes.py

@@ -2,10 +2,9 @@
 
 #===- cindex-includes.py - cindex/Python Inclusion Graph -----*- python -*--===#
 #
-#                     The LLVM Compiler Infrastructure
-#
-# This file is distributed under the University of Illinois Open Source
-# License. See LICENSE.TXT for details.
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 

bindings/python/tests/CMakeLists.txt

@@ -0,0 +1,46 @@
+# Test target to run Python test suite from main build.
+
+add_custom_target(check-clang-python
+    COMMAND ${CMAKE_COMMAND} -E env
+            CLANG_LIBRARY_PATH=$<TARGET_FILE_DIR:libclang>
+            ${PYTHON_EXECUTABLE} -m unittest discover
+    DEPENDS libclang
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/..)
+
+set(RUN_PYTHON_TESTS TRUE)
+set_target_properties(check-clang-python PROPERTIES FOLDER "Clang tests")
+
+# Tests require libclang.so which is only built with LLVM_ENABLE_PIC=ON
+if(NOT LLVM_ENABLE_PIC)
+  set(RUN_PYTHON_TESTS FALSE)
+endif()
+
+# Do not try to run if libclang was built with ASan because
+# the sanitizer library will likely be loaded too late to perform
+# interception and will then fail.
+# We could use LD_PRELOAD/DYLD_INSERT_LIBRARIES but this isn't
+# portable so its easier just to not run the tests when building
+# with ASan.
+list(FIND LLVM_USE_SANITIZER "Address" LLVM_USE_ASAN_INDEX)
+if(NOT LLVM_USE_ASAN_INDEX EQUAL -1)
+  set(RUN_PYTHON_TESTS FALSE)
+endif()
+
+# Tests fail on Windows, and need someone knowledgeable to fix.
+# It's not clear whether it's a test or a valid binding problem.
+if(WIN32)
+  set(RUN_PYTHON_TESTS FALSE)
+endif()
+
+# AArch64, Hexagon, and Sparc have known test failures that need to be
+# addressed.
+# SystemZ has broken Python/FFI interface:
+# https://reviews.llvm.org/D52840#1265716
+if(${LLVM_NATIVE_ARCH} MATCHES "^(AArch64|Hexagon|Sparc|SystemZ)$")
+  set(RUN_PYTHON_TESTS FALSE)
+endif()
+
+if(RUN_PYTHON_TESTS)
+    set_property(GLOBAL APPEND PROPERTY
+                 LLVM_ADDITIONAL_TEST_TARGETS check-clang-python)
+endif()

bindings/python/tests/cindex/test_access_specifiers.py

@@ -1,3 +1,7 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
 
 from clang.cindex import AccessSpecifier
 from clang.cindex import Cursor

bindings/python/tests/cindex/test_cdb.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import CompilationDatabase
 from clang.cindex import CompilationDatabaseError
 from clang.cindex import CompileCommands
@@ -5,17 +10,30 @@ from clang.cindex import CompileCommand
 import os
 import gc
 import unittest
+import sys
+from .util import skip_if_no_fspath
+from .util import str_to_path
 
 
 kInputsDir = os.path.join(os.path.dirname(__file__), 'INPUTS')
 
 
+@unittest.skipIf(sys.platform == 'win32', "TODO: Fix these tests on Windows")
 class TestCDB(unittest.TestCase):
     def test_create_fail(self):
         """Check we fail loading a database with an assertion"""
         path = os.path.dirname(__file__)
+
+        # clang_CompilationDatabase_fromDirectory calls fprintf(stderr, ...)
+        # Suppress its output.
+        stderr = os.dup(2)
+        with open(os.devnull, 'wb') as null:
+            os.dup2(null.fileno(), 2)
         with self.assertRaises(CompilationDatabaseError) as cm:
             cdb = CompilationDatabase.fromDirectory(path)
+        os.dup2(stderr, 2)
+        os.close(stderr)
+
         e = cm.exception
         self.assertEqual(e.cdb_error,
             CompilationDatabaseError.ERROR_CANNOTLOADDATABASE)
@@ -24,17 +42,19 @@ class TestCDB(unittest.TestCase):
         """Check we can load a compilation database"""
         cdb = CompilationDatabase.fromDirectory(kInputsDir)
 
-    def test_lookup_fail(self):
-        """Check file lookup failure"""
-        cdb = CompilationDatabase.fromDirectory(kInputsDir)
-        self.assertIsNone(cdb.getCompileCommands('file_do_not_exist.cpp'))
-
     def test_lookup_succeed(self):
         """Check we get some results if the file exists in the db"""
         cdb = CompilationDatabase.fromDirectory(kInputsDir)
         cmds = cdb.getCompileCommands('/home/john.doe/MyProject/project.cpp')
         self.assertNotEqual(len(cmds), 0)
 
+    @skip_if_no_fspath
+    def test_lookup_succeed_pathlike(self):
+        """Same as test_lookup_succeed, but with PathLikes"""
+        cdb = CompilationDatabase.fromDirectory(str_to_path(kInputsDir))
+        cmds = cdb.getCompileCommands(str_to_path('/home/john.doe/MyProject/project.cpp'))
+        self.assertNotEqual(len(cmds), 0)
+
     def test_all_compilecommand(self):
         """Check we get all results from the db"""
         cdb = CompilationDatabase.fromDirectory(kInputsDir)
@@ -43,15 +63,16 @@ class TestCDB(unittest.TestCase):
         expected = [
             { 'wd': '/home/john.doe/MyProject',
               'file': '/home/john.doe/MyProject/project.cpp',
-              'line': ['clang++', '-o', 'project.o', '-c',
+              'line': ['clang++', '--driver-mode=g++', '-o', 'project.o', '-c',
                        '/home/john.doe/MyProject/project.cpp']},
             { 'wd': '/home/john.doe/MyProjectA',
               'file': '/home/john.doe/MyProject/project2.cpp',
-              'line': ['clang++', '-o', 'project2.o', '-c',
+              'line': ['clang++', '--driver-mode=g++', '-o', 'project2.o', '-c',
                        '/home/john.doe/MyProject/project2.cpp']},
             { 'wd': '/home/john.doe/MyProjectB',
               'file': '/home/john.doe/MyProject/project2.cpp',
-              'line': ['clang++', '-DFEATURE=1', '-o', 'project2-feature.o', '-c',
+              'line': ['clang++', '--driver-mode=g++', '-DFEATURE=1', '-o',
+                       'project2-feature.o', '-c',
                        '/home/john.doe/MyProject/project2.cpp']},
 
             ]
@@ -69,7 +90,7 @@ class TestCDB(unittest.TestCase):
         self.assertEqual(len(cmds), 1)
         self.assertEqual(cmds[0].directory, os.path.dirname(file))
         self.assertEqual(cmds[0].filename, file)
-        expected = [ 'clang++', '-o', 'project.o', '-c',
+        expected = [ 'clang++', '--driver-mode=g++', '-o', 'project.o', '-c',
                      '/home/john.doe/MyProject/project.cpp']
         for arg, exp in zip(cmds[0].arguments, expected):
             self.assertEqual(arg, exp)
@@ -81,10 +102,11 @@ class TestCDB(unittest.TestCase):
         self.assertEqual(len(cmds), 2)
         expected = [
             { 'wd': '/home/john.doe/MyProjectA',
-              'line': ['clang++', '-o', 'project2.o', '-c',
+              'line': ['clang++', '--driver-mode=g++', '-o', 'project2.o', '-c',
                        '/home/john.doe/MyProject/project2.cpp']},
             { 'wd': '/home/john.doe/MyProjectB',
-              'line': ['clang++', '-DFEATURE=1', '-o', 'project2-feature.o', '-c',
+              'line': ['clang++', '--driver-mode=g++', '-DFEATURE=1', '-o',
+                       'project2-feature.o', '-c',
                        '/home/john.doe/MyProject/project2.cpp']}
             ]
         for i in range(len(cmds)):

bindings/python/tests/cindex/test_code_completion.py

@@ -1,6 +1,13 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import TranslationUnit
 
 import unittest
+from .util import skip_if_no_fspath
+from .util import str_to_path
 
 
 class TestCodeCompletion(unittest.TestCase):
@@ -34,7 +41,33 @@ void f() {
         expected = [
           "{'int', ResultType} | {'test1', TypedText} || Priority: 50 || Availability: Available || Brief comment: Aaa.",
           "{'void', ResultType} | {'test2', TypedText} | {'(', LeftParen} | {')', RightParen} || Priority: 50 || Availability: Available || Brief comment: Bbb.",
-          "{'return', TypedText} || Priority: 40 || Availability: Available || Brief comment: None"
+          "{'return', TypedText} | {';', SemiColon} || Priority: 40 || Availability: Available || Brief comment: None"
+        ]
+        self.check_completion_results(cr, expected)
+
+    @skip_if_no_fspath
+    def test_code_complete_pathlike(self):
+        files = [(str_to_path('fake.c'), """
+/// Aaa.
+int test1;
+
+/// Bbb.
+void test2(void);
+
+void f() {
+
+}
+""")]
+
+        tu = TranslationUnit.from_source(str_to_path('fake.c'), ['-std=c99'], unsaved_files=files,
+                options=TranslationUnit.PARSE_INCLUDE_BRIEF_COMMENTS_IN_CODE_COMPLETION)
+
+        cr = tu.codeComplete(str_to_path('fake.c'), 9, 1, unsaved_files=files, include_brief_comments=True)
+
+        expected = [
+          "{'int', ResultType} | {'test1', TypedText} || Priority: 50 || Availability: Available || Brief comment: Aaa.",
+          "{'void', ResultType} | {'test2', TypedText} | {'(', LeftParen} | {')', RightParen} || Priority: 50 || Availability: Available || Brief comment: Bbb.",
+          "{'return', TypedText} | {';', SemiColon} || Priority: 40 || Availability: Available || Brief comment: None"
         ]
         self.check_completion_results(cr, expected)
 
@@ -61,11 +94,11 @@ void f(P x, Q y) {
         cr = tu.codeComplete('fake.cpp', 12, 5, unsaved_files=files)
 
         expected = [
-          "{'const', TypedText} || Priority: 40 || Availability: Available || Brief comment: None",
-          "{'volatile', TypedText} || Priority: 40 || Availability: Available || Brief comment: None",
+          "{'const', TypedText} || Priority: 50 || Availability: Available || Brief comment: None",
+          "{'volatile', TypedText} || Priority: 50 || Availability: Available || Brief comment: None",
           "{'operator', TypedText} || Priority: 40 || Availability: Available || Brief comment: None",
-          "{'P', TypedText} | {'::', Text} || Priority: 75 || Availability: Available || Brief comment: None",
-          "{'Q', TypedText} | {'::', Text} || Priority: 75 || Availability: Available || Brief comment: None"
+          "{'P', TypedText} || Priority: 50 || Availability: Available || Brief comment: None",
+          "{'Q', TypedText} || Priority: 50 || Availability: Available || Brief comment: None"
         ]
         self.check_completion_results(cr, expected)
 

bindings/python/tests/cindex/test_comment.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import TranslationUnit
 from tests.cindex.util import get_cursor
 

bindings/python/tests/cindex/test_cursor.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 import ctypes
 import gc
 import unittest
@@ -335,7 +340,7 @@ class TestCursor(unittest.TestCase):
 
         self.assertEqual(enum.kind, CursorKind.ENUM_DECL)
         enum_type = enum.enum_type
-        self.assertEqual(enum_type.kind, TypeKind.UINT)
+        self.assertIn(enum_type.kind, (TypeKind.UINT, TypeKind.INT))
 
     def test_enum_type_cpp(self):
         tu = get_tu('enum TEST : long long { FOO=1, BAR=2 };', lang="cpp")
@@ -561,4 +566,4 @@ class TestCursor(unittest.TestCase):
         # all valid manglings.
         # [c-index-test handles this by running the source through clang, emitting
         #  an AST file and running libclang on that AST file]
-        self.assertIn(foo.mangled_name, ('_Z3fooii', '__Z3fooii', '?foo@@YAHHH'))
+        self.assertIn(foo.mangled_name, ('_Z3fooii', '__Z3fooii', '?foo@@YAHHH', '?foo@@YAHHH@Z'))

bindings/python/tests/cindex/test_cursor_kind.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import CursorKind
 
 import unittest

bindings/python/tests/cindex/test_diagnostics.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import *
 from .util import get_tu
 
@@ -46,7 +51,7 @@ class TestDiagnostics(unittest.TestCase):
         self.assertEqual(tu.diagnostics[0].fixits[0].value, '.f0 = ')
 
     def test_diagnostic_range(self):
-        tu = get_tu('void f() { int i = "a" + 1; }')
+        tu = get_tu('void f() { int i = "a"; }')
         self.assertEqual(len(tu.diagnostics), 1)
         self.assertEqual(tu.diagnostics[0].severity, Diagnostic.Warning)
         self.assertEqual(tu.diagnostics[0].location.line, 1)
@@ -58,7 +63,7 @@ class TestDiagnostics(unittest.TestCase):
         self.assertEqual(tu.diagnostics[0].ranges[0].start.line, 1)
         self.assertEqual(tu.diagnostics[0].ranges[0].start.column, 20)
         self.assertEqual(tu.diagnostics[0].ranges[0].end.line, 1)
-        self.assertEqual(tu.diagnostics[0].ranges[0].end.column, 27)
+        self.assertEqual(tu.diagnostics[0].ranges[0].end.column, 23)
         with self.assertRaises(IndexError):
             tu.diagnostics[0].ranges[1].start.line
 

bindings/python/tests/cindex/test_exception_specification_kind.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 import clang.cindex
 from clang.cindex import ExceptionSpecificationKind
 from .util import get_tu

bindings/python/tests/cindex/test_file.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import Index, File
 
 import unittest

bindings/python/tests/cindex/test_index.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import *
 import os
 import unittest

bindings/python/tests/cindex/test_linkage.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import LinkageKind
 from clang.cindex import Cursor
 from clang.cindex import TranslationUnit

bindings/python/tests/cindex/test_location.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import Cursor
 from clang.cindex import File
 from clang.cindex import SourceLocation

bindings/python/tests/cindex/test_tls_kind.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import TLSKind
 from clang.cindex import Cursor
 from clang.cindex import TranslationUnit

bindings/python/tests/cindex/test_token_kind.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import TokenKind
 
 import unittest

bindings/python/tests/cindex/test_tokens.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 from clang.cindex import CursorKind
 from clang.cindex import Index
 from clang.cindex import SourceLocation

bindings/python/tests/cindex/test_translation_unit.py

@@ -1,5 +1,12 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
+from contextlib import contextmanager
 import gc
 import os
+import sys
 import tempfile
 import unittest
 
@@ -14,20 +21,33 @@ from clang.cindex import TranslationUnitLoadError
 from clang.cindex import TranslationUnit
 from .util import get_cursor
 from .util import get_tu
+from .util import skip_if_no_fspath
+from .util import str_to_path
 
 
 kInputsDir = os.path.join(os.path.dirname(__file__), 'INPUTS')
 
 
+@contextmanager
 def save_tu(tu):
     """Convenience API to save a TranslationUnit to a file.
 
     Returns the filename it was saved to.
     """
-    _, path = tempfile.mkstemp()
-    tu.save(path)
+    with tempfile.NamedTemporaryFile() as t:
+        tu.save(t.name)
+        yield t.name
 
-    return path
+
+@contextmanager
+def save_tu_pathlike(tu):
+    """Convenience API to save a TranslationUnit to a file.
+
+    Returns the filename it was saved to.
+    """
+    with tempfile.NamedTemporaryFile() as t:
+        tu.save(str_to_path(t.name))
+        yield t.name
 
 
 class TestTranslationUnit(unittest.TestCase):
@@ -74,15 +94,31 @@ int SOME_DEFINE;
         self.assertEqual(spellings[-1], 'y')
 
     def test_unsaved_files_2(self):
-        try:
-            from StringIO import StringIO
-        except:
+        if sys.version_info.major >= 3:
             from io import StringIO
+        else:
+            from io import BytesIO as StringIO
         tu = TranslationUnit.from_source('fake.c', unsaved_files = [
                 ('fake.c', StringIO('int x;'))])
         spellings = [c.spelling for c in tu.cursor.get_children()]
         self.assertEqual(spellings[-1], 'x')
 
+    @skip_if_no_fspath
+    def test_from_source_accepts_pathlike(self):
+        tu = TranslationUnit.from_source(str_to_path('fake.c'), ['-Iincludes'], unsaved_files = [
+                (str_to_path('fake.c'), """
+#include "fake.h"
+    int x;
+    int SOME_DEFINE;
+    """),
+                    (str_to_path('includes/fake.h'), """
+#define SOME_DEFINE y
+    """)
+                ])
+        spellings = [c.spelling for c in tu.cursor.get_children()]
+        self.assertEqual(spellings[-2], 'x')
+        self.assertEqual(spellings[-1], 'y')
+
     def assert_normpaths_equal(self, path1, path2):
         """ Compares two paths for equality after normalizing them with
             os.path.normpath
@@ -108,15 +144,36 @@ int SOME_DEFINE;
         for i in zip(inc, tu.get_includes()):
             eq(i[0], i[1])
 
+    def test_inclusion_directive(self):
+        src = os.path.join(kInputsDir, 'include.cpp')
+        h1 = os.path.join(kInputsDir, "header1.h")
+        h2 = os.path.join(kInputsDir, "header2.h")
+        h3 = os.path.join(kInputsDir, "header3.h")
+        inc = [h1, h3, h2, h3, h1]
+
+        tu = TranslationUnit.from_source(src, options=TranslationUnit.PARSE_DETAILED_PROCESSING_RECORD)
+        inclusion_directive_files = [c.get_included_file().name for c in tu.cursor.get_children() if c.kind == CursorKind.INCLUSION_DIRECTIVE]
+        for i in zip(inc, inclusion_directive_files):
+            self.assert_normpaths_equal(i[0], i[1])
+
     def test_save(self):
         """Ensure TranslationUnit.save() works."""
 
         tu = get_tu('int foo();')
 
-        path = save_tu(tu)
-        self.assertTrue(os.path.exists(path))
-        self.assertGreater(os.path.getsize(path), 0)
-        os.unlink(path)
+        with save_tu(tu) as path:
+            self.assertTrue(os.path.exists(path))
+            self.assertGreater(os.path.getsize(path), 0)
+
+    @skip_if_no_fspath
+    def test_save_pathlike(self):
+        """Ensure TranslationUnit.save() works with PathLike filename."""
+
+        tu = get_tu('int foo();')
+
+        with save_tu_pathlike(tu) as path:
+            self.assertTrue(os.path.exists(path))
+            self.assertGreater(os.path.getsize(path), 0)
 
     def test_save_translation_errors(self):
         """Ensure that saving to an invalid directory raises."""
@@ -137,21 +194,34 @@ int SOME_DEFINE;
 
         tu = get_tu('int foo();')
         self.assertEqual(len(tu.diagnostics), 0)
-        path = save_tu(tu)
+        with save_tu(tu) as path:
+            self.assertTrue(os.path.exists(path))
+            self.assertGreater(os.path.getsize(path), 0)
 
-        self.assertTrue(os.path.exists(path))
-        self.assertGreater(os.path.getsize(path), 0)
+            tu2 = TranslationUnit.from_ast_file(filename=path)
+            self.assertEqual(len(tu2.diagnostics), 0)
 
-        tu2 = TranslationUnit.from_ast_file(filename=path)
-        self.assertEqual(len(tu2.diagnostics), 0)
+            foo = get_cursor(tu2, 'foo')
+            self.assertIsNotNone(foo)
 
-        foo = get_cursor(tu2, 'foo')
-        self.assertIsNotNone(foo)
+            # Just in case there is an open file descriptor somewhere.
+            del tu2
+
+    @skip_if_no_fspath
+    def test_load_pathlike(self):
+        """Ensure TranslationUnits can be constructed from saved files -
+        PathLike variant."""
+        tu = get_tu('int foo();')
+        self.assertEqual(len(tu.diagnostics), 0)
+        with save_tu(tu) as path:
+            tu2 = TranslationUnit.from_ast_file(filename=str_to_path(path))
+            self.assertEqual(len(tu2.diagnostics), 0)
 
-        # Just in case there is an open file descriptor somewhere.
-        del tu2
+            foo = get_cursor(tu2, 'foo')
+            self.assertIsNotNone(foo)
 
-        os.unlink(path)
+            # Just in case there is an open file descriptor somewhere.
+            del tu2
 
     def test_index_parse(self):
         path = os.path.join(kInputsDir, 'hello.cpp')
@@ -171,6 +241,19 @@ int SOME_DEFINE;
         with self.assertRaises(Exception):
             f = tu.get_file('foobar.cpp')
 
+    @skip_if_no_fspath
+    def test_get_file_pathlike(self):
+        """Ensure tu.get_file() works appropriately with PathLike filenames."""
+
+        tu = get_tu('int foo();')
+
+        f = tu.get_file(str_to_path('t.c'))
+        self.assertIsInstance(f, File)
+        self.assertEqual(f.name, 't.c')
+
+        with self.assertRaises(Exception):
+            f = tu.get_file(str_to_path('foobar.cpp'))
+
     def test_get_source_location(self):
         """Ensure tu.get_source_location() works."""
 

bindings/python/tests/cindex/test_type.py

@@ -1,3 +1,8 @@
+import os
+from clang.cindex import Config
+if 'CLANG_LIBRARY_PATH' in os.environ:
+    Config.set_library_path(os.environ['CLANG_LIBRARY_PATH'])
+
 import gc
 import unittest
 
@@ -436,3 +441,28 @@ class TestType(unittest.TestCase):
 
         self.assertIsNotNone(testInteger, "Could not find testInteger.")
         self.assertEqual(testInteger.type.get_address_space(), 2)
+
+    def test_template_arguments(self):
+        source = """
+        class Foo {
+        };
+        template <typename T>
+        class Template {
+        };
+        Template<Foo> instance;
+        int bar;
+        """
+        tu = get_tu(source, lang='cpp')
+
+        # Varible with a template argument.
+        cursor = get_cursor(tu, 'instance')
+        cursor_type = cursor.type
+        self.assertEqual(cursor.kind, CursorKind.VAR_DECL)
+        self.assertEqual(cursor_type.spelling, 'Template<Foo>')
+        self.assertEqual(cursor_type.get_num_template_arguments(), 1)
+        template_type = cursor_type.get_template_argument_type(0)
+        self.assertEqual(template_type.spelling, 'Foo')
+
+        # Variable without a template argument.
+        cursor = get_cursor(tu, 'bar')
+        self.assertEqual(cursor.get_num_template_arguments(), -1)

bindings/python/tests/cindex/util.py

@@ -1,5 +1,15 @@
 # This file provides common utility functions for the test suite.
 
+import os
+HAS_FSPATH = hasattr(os, 'fspath')
+
+if HAS_FSPATH:
+    from pathlib import Path as str_to_path
+else:
+    str_to_path = None
+
+import unittest
+
 from clang.cindex import Cursor
 from clang.cindex import TranslationUnit
 
@@ -68,8 +78,13 @@ def get_cursors(source, spelling):
     return cursors
 
 
+skip_if_no_fspath = unittest.skipUnless(HAS_FSPATH,
+                                        "Requires file system path protocol / Python 3.6+")
+
 __all__ = [
     'get_cursor',
     'get_cursors',
     'get_tu',
+    'skip_if_no_fspath',
+    'str_to_path',
 ]

cmake/caches/Apple-stage1.cmake

@@ -33,6 +33,9 @@ set(COMPILER_RT_ENABLE_TVOS OFF CACHE BOOL "")
 set(BOOTSTRAP_LLVM_ENABLE_LTO ON CACHE BOOL "")
 set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "")
 
+set(LIBCXX_ENABLE_NEW_DELETE_DEFINITIONS OFF CACHE BOOL "")
+set(LIBCXXABI_ENABLE_NEW_DELETE_DEFINITIONS ON CACHE BOOL "")
+
 set(CLANG_BOOTSTRAP_TARGETS
   generate-order-file
   check-all

cmake/caches/Apple-stage2.cmake

@@ -38,6 +38,7 @@ set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "")
 set(LIBCXX_INSTALL_LIBRARY OFF CACHE BOOL "")
 set(LIBCXX_INSTALL_HEADERS ON CACHE BOOL "")
 set(LIBCXX_INCLUDE_TESTS OFF CACHE BOOL "")
+set(LIBCXX_USE_COMPILER_RT ON CACHE BOOL "")
 set(LLVM_LTO_VERSION_OFFSET 3000 CACHE STRING "")
 
 # Generating Xcode toolchains is useful for developers wanting to build and use
@@ -60,8 +61,9 @@ set(LLVM_DISTRIBUTION_COMPONENTS
   clang
   LTO
   clang-format
-  clang-headers
+  clang-resource-headers
   cxx-headers
+  Remarks
   ${LLVM_TOOLCHAIN_TOOLS}
   CACHE STRING "")
 

cmake/caches/BaremetalARM.cmake

@@ -41,7 +41,7 @@ set(LLVM_TOOLCHAIN_TOOLS
 set(LLVM_DISTRIBUTION_COMPONENTS
   clang
   lld
-  clang-headers
+  clang-resource-headers
   builtins-armv6m-none-eabi
   builtins-armv7m-none-eabi
   builtins-armv7em-none-eabi

cmake/caches/DistributionExample-stage2.cmake

@@ -1,6 +1,9 @@
 # This file sets up a CMakeCache for the second stage of a simple distribution
 # bootstrap build.
 
+set(LLVM_ENABLE_PROJECTS "clang;clang-tools-extra;lld" CACHE STRING "")
+set(LLVM_ENABLE_RUNTIMES "compiler-rt;libcxx;libcxxabi" CACHE STRING "")
+
 set(LLVM_TARGETS_TO_BUILD X86;ARM;AArch64 CACHE STRING "")
 
 set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "")
@@ -23,7 +26,7 @@ set(LLVM_DISTRIBUTION_COMPONENTS
   clang
   LTO
   clang-format
-  clang-headers
+  clang-resource-headers
   builtins
   runtimes
   ${LLVM_TOOLCHAIN_TOOLS}

cmake/caches/DistributionExample.cmake

@@ -1,5 +1,9 @@
 # This file sets up a CMakeCache for a simple distribution bootstrap build.
 
+#Enable LLVM projects and runtimes
+set(LLVM_ENABLE_PROJECTS "clang;clang-tools-extra;lld" CACHE STRING "")
+set(LLVM_ENABLE_RUNTIMES "compiler-rt;libcxx;libcxxabi" CACHE STRING "")
+
 # Only build the native target in stage1 since it is a throwaway build.
 set(LLVM_TARGETS_TO_BUILD Native CACHE STRING "")
 
@@ -13,6 +17,11 @@ set(PACKAGE_VENDOR LLVM.org CACHE STRING "")
 # the proper LTO library dependencies can be connected.
 set(BOOTSTRAP_LLVM_ENABLE_LTO ON CACHE BOOL "")
 
+if (NOT APPLE)
+  # Since LLVM_ENABLE_LTO is ON we need a LTO capable linker
+  set(BOOTSTRAP_LLVM_ENABLE_LLD ON CACHE BOOL "")
+endif()
+
 # Expose stage2 targets through the stage1 build configuration.
 set(CLANG_BOOTSTRAP_TARGETS
   check-all

cmake/caches/Fuchsia-stage2.cmake

@@ -1,78 +1,180 @@
-# This file sets up a CMakeCache for the second stage of a Fuchsia toolchain
-# build.
+# This file sets up a CMakeCache for the second stage of a Fuchsia toolchain build.
 
 set(LLVM_TARGETS_TO_BUILD X86;ARM;AArch64 CACHE STRING "")
 
 set(PACKAGE_VENDOR Fuchsia CACHE STRING "")
 
-set(LLVM_INCLUDE_EXAMPLES OFF CACHE BOOL "")
-set(LLVM_INCLUDE_DOCS OFF CACHE BOOL "")
 set(LLVM_ENABLE_BACKTRACES OFF CACHE BOOL "")
+if(NOT APPLE)
+  set(LLVM_ENABLE_LLD ON CACHE BOOL "")
+endif()
+set(LLVM_ENABLE_LTO ON CACHE BOOL "")
+set(LLVM_ENABLE_PER_TARGET_RUNTIME_DIR ON CACHE BOOL "")
 set(LLVM_ENABLE_TERMINFO OFF CACHE BOOL "")
 set(LLVM_ENABLE_ZLIB ON CACHE BOOL "")
 set(LLVM_EXTERNALIZE_DEBUGINFO ON CACHE BOOL "")
-set(CLANG_PLUGIN_SUPPORT OFF CACHE BOOL "")
+set(LLVM_INCLUDE_EXAMPLES OFF CACHE BOOL "")
+set(LLVM_INCLUDE_DOCS OFF CACHE BOOL "")
+set(LLVM_USE_RELATIVE_PATHS_IN_DEBUG_INFO ON CACHE BOOL "")
 
-set(LLVM_ENABLE_LTO ON CACHE BOOL "")
+set(CLANG_DEFAULT_CXX_STDLIB libc++ CACHE STRING "")
 if(NOT APPLE)
-  set(LLVM_ENABLE_LLD ON CACHE BOOL "")
   set(CLANG_DEFAULT_LINKER lld CACHE STRING "")
   set(CLANG_DEFAULT_OBJCOPY llvm-objcopy CACHE STRING "")
 endif()
-set(CLANG_DEFAULT_CXX_STDLIB libc++ CACHE STRING "")
 set(CLANG_DEFAULT_RTLIB compiler-rt CACHE STRING "")
+set(CLANG_PLUGIN_SUPPORT OFF CACHE BOOL "")
 
-set(LLVM_ENABLE_ASSERTIONS ON CACHE BOOL "")
-set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "")
-set(CMAKE_C_FLAGS_RELWITHDEBINFO "-O3 -gline-tables-only -DNDEBUG" CACHE STRING "")
-set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-O3 -gline-tables-only -DNDEBUG" CACHE STRING "")
+set(ENABLE_EXPERIMENTAL_NEW_PASS_MANAGER ON CACHE BOOL "")
+set(ENABLE_LINKER_BUILD_ID ON CACHE BOOL "")
+set(ENABLE_X86_RELAX_RELOCATIONS ON CACHE BOOL "")
 
-set(LLVM_BUILTIN_TARGETS "default;x86_64-fuchsia;aarch64-fuchsia" CACHE STRING "")
+set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "")
+set(CMAKE_C_FLAGS_RELWITHDEBINFO "-O3 -gline-tables-only" CACHE STRING "")
+set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-O3 -gline-tables-only" CACHE STRING "")
 
-# Set the per-target builtins options.
-foreach(target x86_64;aarch64)
-  set(BUILTINS_${target}-fuchsia_CMAKE_SYSROOT ${FUCHSIA_${target}_SYSROOT} CACHE PATH "")
-  set(BUILTINS_${target}-fuchsia_CMAKE_SYSTEM_NAME Fuchsia CACHE STRING "")
-endforeach()
+if(APPLE)
+  list(APPEND BUILTIN_TARGETS "default")
+  list(APPEND RUNTIME_TARGETS "default")
 
-set(LLVM_RUNTIME_TARGETS "default;x86_64-fuchsia;aarch64-fuchsia;x86_64-fuchsia-asan:x86_64-fuchsia;aarch64-fuchsia-asan:aarch64-fuchsia" CACHE STRING "")
+  set(COMPILER_RT_ENABLE_TVOS OFF CACHE BOOL "")
+  set(COMPILER_RT_ENABLE_WATCHOS OFF CACHE BOOL "")
 
-# Set the default target runtimes options.
-if(NOT APPLE)
   set(LIBUNWIND_ENABLE_SHARED OFF CACHE BOOL "")
-  set(LIBUNWIND_USE_COMPILER_RT ON CACHE BOOL "")
   set(LIBUNWIND_INSTALL_LIBRARY OFF CACHE BOOL "")
-  set(LIBCXXABI_USE_COMPILER_RT ON CACHE BOOL "")
+  set(LIBUNWIND_USE_COMPILER_RT ON CACHE BOOL "")
   set(LIBCXXABI_ENABLE_SHARED OFF CACHE BOOL "")
-  set(LIBCXXABI_USE_LLVM_UNWINDER ON CACHE BOOL "")
   set(LIBCXXABI_ENABLE_STATIC_UNWINDER ON CACHE BOOL "")
   set(LIBCXXABI_INSTALL_LIBRARY OFF CACHE BOOL "")
+  set(LIBCXXABI_USE_COMPILER_RT ON CACHE BOOL "")
+  set(LIBCXXABI_USE_LLVM_UNWINDER ON CACHE BOOL "")
   set(LIBCXX_USE_COMPILER_RT ON CACHE BOOL "")
   set(LIBCXX_ENABLE_SHARED OFF CACHE BOOL "")
   set(LIBCXX_ENABLE_STATIC_ABI_LIBRARY ON CACHE BOOL "")
+  set(LIBCXX_ABI_VERSION 2 CACHE STRING "")
 endif()
 
-# Set the per-target runtimes options.
-foreach(target x86_64;aarch64)
-  set(RUNTIMES_${target}-fuchsia_CMAKE_BUILD_WITH_INSTALL_RPATH ON CACHE BOOL "")
-  set(RUNTIMES_${target}-fuchsia_CMAKE_SYSROOT ${FUCHSIA_${target}_SYSROOT} CACHE PATH "")
-  set(RUNTIMES_${target}-fuchsia_CMAKE_SYSTEM_NAME Fuchsia CACHE STRING "")
-  set(RUNTIMES_${target}-fuchsia_UNIX 1 CACHE BOOL "")
-  set(RUNTIMES_${target}-fuchsia_LIBUNWIND_USE_COMPILER_RT ON CACHE BOOL "")
-  set(RUNTIMES_${target}-fuchsia_LIBUNWIND_ENABLE_STATIC OFF CACHE BOOL "")
-  set(RUNTIMES_${target}-fuchsia_LIBCXXABI_USE_COMPILER_RT ON CACHE BOOL "")
-  set(RUNTIMES_${target}-fuchsia_LIBCXXABI_USE_LLVM_UNWINDER ON CACHE BOOL "")
-  set(RUNTIMES_${target}-fuchsia_LIBCXXABI_ENABLE_STATIC OFF CACHE BOOL "")
-  set(RUNTIMES_${target}-fuchsia_LIBCXX_USE_COMPILER_RT ON CACHE BOOL "")
-  set(RUNTIMES_${target}-fuchsia_LIBCXX_ENABLE_STATIC OFF CACHE BOOL "")
-  set(RUNTIMES_${target}-fuchsia_SANITIZER_USE_COMPILER_RT ON CACHE BOOL "")
-
-  set(RUNTIMES_${target}-fuchsia-asan_LLVM_USE_SANITIZER Address CACHE STRING "")
-  set(RUNTIMES_${target}-fuchsia-asan_LLVM_RUNTIMES_PREFIX "${target}-fuchsia/" CACHE STRING "")
-  set(RUNTIMES_${target}-fuchsia-asan_LLVM_RUNTIMES_LIBDIR_SUFFIX "/asan" CACHE STRING "")
-  set(RUNTIMES_${target}-fuchsia-asan_LIBCXX_INSTALL_HEADERS OFF CACHE BOOL "")
+foreach(target aarch64-unknown-linux-gnu;armv7-unknown-linux-gnueabihf;i386-unknown-linux-gnu;x86_64-unknown-linux-gnu)
+  if(LINUX_${target}_SYSROOT)
+    # Set the per-target builtins options.
+    list(APPEND BUILTIN_TARGETS "${target}")
+    set(BUILTINS_${target}_CMAKE_SYSTEM_NAME Linux CACHE STRING "")
+    set(BUILTINS_${target}_CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "")
+    set(BUILTINS_${target}_CMAKE_SYSROOT ${LINUX_${target}_SYSROOT} CACHE STRING "")
+    set(BUILTINS_${target}_CMAKE_SHARED_LINKER_FLAGS "-fuse-ld=lld" CACHE STRING "")
+    set(BUILTINS_${target}_CMAKE_MODULE_LINKER_FLAGS "-fuse-ld=lld" CACHE STRING "")
+    set(BUILTINS_${target}_CMAKE_EXE_LINKER_FLAG "-fuse-ld=lld" CACHE STRING "")
+
+    # Set the per-target runtimes options.
+    list(APPEND RUNTIME_TARGETS "${target}")
+    set(RUNTIMES_${target}_CMAKE_SYSTEM_NAME Linux CACHE STRING "")
+    set(RUNTIMES_${target}_CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "")
+    set(RUNTIMES_${target}_CMAKE_SYSROOT ${LINUX_${target}_SYSROOT} CACHE STRING "")
+    set(RUNTIMES_${target}_CMAKE_SHARED_LINKER_FLAGS "-fuse-ld=lld" CACHE STRING "")
+    set(RUNTIMES_${target}_CMAKE_MODULE_LINKER_FLAGS "-fuse-ld=lld" CACHE STRING "")
+    set(RUNTIMES_${target}_CMAKE_EXE_LINKER_FLAGS "-fuse-ld=lld" CACHE STRING "")
+    set(RUNTIMES_${target}_LLVM_ENABLE_ASSERTIONS ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBUNWIND_ENABLE_SHARED OFF CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBUNWIND_USE_COMPILER_RT ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBUNWIND_INSTALL_LIBRARY OFF CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXXABI_USE_COMPILER_RT ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXXABI_ENABLE_SHARED OFF CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXXABI_USE_LLVM_UNWINDER ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXXABI_ENABLE_STATIC_UNWINDER ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXXABI_INSTALL_LIBRARY OFF CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXX_USE_COMPILER_RT ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXX_ENABLE_SHARED OFF CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXX_ENABLE_STATIC_ABI_LIBRARY ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXX_ABI_VERSION 2 CACHE STRING "")
+    set(RUNTIMES_${target}_SANITIZER_CXX_ABI "libc++" CACHE STRING "")
+    set(RUNTIMES_${target}_SANITIZER_CXX_ABI_INTREE ON CACHE BOOL "")
+    set(RUNTIMES_${target}_COMPILER_RT_USE_BUILTINS_LIBRARY ON CACHE BOOL "")
+
+    # Use .build-id link.
+    list(APPEND RUNTIME_BUILD_ID_LINK "${target}")
+  endif()
 endforeach()
 
+if(FUCHSIA_SDK)
+  set(FUCHSIA_aarch64_NAME arm64)
+  set(FUCHSIA_x86_64_NAME x64)
+  foreach(target x86_64;aarch64)
+    set(FUCHSIA_${target}_COMPILER_FLAGS "-I${FUCHSIA_SDK}/pkg/fdio/include")
+    set(FUCHSIA_${target}_LINKER_FLAGS "-L${FUCHSIA_SDK}/arch/${FUCHSIA_${target}_NAME}/lib")
+    set(FUCHSIA_${target}_SYSROOT "${FUCHSIA_SDK}/arch/${FUCHSIA_${target}_NAME}/sysroot")
+  endforeach()
+
+  foreach(target x86_64;aarch64)
+    # Set the per-target builtins options.
+    list(APPEND BUILTIN_TARGETS "${target}-unknown-fuchsia")
+    set(BUILTINS_${target}-unknown-fuchsia_CMAKE_SYSTEM_NAME Fuchsia CACHE STRING "")
+    set(BUILTINS_${target}-unknown-fuchsia_CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "")
+    set(BUILTINS_${target}-unknown-fuchsia_CMAKE_ASM_FLAGS ${FUCHSIA_${target}_COMPILER_FLAGS} CACHE STRING "")
+    set(BUILTINS_${target}-unknown-fuchsia_CMAKE_C_FLAGS ${FUCHSIA_${target}_COMPILER_FLAGS} CACHE STRING "")
+    set(BUILTINS_${target}-unknown-fuchsia_CMAKE_CXX_FLAGS ${FUCHSIA_${target}_COMPILER_FLAGS} CACHE STRING "")
+    set(BUILTINS_${target}-unknown-fuchsia_CMAKE_SHARED_LINKER_FLAGS ${FUCHSIA_${target}_LINKER_FLAGS} CACHE STRING "")
+    set(BUILTINS_${target}-unknown-fuchsia_CMAKE_MODULE_LINKER_FLAGS ${FUCHSIA_${target}_LINKER_FLAGS} CACHE STRING "")
+    set(BUILTINS_${target}-unknown-fuchsia_CMAKE_EXE_LINKER_FLAGS ${FUCHSIA_${target}_LINKER_FLAGS} CACHE STRING "")
+    set(BUILTINS_${target}-unknown-fuchsia_CMAKE_SYSROOT ${FUCHSIA_${target}_SYSROOT} CACHE PATH "")
+
+    # Set the per-target runtimes options.
+    list(APPEND RUNTIME_TARGETS "${target}-unknown-fuchsia")
+    set(RUNTIMES_${target}-unknown-fuchsia_CMAKE_SYSTEM_NAME Fuchsia CACHE STRING "")
+    set(RUNTIMES_${target}-unknown-fuchsia_CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "")
+    set(RUNTIMES_${target}-unknown-fuchsia_CMAKE_BUILD_WITH_INSTALL_RPATH ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_CMAKE_ASM_FLAGS ${FUCHSIA_${target}_COMPILER_FLAGS} CACHE STRING "")
+    set(RUNTIMES_${target}-unknown-fuchsia_CMAKE_C_FLAGS ${FUCHSIA_${target}_COMPILER_FLAGS} CACHE STRING "")
+    set(RUNTIMES_${target}-unknown-fuchsia_CMAKE_CXX_FLAGS ${FUCHSIA_${target}_COMPILER_FLAGS} CACHE STRING "")
+    set(RUNTIMES_${target}-unknown-fuchsia_CMAKE_SHARED_LINKER_FLAGS ${FUCHSIA_${target}_LINKER_FLAGS} CACHE STRING "")
+    set(RUNTIMES_${target}-unknown-fuchsia_CMAKE_MODULE_LINKER_FLAGS ${FUCHSIA_${target}_LINKER_FLAGS} CACHE STRING "")
+    set(RUNTIMES_${target}-unknown-fuchsia_CMAKE_EXE_LINKER_FLAGS ${FUCHSIA_${target}_LINKER_FLAGS} CACHE STRING "")
+    set(RUNTIMES_${target}-unknown-fuchsia_CMAKE_SYSROOT ${FUCHSIA_${target}_SYSROOT} CACHE PATH "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LLVM_ENABLE_ASSERTIONS ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBUNWIND_USE_COMPILER_RT ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBUNWIND_HERMETIC_STATIC_LIBRARY ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBUNWIND_INSTALL_STATIC_LIBRARY OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXXABI_USE_COMPILER_RT ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXXABI_USE_LLVM_UNWINDER ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXXABI_ENABLE_STATIC_UNWINDER ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXXABI_HERMETIC_STATIC_LIBRARY ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXXABI_INSTALL_STATIC_LIBRARY OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXXABI_STATICALLY_LINK_UNWINDER_IN_SHARED_LIBRARY OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXX_USE_COMPILER_RT ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXX_ENABLE_STATIC_ABI_LIBRARY ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXX_HERMETIC_STATIC_LIBRARY ON CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXX_STATICALLY_LINK_ABI_IN_SHARED_LIBRARY OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia_LIBCXX_ABI_VERSION 2 CACHE STRING "")
+
+    set(RUNTIMES_${target}-unknown-fuchsia+asan_LLVM_BUILD_COMPILER_RT OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia+asan_LLVM_USE_SANITIZER "Address" CACHE STRING "")
+    set(RUNTIMES_${target}-unknown-fuchsia+asan_LIBCXXABI_ENABLE_NEW_DELETE_DEFINITIONS OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia+asan_LIBCXX_ENABLE_NEW_DELETE_DEFINITIONS OFF CACHE BOOL "")
+
+    set(RUNTIMES_${target}-unknown-fuchsia+noexcept_LLVM_BUILD_COMPILER_RT OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia+noexcept_LIBCXXABI_ENABLE_EXCEPTIONS OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia+noexcept_LIBCXX_ENABLE_EXCEPTIONS OFF CACHE BOOL "")
+
+    set(RUNTIMES_${target}-unknown-fuchsia+asan+noexcept_LLVM_BUILD_COMPILER_RT OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia+asan+noexcept_LLVM_USE_SANITIZER "Address" CACHE STRING "")
+    set(RUNTIMES_${target}-unknown-fuchsia+asan+noexcept_LIBCXXABI_ENABLE_NEW_DELETE_DEFINITIONS OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia+asan+noexcept_LIBCXX_ENABLE_NEW_DELETE_DEFINITIONS OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia+asan+noexcept_LIBCXXABI_ENABLE_EXCEPTIONS OFF CACHE BOOL "")
+    set(RUNTIMES_${target}-unknown-fuchsia+asan+noexcept_LIBCXX_ENABLE_EXCEPTIONS OFF CACHE BOOL "")
+
+    # Use .build-id link.
+    list(APPEND RUNTIME_BUILD_ID_LINK "${target}-unknown-fuchsia")
+  endforeach()
+
+  set(LLVM_RUNTIME_MULTILIBS "asan;noexcept;asan+noexcept" CACHE STRING "")
+  set(LLVM_RUNTIME_MULTILIB_asan_TARGETS "x86_64-unknown-fuchsia;aarch64-unknown-fuchsia" CACHE STRING "")
+  set(LLVM_RUNTIME_MULTILIB_noexcept_TARGETS "x86_64-unknown-fuchsia;aarch64-unknown-fuchsia" CACHE STRING "")
+  set(LLVM_RUNTIME_MULTILIB_asan+noexcept_TARGETS "x86_64-unknown-fuchsia;aarch64-unknown-fuchsia" CACHE STRING "")
+endif()
+
+set(LLVM_BUILTIN_TARGETS "${BUILTIN_TARGETS}" CACHE STRING "")
+set(LLVM_RUNTIME_TARGETS "${RUNTIME_TARGETS}" CACHE STRING "")
+set(LLVM_RUNTIME_BUILD_ID_LINK_TARGETS "${RUNTIME_BUILD_ID_LINK}" CACHE STRING "")
+
 # Setup toolchain.
 set(LLVM_INSTALL_TOOLCHAIN_ONLY ON CACHE BOOL "")
 set(LLVM_TOOLCHAIN_TOOLS
@@ -82,6 +184,7 @@ set(LLVM_TOOLCHAIN_TOOLS
   llvm-cov
   llvm-cxxfilt
   llvm-dwarfdump
+  llvm-dwp
   llvm-lib
   llvm-nm
   llvm-objcopy
@@ -91,18 +194,21 @@ set(LLVM_TOOLCHAIN_TOOLS
   llvm-readelf
   llvm-readobj
   llvm-size
+  llvm-strip
   llvm-symbolizer
+  llvm-xray
   opt
   sancov
   CACHE STRING "")
 
 set(LLVM_DISTRIBUTION_COMPONENTS
   clang
-  libclang
   lld
   LTO
+  clang-apply-replacements
+  clang-doc
   clang-format
-  clang-headers
+  clang-resource-headers
   clang-include-fixer
   clang-refactor
   clang-tidy

cmake/caches/Fuchsia.cmake

@@ -1,53 +1,123 @@
 # This file sets up a CMakeCache for a Fuchsia toolchain build.
 
-set(LLVM_TARGETS_TO_BUILD Native CACHE STRING "")
+set(LLVM_TARGETS_TO_BUILD X86;ARM;AArch64 CACHE STRING "")
 
 set(PACKAGE_VENDOR Fuchsia CACHE STRING "")
 
-set(LLVM_INCLUDE_EXAMPLES OFF CACHE BOOL "")
-set(LLVM_INCLUDE_TESTS OFF CACHE BOOL "")
-set(LLVM_INCLUDE_DOCS OFF CACHE BOOL "")
-set(CLANG_INCLUDE_TESTS OFF CACHE BOOL "")
 set(LLVM_ENABLE_BACKTRACES OFF CACHE BOOL "")
+set(LLVM_ENABLE_PER_TARGET_RUNTIME_DIR ON CACHE BOOL "")
 set(LLVM_ENABLE_TERMINFO OFF CACHE BOOL "")
 set(LLVM_ENABLE_ZLIB OFF CACHE BOOL "")
+set(LLVM_INCLUDE_EXAMPLES OFF CACHE BOOL "")
+set(LLVM_INCLUDE_DOCS OFF CACHE BOOL "")
+
+set(CLANG_DEFAULT_CXX_STDLIB libc++ CACHE STRING "")
+if(NOT APPLE)
+  set(CLANG_DEFAULT_LINKER lld CACHE STRING "")
+  set(CLANG_DEFAULT_OBJCOPY llvm-objcopy CACHE STRING "")
+endif()
+set(CLANG_DEFAULT_RTLIB compiler-rt CACHE STRING "")
 set(CLANG_PLUGIN_SUPPORT OFF CACHE BOOL "")
 
+set(ENABLE_EXPERIMENTAL_NEW_PASS_MANAGER ON CACHE BOOL "")
+set(ENABLE_LINKER_BUILD_ID ON CACHE BOOL "")
+set(ENABLE_X86_RELAX_RELOCATIONS ON CACHE BOOL "")
+
 set(LLVM_ENABLE_ASSERTIONS ON CACHE BOOL "")
 set(CMAKE_BUILD_TYPE Release CACHE STRING "")
 
-set(BOOTSTRAP_LLVM_ENABLE_LTO ON CACHE BOOL "")
-if(NOT APPLE)
-  set(BOOTSTRAP_LLVM_ENABLE_LLD ON CACHE BOOL "")
-endif()
-
 if(APPLE)
   set(COMPILER_RT_ENABLE_IOS OFF CACHE BOOL "")
   set(COMPILER_RT_ENABLE_TVOS OFF CACHE BOOL "")
   set(COMPILER_RT_ENABLE_WATCHOS OFF CACHE BOOL "")
 endif()
 
+set(LIBUNWIND_ENABLE_SHARED OFF CACHE BOOL "")
+set(LIBUNWIND_INSTALL_LIBRARY OFF CACHE BOOL "")
+set(LIBUNWIND_USE_COMPILER_RT ON CACHE BOOL "")
+set(LIBCXXABI_ENABLE_SHARED OFF CACHE BOOL "")
+set(LIBCXXABI_ENABLE_STATIC_UNWINDER ON CACHE BOOL "")
+set(LIBCXXABI_INSTALL_LIBRARY OFF CACHE BOOL "")
+set(LIBCXXABI_USE_COMPILER_RT ON CACHE BOOL "")
+set(LIBCXXABI_USE_LLVM_UNWINDER ON CACHE BOOL "")
+set(LIBCXX_ABI_VERSION 2 CACHE STRING "")
+set(LIBCXX_ENABLE_SHARED OFF CACHE BOOL "")
+set(LIBCXX_ENABLE_STATIC_ABI_LIBRARY ON CACHE BOOL "")
+set(LIBCXX_USE_COMPILER_RT ON CACHE BOOL "")
+
+if(BOOTSTRAP_CMAKE_SYSTEM_NAME)
+  set(target "${BOOTSTRAP_CMAKE_CXX_COMPILER_TARGET}")
+  if(STAGE2_LINUX_${target}_SYSROOT)
+    set(BUILTINS_${target}_CMAKE_SYSTEM_NAME Linux CACHE STRING "")
+    set(BUILTINS_${target}_CMAKE_BUILD_TYPE Release CACHE STRING "")
+    set(BUILTINS_${target}_CMAKE_SYSROOT ${STAGE2_LINUX_${target}_SYSROOT} CACHE STRING "")
+    set(LLVM_BUILTIN_TARGETS "${target}" CACHE STRING "")
+
+    set(RUNTIMES_${target}_CMAKE_SYSTEM_NAME Linux CACHE STRING "")
+    set(RUNTIMES_${target}_CMAKE_BUILD_TYPE Release CACHE STRING "")
+    set(RUNTIMES_${target}_CMAKE_SYSROOT ${STAGE2_LINUX_${target}_SYSROOT} CACHE STRING "")
+    set(RUNTIMES_${target}_LLVM_ENABLE_ASSERTIONS ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBUNWIND_ENABLE_SHARED OFF CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBUNWIND_USE_COMPILER_RT ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBUNWIND_INSTALL_LIBRARY OFF CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXXABI_USE_COMPILER_RT ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXXABI_ENABLE_SHARED OFF CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXXABI_USE_LLVM_UNWINDER ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXXABI_ENABLE_STATIC_UNWINDER ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXXABI_INSTALL_LIBRARY OFF CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXX_USE_COMPILER_RT ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXX_ENABLE_SHARED OFF CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXX_ENABLE_STATIC_ABI_LIBRARY ON CACHE BOOL "")
+    set(RUNTIMES_${target}_LIBCXX_ABI_VERSION 2 CACHE STRING "")
+    set(RUNTIMES_${target}_SANITIZER_CXX_ABI "libc++" CACHE STRING "")
+    set(RUNTIMES_${target}_SANITIZER_CXX_ABI_INTREE ON CACHE BOOL "")
+    set(RUNTIMES_${target}_COMPILER_RT_USE_BUILTINS_LIBRARY ON CACHE BOOL "")
+    set(LLVM_RUNTIME_TARGETS "${target}" CACHE STRING "")
+  endif()
+endif()
+
+if(UNIX)
+  set(BOOTSTRAP_CMAKE_SHARED_LINKER_FLAGS "-ldl -lpthread" CACHE STRING "")
+  set(BOOTSTRAP_CMAKE_MODULE_LINKER_FLAGS "-ldl -lpthread" CACHE STRING "")
+  set(BOOTSTRAP_CMAKE_EXE_LINKER_FLAGS "-ldl -lpthread" CACHE STRING "")
+endif()
+
+set(BOOTSTRAP_LLVM_ENABLE_LTO ON CACHE BOOL "")
+if(NOT APPLE)
+  set(BOOTSTRAP_LLVM_ENABLE_LLD ON CACHE BOOL "")
+endif()
+
 set(CLANG_BOOTSTRAP_TARGETS
   check-all
   check-llvm
   check-clang
+  check-lld
   llvm-config
   test-suite
   test-depends
   llvm-test-depends
   clang-test-depends
+  lld-test-depends
   distribution
   install-distribution
+  install-distribution-stripped
+  install-distribution-toolchain
   clang CACHE STRING "")
 
-foreach(target x86_64;aarch64)
-  if(FUCHSIA_${target}_SYSROOT)
-    list(APPEND EXTRA_ARGS -DFUCHSIA_${target}_SYSROOT=${FUCHSIA_${target}_SYSROOT})
+get_cmake_property(variableNames VARIABLES)
+foreach(variableName ${variableNames})
+  if(variableName MATCHES "^STAGE2_")
+    string(REPLACE "STAGE2_" "" new_name ${variableName})
+    list(APPEND EXTRA_ARGS "-D${new_name}=${${variableName}}")
   endif()
 endforeach()
 
 # Setup the bootstrap build.
 set(CLANG_ENABLE_BOOTSTRAP ON CACHE BOOL "")
+set(CLANG_BOOTSTRAP_EXTRA_DEPS
+  builtins
+  runtimes
+  CACHE STRING "")
 set(CLANG_BOOTSTRAP_CMAKE_ARGS
   ${EXTRA_ARGS}
   -C ${CMAKE_CURRENT_LIST_DIR}/Fuchsia-stage2.cmake

cmake/modules/AddClang.cmake

@@ -44,7 +44,7 @@ endmacro()
 
 macro(add_clang_library name)
   cmake_parse_arguments(ARG
-    "SHARED"
+    "SHARED;INSTALL_WITH_TOOLCHAIN"
     ""
     "ADDITIONAL_HEADERS"
     ${ARGN})
@@ -81,16 +81,30 @@ macro(add_clang_library name)
       )
   endif()
   if(ARG_SHARED)
-    set(ARG_ENABLE_SHARED SHARED)
+    set(LIBTYPE SHARED)
+  else()
+    # llvm_add_library ignores BUILD_SHARED_LIBS if STATIC is explicitly set,
+    # so we need to handle it here.
+    if(BUILD_SHARED_LIBS)
+      set(LIBTYPE SHARED)
+    else()
+      set(LIBTYPE STATIC)
+    endif()
+    if(NOT XCODE)
+      # The Xcode generator doesn't handle object libraries correctly.
+      list(APPEND LIBTYPE OBJECT)
+    endif()
+    set_property(GLOBAL APPEND PROPERTY CLANG_STATIC_LIBS ${name})
   endif()
-  llvm_add_library(${name} ${ARG_ENABLE_SHARED} ${ARG_UNPARSED_ARGUMENTS} ${srcs})
+  llvm_add_library(${name} ${LIBTYPE} ${ARG_UNPARSED_ARGUMENTS} ${srcs})
 
   if(TARGET ${name})
     target_link_libraries(${name} INTERFACE ${LLVM_COMMON_LIBS})
 
-    if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY OR ${name} STREQUAL "libclang")
-
+    if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY OR ARG_INSTALL_WITH_TOOLCHAIN)
+      set(export_to_clangtargets)
       if(${name} IN_LIST LLVM_DISTRIBUTION_COMPONENTS OR
+          "clang-libraries" IN_LIST LLVM_DISTRIBUTION_COMPONENTS OR
           NOT LLVM_DISTRIBUTION_COMPONENTS)
         set(export_to_clangtargets EXPORT ClangTargets)
         set_property(GLOBAL PROPERTY CLANG_HAS_EXPORTS True)
@@ -103,11 +117,13 @@ macro(add_clang_library name)
         ARCHIVE DESTINATION lib${LLVM_LIBDIR_SUFFIX}
         RUNTIME DESTINATION bin)
 
-      if (${ARG_SHARED} AND NOT CMAKE_CONFIGURATION_TYPES)
+      if (NOT LLVM_ENABLE_IDE)
         add_llvm_install_targets(install-${name}
                                  DEPENDS ${name}
                                  COMPONENT ${name})
       endif()
+
+      set_property(GLOBAL APPEND PROPERTY CLANG_LIBS ${name})
     endif()
     set_property(GLOBAL APPEND PROPERTY CLANG_EXPORTS ${name})
   else()
@@ -131,8 +147,10 @@ macro(add_clang_tool name)
   endif()
 
   add_clang_executable(${name} ${ARGN})
+  add_dependencies(${name} clang-resource-headers)
 
   if (CLANG_BUILD_TOOLS)
+    set(export_to_clangtargets)
     if(${name} IN_LIST LLVM_DISTRIBUTION_COMPONENTS OR
         NOT LLVM_DISTRIBUTION_COMPONENTS)
       set(export_to_clangtargets EXPORT ClangTargets)
@@ -144,7 +162,7 @@ macro(add_clang_tool name)
       RUNTIME DESTINATION bin
       COMPONENT ${name})
 
-    if(NOT CMAKE_CONFIGURATION_TYPES)
+    if(NOT LLVM_ENABLE_IDE)
       add_llvm_install_targets(install-${name}
                                DEPENDS ${name}
                                COMPONENT ${name})
@@ -158,3 +176,12 @@ macro(add_clang_symlink name dest)
   # Always generate install targets
   llvm_install_symlink(${name} ${dest} ALWAYS_GENERATE)
 endmacro()
+
+function(clang_target_link_libraries target type)
+  if (CLANG_LINK_CLANG_DYLIB)
+    target_link_libraries(${target} ${type} clang-cpp)
+  else()
+    target_link_libraries(${target} ${type} ${ARGN})
+  endif()
+
+endfunction()

cmake/modules/CMakeLists.txt

@@ -55,10 +55,19 @@ set(CLANG_CONFIG_EXPORTS_FILE)
 if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
   get_property(clang_has_exports GLOBAL PROPERTY CLANG_HAS_EXPORTS)
   if(clang_has_exports)
-    install(EXPORT ClangTargets DESTINATION ${CLANG_INSTALL_PACKAGE_DIR})
+    install(EXPORT ClangTargets DESTINATION ${CLANG_INSTALL_PACKAGE_DIR}
+            COMPONENT clang-cmake-exports)
   endif()
 
   install(FILES
     ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/ClangConfig.cmake
-    DESTINATION ${CLANG_INSTALL_PACKAGE_DIR})
+    DESTINATION ${CLANG_INSTALL_PACKAGE_DIR}
+    COMPONENT clang-cmake-exports)
+
+  if(NOT LLVM_ENABLE_IDE)
+    # Add a dummy target so this can be used with LLVM_DISTRIBUTION_COMPONENTS
+    add_custom_target(clang-cmake-exports)
+    add_llvm_install_targets(install-clang-cmake-exports
+                             COMPONENT clang-cmake-exports)
+  endif()
 endif()

cmake/modules/FindZ3.cmake

@@ -1,28 +0,0 @@
-find_path(Z3_INCLUDE_DIR NAMES z3.h
-   PATH_SUFFIXES libz3 z3
-   )
-
-find_library(Z3_LIBRARIES NAMES z3 libz3
-   )
-
-find_program(Z3_EXECUTABLE z3)
-
-if(Z3_INCLUDE_DIR AND Z3_EXECUTABLE)
-    execute_process (COMMAND ${Z3_EXECUTABLE} -version
-      OUTPUT_VARIABLE libz3_version_str
-      ERROR_QUIET
-      OUTPUT_STRIP_TRAILING_WHITESPACE)
-
-    string(REGEX REPLACE "^Z3 version ([0-9.]+)" "\\1"
-           Z3_VERSION_STRING "${libz3_version_str}")
-    unset(libz3_version_str)
-endif()
-
-# handle the QUIETLY and REQUIRED arguments and set Z3_FOUND to TRUE if
-# all listed variables are TRUE
-include(FindPackageHandleStandardArgs)
-FIND_PACKAGE_HANDLE_STANDARD_ARGS(Z3
-                                  REQUIRED_VARS Z3_LIBRARIES Z3_INCLUDE_DIR
-                                  VERSION_VAR Z3_VERSION_STRING)
-
-mark_as_advanced(Z3_INCLUDE_DIR Z3_LIBRARIES)

cmake/modules/ProtobufMutator.cmake

@@ -1,3 +1,4 @@
+include(ExternalProject)
 set(PBM_PREFIX protobuf_mutator)
 set(PBM_PATH ${CMAKE_CURRENT_BINARY_DIR}/${PBM_PREFIX}/src/${PBM_PREFIX})
 set(PBM_LIB_PATH ${PBM_PATH}-build/src/libprotobuf-mutator.a)

docs/AddressSanitizer.rst

@@ -24,7 +24,7 @@ Typical slowdown introduced by AddressSanitizer is **2x**.
 How to build
 ============
 
-Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_.
+Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_.
 
 Usage
 =====
@@ -119,7 +119,7 @@ force disabled by setting ``ASAN_OPTIONS=symbolize=0``):
         #1 0x7f7ddabcac4d in __libc_start_main ??:0
     ...
 
-Note that on OS X you may need to run ``dsymutil`` on your binary to have the
+Note that on macOS you may need to run ``dsymutil`` on your binary to have the
 file\:line info in the AddressSanitizer reports.
 
 Additional Checks
@@ -134,14 +134,14 @@ globals defined in another translation unit. To enable this check at runtime,
 you should set environment variable
 ``ASAN_OPTIONS=check_initialization_order=1``.
 
-Note that this option is not supported on OS X.
+Note that this option is not supported on macOS.
 
 Memory leak detection
 ---------------------
 
 For more information on leak detector in AddressSanitizer, see
 :doc:`LeakSanitizer`. The leak detection is turned on by default on Linux,
-and can be enabled using ``ASAN_OPTIONS=detect_leaks=1`` on OS X;
+and can be enabled using ``ASAN_OPTIONS=detect_leaks=1`` on macOS;
 however, it is not yet supported on other platforms.
 
 Issue Suppression
@@ -197,13 +197,17 @@ this purpose.
 Disabling Instrumentation with ``__attribute__((no_sanitize("address")))``
 --------------------------------------------------------------------------
 
-Some code should not be instrumented by AddressSanitizer. One may use the
-function attribute ``__attribute__((no_sanitize("address")))`` (which has
-deprecated synonyms `no_sanitize_address` and `no_address_safety_analysis`) to
-disable instrumentation of a particular function. This attribute may not be
-supported by other compilers, so we suggest to use it together with
+Some code should not be instrumented by AddressSanitizer. One may use
+the attribute ``__attribute__((no_sanitize("address")))`` (which has
+deprecated synonyms `no_sanitize_address` and
+`no_address_safety_analysis`) to disable instrumentation of a
+particular function. This attribute may not be supported by other
+compilers, so we suggest to use it together with
 ``__has_feature(address_sanitizer)``.
 
+The same attribute used on a global variable prevents AddressSanitizer
+from adding redzones around it and detecting out of bounds accesses.
+
 Suppressing Errors in Recompiled Code (Blacklist)
 -------------------------------------------------
 
@@ -261,7 +265,7 @@ Limitations
 * On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
   virtual address space. This means that tools like ``ulimit`` may not work as
   usually expected.
-* Static linking is not supported.
+* Static linking of executables is not supported.
 
 Supported Platforms
 ===================
@@ -269,10 +273,12 @@ Supported Platforms
 AddressSanitizer is supported on:
 
 * Linux i386/x86\_64 (tested on Ubuntu 12.04)
-* OS X 10.7 - 10.11 (i386/x86\_64)
+* macOS 10.7 - 10.11 (i386/x86\_64)
 * iOS Simulator
 * Android ARM
+* NetBSD i386/x86\_64
 * FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
+* Windows 8.1+ (i386/x86\_64)
 
 Ports to various other platforms are in progress.
 
@@ -283,6 +289,9 @@ AddressSanitizer is fully functional on supported platforms starting from LLVM
 3.1. The test suite is integrated into CMake build and can be run with ``make
 check-asan`` command.
 
+The Windows port is functional and is used by Chrome and Firefox, but it is not
+as well supported as the other ports.
+
 More Information
 ================
 

docs/AutomaticReferenceCounting.rst

@@ -9,7 +9,7 @@
 
     /*
      * Automatic numbering is described in this article:
-     * http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
+     * https://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
      */
     /*
      * Automatic numbering for the TOC.
@@ -268,7 +268,7 @@ ARC's semantics and restrictions.
   * There must be reliable conventions for whether and when "ownership" is
     passed between caller and callee, for both arguments and return values.
     Objective-C methods follow such a convention very reliably, at least for
-    system libraries on Mac OS X, and functions always pass objects at +0.  The
+    system libraries on macOS, and functions always pass objects at +0.  The
     C-based APIs for Core Foundation objects, on the other hand, have much more
     varied transfer semantics.
 
@@ -974,28 +974,66 @@ It is undefined behavior to access an ownership-qualified object through an
 lvalue of a differently-qualified type, except that any non-``__weak`` object
 may be read through an ``__unsafe_unretained`` lvalue.
 
-It is undefined behavior if a managed operation is performed on a ``__strong``
-or ``__weak`` object without a guarantee that it contains a primitive zero
-bit-pattern, or if the storage for such an object is freed or reused without the
-object being first assigned a null pointer.
+It is undefined behavior if the storage of a ``__strong`` or ``__weak``
+object is not properly initialized before the first managed operation
+is performed on the object, or if the storage of such an object is freed
+or reused before the object has been properly deinitialized.  Storage for
+a ``__strong`` or ``__weak`` object may be properly initialized by filling
+it with the representation of a null pointer, e.g. by acquiring the memory
+with ``calloc`` or using ``bzero`` to zero it out.  A ``__strong`` or
+``__weak`` object may be properly deinitialized by assigning a null pointer
+into it.  A ``__strong`` object may also be properly initialized
+by copying into it (e.g. with ``memcpy``) the representation of a
+different ``__strong`` object whose storage has been properly initialized;
+doing this properly deinitializes the source object and causes its storage
+to no longer be properly initialized.  A ``__weak`` object may not be
+representation-copied in this way.
+
+These requirements are followed automatically for objects whose
+initialization and deinitialization are under the control of ARC:
+
+* objects of static, automatic, and temporary storage duration
+* instance variables of Objective-C objects
+* elements of arrays where the array object's initialization and
+  deinitialization are under the control of ARC
+* fields of Objective-C struct types where the struct object's
+  initialization and deinitialization are under the control of ARC
+* non-static data members of Objective-C++ non-union class types
+* Objective-C++ objects and arrays of dynamic storage duration created
+  with the ``new`` or ``new[]`` operators and destroyed with the
+  corresponding ``delete`` or ``delete[]`` operator
+
+They are not followed automatically for these objects:
+
+* objects of dynamic storage duration created in other memory, such as
+  that returned by ``malloc``
+* union members
 
 .. admonition:: Rationale
 
-  ARC cannot differentiate between an assignment operator which is intended to
-  "initialize" dynamic memory and one which is intended to potentially replace
-  a value.  Therefore the object's pointer must be valid before letting ARC at
-  it.  Similarly, C and Objective-C do not provide any language hooks for
-  destroying objects held in dynamic memory, so it is the programmer's
-  responsibility to avoid leaks (``__strong`` objects) and consistency errors
-  (``__weak`` objects).
-
-These requirements are followed automatically in Objective-C++ when creating
-objects of retainable object owner type with ``new`` or ``new[]`` and destroying
-them with ``delete``, ``delete[]``, or a pseudo-destructor expression.  Note
-that arrays of nontrivially-ownership-qualified type are not ABI compatible with
-non-ARC code because the element type is non-POD: such arrays that are
-``new[]``'d in ARC translation units cannot be ``delete[]``'d in non-ARC
-translation units and vice-versa.
+  ARC must perform special operations when initializing an object and
+  when destroying it.  In many common situations, ARC knows when an
+  object is created and when it is destroyed and can ensure that these
+  operations are performed correctly.  Otherwise, however, ARC requires
+  programmer cooperation to establish its initialization invariants
+  because it is infeasible for ARC to dynamically infer whether they
+  are intact.  For example, there is no syntactic difference in C between
+  an assignment that is intended by the programmer to initialize a variable
+  and one that is intended to replace the existing value stored there,
+  but ARC must perform one operation or the other.  ARC chooses to always
+  assume that objects are initialized (except when it is in charge of
+  initializing them) because the only workable alternative would be to
+  ban all code patterns that could potentially be used to access
+  uninitialized memory, and that would be too limiting.  In practice,
+  this is rarely a problem because programmers do not generally need to
+  work with objects for which the requirements are not handled
+  automatically.
+
+Note that dynamically-allocated Objective-C++ arrays of
+nontrivially-ownership-qualified type are not ABI-compatible with non-ARC
+code because the non-ARC code will consider the element type to be POD.
+Such arrays that are ``new[]``'d in ARC translation units cannot be
+``delete[]``'d in non-ARC translation units and vice-versa.
 
 .. _arc.ownership.restrictions.pass_by_writeback:
 
@@ -1696,20 +1734,78 @@ A program is ill-formed if it refers to the ``NSAutoreleasePool`` class.
   rest of the language.  Not draining the pool during an unwind is apparently
   required by the Objective-C exceptions implementation.
 
+.. _arc.misc.externally_retained:
+
+Externally-Retained Variables
+-----------------------------
+
+In some situations, variables with strong ownership are considered
+externally-retained by the implementation. This means that the variable is
+retained elsewhere, and therefore the implementation can elide retaining and
+releasing its value. Such a variable is implicitly ``const`` for safety. In
+contrast with ``__unsafe_unretained``, an externally-retained variable still
+behaves as a strong variable outside of initialization and destruction. For
+instance, when an externally-retained variable is captured in a block the value
+of the variable is retained and released on block capture and destruction. It
+also affects C++ features such as lambda capture, ``decltype``, and template
+argument deduction.
+
+Implicitly, the implementation assumes that the :ref:`self parameter in a
+non-init method <arc.misc.self>` and the :ref:`variable in a for-in loop
+<arc.misc.enumeration>` are externally-retained.
+
+Externally-retained semantics can also be opted into with the
+``objc_externally_retained`` attribute. This attribute can apply to strong local
+variables, functions, methods, or blocks:
+
+.. code-block:: objc
+
+  @class WobbleAmount;
+
+  @interface Widget : NSObject
+  -(void)wobble:(WobbleAmount *)amount;
+  @end
+
+  @implementation Widget
+
+  -(void)wobble:(WobbleAmount *)amount
+           __attribute__((objc_externally_retained)) {
+    // 'amount' and 'alias' aren't retained on entry, nor released on exit.
+    __attribute__((objc_externally_retained)) WobbleAmount *alias = amount;
+  }
+  @end
+
+Annotating a function with this attribute makes every parameter with strong
+retainable object pointer type externally-retained, unless the variable was
+explicitly qualified with ``__strong``. For instance, ``first_param`` is
+externally-retained (and therefore ``const``) below, but not ``second_param``:
+
+.. code-block:: objc
+
+  __attribute__((objc_externally_retained))
+  void f(NSArray *first_param, __strong NSArray *second_param) {
+    // ...
+  }
+
+You can test if your compiler has support for ``objc_externally_retained`` with
+``__has_attribute``:
+
+.. code-block:: objc
+
+  #if __has_attribute(objc_externally_retained)
+  // Use externally retained...
+  #endif
+
 .. _arc.misc.self:
 
 ``self``
 --------
 
-The ``self`` parameter variable of an Objective-C method is never actually
-retained by the implementation.  It is undefined behavior, or at least
-dangerous, to cause an object to be deallocated during a message send to that
-object.
-
-To make this safe, for Objective-C instance methods ``self`` is implicitly
-``const`` unless the method is in the :ref:`init family
-<arc.family.semantics.init>`.  Further, ``self`` is **always** implicitly
-``const`` within a class method.
+The ``self`` parameter variable of an non-init Objective-C method is considered
+:ref:`externally-retained <arc.misc.externally_retained>` by the implementation.
+It is undefined behavior, or at least dangerous, to cause an object to be
+deallocated during a message send to that object.  In an init method, ``self``
+follows the :ref:``init family rules <arc.family.semantics.init>``.
 
 .. admonition:: Rationale
 
@@ -1720,9 +1816,9 @@ To make this safe, for Objective-C instance methods ``self`` is implicitly
   without this retain and release.  Since it's extremely uncommon to actually
   do so, even unintentionally, and since there's no natural way for the
   programmer to remove this retain/release pair otherwise (as there is for
-  other parameters by, say, making the variable ``__unsafe_unretained``), we
-  chose to make this optimizing assumption and shift some amount of risk to the
-  user.
+  other parameters by, say, making the variable ``objc_externally_retained`` or
+  qualifying it with ``__unsafe_unretained``), we chose to make this optimizing
+  assumption and shift some amount of risk to the user.
 
 .. _arc.misc.enumeration:
 
@@ -1731,8 +1827,9 @@ Fast enumeration iteration variables
 
 If a variable is declared in the condition of an Objective-C fast enumeration
 loop, and the variable has no explicit ownership qualifier, then it is
-qualified with ``const __strong`` and objects encountered during the
-enumeration are not actually retained.
+implicitly :ref:`externally-retained <arc.misc.externally_retained>` so that
+objects encountered during the enumeration are not actually retained and
+released.
 
 .. admonition:: Rationale
 
@@ -2246,8 +2343,8 @@ block exactly as if it had been sent the ``retain`` message.
 
 .. _arc.runtime.objc_storeStrong:
 
-``id objc_storeStrong(id *object, id value);``
-----------------------------------------------
+``void objc_storeStrong(id *object, id value);``
+------------------------------------------------
 
 *Precondition:* ``object`` is a valid pointer to a ``__strong`` object which is
 adequately aligned for a pointer.  ``value`` is null or a pointer to a valid

docs/Block-ABI-Apple.rst

@@ -61,6 +61,14 @@ The following flags bits are in use thusly for a possible ABI.2010.3.16:
 .. code-block:: c
 
     enum {
+        // Set to true on blocks that have captures (and thus are not true
+        // global blocks) but are known not to escape for various other
+        // reasons. For backward compatiblity with old runtimes, whenever
+        // BLOCK_IS_NOESCAPE is set, BLOCK_IS_GLOBAL is set too. Copying a
+        // non-escaping block returns the original block and releasing such a
+        // block is a no-op, which is exactly how global blocks are handled.
+        BLOCK_IS_NOESCAPE      =  (1 << 23),
+
         BLOCK_HAS_COPY_DISPOSE =  (1 << 25),
         BLOCK_HAS_CTOR =          (1 << 26), // helpers have C++ code
         BLOCK_IS_GLOBAL =         (1 << 28),

docs/Block-ABI-Apple.txt

@@ -1 +1 @@
-*NOTE* This document has moved to http://clang.llvm.org/docs/Block-ABI-Apple.html.
+*NOTE* This document has moved to https://clang.llvm.org/docs/Block-ABI-Apple.html.

docs/ClangCommandLineReference.rst

@@ -36,7 +36,7 @@ Treat source input files as Objective-C inputs
 
 Treat source input files as Objective-C++ inputs
 
-.. option:: -Qn
+.. option:: -Qn, -fno-ident
 
 Do not emit metadata containing compiler name and version
 
@@ -44,7 +44,7 @@ Do not emit metadata containing compiler name and version
 
 Don't emit warning for unused driver arguments
 
-.. option:: -Qy
+.. option:: -Qy, -fident
 
 Emit metadata containing compiler name and version
 
@@ -86,8 +86,6 @@ Pass <arg> to the target offloading toolchain identified by <triple>.
 
 Run the static analyzer
 
-.. option:: --analyze-auto
-
 .. option:: --analyzer-no-default-checks
 
 .. option:: --analyzer-output<arg>
@@ -158,7 +156,7 @@ Compile CUDA code for host only.  Has no effect on non-CUDA compilations.
 
 .. option:: --cuda-include-ptx=<arg>, --no-cuda-include-ptx=<arg>
 
-Include PTX for the follwing GPU architecture (e.g. sm\_35) or 'all'. May be specified more than once.
+Include PTX for the following GPU architecture (e.g. sm\_35) or 'all'. May be specified more than once.
 
 .. option:: --cuda-noopt-device-debug, --no-cuda-noopt-device-debug
 
@@ -214,9 +212,13 @@ Flush denormal floating point values to zero in CUDA device mode.
 
 Generate relocatable device code, also known as separate compilation mode.
 
+.. option:: -fcuda-short-ptr, -fno-cuda-short-ptr
+
+Use 32-bit pointers for accessing const/local/shared address spaces.
+
 .. option:: -ffixed-r19
 
-Reserve the r19 register (Hexagon only)
+Reserve register r19 (Hexagon only)
 
 .. option:: -fheinous-gnu-extensions
 
@@ -260,6 +262,10 @@ Display available options
 
 Display help for hidden options
 
+.. option:: --hip-link
+
+Link clang-offload-bundler bundles for HIP
+
 .. option:: -image\_base <arg>
 
 .. option:: -index-header-map
@@ -338,6 +344,8 @@ Disable builtin #include directories
 
 .. option:: -noprebind
 
+.. option:: -noprofilelib
+
 .. option:: -noseglinkedit
 
 .. option:: -nostartfiles
@@ -452,6 +460,10 @@ Use pipes between commands, when possible
 
 .. option:: --print-diagnostic-categories
 
+.. option:: -print-effective-triple, --print-effective-triple
+
+Print the effective target triple
+
 .. option:: -print-file-name=<file>, --print-file-name=<file>, --print-file-name <arg>
 
 Print the full library path of <file>
@@ -480,6 +492,10 @@ Print the resource directory pathname
 
 Print the paths used for finding libraries and programs
 
+.. option:: -print-target-triple, --print-target-triple
+
+Print the normalized target triple
+
 .. option:: -private\_bundle
 
 .. option:: -pthread, -no-pthread
@@ -558,6 +574,8 @@ Serialize compiler diagnostics to a file
 
 .. option:: -shared-libsan, -shared-libasan
 
+Dynamically link the sanitizer runtime
+
 .. option:: -single\_module
 
 .. option:: -specs=<arg>, --specs=<arg>
@@ -568,6 +586,8 @@ Serialize compiler diagnostics to a file
 
 .. option:: -static-libsan
 
+Statically link the sanitizer runtime
+
 .. option:: -static-libstdc++
 
 .. option:: -std-default=<arg>
@@ -590,6 +610,10 @@ C++ standard library to use
 
 Generate code for the given target
 
+.. option:: --print-supported-cpus
+
+Print supported cpu models for the given target
+
 .. option:: -time
 
 Time individual commands
@@ -712,6 +736,12 @@ Attempt to match the ABI of Clang <version>
 
 Treat each comma separated argument in <arg> as a documentation comment block command
 
+.. option:: -fcomplete-member-pointers, -fno-complete-member-pointers
+
+Require member pointer base types to be complete if they would be significant under the Microsoft ABI
+
+.. option:: -fcrash-diagnostics-dir=<arg>
+
 .. option:: -fdeclspec, -fno-declspec
 
 Allow \_\_declspec as a keyword
@@ -746,7 +776,7 @@ Enables an experimental new pass manager in LLVM.
 
 .. option:: -ffine-grained-bitfield-accesses, -fno-fine-grained-bitfield-accesses
 
-Use separate accesses for bitfields with legal widths and alignments.
+Use separate accesses for consecutive bitfield runs with legal widths and alignments.
 
 .. option:: -finline-functions, -fno-inline-functions
 
@@ -766,6 +796,16 @@ Don't use blacklist file for sanitizers
 
 .. option:: -fparse-all-comments
 
+.. option:: -frecord-command-line, -frecord-gcc-switches, -fno-record-command-line, -fno-record-gcc-switches
+
+Generate a section named ".GCC.command.line" containing the clang driver
+command-line. After linking, the section may contain multiple command lines,
+which will be individually terminated by null bytes. Separate arguments within
+a command line are combined with spaces; spaces and backslashes within an
+argument are escaped with backslashes. This format differs from the format of
+the equivalent section produced by GCC with the -frecord-gcc-switches flag.
+This option is currently only supported on ELF targets.
+
 .. option:: -fsanitize-address-field-padding=<arg>
 
 Level of field padding for AddressSanitizer
@@ -774,9 +814,15 @@ Level of field padding for AddressSanitizer
 
 Enable linker dead stripping of globals in AddressSanitizer
 
-.. option:: -fsanitize-address-poison-class-member-array-new-cookie, -fno-sanitize-address-poison-class-member-array-new-cookie
+.. option:: -fsanitize-address-use-odr-indicator, -fno-sanitize-address-use-odr-indicator
+
+Enable ODR indicator globals to avoid false ODR violation reports in partially sanitized programs at the cost of an increase in binary size
 
-Enable poisoning array cookies when using class member operator new\[\] in AddressSanitizer
+.. option:: -fsanitize-address-poison-custom-array-cookie, -fno-sanitize-address-poison-custom-array-cookie
+
+Enable "poisoning" array cookies when allocating arrays with a custom operator new\[\] in Address Sanitizer, preventing accesses to the cookies from user code. An array cookie is a small implementation-defined header added to certain array allocations to record metadata such as the length of the array. Accesses to array cookies from user code are technically allowed by the standard but are more likely to be the result of an out-of-bounds array access.
+
+An operator new\[\] is "custom" if it is not one of the allocation functions provided by the C++ standard library. Array cookies from non-custom allocation functions are always poisoned.
 
 .. option:: -fsanitize-address-use-after-scope, -fno-sanitize-address-use-after-scope
 
@@ -854,6 +900,10 @@ Strip (or keep only, if negative) a given number of path components when emittin
 
 Turn on runtime checks for various forms of undefined or suspicious behavior. See user manual for available checks
 
+.. option:: -moutline, -mno-outline
+
+Enable function outlining (AArch64 only)
+
 .. option:: --param <arg>, --param=<arg>
 
 .. option:: -std=<arg>, --std=<arg>, --std <arg>
@@ -1095,8 +1145,6 @@ Flags allowing the state of the preprocessor to be dumped in various ways.
 .. option:: -d<arg>
 .. program:: clang
 
-.. option:: -dA
-
 .. option:: -dD
 
 Print macro definitions in -E mode in addition to normal output
@@ -1151,6 +1199,10 @@ Target-independent compilation options
 
 .. option:: -faccess-control, -fno-access-control
 
+.. option:: -faddrsig, -fno-addrsig
+
+Emit an address-significance table
+
 .. option:: -falign-functions, -fno-align-functions
 
 .. program:: clang1
@@ -1223,12 +1275,20 @@ Accept non-standard constructs supported by the Borland compiler
 
 Load the clang builtins module map file.
 
+.. option:: -fc++-static-destructors, -fno-c++-static-destructors
+
+Enable C++ static destructor registration (the default)
+
 .. option:: -fcaret-diagnostics, -fno-caret-diagnostics
 
 .. option:: -fcf-protection=<arg>, -fcf-protection (equivalent to -fcf-protection=full)
 
 Instrument control-flow architecture protection. Options: return, branch, full, none.
 
+.. option:: -fchar8\_t, -fno-char8\_t
+
+Enable C++ builtin type char8\_t
+
 .. option:: -fclasspath=<arg>, --CLASSPATH <arg>, --CLASSPATH=<arg>, --classpath <arg>, --classpath=<arg>
 
 .. option:: -fcolor-diagnostics, -fno-color-diagnostics
@@ -1293,6 +1353,10 @@ Place debug types in their own section (ELF Only)
 
 Parse templated function definitions at the end of the translation unit
 
+.. option:: -fdelete-null-pointer-checks, -fno-delete-null-pointer-checks
+
+Treat usage of null pointers as undefined behavior.
+
 .. option:: -fdenormal-fp-math=<arg>
 
 .. option:: -fdiagnostics-absolute-paths
@@ -1325,6 +1389,10 @@ Print option name with mappable diagnostics
 
 Print a template comparison tree for differing templates
 
+.. option:: -fdigraphs, -fno-digraphs
+
+Enable alternative token representations '<:', ':>', '<%', '%>', '%:', '%:%:' (default)
+
 .. option:: -fdollars-in-identifiers, -fno-dollars-in-identifiers
 
 Allow '$' in identifiers
@@ -1375,8 +1443,16 @@ Allow aggressive, lossy floating-point optimizations
 
 .. option:: -ffinite-math-only, -fno-finite-math-only
 
+.. option:: -ffixed-point, -fno-fixed-point
+
+Enable fixed point types
+
 .. option:: -ffor-scope, -fno-for-scope
 
+.. option:: -fforce-emit-vtables, -fno-force-emit-vtables
+
+Emits more virtual tables to improve devirtualization
+
 .. option:: -fforce-enable-int128, -fno-force-enable-int128
 
 Enable support for int128\_t type
@@ -1439,6 +1515,10 @@ Enable the integrated assembler
 
 .. option:: -fjump-tables, -fno-jump-tables
 
+.. option:: -fkeep-static-consts
+
+Keep static const variables even if unused
+
 .. option:: -flax-vector-conversions, -fno-lax-vector-conversions
 
 .. option:: -flimited-precision=<arg>
@@ -1826,6 +1906,10 @@ Emit full debug info for all types used by the program
 
 Enable optimizations based on the strict definition of an enum's value range
 
+.. option:: -fstrict-float-cast-overflow, -fno-strict-float-cast-overflow
+
+Assume that overflowing float-to-int casts are undefined (default)
+
 .. option:: -fstrict-overflow, -fno-strict-overflow
 
 .. option:: -fstrict-return, -fno-strict-return
@@ -1856,6 +1940,15 @@ Perform ThinLTO importing using provided function summary index
 
 .. option:: -ftime-report
 
+.. option:: -ftime-trace
+
+Turn on time profiler. Results can be analyzed with chrome://tracing or
+`Speedscope App <https://www.speedscope.app>`_ for flamegraph visualization
+
+.. option:: -ftime-trace-granularity=<arg>
+
+Minimum time granularity (in microseconds) traced by time profiler
+
 .. option:: -ftls-model=<arg>
 
 .. option:: -ftrap-function=<arg>
@@ -1916,11 +2009,11 @@ Use the given vector functions library
 
 Enable the loop vectorization passes
 
-.. option:: -fverbose-asm, -fno-verbose-asm
+.. option:: -fverbose-asm, -fno-verbose-asm, -dA
 
 .. option:: -fvisibility-inlines-hidden
 
-Give inline C++ member functions default visibility by default
+Give inline C++ member functions hidden visibility by default
 
 .. option:: -fvisibility-ms-compat
 
@@ -2064,12 +2157,6 @@ Put objects of at most <size> bytes into small data section (MIPS / Hexagon)
 
 .. option:: -mabi=<arg>
 
-.. option:: -mabicalls, -mno-abicalls
-
-Enable SVR4-style position-independent code (Mips only)
-
-.. option:: -mabs=<arg>
-
 .. option:: -malign-double
 
 Align doubles to two words in structs (x86 only)
@@ -2082,25 +2169,21 @@ Align doubles to two words in structs (x86 only)
 
 Link stack frames through backchain on System Z
 
-.. option:: -mcheck-zero-division, -mno-check-zero-division
-
 .. option:: -mcmodel=<arg>
 
-.. option:: -mcompact-branches=<arg>
-
 .. option:: -mconsole<arg>
 
-.. option:: -mcpu=<arg>, -mv4 (equivalent to -mcpu=hexagonv4), -mv5 (equivalent to -mcpu=hexagonv5), -mv55 (equivalent to -mcpu=hexagonv55), -mv60 (equivalent to -mcpu=hexagonv60), -mv62 (equivalent to -mcpu=hexagonv62), -mv65 (equivalent to -mcpu=hexagonv65)
+.. option:: -mcpu=<arg>, -mv5 (equivalent to -mcpu=hexagonv5), -mv55 (equivalent to -mcpu=hexagonv55), -mv60 (equivalent to -mcpu=hexagonv60), -mv62 (equivalent to -mcpu=hexagonv62), -mv65 (equivalent to -mcpu=hexagonv65)
 
-.. option:: -mdefault-build-attributes<arg>, -mno-default-build-attributes<arg>
+Use -mcpu=? to see a list of supported cpu models.
 
-.. option:: -mdll<arg>
+.. option:: -mcrc, -mno-crc
 
-.. option:: -mdouble-float
+Allow use of CRC instructions (ARM/Mips only)
 
-.. option:: -mdsp, -mno-dsp
+.. option:: -mdefault-build-attributes<arg>, -mno-default-build-attributes<arg>
 
-.. option:: -mdspr2, -mno-dspr2
+.. option:: -mdll<arg>
 
 .. option:: -mdynamic-no-pic<arg>
 
@@ -2108,28 +2191,12 @@ Link stack frames through backchain on System Z
 
 Set EABI type, e.g. 4, 5 or gnu (default depends on triple)
 
-.. option:: -membedded-data, -mno-embedded-data
-
-Place constants in the .rodata section instead of the .sdata section even if they meet the -G <size> threshold (MIPS)
-
-.. option:: -mextern-sdata, -mno-extern-sdata
-
-Assume that externally defined data is in the small data if it meets the -G <size> threshold (MIPS)
-
 .. option:: -mfentry
 
-Insert calls to fentry at function entry (x86 only)
+Insert calls to fentry at function entry (x86/SystemZ only)
 
 .. option:: -mfloat-abi=<arg>
 
-.. option:: -mfp32
-
-Use 32-bit floating point registers (MIPS only)
-
-.. option:: -mfp64
-
-Use 64-bit floating point registers (MIPS only)
-
 .. option:: -mfpmath=<arg>
 
 .. option:: -mfpu=<arg>
@@ -2138,10 +2205,6 @@ Use 64-bit floating point registers (MIPS only)
 
 Enable merging of globals
 
-.. option:: -mgpopt, -mno-gpopt
-
-Use GP relative accesses for symbols known to be in a small data section (MIPS)
-
 .. option:: -mhard-float
 
 .. option:: -mhwdiv=<arg>, --mhwdiv <arg>, --mhwdiv=<arg>
@@ -2158,54 +2221,24 @@ Use Intel MCU ABI
 
 (integrated-as) Emit an object file which can be used with an incremental linker
 
-.. option:: -mindirect-jump=<arg>
-
-Change indirect jump instructions to inhibit speculation
-
 .. option:: -miphoneos-version-min=<arg>, -mios-version-min=<arg>
 
-.. option:: -mips16
-
 .. option:: -mkernel
 
-.. option:: -mldc1-sdc1, -mno-ldc1-sdc1
-
-.. option:: -mlocal-sdata, -mno-local-sdata
-
-Extend the -G behaviour to object local data (MIPS)
-
 .. option:: -mlong-calls, -mno-long-calls
 
 Generate branches with extended addressability, usually via indirect jumps.
 
 .. option:: -mmacosx-version-min=<arg>, -mmacos-version-min=<arg>
 
-Set Mac OS X deployment target
-
-.. option:: -mmadd4, -mno-madd4
-
-Enable the generation of 4-operand madd.s, madd.d and related instructions.
+Set macOS deployment target
 
 .. option:: -mmcu=<arg>
 
-.. option:: -mmicromips, -mno-micromips
-
 .. option:: -mms-bitfields, -mno-ms-bitfields
 
 Set the default structure layout to be compatible with the Microsoft compiler standard
 
-.. option:: -mmsa, -mno-msa
-
-Enable MSA ASE (MIPS only)
-
-.. option:: -mmt, -mno-mt
-
-Enable MT ASE (MIPS only)
-
-.. option:: -mnan=<arg>
-
-.. option:: -mno-mips16
-
 .. option:: -momit-leaf-frame-pointer, -mno-omit-leaf-frame-pointer
 
 Omit frame pointer setup for leaf functions
@@ -2238,11 +2271,15 @@ Enable hexagon-qdsp6 backward compatibility
 
 (integrated-as) Relax all machine instructions
 
+.. option:: -mretpoline, -mno-retpoline
+
 .. option:: -mrtd, -mno-rtd
 
 Make StdCall calling convention the default
 
-.. option:: -msingle-float
+.. option:: -msign-return-address=<arg>
+
+Select return address signing scope
 
 .. option:: -msoft-float, -mno-soft-float
 
@@ -2274,6 +2311,8 @@ The thread model to use, e.g. posix, single (posix by default)
 
 .. option:: -mtune=<arg>
 
+Use -mtune=? to see a list of supported cpu models.
+
 .. option:: -mtvos-version-min=<arg>, -mappletvos-version-min=<arg>
 
 .. option:: -municode<arg>
@@ -2288,14 +2327,80 @@ The thread model to use, e.g. posix, single (posix by default)
 
 .. option:: -mx32
 
-.. option:: -mxgot, -mno-xgot
-
 AARCH64
 -------
+.. option:: -ffixed-x1
+
+Reserve the x1 register (AArch64 only)
+
+.. option:: -ffixed-x2
+
+Reserve the x2 register (AArch64 only)
+
+.. option:: -ffixed-x3
+
+Reserve the x3 register (AArch64 only)
+
+.. option:: -ffixed-x4
+
+Reserve the x4 register (AArch64 only)
+
+.. option:: -ffixed-x5
+
+Reserve the x5 register (AArch64 only)
+
+.. option:: -ffixed-x6
+
+Reserve the x6 register (AArch64 only)
+
+.. option:: -ffixed-x7
+
+Reserve the x7 register (AArch64 only)
+
 .. option:: -ffixed-x18
 
 Reserve the x18 register (AArch64 only)
 
+.. option:: -ffixed-x20
+
+Reserve the x20 register (AArch64 only)
+
+.. option:: -fcall-saved-x8
+
+Make the x8 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x9
+
+Make the x9 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x10
+
+Make the x10 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x11
+
+Make the x11 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x12
+
+Make the x12 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x13
+
+Make the x13 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x14
+
+Make the x14 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x15
+
+Make the x15 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x18
+
+Make the x18 register call-saved (AArch64 only)
+
 .. option:: -mfix-cortex-a53-835769, -mno-fix-cortex-a53-835769
 
 Workaround Cortex-A53 erratum 835769 (AArch64 only)
@@ -2306,6 +2411,15 @@ Generate code which only uses the general purpose registers (AArch64 only)
 
 AMDGPU
 ------
+.. option:: -mcumode, -mno-cumode
+
+CU wavefront execution mode is used if enabled and WGP wavefront execution mode
+is used if disabled (AMDGPU only)
+
+.. option:: -mwavefrontsize64, -mno-wavefrontsize64
+
+Wavefront size 64 is used if enabled and wavefront size 32 if disabled (AMDGPU only)
+
 .. option:: -mxnack, -mno-xnack
 
 Enable XNACK (AMDGPU only)
@@ -2316,10 +2430,6 @@ ARM
 
 Reserve the r9 register (ARM only)
 
-.. option:: -mcrc
-
-Allow use of CRC instructions (ARM only)
-
 .. option:: -mexecute-only, -mno-execute-only, -mpure-code
 
 Disallow generation of data access to code sections (ARM only)
@@ -2352,6 +2462,18 @@ Hexagon
 -------
 .. option:: -mieee-rnd-near
 
+.. option:: -mmemops, -mno-memops
+
+Enable generation of memop instructions
+
+.. option:: -mnvj, -mno-nvj
+
+Enable generation of new-value jumps
+
+.. option:: -mnvs, -mno-nvs
+
+Enable generation of new-value stores
+
 .. option:: -mpackets, -mno-packets
 
 Enable generation of instruction packets
@@ -2372,6 +2494,82 @@ Set Hexagon Vector Length
 
 Enable Hexagon Vector eXtensions
 
+MIPS
+----
+.. option:: -mabicalls, -mno-abicalls
+
+Enable SVR4-style position-independent code (Mips only)
+
+.. option:: -mabs=<arg>
+
+.. option:: -mcheck-zero-division, -mno-check-zero-division
+
+.. option:: -mcompact-branches=<arg>
+
+.. option:: -mdouble-float
+
+.. option:: -mdsp, -mno-dsp
+
+.. option:: -mdspr2, -mno-dspr2
+
+.. option:: -membedded-data, -mno-embedded-data
+
+Place constants in the .rodata section instead of the .sdata section even if they meet the -G <size> threshold (MIPS)
+
+.. option:: -mextern-sdata, -mno-extern-sdata
+
+Assume that externally defined data is in the small data if it meets the -G <size> threshold (MIPS)
+
+.. option:: -mfp32
+
+Use 32-bit floating point registers (MIPS only)
+
+.. option:: -mfp64
+
+Use 64-bit floating point registers (MIPS only)
+
+.. option:: -mginv, -mno-ginv
+
+.. option:: -mgpopt, -mno-gpopt
+
+Use GP relative accesses for symbols known to be in a small data section (MIPS)
+
+.. option:: -mindirect-jump=<arg>
+
+Change indirect jump instructions to inhibit speculation
+
+.. option:: -mips16
+
+.. option:: -mldc1-sdc1, -mno-ldc1-sdc1
+
+.. option:: -mlocal-sdata, -mno-local-sdata
+
+Extend the -G behaviour to object local data (MIPS)
+
+.. option:: -mmadd4, -mno-madd4
+
+Enable the generation of 4-operand madd.s, madd.d and related instructions.
+
+.. option:: -mmicromips, -mno-micromips
+
+.. option:: -mmsa, -mno-msa
+
+Enable MSA ASE (MIPS only)
+
+.. option:: -mmt, -mno-mt
+
+Enable MT ASE (MIPS only)
+
+.. option:: -mnan=<arg>
+
+.. option:: -mno-mips16
+
+.. option:: -msingle-float
+
+.. option:: -mvirt, -mno-virt
+
+.. option:: -mxgot, -mno-xgot
+
 PowerPC
 -------
 .. option:: -maltivec, -mno-altivec
@@ -2436,6 +2634,8 @@ X86
 
 .. option:: -mavx512bitalg, -mno-avx512bitalg
 
+.. option:: -mavx512bf16, -mno-avx512bf16
+
 .. option:: -mavx512bw, -mno-avx512bw
 
 .. option:: -mavx512cd, -mno-avx512cd
@@ -2458,6 +2658,8 @@ X86
 
 .. option:: -mavx512vnni, -mno-avx512vnni
 
+.. option:: -mavx512vp2intersect, -mno-avx512vp2intersect
+
 .. option:: -mavx512vpopcntdq, -mno-avx512vpopcntdq
 
 .. option:: -mbmi, -mno-bmi
@@ -2474,6 +2676,8 @@ X86
 
 .. option:: -mcx16, -mno-cx16
 
+.. option:: -menqcmd, -mno-enqcmd
+
 .. option:: -mf16c, -mno-f16c
 
 .. option:: -mfma, -mno-fma
@@ -2486,7 +2690,7 @@ X86
 
 .. option:: -mgfni, -mno-gfni
 
-.. option:: -mibt, -mno-ibt
+.. option:: -minvpcid, -mno-invpcid
 
 .. option:: -mlwp, -mno-lwp
 
@@ -2496,12 +2700,18 @@ X86
 
 .. option:: -mmovbe, -mno-movbe
 
+.. option:: -mmovdir64b, -mno-movdir64b
+
+.. option:: -mmovdiri, -mno-movdiri
+
 .. option:: -mmpx, -mno-mpx
 
 .. option:: -mmwaitx, -mno-mwaitx
 
 .. option:: -mpclmul, -mno-pclmul
 
+.. option:: -mpconfig, -mno-pconfig
+
 .. option:: -mpku, -mno-pku
 
 .. option:: -mpopcnt, -mno-popcnt
@@ -2510,14 +2720,14 @@ X86
 
 .. option:: -mprfchw, -mno-prfchw
 
+.. option:: -mptwrite, -mno-ptwrite
+
 .. option:: -mrdpid, -mno-rdpid
 
 .. option:: -mrdrnd, -mno-rdrnd
 
 .. option:: -mrdseed, -mno-rdseed
 
-.. option:: -mretpoline, -mno-retpoline
-
 .. option:: -mretpoline-external-thunk, -mno-retpoline-external-thunk
 
 .. option:: -mrtm, -mno-rtm
@@ -2568,6 +2778,12 @@ X86
 
 .. option:: -mxsaves, -mno-xsaves
 
+RISCV
+-----
+.. option:: -mrelax, -mno-relax
+
+Enable linker relaxation
+
 Optimization level
 ~~~~~~~~~~~~~~~~~~
 
@@ -2651,9 +2867,11 @@ Debug information flags
 
 Embed source text in DWARF debug sections
 
-.. option:: -ggnu-pubnames
+.. option:: -ggnu-pubnames, -gno-gnu-pubnames
 
-.. option:: -grecord-gcc-switches, -gno-record-gcc-switches
+.. option:: -gpubnames, -gno-pubnames
+
+.. option:: -grecord-command-line, -grecord-gcc-switches, -gno-record-command-line, -gno-record-gcc-switches
 
 .. option:: -gsplit-dwarf
 
@@ -2866,6 +3084,14 @@ Pass <arg> to the linker
 
 .. option:: -filelist <arg>
 
+.. option:: --hip-device-lib-path=<arg>
+
+HIP device library path
+
+.. option:: --hip-device-lib=<arg>
+
+HIP device library
+
 .. option:: -l<arg>
 
 .. option:: -r

docs/ClangFormat.rst

@@ -11,12 +11,12 @@ Standalone Tool
 ===============
 
 :program:`clang-format` is located in `clang/tools/clang-format` and can be used
-to format C/C++/Java/JavaScript/Objective-C/Protobuf code.
+to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code.
 
 .. code-block:: console
 
   $ clang-format -help
-  OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf code.
+  OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code.
 
   If no arguments are specified, it formats the code from standard input
   and writes the result to the standard output.
@@ -165,11 +165,24 @@ menu item by renaming the script, and can assign the menu item a keyboard
 shortcut in the BBEdit preferences, under Menus & Shortcuts.
 
 
+CLion Integration
+==================
+
+:program:`clang-format` is integrated into `CLion <https://www.jetbrains
+.com/clion/>`_ as an alternative code formatter. It is disabled by default and
+can be turned on in Settings/Preferences | Editor | Code Style.
+
+If :program:`clang-format` support is enabled, CLion detects config files when
+opening a project and suggests overriding the current IDE settings. Code style
+rules from the ``.clang-format`` files are then applied automatically to all
+editor actions, including auto-completion, code generation, and refactorings.
+
+
 Visual Studio Integration
 =========================
 
 Download the latest Visual Studio extension from the `alpha build site
-<http://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
+<https://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
 
 
 Script for patch reformatting
@@ -200,6 +213,12 @@ So to reformat all the lines in the latest :program:`git` commit, just do:
 
   git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1
 
+With Mercurial/:program:`hg`:
+
+.. code-block:: console
+
+  hg diff -U0 --color=never | clang-format-diff.py -i -p1
+
 In an SVN client, you can do:
 
 .. code-block:: console

docs/ClangFormatStyleOptions.rst

@@ -7,8 +7,8 @@ supported by :doc:`LibFormat` and :doc:`ClangFormat`.
 
 When using :program:`clang-format` command line utility or
 ``clang::format::reformat(...)`` functions from code, one can either use one of
-the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit) or create a
-custom style by configuring specific style options.
+the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft) or
+create a custom style by configuring specific style options.
 
 
 Configuring Style with clang-format
@@ -68,6 +68,10 @@ An example of a configuration file for multiple languages:
   Language: Proto
   # Don't format .proto files.
   DisableFormat: true
+  ---
+  Language: CSharp
+  # Use 100 columns for C#.
+  ColumnLimit: 100
   ...
 
 An easy way to get a valid ``.clang-format`` file containing all configuration
@@ -108,7 +112,7 @@ Configuring Style in Code
 
 When using ``clang::format::reformat(...)`` functions, the format is specified
 by supplying the `clang::format::FormatStyle
-<http://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
+<https://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
 structure.
 
 
@@ -131,19 +135,22 @@ the configuration (without a prefix: ``Auto``).
 
   * ``LLVM``
     A style complying with the `LLVM coding standards
-    <http://llvm.org/docs/CodingStandards.html>`_
+    <https://llvm.org/docs/CodingStandards.html>`_
   * ``Google``
     A style complying with `Google's C++ style guide
-    <http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml>`_
+    <https://google.github.io/styleguide/cppguide.html>`_
   * ``Chromium``
     A style complying with `Chromium's style guide
-    <http://www.chromium.org/developers/coding-style>`_
+    <https://chromium.googlesource.com/chromium/src/+/master/styleguide/styleguide.md>`_
   * ``Mozilla``
     A style complying with `Mozilla's style guide
     <https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_
   * ``WebKit``
     A style complying with `WebKit's style guide
-    <http://www.webkit.org/coding/coding-style.html>`_
+    <https://www.webkit.org/coding/coding-style.html>`_
+  * ``Microsoft``
+    A style complying with `Microsoft's style guide
+    <https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2017>`_
 
 .. START_FORMAT_STYLE_OPTIONS
 
@@ -209,6 +216,20 @@ the configuration (without a prefix: ``Auto``).
     float       b = 23;
     std::string ccc = 23;
 
+**AlignConsecutiveMacros** (``bool``)
+  If ``true``, aligns consecutive C/C++ preprocessor macros.
+
+  This will align C/C++ preprocessor macros of consecutive lines.
+  Will result in formattings like
+
+  .. code-block:: c++
+
+    #define SHORT_NAME       42
+    #define LONGER_NAME      0x007f
+    #define EVEN_LONGER_NAME (2)
+    #define foo(x)           (x * x)
+    #define bar(y, z)        (y + z)
+
 **AlignEscapedNewlines** (``EscapedNewlineAlignmentStyle``)
   Options for aligning backslashes in escaped newlines.
 
@@ -270,6 +291,41 @@ the configuration (without a prefix: ``Auto``).
     int a;     // My comment a      vs.     int a; // My comment a
     int b = 2; // comment  b                int b = 2; // comment about b
 
+**AllowAllArgumentsOnNextLine** (``bool``)
+  If a function call or braced initializer list doesn't fit on a
+  line, allow putting all arguments onto the next line, even if
+  ``BinPackArguments`` is ``false``.
+
+  .. code-block:: c++
+
+    true:
+    callFunction(
+        a, b, c, d);
+
+    false:
+    callFunction(a,
+                 b,
+                 c,
+                 d);
+
+**AllowAllConstructorInitializersOnNextLine** (``bool``)
+  If a constructor definition with a member initializer list doesn't
+  fit on a single line, allow putting all member initializers onto the next
+  line, if ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is true.
+  Note that this parameter has no effect if
+  ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is false.
+
+  .. code-block:: c++
+
+    true:
+    MyClass::MyClass() :
+        member0(0), member1(2) {}
+
+    false:
+    MyClass::MyClass() :
+        member0(0),
+        member1(2) {}
+
 **AllowAllParametersOfDeclarationOnNextLine** (``bool``)
   If the function declaration doesn't fit on a line,
   allow putting all parameters of a function declaration onto
@@ -288,10 +344,42 @@ the configuration (without a prefix: ``Auto``).
                     int d,
                     int e);
 
-**AllowShortBlocksOnASingleLine** (``bool``)
-  Allows contracting simple braced statements to a single line.
+**AllowShortBlocksOnASingleLine** (``ShortBlockStyle``)
+  Dependent on the value, ``while (true) { continue; }`` can be put on a
+  single line.
+
+  Possible values:
+
+  * ``SBS_Never`` (in configuration: ``Never``)
+    Never merge blocks into a single line.
+
+    .. code-block:: c++
+
+      while (true) {
+      }
+      while (true) {
+        continue;
+      }
+
+  * ``SBS_Empty`` (in configuration: ``Empty``)
+    Only merge empty blocks.
+
+    .. code-block:: c++
+
+      while (true) {}
+      while (true) {
+        continue;
+      }
+
+  * ``SBS_Always`` (in configuration: ``Always``)
+    Always merge short blocks into a single line.
+
+    .. code-block:: c++
+
+      while (true) {}
+      while (true) { continue; }
+
 
-  E.g., this allows ``if (a) { return; }`` to be put on a single line.
 
 **AllowShortCaseLabelsOnASingleLine** (``bool``)
   If ``true``, short case labels will be contracted to a single line.
@@ -367,9 +455,84 @@ the configuration (without a prefix: ``Auto``).
 
 
 
-**AllowShortIfStatementsOnASingleLine** (``bool``)
+**AllowShortIfStatementsOnASingleLine** (``ShortIfStyle``)
   If ``true``, ``if (a) return;`` can be put on a single line.
 
+  Possible values:
+
+  * ``SIS_Never`` (in configuration: ``Never``)
+    Never put short ifs on the same line.
+
+    .. code-block:: c++
+
+      if (a)
+        return ;
+      else {
+        return;
+      }
+
+  * ``SIS_WithoutElse`` (in configuration: ``WithoutElse``)
+    Without else put short ifs on the same line only if
+    the else is not a compound statement.
+
+    .. code-block:: c++
+
+      if (a) return;
+      else
+        return;
+
+  * ``SIS_Always`` (in configuration: ``Always``)
+    Always put short ifs on the same line if
+    the else is not a compound statement or not.
+
+    .. code-block:: c++
+
+      if (a) return;
+      else {
+        return;
+      }
+
+
+
+**AllowShortLambdasOnASingleLine** (``ShortLambdaStyle``)
+  Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a
+  single line.
+
+  Possible values:
+
+  * ``SLS_None`` (in configuration: ``None``)
+    Never merge lambdas into a single line.
+
+  * ``SLS_Empty`` (in configuration: ``Empty``)
+    Only merge empty lambdas.
+
+    .. code-block:: c++
+
+      auto lambda = [](int a) {}
+      auto lambda2 = [](int a) {
+          return a;
+      };
+
+  * ``SLS_Inline`` (in configuration: ``Inline``)
+    Merge lambda into a single line if argument of a function.
+
+    .. code-block:: c++
+
+      auto lambda = [](int a) {
+          return a;
+      };
+      sort(a.begin(), a.end(), ()[] { return x < y; })
+
+  * ``SLS_All`` (in configuration: ``All``)
+    Merge all lambdas fitting on a single line.
+
+    .. code-block:: c++
+
+      auto lambda = [](int a) {}
+      auto lambda2 = [](int a) { return a; };
+
+
+
 **AllowShortLoopsOnASingleLine** (``bool``)
   If ``true``, ``while (true) continue;`` can be put on a single
   line.
@@ -490,15 +653,50 @@ the configuration (without a prefix: ``Auto``).
          "bbbb"                                    "cccc";
          "cccc";
 
-**AlwaysBreakTemplateDeclarations** (``bool``)
-  If ``true``, always break after the ``template<...>`` of a template
-  declaration.
+**AlwaysBreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``)
+  The template declaration breaking style to use.
+
+  Possible values:
+
+  * ``BTDS_No`` (in configuration: ``No``)
+    Do not force break before declaration.
+    ``PenaltyBreakTemplateDeclaration`` is taken into account.
+
+    .. code-block:: c++
+
+       template <typename T> T foo() {
+       }
+       template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
+                                   int bbbbbbbbbbbbbbbbbbbbb) {
+       }
+
+  * ``BTDS_MultiLine`` (in configuration: ``MultiLine``)
+    Force break after template declaration only when the following
+    declaration spans multiple lines.
+
+    .. code-block:: c++
+
+       template <typename T> T foo() {
+       }
+       template <typename T>
+       T foo(int aaaaaaaaaaaaaaaaaaaaa,
+             int bbbbbbbbbbbbbbbbbbbbb) {
+       }
+
+  * ``BTDS_Yes`` (in configuration: ``Yes``)
+    Always break after template declaration.
+
+    .. code-block:: c++
+
+       template <typename T>
+       T foo() {
+       }
+       template <typename T>
+       T foo(int aaaaaaaaaaaaaaaaaaaaa,
+             int bbbbbbbbbbbbbbbbbbbbb) {
+       }
 
-  .. code-block:: c++
 
-     true:                                  false:
-     template <typename T>          vs.     template <typename T> class C {};
-     class C {};
 
 **BinPackArguments** (``bool``)
   If ``false``, a function call's arguments will either be all on the
@@ -552,6 +750,23 @@ the configuration (without a prefix: ``Auto``).
   Nested configuration flags:
 
 
+  * ``bool AfterCaseLabel`` Wrap case labels.
+
+    .. code-block:: c++
+
+      false:                                true:
+      switch (foo) {                vs.     switch (foo) {
+        case 1: {                             case 1:
+          bar();                              {
+          break;                                bar();
+        }                                       break;
+        default: {                            }
+          plop();                             default:
+        }                                     {
+      }                                         plop();
+                                              }
+                                            }
+
   * ``bool AfterClass`` Wrap class definitions.
 
     .. code-block:: c++
@@ -563,24 +778,46 @@ the configuration (without a prefix: ``Auto``).
       class foo
       {};
 
-  * ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..).
+  * ``BraceWrappingAfterControlStatementStyle AfterControlStatement``
+    Wrap control statements (``if``/``for``/``while``/``switch``/..).
 
-    .. code-block:: c++
+    Possible values:
 
-      true:
-      if (foo())
-      {
-      } else
-      {}
-      for (int i = 0; i < 10; ++i)
-      {}
+    * ``BWACS_Never`` (in configuration: ``Never``)
+      Never wrap braces after a control statement.
 
-      false:
-      if (foo()) {
-      } else {
-      }
-      for (int i = 0; i < 10; ++i) {
-      }
+      .. code-block:: c++
+
+        if (foo()) {
+        } else {
+        }
+        for (int i = 0; i < 10; ++i) {
+        }
+
+    * ``BWACS_MultiLine`` (in configuration: ``MultiLine``)
+      Only wrap braces after a multi-line control statement.
+
+      .. code-block:: c++
+
+        if (foo && bar &&
+            baz)
+        {
+          quux();
+        }
+        while (foo || bar) {
+        }
+
+    * ``BWACS_Always`` (in configuration: ``Always``)
+      Always wrap braces after a control statement.
+
+      .. code-block:: c++
+
+        if (foo())
+        {
+        } else
+        {}
+        for (int i = 0; i < 10; ++i)
+        {}
 
   * ``bool AfterEnum`` Wrap enum definitions.
 
@@ -873,39 +1110,73 @@ the configuration (without a prefix: ``Auto``).
 
       try {
         foo();
-      } catch () {
+      }
+      catch () {
       }
       void foo() { bar(); }
-      class foo
-      {
+      class foo {
       };
       if (foo()) {
-      } else {
       }
-      enum X : int
-      {
-        A,
-        B
-      };
+      else {
+      }
+      enum X : int { A, B };
 
   * ``BS_Allman`` (in configuration: ``Allman``)
     Always break before braces.
 
     .. code-block:: c++
 
-      try {
+      try
+      {
         foo();
       }
-      catch () {
+      catch ()
+      {
       }
       void foo() { bar(); }
-      class foo {
+      class foo
+      {
       };
-      if (foo()) {
+      if (foo())
+      {
       }
-      else {
+      else
+      {
       }
-      enum X : int { A, B };
+      enum X : int
+      {
+        A,
+        B
+      };
+
+  * ``BS_Whitesmiths`` (in configuration: ``Whitesmiths``)
+    Like ``Allman`` but always indent braces and line up code with braces.
+
+    .. code-block:: c++
+
+      try
+        {
+        foo();
+        }
+      catch ()
+        {
+        }
+      void foo() { bar(); }
+      class foo
+        {
+        };
+      if (foo())
+        {
+        }
+      else
+        {
+        }
+      enum X : int
+        {
+        A,
+        B
+        };
 
   * ``BS_GNU`` (in configuration: ``GNU``)
     Always break before braces and add an extra level of indentation to
@@ -959,18 +1230,6 @@ the configuration (without a prefix: ``Auto``).
 
 
 
-**BreakBeforeInheritanceComma** (``bool``)
-  If ``true``, in the class inheritance expression clang-format will
-  break before ``:`` and ``,`` if there is multiple inheritance.
-
-  .. code-block:: c++
-
-     true:                                  false:
-     class MyClass                  vs.     class MyClass : public X, public Y {
-         : public X                         };
-         , public Y {
-     };
-
 **BreakBeforeTernaryOperators** (``bool``)
   If ``true``, ternary operators will be placed after line breaks.
 
@@ -996,9 +1255,9 @@ the configuration (without a prefix: ``Auto``).
 
     .. code-block:: c++
 
-    Constructor()
-        : initializer1(),
-          initializer2()
+       Constructor()
+           : initializer1(),
+             initializer2()
 
   * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``)
     Break constructor initializers before the colon and commas, and align
@@ -1006,18 +1265,56 @@ the configuration (without a prefix: ``Auto``).
 
     .. code-block:: c++
 
-    Constructor()
-        : initializer1()
-        , initializer2()
+       Constructor()
+           : initializer1()
+           , initializer2()
 
   * ``BCIS_AfterColon`` (in configuration: ``AfterColon``)
     Break constructor initializers after the colon and commas.
 
     .. code-block:: c++
 
-    Constructor() :
-        initializer1(),
-        initializer2()
+       Constructor() :
+           initializer1(),
+           initializer2()
+
+
+
+**BreakInheritanceList** (``BreakInheritanceListStyle``)
+  The inheritance list style to use.
+
+  Possible values:
+
+  * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``)
+    Break inheritance list before the colon and after the commas.
+
+    .. code-block:: c++
+
+       class Foo
+           : Base1,
+             Base2
+       {};
+
+  * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``)
+    Break inheritance list before the colon and commas, and align
+    the commas with the colon.
+
+    .. code-block:: c++
+
+       class Foo
+           : Base1
+           , Base2
+       {};
+
+  * ``BILS_AfterColon`` (in configuration: ``AfterColon``)
+    Break inheritance list after the colon and commas.
+
+    .. code-block:: c++
+
+       class Foo :
+           Base1,
+           Base2
+       {};
 
 
 
@@ -1087,7 +1384,7 @@ the configuration (without a prefix: ``Auto``).
 
 **ConstructorInitializerIndentWidth** (``unsigned``)
   The number of characters to use for indentation of constructor
-  initializer lists.
+  initializer lists as well as inheritance lists.
 
 **ContinuationIndentWidth** (``unsigned``)
   Indent width for line continuations.
@@ -1154,7 +1451,7 @@ the configuration (without a prefix: ``Auto``).
      true:                                  false:
      namespace a {                  vs.     namespace a {
      foo();                                 foo();
-     } // namespace a;                      }
+     } // namespace a                       }
 
 **ForEachMacros** (``std::vector<std::string>``)
   A vector of macros that should be interpreted as foreach loops
@@ -1219,6 +1516,10 @@ the configuration (without a prefix: ``Auto``).
   Regular expressions denoting the different ``#include`` categories
   used for ordering ``#includes``.
 
+  `POSIX extended
+  <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
+  regular expressions are supported.
+
   These regular expressions are matched against the filename of an include
   (including the <> or "") in order. The value belonging to the first
   matching regular expression is assigned and ``#includes`` are sorted first
@@ -1228,10 +1529,17 @@ the configuration (without a prefix: ``Auto``).
   If none of the regular expressions match, INT_MAX is assigned as
   category. The main header for a source file automatically gets category 0.
   so that it is generally kept at the beginning of the ``#includes``
-  (http://llvm.org/docs/CodingStandards.html#include-style). However, you
+  (https://llvm.org/docs/CodingStandards.html#include-style). However, you
   can also assign negative priorities if you have certain headers that
   always need to be first.
 
+  There is a third and optional field ``SortPriority`` which can used while
+  ``IncludeBloks = IBS_Regroup`` to define the priority in which ``#includes``
+  should be ordered, and value of ``Priority`` defines the order of
+  ``#include blocks`` and also enables to group ``#includes`` of different
+  priority for order.``SortPriority`` is set to the value of ``Priority``
+  as default if it is not assigned.
+
   To configure this in the .clang-format file, use:
 
   .. code-block:: yaml
@@ -1239,10 +1547,14 @@ the configuration (without a prefix: ``Auto``).
     IncludeCategories:
       - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
         Priority:        2
+        SortPriority:    2
       - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
         Priority:        3
+      - Regex:           '<[[:alnum:].]+>'
+        Priority:        4
       - Regex:           '.*'
         Priority:        1
+        SortPriority:    0
 
 **IncludeIsMainRegex** (``std::string``)
   Specify a regular expression of suffixes that are allowed in the
@@ -1274,6 +1586,23 @@ the configuration (without a prefix: ``Auto``).
        plop();                                  plop();
      }                                      }
 
+**IndentGotoLabels** (``bool``)
+  Indent goto labels.
+
+  When ``false``, goto labels are flushed left.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     int f() {                      vs.     int f() {
+       if (foo()) {                           if (foo()) {
+       label1:                              label1:
+         bar();                                 bar();
+       }                                      }
+     label2:                                label2:
+       return 1;                              return 1;
+     }                                      }
+
 **IndentPPDirectives** (``PPDirectiveIndentStyle``)
   The preprocessor directive indenting style to use.
 
@@ -1301,6 +1630,17 @@ the configuration (without a prefix: ``Auto``).
        #  endif
        #endif
 
+  * ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``)
+    Indents directives before the hash.
+
+    .. code-block:: c++
+
+       #if FOO
+         #if BAR
+           #include <foo>
+         #endif
+       #endif
+
 
 
 **IndentWidth** (``unsigned``)
@@ -1331,6 +1671,39 @@ the configuration (without a prefix: ``Auto``).
      LoooooooooooooooooooooooooooooooooooooooongReturnType
      LoooooooooooooooooooooooooooooooongFunctionDeclaration();
 
+**JavaImportGroups** (``std::vector<std::string>``)
+  A vector of prefixes ordered by the desired groups for Java imports.
+
+  Each group is separated by a newline. Static imports will also follow the
+  same grouping convention above all non-static imports. One group's prefix
+  can be a subset of another - the longest prefix is always matched. Within
+  a group, the imports are ordered lexicographically.
+
+  In the .clang-format configuration file, this can be configured like
+  in the following yaml example. This will result in imports being
+  formatted as in the Java example below.
+
+  .. code-block:: yaml
+
+    JavaImportGroups: ['com.example', 'com', 'org']
+
+
+  .. code-block:: java
+
+     import static com.example.function1;
+
+     import static com.test.function2;
+
+     import static org.example.function3;
+
+     import com.example.ClassA;
+     import com.example.Test;
+     import com.example.a.ClassB;
+
+     import com.test.ClassC;
+
+     import org.example.ClassD;
+
 **JavaScriptQuotes** (``JavaScriptQuoteStyle``)
   The JavaScriptQuoteStyle to use for JavaScript strings.
 
@@ -1399,6 +1772,9 @@ the configuration (without a prefix: ``Auto``).
   * ``LK_Cpp`` (in configuration: ``Cpp``)
     Should be used for C, C++.
 
+  * ``LK_CSharp`` (in configuration: ``CSharp``)
+    Should be used for C#.
+
   * ``LK_Java`` (in configuration: ``Java``)
     Should be used for Java.
 
@@ -1510,6 +1886,19 @@ the configuration (without a prefix: ``Auto``).
 
 
 
+**NamespaceMacros** (``std::vector<std::string>``)
+  A vector of macros which are used to open namespace blocks.
+
+  These are expected to be macros of the form:
+
+  .. code-block:: c++
+
+    NAMESPACE(<namespace-name>, ...) {
+      <namespace-content>
+    }
+
+  For example: TESTSUITE
+
 **ObjCBinPackProtocolList** (``BinPackStyle``)
   Controls bin-packing Objective-C protocol conformance list
   items into as few lines as possible when they go over ``ColumnLimit``.
@@ -1527,7 +1916,7 @@ the configuration (without a prefix: ``Auto``).
   onto individual lines whenever they go over ``ColumnLimit``.
 
 
-  .. code-block:: c++
+  .. code-block:: objc
 
      Always (or Auto, if BinPackParameters=true):
      @interface ccccccccccccc () <
@@ -1590,6 +1979,9 @@ the configuration (without a prefix: ``Auto``).
 **PenaltyBreakString** (``unsigned``)
   The penalty for each line break introduced inside a string literal.
 
+**PenaltyBreakTemplateDeclaration** (``unsigned``)
+  The penalty for breaking after template declaration.
+
 **PenaltyExcessCharacter** (``unsigned``)
   The penalty for each character outside of the column limit.
 
@@ -1712,6 +2104,14 @@ the configuration (without a prefix: ``Auto``).
      true:                                  false:
      (int) i;                       vs.     (int)i;
 
+**SpaceAfterLogicalNot** (``bool``)
+  If ``true``, a space is inserted after the logical not operator (``!``).
+
+  .. code-block:: c++
+
+     true:                                  false:
+     ! someExpression();            vs.     !someExpression();
+
 **SpaceAfterTemplateKeyword** (``bool``)
   If ``true``, a space will be inserted after the 'template' keyword.
 
@@ -1726,8 +2126,20 @@ the configuration (without a prefix: ``Auto``).
   .. code-block:: c++
 
      true:                                  false:
-     int a = 5;                     vs.     int a=5;
-     a += 42                                a+=42;
+     int a = 5;                     vs.     int a= 5;
+     a += 42;                               a+= 42;
+
+**SpaceBeforeCpp11BracedList** (``bool``)
+  If ``true``, a space will be inserted before a C++11 braced list
+  used to initialize an object (after the preceding identifier or type).
+
+  .. code-block:: c++
+
+     true:                                  false:
+     Foo foo { bar };               vs.     Foo foo{ bar };
+     Foo {};                                Foo{};
+     vector<int> { 1, 2, 3 };               vector<int>{ 1, 2, 3 };
+     new int[3] { 1, 2, 3 };                new int[3]{ 1, 2, 3 };
 
 **SpaceBeforeCtorInitializerColon** (``bool``)
   If ``false``, spaces will be removed before constructor initializer
@@ -1774,6 +2186,19 @@ the configuration (without a prefix: ``Auto``).
          }
        }
 
+  * ``SBPO_NonEmptyParentheses`` (in configuration: ``NonEmptyParentheses``)
+    Put a space before opening parentheses only if the parentheses are not
+    empty i.e. '()'
+
+    .. code-block:: c++
+
+      void() {
+        if (true) {
+          f();
+          g (x, y, z);
+        }
+      }
+
   * ``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
@@ -1799,6 +2224,15 @@ the configuration (without a prefix: ``Auto``).
      true:                                  false:
      for (auto v : values) {}       vs.     for(auto v: values) {}
 
+**SpaceInEmptyBlock** (``bool``)
+  If ``true``, spaces will be inserted into ``{}``.
+
+  .. code-block:: c++
+
+     true:                                false:
+     void f() { }                   vs.   void f() {}
+     while (true) { }                     while (true) {}
+
 **SpaceInEmptyParentheses** (``bool``)
   If ``true``, spaces may be inserted into ``()``.
 
@@ -1867,7 +2301,8 @@ the configuration (without a prefix: ``Auto``).
 
 **SpacesInSquareBrackets** (``bool``)
   If ``true``, spaces will be inserted after ``[`` and before ``]``.
-  Lambdas or unspecified size array declarations will not be affected.
+  Lambdas without arguments or unspecified size array declarations will not be
+  affected.
 
   .. code-block:: c++
 
@@ -1876,26 +2311,71 @@ the configuration (without a prefix: ``Auto``).
      std::unique_ptr<int[]> foo() {} // Won't be affected
 
 **Standard** (``LanguageStandard``)
-  Format compatible with this standard, e.g. use ``A<A<int> >``
-  instead of ``A<A<int>>`` for ``LS_Cpp03``.
+  Parse and format C++ constructs compatible with this standard.
+
+  .. code-block:: c++
+
+     c++03:                                 latest:
+     vector<set<int> > x;           vs.     vector<set<int>> x;
 
   Possible values:
 
-  * ``LS_Cpp03`` (in configuration: ``Cpp03``)
+  * ``LS_Cpp03`` (in configuration: ``c++03``)
     Use C++03-compatible syntax.
 
-  * ``LS_Cpp11`` (in configuration: ``Cpp11``)
-    Use features of C++11, C++14 and C++1z (e.g. ``A<A<int>>`` instead of
-    ``A<A<int> >``).
+  * ``LS_Cpp11`` (in configuration: ``c++11``)
+    Use C++11-compatible syntax.
+
+  * ``LS_Cpp14`` (in configuration: ``c++14``)
+    Use C++14-compatible syntax.
+
+  * ``LS_Cpp17`` (in configuration: ``c++17``)
+    Use C++17-compatible syntax.
+
+  * ``LS_Cpp20`` (in configuration: ``c++20``)
+    Use C++20-compatible syntax.
+
+  * ``LS_Latest`` (in configuration: ``Latest``)
+    Parse and format using the latest supported language version.
 
   * ``LS_Auto`` (in configuration: ``Auto``)
     Automatic detection based on the input.
 
+  * ``Cpp03``: deprecated alias for ``c++03``
+
+  * ``Cpp11``: deprecated alias for ``Latest``
+
+**StatementMacros** (``std::vector<std::string>``)
+  A vector of macros that should be interpreted as complete
+  statements.
+
+  Typical macros are expressions, and require a semi-colon to be
+  added; sometimes this is not the case, and this allows to make
+  clang-format aware of such cases.
 
+  For example: Q_UNUSED
 
 **TabWidth** (``unsigned``)
   The number of columns used for tab stops.
 
+**TypenameMacros** (``std::vector<std::string>``)
+  A vector of macros that should be interpreted as type declarations
+  instead of as function calls.
+
+  These are expected to be macros of the form:
+
+  .. code-block:: c++
+
+    STACK_OF(...)
+
+  In the .clang-format configuration file, this can be configured like:
+
+  .. code-block:: yaml
+
+    TypenameMacros: ['STACK_OF', 'LIST']
+
+  For example: OpenSSL STACK_OF, BSD LIST_ENTRY.
+
 **UseTab** (``UseTabStyle``)
   The way to use tab characters in the resulting file.
 

docs/ClangPlugins.rst

@@ -55,7 +55,7 @@ registering it using ``PragmaHandlerRegistry::Add<>``:
   class ExamplePragmaHandler : public PragmaHandler {
   public:
     ExamplePragmaHandler() : PragmaHandler("example_pragma") { }
-    void HandlePragma(Preprocessor &PP, PragmaIntroducerKind Introducer,
+    void HandlePragma(Preprocessor &PP, PragmaIntroducer Introducer,
                       Token &PragmaTok) {
       // Handle the pragma
     }
@@ -69,7 +69,7 @@ Putting it all together
 Let's look at an example plugin that prints top-level function names.  This
 example is checked into the clang repository; please take a look at
 the `latest version of PrintFunctionNames.cpp
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_.
+<https://github.com/llvm/llvm-project/blob/master/clang/examples/PrintFunctionNames/PrintFunctionNames.cpp>`_.
 
 Running the plugin
 ==================
@@ -110,7 +110,7 @@ source tree:
             -plugin -Xclang print-fns
 
 Also see the print-function-name plugin example's
-`README <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup>`_
+`README <https://github.com/llvm/llvm-project/blob/master/clang/examples/PrintFunctionNames/README.txt>`_
 
 
 Using the clang command line

docs/ClangStaticAnalyzer.rst

@@ -0,0 +1,20 @@
+=====================
+Clang Static Analyzer
+=====================
+
+The Clang Static Analyzer is a source code analysis tool that finds bugs in C, C++, and Objective-C programs.
+It implements *path-sensitive*, *inter-procedural analysis* based on *symbolic execution* technique.
+
+This is the Static Analyzer documentation page.
+
+See the `Official Tool Page <https://clang-analyzer.llvm.org/>`_.
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+   :maxdepth: 2
+
+   analyzer/checkers
+   analyzer/user-docs
+   analyzer/developer-docs
+

docs/ClangTools.rst

@@ -9,22 +9,9 @@ functionality such as fast syntax checking, automatic formatting,
 refactoring, etc.
 
 Only a couple of the most basic and fundamental tools are kept in the
-primary Clang Subversion project. The rest of the tools are kept in a
-side-project so that developers who don't want or need to build them
-don't. If you want to get access to the extra Clang Tools repository,
-simply check it out into the tools tree of your Clang checkout and
-follow the usual process for building and working with a combined
-LLVM/Clang checkout:
-
--  With Subversion:
-
-   -  ``cd llvm/tools/clang/tools``
-   -  ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra``
-
--  Or with Git:
-
-   -  ``cd llvm/tools/clang/tools``
-   -  ``git clone http://llvm.org/git/clang-tools-extra.git extra``
+primary Clang tree. The rest of the tools are kept in a separate
+directory tree, `clang-tools-extra
+<https://github.com/llvm/llvm-project/tree/master/clang-tools-extra>`_.
 
 This document describes a high-level overview of the organization of
 Clang Tools within the project as well as giving an introduction to some
@@ -105,7 +92,7 @@ provide its own user-focused documentation.
 ``clang-tidy``
 --------------
 
-`clang-tidy <http://clang.llvm.org/extra/clang-tidy/>`_ is a clang-based C++
+`clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`_ is a clang-based C++
 linter tool. It provides an extensible framework for building compiler-based
 static analyses detecting and fixing bug-prone patterns, performance,
 portability and maintainability issues.

docs/CommandGuide/clang.rst

@@ -60,7 +60,7 @@ Linker
 
 The Clang Static Analyzer is a tool that scans source code to try to find bugs
 through code analysis.  This tool uses many parts of Clang and is built into
-the same driver.  Please see <http://clang-analyzer.llvm.org> for more details
+the same driver.  Please see <https://clang-analyzer.llvm.org> for more details
 on how to use the static analyzer.
 
 OPTIONS
@@ -316,7 +316,7 @@ number of cross compilers, or may only support a native target.
 
 .. option:: -mmacosx-version-min=<version>
 
-  When building for Mac OS X, specify the minimum version supported by your
+  When building for macOS, specify the minimum version supported by your
   application.
 
 .. option:: -miphoneos-version-min
@@ -324,6 +324,16 @@ number of cross compilers, or may only support a native target.
   When building for iPhone OS, specify the minimum version supported by your
   application.
 
+.. option:: --print-supported-cpus
+
+  Print out a list of supported processors for the given target (specified
+  through --target=<architecture> or -arch <architecture>). If no target is
+  specified, the system default target will be used.
+
+.. option:: -mcpu=?, -mtune=?
+
+  Aliases of --print-supported-cpus
+
 .. option:: -march=<cpu>
 
   Specify that Clang should generate code for a specific processor family
@@ -361,7 +371,7 @@ Code Generation Options
     :option:`-Oz` Like :option:`-Os` (and thus :option:`-O2`), but reduces code
     size further.
 
-    :option:`-Og` Like :option:`-O1`. In future versions, this option might 
+    :option:`-Og` Like :option:`-O1`. In future versions, this option might
     disable different optimizations in order to improve debuggability.
 
     :option:`-O` Equivalent to :option:`-O2`.
@@ -625,7 +635,7 @@ ENVIRONMENT
 BUGS
 ----
 
-To report bugs, please visit <http://llvm.org/bugs/>.  Most bug reports should
+To report bugs, please visit <https://bugs.llvm.org/>.  Most bug reports should
 include preprocessed source files (use the :option:`-E` option) and the full
 output of the compiler, along with information to reproduce.
 
@@ -633,4 +643,3 @@ SEE ALSO
 --------
 
 :manpage:`as(1)`, :manpage:`ld(1)`
-

docs/CommandGuide/diagtool.rst

@@ -0,0 +1,52 @@
+diagtool - clang diagnostics tool
+=================================
+
+SYNOPSIS
+--------
+
+:program:`diagtool` *command* [*args*]
+
+DESCRIPTION
+-----------
+
+:program:`diagtool` is a combination of four tools for dealing with diagnostics in :program:`clang`.
+
+SUBCOMMANDS
+-----------
+
+:program:`diagtool` is separated into several subcommands each tailored to a
+different purpose. A brief summary of each command follows, with more detail in
+the sections that follow.
+
+  * :ref:`find_diagnostic_id` - Print the id of the given diagnostic.
+  * :ref:`list_warnings` - List warnings and their corresponding flags.
+  * :ref:`show_enabled` - Show which warnings are enabled for a given command line.
+  * :ref:`tree` - Show warning flags in a tree view.
+
+.. _find_diagnostic_id:
+
+find-diagnostic-id
+~~~~~~~~~~~~~~~~~~
+
+:program:`diagtool` find-diagnostic-id *diagnostic-name*
+
+.. _list_warnings:
+
+list-warnings
+~~~~~~~~~~~~~
+
+:program:`diagtool` list-warnings
+
+.. _show_enabled:
+
+show-enabled
+~~~~~~~~~~~~
+
+:program:`diagtool` show-enabled [*options*] *filename ...*
+
+.. _tree:
+
+tree
+~~~~
+
+:program:`diagtool` tree [*diagnostic-group*]

docs/CommandGuide/index.rst

@@ -15,3 +15,4 @@ Basic Commands
    :maxdepth: 1
 
    clang
+   diagtool

docs/ConstantInterpreter.rst

@@ -0,0 +1,194 @@
+====================
+Constant Interpreter
+====================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+The constexpr interpreter aims to replace the existing tree evaluator in clang, improving performance on constructs which are executed inefficiently by the evaluator. The interpreter is activated using the following flags:
+
+* ``-fexperimental-new-constant-interpreter`` enables the interpreter, falling back to the evaluator for unsupported features
+* ``-fforce-experimental-new-constant-interpreter`` forces the use of the interpreter, bailing out if an unsupported feature is encountered
+
+Bytecode Compilation
+====================
+
+Bytecode compilation is handled in ``ByteCodeStmtGen.h`` for statements and ``ByteCodeExprGen.h`` for expressions. The compiler has two different backends: one to generate bytecode for functions (``ByteCodeEmitter``) and one to directly evaluate expressions as they are compiled, without generating bytecode (``EvalEmitter``). All functions are compiled to bytecode, while toplevel expressions used in constant contexts are directly evaluated since the bytecode would never be reused. This mechanism aims to pave the way towards replacing the evaluator, improving its performance on functions and loops, while being just as fast on single-use toplevel expressions.
+
+The interpreter relies on stack-based, strongly-typed opcodes. The glue logic between the code generator, along with the enumeration and description of opcodes, can be found in ``Opcodes.td``. The opcodes are implemented as generic template methods in ``Interp.h`` and instantiated with the relevant primitive types by the interpreter loop or by the evaluating emitter.
+
+Primitive Types
+---------------
+
+* ``PT_{U|S}int{8|16|32|64}``
+
+  Signed or unsigned integers of a specific bit width, implemented using the ```Integral``` type.
+
+* ``PT_{U|S}intFP``
+
+  Signed or unsigned integers of an arbitrary, but fixed width used to implement
+  integral types which are required by the target, but are not supported by the host.
+  Under the hood, they rely on APValue. The ``Integral`` specialisation for these
+  types is required by opcodes to share an implementation with fixed integrals.
+
+* ``PT_Bool``
+
+  Representation for boolean types, essentially a 1-bit unsigned ``Integral``.
+
+* ``PT_RealFP``
+
+  Arbitrary, but fixed precision floating point numbers. Could be specialised in
+  the future similarly to integers in order to improve floating point performance.
+
+* ``PT_Ptr``
+
+  Pointer type, defined in ``"Pointer.h"``.
+
+* ``PT_FnPtr``
+
+  Function pointer type, can also be a null function pointer. Defined in ``"Pointer.h"``.
+
+* ``PT_MemPtr``
+
+  Member pointer type, can also be a null member pointer. Defined in ``"Pointer.h"``
+
+Composite types
+---------------
+
+The interpreter distinguishes two kinds of composite types: arrays and records. Unions are represented as records, except a single field can be marked as active. The contents of inactive fields are kept until they
+are reactivated and overwritten.
+
+
+Bytecode Execution
+==================
+
+Bytecode is executed using a stack-based interpreter. The execution context consists of an ``InterpStack``, along with a chain of ``InterpFrame`` objects storing the call frames. Frames are built by call instructions and destroyed by return instructions. They perform one allocation to reserve space for all locals in a single block. These objects store all the required information to emit stack traces whenever evaluation fails.
+
+Memory Organisation
+===================
+
+Memory management in the interpreter relies on 3 data structures: ``Block``
+object which store the data and associated inline metadata, ``Pointer`` objects
+which refer to or into blocks, and ``Descriptor`` structures which describe
+blocks and subobjects nested inside blocks.
+
+Blocks
+------
+
+Blocks contain data interleaved with metadata. They are allocated either statically
+in the code generator (globals, static members, dummy parameter values etc.) or
+dynamically in the interpreter, when creating the frame containing the local variables
+of a function. Blocks are associated with a descriptor that characterises the entire
+allocation, along with a few additional attributes:
+
+* ``IsStatic`` indicates whether the block has static duration in the interpreter, i.e. it is not a local in a frame.
+
+* ``IsExtern`` indicates that the block was created for an extern and the storage cannot be read or written.
+
+* ``DeclID`` identifies each global declaration (it is set to an invalid and irrelevant value for locals) in order to prevent illegal writes and reads involving globals and temporaries with static storage duration.
+
+Static blocks are never deallocated, but local ones might be deallocated even when there are live pointers to them. Pointers are only valid as long as the blocks they point to are valid, so a block with pointers to it whose lifetime ends is kept alive until all pointers to it go out of scope. Since the frame is destroyed on function exit, such blocks are turned into a ``DeadBlock`` and copied to storage managed by the interpreter itself, not the frame. Reads and writes to these blocks are illegal and cause an appropriate diagnostic to be emitted. When the last pointer goes out of scope, dead blocks are also deallocated.
+
+The lifetime of blocks is managed through 3 methods stored in the descriptor of the block:
+
+* **CtorFn**: initializes the metadata which is store in the block, alongside actual data. Invokes the default constructors of objects which are not trivial (``Pointer``, ``RealFP``, etc.)
+* **DtorFn**: invokes the destructors of non-trivial objects.
+* **MoveFn**: moves a block to dead storage.
+
+Non-static blocks track all the pointers into them through an intrusive doubly-linked list, this is required in order to adjust all pointers when transforming a block into a dead block.
+
+Descriptors
+-----------
+
+Descriptor are generated at bytecode compilation time and contain information required to determine if a particular memory access is allowed in constexpr. Even though there is a single descriptor object, it encodes information for several kinds of objects:
+
+* **Primitives**
+
+  A block containing a primitive reserved storage only for the primitive.
+
+* **Arrays of primitives**
+
+  An array of primitives contains a pointer to an ``InitMap`` storage as its first field: the initialisation map is a bit map indicating all elements of the array which were initialised. If the pointer is null, no elements were initialised, while a value of ``(InitMap)-1`` indicates that the object was fully initialised. when all fields are initialised, the map is deallocated and replaced with that token.
+
+  Array elements are stored sequentially, without padding, after the pointer to the map.
+
+* **Arrays of composites and records**
+
+  Each element in an array of composites is preceded by an ``InlineDescriptor``. Descriptors and elements are stored sequentially in the block. Records are laid out identically to arrays of composites: each field and base class is preceded by an inline descriptor. The ``InlineDescriptor`` has the following field:
+
+ * **Offset**: byte offset into the array or record, used to step back to the parent array or record.
+ * **IsConst**: flag indicating if the field is const-qualified.
+ * **IsInitialized**: flag indicating whether the field or element was initialized. For non-primitive fields, this is only relevant for base classes.
+ * **IsBase**: flag indicating whether the record is a base class. In that case, the offset can be used to identify the derived class.
+ * **IsActive**: indicates if the field is the active field of a union.
+ * **IsMutable**: indicates if the field is marked as mutable.
+
+Inline descriptors are filled in by the `CtorFn` of blocks, which leaves storage in an uninitialised, but valid state.
+
+Pointers
+--------
+
+Pointers track a ``Pointee``, the block to which they point or ``nullptr`` for null pointers, along with a ``Base`` and an ``Offset``. The base identifies the innermost field, while the offset points to an array element relative to the base (including one-past-end pointers). Most subobject the pointer points to in block, while the offset identifies the array element the pointer points to. These two fields allow all pointers to be uniquely identified and disambiguated.
+
+As an example, consider the following structure:
+
+.. code-block:: c
+
+    struct A {
+        struct B {
+            int x;
+            int y;
+        } b;
+        struct C {
+            int a;
+            int b;
+        } c[2];
+        int z;
+    };
+    constexpr A a;
+
+On the target, ``&a`` and ``&a.b.x`` are equal. So are ``&a.c[0]`` and ``&a.c[0].a``. In the interpreter, all these pointers must be distinguished since the are all allowed to address distinct range of memory.
+
+In the interpreter, the object would require 240 bytes of storage and would have its field interleaved with metadata. The pointers which can be derived to the object are illustrated in the following diagram:
+
+::
+
+      0   16  32  40  56  64  80  96  112 120 136 144 160 176 184 200 208 224 240
+  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
+  + B | D | D | x | D | y | D | D | D | a | D | b | D | D | a | D | b | D | z |
+  +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
+      ^   ^   ^       ^       ^   ^   ^       ^       ^   ^       ^       ^
+      |   |   |       |       |   |   |   &a.c[0].b   |   |   &a.c[1].b   |
+      a   |&a.b.x   &a.y    &a.c  |&a.c[0].a          |&a.c[1].a          |
+        &a.b                   &a.c[0]            &a.c[1]               &a.z
+
+The ``Base`` offset of all pointers points to the start of a field or an array and is preceded by an inline descriptor (unless ``Base == 0``, pointing to the root). All the relevant attributes can be read from either the inline descriptor or the descriptor of the block.
+
+Array elements are identified by the ``Offset`` field of pointers, pointing to past the inline descriptors for composites and before the actual data in the case of primitive arrays. The ``Offset`` points to the offset where primitives can be read from. As an example, ``a.c + 1`` would have the same base as ``a.c`` since it is an element of ``a.c``, but its offset would point to ``&a.c[1]``. The ``*`` operation narrows the scope of the pointer, adjusting the base to ``&a.c[1]``. The reverse operator, ``&``, expands the scope of ``&a.c[1]``, turning it into ``a.c + 1``. When a one-past-end pointer is narrowed, its offset is set to ``-1`` to indicate that it is an invalid value (expanding returns the past-the-end pointer). As a special case, narrowing ``&a.c`` results in ``&a.c[0]``. The `narrow` and `expand` methods can be used to follow the chain of equivalent pointers.
+
+TODO
+====
+
+Missing Language Features
+-------------------------
+
+* Definition of externs must override previous declaration
+* Changing the active field of unions
+* Union copy constructors
+* ``typeid``
+* ``volatile``
+* ``__builtin_constant_p``
+* ``std::initializer_list``
+* lambdas
+* range-based for loops
+* ``vector_size``
+* ``dynamic_cast``
+
+Known Bugs
+----------
+
+* Pointer comparison for equality needs to narrow/expand pointers
+* If execution fails, memory storing APInts and APFloats is leaked when the stack is cleared

docs/ControlFlowIntegrity.rst

@@ -45,7 +45,7 @@ Experimental support for :ref:`cross-DSO control flow integrity
 <cfi-cross-dso>` exists that does not require classes to have hidden LTO
 visibility. This cross-DSO support has unstable ABI at this time.
 
-.. _gold plugin: http://llvm.org/docs/GoldPlugin.html
+.. _gold plugin: https://llvm.org/docs/GoldPlugin.html
 
 .. _cfi-schemes:
 
@@ -66,6 +66,8 @@ Available schemes are:
      wrong dynamic type.
   -  ``-fsanitize=cfi-icall``: Indirect call of a function with wrong dynamic
      type.
+  -  ``-fsanitize=cfi-mfcall``: Indirect call via a member function pointer with
+     wrong dynamic type.
 
 You can use ``-fsanitize=cfi`` to enable all the schemes and use
 ``-fno-sanitize`` flag to narrow down the set of schemes as desired.
@@ -106,8 +108,9 @@ This CFI scheme can be enabled on its own using ``-fsanitize=cfi-vcall``.
 
 For this scheme to work, all translation units containing the definition
 of a virtual member function (whether inline or not), other than members
-of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with
-``-fsanitize=cfi-vcall`` enabled and be statically linked into the program.
+of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO
+visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin``
+enabled and be statically linked into the program.
 
 Performance
 -----------
@@ -152,9 +155,9 @@ functions may be :ref:`blacklisted <cfi-blacklist>`.
 
 For this scheme to work, all translation units containing the definition
 of a virtual member function (whether inline or not), other than members
-of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with
-``-fsanitize=cfi-derived-cast`` or ``-fsanitize=cfi-unrelated-cast`` enabled
-and be statically linked into the program.
+of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO
+visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin``
+enabled and be statically linked into the program.
 
 Non-Virtual Member Function Call Checking
 =========================================
@@ -168,8 +171,9 @@ polymorphic class type.  This CFI scheme can be enabled on its own using
 
 For this scheme to work, all translation units containing the definition
 of a virtual member function (whether inline or not), other than members
-of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with
-``-fsanitize=cfi-nvcall`` enabled and be statically linked into the program.
+of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO
+visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin``
+enabled and be statically linked into the program.
 
 .. _cfi-strictness:
 
@@ -231,6 +235,54 @@ long as the qualifiers for the type they point to match. For example, ``char*``,
 ``-fsanitize-cfi-icall-generalize-pointers`` is not compatible with
 ``-fsanitize-cfi-cross-dso``.
 
+.. _cfi-canonical-jump-tables:
+
+``-fsanitize-cfi-canonical-jump-tables``
+----------------------------------------
+
+The default behavior of Clang's indirect function call checker will replace
+the address of each CFI-checked function in the output file's symbol table
+with the address of a jump table entry which will pass CFI checks. We refer
+to this as making the jump table `canonical`. This property allows code that
+was not compiled with ``-fsanitize=cfi-icall`` to take a CFI-valid address
+of a function, but it comes with a couple of caveats that are especially
+relevant for users of cross-DSO CFI:
+
+- There is a performance and code size overhead associated with each
+  exported function, because each such function must have an associated
+  jump table entry, which must be emitted even in the common case where the
+  function is never address-taken anywhere in the program, and must be used
+  even for direct calls between DSOs, in addition to the PLT overhead.
+
+- There is no good way to take a CFI-valid address of a function written in
+  assembly or a language not supported by Clang. The reason is that the code
+  generator would need to insert a jump table in order to form a CFI-valid
+  address for assembly functions, but there is no way in general for the
+  code generator to determine the language of the function. This may be
+  possible with LTO in the intra-DSO case, but in the cross-DSO case the only
+  information available is the function declaration. One possible solution
+  is to add a C wrapper for each assembly function, but these wrappers can
+  present a significant maintenance burden for heavy users of assembly in
+  addition to adding runtime overhead.
+
+For these reasons, we provide the option of making the jump table non-canonical
+with the flag ``-fno-sanitize-cfi-canonical-jump-tables``. When the jump
+table is made non-canonical, symbol table entries point directly to the
+function body. Any instances of a function's address being taken in C will
+be replaced with a jump table address.
+
+This scheme does have its own caveats, however. It does end up breaking
+function address equality more aggressively than the default behavior,
+especially in cross-DSO mode which normally preserves function address
+equality entirely.
+
+Furthermore, it is occasionally necessary for code not compiled with
+``-fsanitize=cfi-icall`` to take a function address that is valid
+for CFI. For example, this is necessary when a function's address
+is taken by assembly code and then called by CFI-checking C code. The
+``__attribute__((cfi_canonical_jump_table))`` attribute may be used to make
+the jump table entry of a specific function canonical so that the external
+code will end up taking a address for the function that will pass CFI checks.
 
 ``-fsanitize=cfi-icall`` and ``-fsanitize=function``
 ----------------------------------------------------
@@ -253,6 +305,34 @@ the identity of function pointers is maintained, and calls across shared
 library boundaries are no different from calls within a single program or
 shared library.
 
+Member Function Pointer Call Checking
+=====================================
+
+This scheme checks that indirect calls via a member function pointer
+take place using an object of the correct dynamic type. Specifically, we
+check that the dynamic type of the member function referenced by the member
+function pointer matches the "function pointer" part of the member function
+pointer, and that the member function's class type is related to the base
+type of the member function. This CFI scheme can be enabled on its own using
+``-fsanitize=cfi-mfcall``.
+
+The compiler will only emit a full CFI check if the member function pointer's
+base type is complete. This is because the complete definition of the base
+type contains information that is necessary to correctly compile the CFI
+check. To ensure that the compiler always emits a full CFI check, it is
+recommended to also pass the flag ``-fcomplete-member-pointers``, which
+enables a non-conforming language extension that requires member pointer
+base types to be complete if they may be used for a call.
+
+For this scheme to work, all translation units containing the definition
+of a virtual member function (whether inline or not), other than members
+of :ref:`blacklisted <cfi-blacklist>` types or types with public :doc:`LTO
+visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin``
+enabled and be statically linked into the program.
+
+This scheme is currently not compatible with cross-DSO CFI or the
+Microsoft ABI.
+
 .. _cfi-blacklist:
 
 Blacklist
@@ -303,7 +383,7 @@ Please refer to the :doc:`design document<ControlFlowIntegrityDesign>`.
 Publications
 ============
 
-`Control-Flow Integrity: Principles, Implementations, and Applications <http://research.microsoft.com/pubs/64250/ccs05.pdf>`_.
+`Control-Flow Integrity: Principles, Implementations, and Applications <https://research.microsoft.com/pubs/64250/ccs05.pdf>`_.
 Martin Abadi, Mihai Budiu, Úlfar Erlingsson, Jay Ligatti.
 
 `Enforcing Forward-Edge Control-Flow Integrity in GCC & LLVM <http://www.pcc.me.uk/~peter/acad/usenix14.pdf>`_.

docs/ControlFlowIntegrityDesign.rst

@@ -92,9 +92,9 @@ The compiler relies on co-operation from the linker in order to assemble
 the bit vectors for the whole program. It currently does this using LLVM's
 `type metadata`_ mechanism together with link-time optimization.
 
-.. _address point: http://itanium-cxx-abi.github.io/cxx-abi/abi.html#vtable-general
-.. _type metadata: http://llvm.org/docs/TypeMetadata.html
-.. _ByteArrayBuilder: http://llvm.org/docs/doxygen/html/structllvm_1_1ByteArrayBuilder.html
+.. _address point: https://itanium-cxx-abi.github.io/cxx-abi/abi.html#vtable-general
+.. _type metadata: https://llvm.org/docs/TypeMetadata.html
+.. _ByteArrayBuilder: https://llvm.org/docs/doxygen/html/structllvm_1_1ByteArrayBuilder.html
 
 Optimizations
 -------------
@@ -196,7 +196,7 @@ those sub-hierarchies need to be (see "Stripping Leading/Trailing Zeros in Bit
 Vectors" above). The `GlobalLayoutBuilder`_ class is responsible for laying
 out the globals efficiently to minimize the sizes of the underlying bitsets.
 
-.. _GlobalLayoutBuilder: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Transforms/IPO/LowerTypeTests.h?view=markup
+.. _GlobalLayoutBuilder: https://github.com/llvm/llvm-project/blob/master/llvm/include/llvm/Transforms/IPO/LowerTypeTests.h
 
 Alignment
 ~~~~~~~~~
@@ -274,6 +274,154 @@ If the bit vector is all ones, the bit vector check is redundant; we simply
 need to check that the address is in range and well aligned. This is more
 likely to occur if the virtual tables are padded.
 
+Forward-Edge CFI for Virtual Calls by Interleaving Virtual Tables
+-----------------------------------------------------------------
+
+Dimitar et. al. proposed a novel approach that interleaves virtual tables in [1]_.  
+This approach is more efficient in terms of space because padding and bit vectors are no longer needed. 
+At the same time, it is also more efficient in terms of performance because in the interleaved layout 
+address points of the virtual tables are consecutive, thus the validity check of a virtual 
+vtable pointer is always a range check. 
+
+At a high level, the interleaving scheme consists of three steps: 1) split virtual table groups into 
+separate virtual tables, 2) order virtual tables by a pre-order traversal of the class hierarchy 
+and 3) interleave virtual tables.
+
+The interleaving scheme implemented in LLVM is inspired by [1]_ but has its own
+enhancements (more in `Interleave virtual tables`_).
+
+.. [1] `Protecting C++ Dynamic Dispatch Through VTable Interleaving <https://cseweb.ucsd.edu/~lerner/papers/ivtbl-ndss16.pdf>`_. Dimitar Bounov, Rami Gökhan Kıcı, Sorin Lerner.
+
+Split virtual table groups into separate virtual tables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Itanium C++ ABI glues multiple individual virtual tables for a class into a combined virtual table (virtual table group). 
+The interleaving scheme, however, can only work with individual virtual tables so it must split the combined virtual tables first.
+In comparison, the old scheme does not require the splitting but it is more efficient when the combined virtual tables have been split.
+The `GlobalSplit`_ pass is responsible for splitting combined virtual tables into individual ones. 
+
+.. _GlobalSplit: https://github.com/llvm/llvm-project/blob/master/llvm/lib/Transforms/IPO/GlobalSplit.cpp
+
+Order virtual tables by a pre-order traversal of the class hierarchy 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This step is common to both the old scheme described above and the interleaving scheme. 
+For the interleaving scheme, since the combined virtual tables have been split in the previous step, 
+this step ensures that for any class all the compatible virtual tables will appear consecutively. 
+For the old scheme, the same property may not hold since it may work on combined virtual tables. 
+
+For example, consider the following four C++ classes:
+
+.. code-block:: c++
+
+  struct A {
+    virtual void f1();
+  };
+
+  struct B : A {
+    virtual void f1();
+    virtual void f2();
+  };
+
+  struct C : A {
+    virtual void f1();
+    virtual void f3();
+  };
+
+  struct D : B {
+    virtual void f1();
+    virtual void f2();
+  };
+
+This step will arrange the virtual tables for A, B, C, and D in the order of *vtable-of-A, vtable-of-B, vtable-of-D, vtable-of-C*.
+
+Interleave virtual tables
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This step is where the interleaving scheme deviates from the old scheme. Instead of laying out 
+whole virtual tables in the previously computed order, the interleaving scheme lays out table 
+entries of the virtual tables strategically to ensure the following properties:  
+
+(1) offset-to-top and RTTI fields layout property
+
+The Itanium C++ ABI specifies that offset-to-top and RTTI fields appear at the offsets behind the 
+address point. Note that libraries like libcxxabi do assume this property. 
+
+(2) virtual function entry layout property
+
+For each virtual function the distance between an virtual table entry for this function and the corresponding 
+address point is always the same. This property ensures that dynamic dispatch still works with the interleaving layout.
+
+Note that the interleaving scheme in the CFI implementation guarantees both properties above whereas the original scheme proposed   
+in [1]_ only guarantees the second property. 
+
+To illustrate how the interleaving algorithm works, let us continue with the running example.
+The algorithm first separates all the virtual table entries into two work lists. To do so, 
+it starts by allocating two work lists, one initialized with all the offset-to-top entries of virtual tables in the order 
+computed in the last step, one initialized with all the RTTI entries in the same order. 
+
+.. csv-table:: Work list 1 Layout 
+  :header: 0, 1, 2, 3
+  
+  A::offset-to-top, B::offset-to-top, D::offset-to-top, C::offset-to-top
+
+
+.. csv-table:: Work list 2 layout
+  :header: 0, 1, 2, 3,
+  
+  &A::rtti, &B::rtti, &D::rtti, &C::rtti 
+
+Then for each virtual function the algorithm goes through all the virtual tables in the previously computed order
+to collect all the related entries into a virtual function list. 
+After this step, there are the following virtual function lists:
+
+.. csv-table:: f1 list 
+  :header: 0, 1, 2, 3
+
+  &A::f1, &B::f1, &D::f1, &C::f1
+
+
+.. csv-table:: f2 list 
+  :header: 0, 1
+
+  &B::f2, &D::f2
+
+
+.. csv-table:: f3 list 
+  :header: 0
+
+  &C::f3
+
+Next, the algorithm picks the longest remaining virtual function list and appends the whole list to the shortest work list
+until no function lists are left, and pads the shorter work list so that they are of the same length. 
+In the example, f1 list will be first added to work list 1, then f2 list will be added 
+to work list 2, and finally f3 list will be added to the work list 2. Since work list 1 now has one more entry than 
+work list 2, a padding entry is added to the latter. After this step, the two work lists look like: 
+
+.. csv-table:: Work list 1 Layout 
+  :header: 0, 1, 2, 3, 4, 5, 6, 7
+
+  A::offset-to-top, B::offset-to-top, D::offset-to-top, C::offset-to-top, &A::f1, &B::f1, &D::f1, &C::f1
+
+
+.. csv-table:: Work list 2 layout
+  :header: 0, 1, 2, 3, 4, 5, 6, 7
+
+  &A::rtti, &B::rtti, &D::rtti, &C::rtti, &B::f2, &D::f2, &C::f3, padding  
+
+Finally, the algorithm merges the two work lists into the interleaved layout by alternatingly 
+moving the head of each list to the final layout. After this step, the final interleaved layout looks like:
+
+.. csv-table:: Interleaved layout
+  :header: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 
+
+  A::offset-to-top, &A::rtti, B::offset-to-top, &B::rtti, D::offset-to-top, &D::rtti, C::offset-to-top, &C::rtti, &A::f1, &B::f2, &B::f1, &D::f2, &D::f1, &C::f3, &C::f1, padding
+
+In the above interleaved layout, each virtual table's offset-to-top and RTTI are always adjacent, which shows that the layout has the first property.
+For the second property, let us look at f2 as an example. In the interleaved layout,
+there are two entries for f2: B::f2 and D::f2. The distance between &B::f2 
+and its address point D::offset-to-top (the entry immediately after &B::rtti) is 5 entry-length, so is the distance between &D::f2 and C::offset-to-top (the entry immediately after &D::rtti).
+
 Forward-Edge CFI for Indirect Function Calls
 ============================================
 
@@ -598,7 +746,7 @@ RCFI does not protect `RET` instructions:
   * embedded into other instructions (e.g. `0f4fc3 cmovg %ebx,%eax`).
 
 .. _SafeStack: https://clang.llvm.org/docs/SafeStack.html
-.. _RFG: http://xlab.tencent.com/en/2016/11/02/return-flow-guard
+.. _RFG: https://xlab.tencent.com/en/2016/11/02/return-flow-guard
 .. _Intel CET: https://software.intel.com/en-us/blogs/2016/06/09/intel-release-new-technology-specifications-protect-rop-attacks
 
 Hardware support

docs/CrossCompilation.rst

@@ -15,7 +15,7 @@ build system or Makefiles, nor choosing the right CMake options, etc.
 Also, it does not cover all the possible options, nor does it contain
 specific examples for specific architectures. For a concrete example, the
 `instructions for cross-compiling LLVM itself
-<http://llvm.org/docs/HowToCrossCompileLLVM.html>`_ may be of interest.
+<https://llvm.org/docs/HowToCrossCompileLLVM.html>`_ may be of interest.
 
 After reading this document, you should be familiar with the main issues
 related to cross-compilation, and what main compiler options Clang provides

docs/DiagnosticsReference.rst

@@ -7885,6 +7885,10 @@ This diagnostic is enabled by default.
 |                                                                                               |+---------------------+|
 +-----------------------------------------------------------------------------------------------+-----------------------+
 
+-Woverride-init
+---------------
+Synonym for `-Winitializer-overrides`_.
+
 
 -Woverride-module
 -----------------
@@ -8637,9 +8641,9 @@ Also controls `-Wpragma-pack-suspicious-include`_.
 
 **Diagnostic text:**
 
-+---------------------------------------------------------------------------------------------------------------+
-|:warning:`warning:` |nbsp| :diagtext:`the current #pragma pack aligment value is modified in the included file`|
-+---------------------------------------------------------------------------------------------------------------+
++----------------------------------------------------------------------------------------------------------------+
+|:warning:`warning:` |nbsp| :diagtext:`the current #pragma pack alignment value is modified in the included file`|
++----------------------------------------------------------------------------------------------------------------+
 
 +---------------------------------------------------------------------------------------------+
 |:warning:`warning:` |nbsp| :diagtext:`unterminated '#pragma pack (push, ...)' at end of file`|

docs/ExternalClangExamples.rst

@@ -20,7 +20,7 @@ where Clang is used are:
 
 If you know of (or wrote!) a tool or project using Clang, please send an
 email to Clang's `development discussion mailing list
-<http://lists.llvm.org/mailman/listinfo/cfe-dev>`_ to have it added.
+<https://lists.llvm.org/mailman/listinfo/cfe-dev>`_ to have it added.
 (or if you are already a Clang contributor, feel free to directly commit
 additions). Since the primary purpose of this page is to provide examples
 that can help developers, generally they must have code available.
@@ -33,7 +33,7 @@ List of projects and tools
    a persistent in-memory database of references, symbolnames, completions
    etc."
 
-`<http://rprichard.github.com/sourceweb/>`_
+`<https://rprichard.github.com/sourceweb/>`_
    "A C/C++ source code indexer and navigator"
 
 `<https://github.com/etaoins/qconnectlint>`_
@@ -42,7 +42,7 @@ List of projects and tools
 
 `<https://github.com/woboq/woboq_codebrowser>`_
    "The Woboq Code Browser is a web-based code browser for C/C++ projects.
-   Check out `<http://code.woboq.org/>`_ for an example!"
+   Check out `<https://code.woboq.org/>`_ for an example!"
 
 `<https://github.com/mozilla/dxr>`_
     "DXR is a source code cross-reference tool that uses static analysis

docs/HardwareAssistedAddressSanitizerDesign.rst

@@ -38,6 +38,30 @@ Algorithm
 
 For a more detailed discussion of this approach see https://arxiv.org/pdf/1802.09517.pdf
 
+Short granules
+--------------
+
+A short granule is a granule of size between 1 and `TG-1` bytes. The size
+of a short granule is stored at the location in shadow memory where the
+granule's tag is normally stored, while the granule's actual tag is stored
+in the last byte of the granule. This means that in order to verify that a
+pointer tag matches a memory tag, HWASAN must check for two possibilities:
+
+* the pointer tag is equal to the memory tag in shadow memory, or
+* the shadow memory tag is actually a short granule size, the value being loaded
+  is in bounds of the granule and the pointer tag is equal to the last byte of
+  the granule.
+
+Pointer tags between 1 to `TG-1` are possible and are as likely as any other
+tag. This means that these tags in memory have two interpretations: the full
+tag interpretation (where the pointer tag is between 1 and `TG-1` and the
+last byte of the granule is ordinary data) and the short tag interpretation
+(where the pointer tag is stored in the granule).
+
+When HWASAN detects an error near a memory tag between 1 and `TG-1`, it
+will show both the memory tag and the last byte of the granule. Currently,
+it is up to the user to disambiguate the two possibilities.
+
 Instrumentation
 ===============
 
@@ -46,24 +70,40 @@ Memory Accesses
 All memory accesses are prefixed with an inline instruction sequence that
 verifies the tags. Currently, the following sequence is used:
 
-
-.. code-block:: asm
+.. code-block:: none
 
   // int foo(int *a) { return *a; }
-  // clang -O2 --target=aarch64-linux -fsanitize=hwaddress -c load.c
+  // clang -O2 --target=aarch64-linux -fsanitize=hwaddress -fsanitize-recover=hwaddress -c load.c
   foo:
-       0:	08 00 00 90 	adrp	x8, 0 <__hwasan_shadow>
-       4:	08 01 40 f9 	ldr	x8, [x8]         // shadow base (to be resolved by the loader)
-       8:	09 dc 44 d3 	ubfx	x9, x0, #4, #52  // shadow offset
-       c:	28 69 68 38 	ldrb	w8, [x9, x8]     // load shadow tag
-      10:	09 fc 78 d3 	lsr	x9, x0, #56      // extract address tag
-      14:	3f 01 08 6b 	cmp	w9, w8           // compare tags
-      18:	61 00 00 54 	b.ne	24               // jump on mismatch
-      1c:	00 00 40 b9 	ldr	w0, [x0]         // original load
-      20:	c0 03 5f d6 	ret
-      24:	40 20 21 d4 	brk	#0x902           // trap
+       0:	90000008 	adrp	x8, 0 <__hwasan_shadow>
+       4:	f9400108 	ldr	x8, [x8]         // shadow base (to be resolved by the loader)
+       8:	d344dc09 	ubfx	x9, x0, #4, #52  // shadow offset
+       c:	38696909 	ldrb	w9, [x8, x9]     // load shadow tag
+      10:	d378fc08 	lsr	x8, x0, #56      // extract address tag
+      14:	6b09011f 	cmp	w8, w9           // compare tags
+      18:	54000061 	b.ne	24 <foo+0x24>    // jump to short tag handler on mismatch
+      1c:	b9400000 	ldr	w0, [x0]         // original load
+      20:	d65f03c0 	ret
+      24:	7100413f 	cmp	w9, #0x10        // is this a short tag?
+      28:	54000142 	b.cs	50 <foo+0x50>    // if not, trap
+      2c:	12000c0a 	and	w10, w0, #0xf    // find the address's position in the short granule
+      30:	11000d4a 	add	w10, w10, #0x3   // adjust to the position of the last byte loaded
+      34:	6b09015f 	cmp	w10, w9          // check that position is in bounds
+      38:	540000c2 	b.cs	50 <foo+0x50>    // if not, trap
+      3c:	9240dc09 	and	x9, x0, #0xffffffffffffff
+      40:	b2400d29 	orr	x9, x9, #0xf     // compute address of last byte of granule
+      44:	39400129 	ldrb	w9, [x9]         // load tag from it
+      48:	6b09011f 	cmp	w8, w9           // compare with pointer tag
+      4c:	54fffe80 	b.eq	1c <foo+0x1c>    // if so, continue
+      50:	d4212440 	brk	#0x922           // otherwise trap
+      54:	b9400000 	ldr	w0, [x0]         // tail duplicated original load (to handle recovery)
+      58:	d65f03c0 	ret
 
 Alternatively, memory accesses are prefixed with a function call.
+On AArch64, a function call is used by default in trapping mode. The code size
+and performance overhead of the call is reduced by using a custom calling
+convention that preserves most registers and is specialized to the register
+containing the address and the type and size of the memory access.
 
 Heap
 ----
@@ -131,7 +171,8 @@ HWASAN:
     https://www.kernel.org/doc/Documentation/arm64/tagged-pointers.txt).
   * **Does not require redzones to detect buffer overflows**,
     but the buffer overflow detection is probabilistic, with roughly
-    `(2**TS-1)/(2**TS)` probability of catching a bug.
+    `1/(2**TS)` chance of missing a bug (6.25% or 0.39% with 4 and 8-bit TS
+    respectively).
   * **Does not require quarantine to detect heap-use-after-free,
     or stack-use-after-return**.
     The detection is similarly probabilistic.
@@ -162,7 +203,7 @@ Related Work
 * *TODO: add more "related work" links. Suggestions are welcome.*
 
 
-.. _Watchdog: http://www.cis.upenn.edu/acg/papers/isca12_watchdog.pdf
+.. _Watchdog: https://www.cis.upenn.edu/acg/papers/isca12_watchdog.pdf
 .. _Effective and Efficient Memory Protection Using Dynamic Tainting: https://www.cc.gatech.edu/~orso/papers/clause.doudalis.orso.prvulovic.pdf
 .. _SPARC ADI: https://lazytyped.blogspot.com/2017/09/getting-started-with-adi.html
 .. _AddressSanitizer paper: https://www.usenix.org/system/files/conference/atc12/atc12-final39.pdf

docs/HowToSetupToolingForLLVM.rst

@@ -23,7 +23,7 @@ Setup Clang Tooling Using CMake and Make
 ========================================
 
 If you intend to use make to build LLVM, you should have CMake 2.8.6 or
-later installed (can be found `here <http://cmake.org>`_).
+later installed (can be found `here <https://cmake.org>`_).
 
 First, you need to generate Makefiles for LLVM with CMake. You need to
 make a build directory and run CMake from it:

docs/InternalsManual.rst

@@ -19,7 +19,7 @@ LLVM Support Library
 ====================
 
 The LLVM ``libSupport`` library provides many underlying libraries and
-`data-structures <http://llvm.org/docs/ProgrammersManual.html>`_, including
+`data-structures <https://llvm.org/docs/ProgrammersManual.html>`_, including
 command line option processing, various containers and a system abstraction
 layer, which is used for file system access.
 
@@ -54,7 +54,7 @@ number of source ranges that related to the diagnostic.
 
 In this section, we'll be giving examples produced by the Clang command line
 driver, but diagnostics can be :ref:`rendered in many different ways
-<DiagnosticClient>` depending on how the ``DiagnosticClient`` interface is
+<DiagnosticConsumer>` depending on how the ``DiagnosticConsumer`` interface is
 implemented.  A representative example of a diagnostic is:
 
 .. code-block:: text
@@ -188,7 +188,7 @@ Formatting a Diagnostic Argument
 Arguments to diagnostics are fully typed internally, and come from a couple
 different classes: integers, types, names, and random strings.  Depending on
 the class of the argument, it can be optionally formatted in different ways.
-This gives the ``DiagnosticClient`` information about what the argument means
+This gives the ``DiagnosticConsumer`` information about what the argument means
 without requiring it to use a specific presentation (consider this MVC for
 Clang :).
 
@@ -319,6 +319,32 @@ they should be discussed before they are added.  If you are creating a lot of
 repetitive diagnostics and/or have an idea for a useful formatter, please bring
 it up on the cfe-dev mailing list.
 
+**"sub" format**
+
+Example:
+  Given the following record definition of type ``TextSubstitution``:
+
+  .. code-block:: text
+
+    def select_ovl_candidate : TextSubstitution<
+      "%select{function|constructor}0%select{| template| %2}1">;
+
+  which can be used as
+
+  .. code-block:: text
+
+    def note_ovl_candidate : Note<
+      "candidate %sub{select_ovl_candidate}3,2,1 not viable">;
+
+  and will act as if it was written
+  ``"candidate %select{function|constructor}3%select{| template| %1}2 not viable"``.
+Description:
+  This format specifier is used to avoid repeating strings verbatim in multiple
+  diagnostics. The argument to ``%sub`` must name a ``TextSubstitution`` tblgen
+  record. The substitution must specify all arguments used by the substitution,
+  and the modifier indexes in the substitution are re-numbered accordingly. The
+  substituted text must itself be a valid format string before substitution.
+
 .. _internals-producing-diag:
 
 Producing the Diagnostic
@@ -387,7 +413,7 @@ exactly where those parentheses would be inserted into the source code.  The
 fix-it hints themselves describe what changes to make to the source code in an
 abstract manner, which the text diagnostic printer renders as a line of
 "insertions" below the caret line.  :ref:`Other diagnostic clients
-<DiagnosticClient>` might choose to render the code differently (e.g., as
+<DiagnosticConsumer>` might choose to render the code differently (e.g., as
 markup inline) or even give the user the ability to automatically fix the
 problem.
 
@@ -397,6 +423,9 @@ Fix-it hints on errors and warnings need to obey these rules:
   driver, they should only be used when it's very likely they match the user's
   intent.
 * Clang must recover from errors as if the fix-it had been applied.
+* Fix-it hints on a warning must not change the meaning of the code.
+  However, a hint may clarify the meaning as intentional, for example by adding
+  parentheses when the precedence of operators isn't obvious.
 
 If a fix-it can't obey these rules, put the fix-it on a note.  Fix-its on notes
 are not applied automatically.
@@ -420,26 +449,26 @@ Fix-it hints can be created with one of three constructors:
     Specifies that the code in the given source ``Range`` should be removed,
     and replaced with the given ``Code`` string.
 
-.. _DiagnosticClient:
+.. _DiagnosticConsumer:
 
-The ``DiagnosticClient`` Interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The ``DiagnosticConsumer`` Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once code generates a diagnostic with all of the arguments and the rest of the
 relevant information, Clang needs to know what to do with it.  As previously
 mentioned, the diagnostic machinery goes through some filtering to map a
 severity onto a diagnostic level, then (assuming the diagnostic is not mapped
-to "``Ignore``") it invokes an object that implements the ``DiagnosticClient``
+to "``Ignore``") it invokes an object that implements the ``DiagnosticConsumer``
 interface with the information.
 
 It is possible to implement this interface in many different ways.  For
-example, the normal Clang ``DiagnosticClient`` (named
+example, the normal Clang ``DiagnosticConsumer`` (named
 ``TextDiagnosticPrinter``) turns the arguments into strings (according to the
 various formatting rules), prints out the file/line/column information and the
 string, then prints out the line of code, the source ranges, and the caret.
 However, this behavior isn't required.
 
-Another implementation of the ``DiagnosticClient`` interface is the
+Another implementation of the ``DiagnosticConsumer`` interface is the
 ``TextDiagnosticBuffer`` class, which is used when Clang is in ``-verify``
 mode.  Instead of formatting and printing out the diagnostics, this
 implementation just captures and remembers the diagnostics as they fly by.
@@ -508,7 +537,7 @@ token.  This concept maps directly to the "spelling location" for the token.
 ``SourceRange`` and ``CharSourceRange``
 ---------------------------------------
 
-.. mostly taken from http://lists.llvm.org/pipermail/cfe-dev/2010-August/010595.html
+.. mostly taken from https://lists.llvm.org/pipermail/cfe-dev/2010-August/010595.html
 
 Clang represents most source ranges by [first, last], where "first" and "last"
 each point to the beginning of their respective tokens.  For example consider
@@ -533,13 +562,9 @@ The clang Driver and library are documented :doc:`here <DriverInternals>`.
 Precompiled Headers
 ===================
 
-Clang supports two implementations of precompiled headers.  The default
-implementation, precompiled headers (:doc:`PCH <PCHInternals>`) uses a
+Clang supports precompiled headers (:doc:`PCH <PCHInternals>`), which  uses a
 serialized representation of Clang's internal data structures, encoded with the
-`LLVM bitstream format <http://llvm.org/docs/BitCodeFormat.html>`_.
-Pretokenized headers (:doc:`PTH <PTHInternals>`), on the other hand, contain a
-serialized representation of the tokens encountered when preprocessing a header
-(and anything that header includes).
+`LLVM bitstream format <https://llvm.org/docs/BitCodeFormat.html>`_.
 
 The Frontend Library
 ====================
@@ -805,6 +830,79 @@ wrappers.
 The AST Library
 ===============
 
+.. _ASTPhilosophy:
+
+Design philosophy
+-----------------
+
+Immutability
+^^^^^^^^^^^^
+
+Clang AST nodes (types, declarations, statements, expressions, and so on) are
+generally designed to be immutable once created. This provides a number of key
+benefits:
+
+  * Canonicalization of the "meaning" of nodes is possible as soon as the nodes
+    are created, and is not invalidated by later addition of more information.
+    For example, we :ref:`canonicalize types <CanonicalType>`, and use a
+    canonicalized representation of expressions when determining whether two
+    function template declarations involving dependent expressions declare the
+    same entity.
+  * AST nodes can be reused when they have the same meaning. For example, we
+    reuse ``Type`` nodes when representing the same type (but maintain separate
+    ``TypeLoc``\s for each instance where a type is written), and we reuse
+    non-dependent ``Stmt`` and ``Expr`` nodes across instantiations of a
+    template.
+  * Serialization and deserialization of the AST to/from AST files is simpler:
+    we do not need to track modifications made to AST nodes imported from AST
+    files and serialize separate "update records".
+
+There are unfortunately exceptions to this general approach, such as:
+
+  * The first declaration of a redeclarable entity maintains a pointer to the
+    most recent declaration of that entity, which naturally needs to change as
+    more declarations are parsed.
+  * Name lookup tables in declaration contexts change after the namespace
+    declaration is formed.
+  * We attempt to maintain only a single declaration for an instantiation of a
+    template, rather than having distinct declarations for an instantiation of
+    the declaration versus the definition, so template instantiation often
+    updates parts of existing declarations.
+  * Some parts of declarations are required to be instantiated separately (this
+    includes default arguments and exception specifications), and such
+    instantiations update the existing declaration.
+
+These cases tend to be fragile; mutable AST state should be avoided where
+possible.
+
+As a consequence of this design principle, we typically do not provide setters
+for AST state. (Some are provided for short-term modifications intended to be
+used immediately after an AST node is created and before it's "published" as
+part of the complete AST, or where language semantics require after-the-fact
+updates.)
+
+Faithfulness
+^^^^^^^^^^^^
+
+The AST intends to provide a representation of the program that is faithful to
+the original source. We intend for it to be possible to write refactoring tools
+using only information stored in, or easily reconstructible from, the Clang AST.
+This means that the AST representation should either not desugar source-level
+constructs to simpler forms, or -- where made necessary by language semantics
+or a clear engineering tradeoff -- should desugar minimally and wrap the result
+in a construct representing the original source form.
+
+For example, ``CXXForRangeStmt`` directly represents the syntactic form of a
+range-based for statement, but also holds a semantic representation of the
+range declaration and iterator declarations. It does not contain a
+fully-desugared ``ForStmt``, however.
+
+Some AST nodes (for example, ``ParenExpr``) represent only syntax, and others
+(for example, ``ImplicitCastExpr``) represent only semantics, but most nodes
+will represent a combination of syntax and associated semantics. Inheritance
+is typically used when representing different (but related) syntaxes for nodes
+with the same or similar semantics.
+
 .. _Type:
 
 The ``Type`` class and its subclasses
@@ -867,6 +965,8 @@ way to query whether two types are structurally identical to each other,
 ignoring typedefs.  The solution to both of these problems is the idea of
 canonical types.
 
+.. _CanonicalType:
+
 Canonical Types
 ^^^^^^^^^^^^^^^
 
@@ -1127,6 +1227,10 @@ the source code.  In the semantics-centric view, only the most recent "``f``"
 will be found by the lookup, since it effectively replaces the first
 declaration of "``f``".
 
+(Note that because ``f`` can be redeclared at block scope, or in a friend
+declaration, etc. it is possible that the declaration of ``f`` found by name
+lookup will not be the most recent one.)
+
 In the semantics-centric view, overloading of functions is represented
 explicitly.  For example, given two declarations of a function "``g``" that are
 overloaded, e.g.,
@@ -1291,7 +1395,7 @@ The transparent ``DeclContext``\ s are:
 Multiply-Defined Declaration Contexts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-C++ namespaces have the interesting --- and, so far, unique --- property that
+C++ namespaces have the interesting property that
 the namespace can be defined multiple times, and the declarations provided by
 each namespace definition are effectively merged (from the semantic point of
 view).  For example, the following two code snippets are semantically
@@ -1331,6 +1435,498 @@ this context (which will be the only result, for non-namespace contexts) via
 internally within the lookup and insertion methods of the ``DeclContext``, so
 the vast majority of clients can ignore them.
 
+Because the same entity can be defined multiple times in different modules,
+it is also possible for there to be multiple definitions of (for instance)
+a ``CXXRecordDecl``, all of which describe a definition of the same class.
+In such a case, only one of those "definitions" is considered by Clang to be
+the definiition of the class, and the others are treated as non-defining
+declarations that happen to also contain member declarations. Corresponding
+members in each definition of such multiply-defined classes are identified
+either by redeclaration chains (if the members are ``Redeclarable``)
+or by simply a pointer to the canonical declaration (if the declarations
+are not ``Redeclarable`` -- in that case, a ``Mergeable`` base class is used
+instead).
+
+The ASTImporter
+---------------
+
+The ``ASTImporter`` class imports nodes of an ``ASTContext`` into another
+``ASTContext``. Please refer to the document :doc:`ASTImporter: Merging Clang
+ASTs <LibASTImporter>` for an introduction. And please read through the
+high-level `description of the import algorithm
+<LibASTImporter.html#algorithm-of-the-import>`_, this is essential for
+understanding further implementation details of the importer.
+
+.. _templated:
+
+Abstract Syntax Graph
+^^^^^^^^^^^^^^^^^^^^^
+
+Despite the name, the Clang AST is not a tree. It is a directed graph with
+cycles. One example of a cycle is the connection between a
+``ClassTemplateDecl`` and its "templated" ``CXXRecordDecl``. The *templated*
+``CXXRecordDecl`` represents all the fields and methods inside the class
+template, while the ``ClassTemplateDecl`` holds the information which is
+related to being a template, i.e. template arguments, etc. We can get the
+*templated* class (the ``CXXRecordDecl``) of a ``ClassTemplateDecl`` with
+``ClassTemplateDecl::getTemplatedDecl()``. And we can get back a pointer of the
+"described" class template from the *templated* class:
+``CXXRecordDecl::getDescribedTemplate()``. So, this is a cycle between two
+nodes: between the *templated* and the *described* node. There may be various
+other kinds of cycles in the AST especially in case of declarations.
+
+.. _structural-eq:
+
+Structural Equivalency
+^^^^^^^^^^^^^^^^^^^^^^
+
+Importing one AST node copies that node into the destination ``ASTContext``. To
+copy one node means that we create a new node in the "to" context then we set
+its properties to be equal to the properties of the source node. Before the
+copy, we make sure that the source node is not *structurally equivalent* to any
+existing node in the destination context. If it happens to be equivalent then
+we skip the copy.
+
+The informal definition of structural equivalency is the following:
+Two nodes are **structurally equivalent** if they are
+
+- builtin types and refer to the same type, e.g. ``int`` and ``int`` are
+  structurally equivalent,
+- function types and all their parameters have structurally equivalent types,
+- record types and all their fields in order of their definition have the same
+  identifier names and structurally equivalent types,
+- variable or function declarations and they have the same identifier name and
+  their types are structurally equivalent.
+
+In C, two types are structurally equivalent if they are *compatible types*. For
+a formal definition of *compatible types*, please refer to 6.2.7/1 in the C11
+standard. However, there is no definition for *compatible types* in the C++
+standard. Still, we extend the definition of structural equivalency to
+templates and their instantiations similarly: besides checking the previously
+mentioned properties, we have to check for equivalent template
+parameters/arguments, etc.
+
+The structural equivalent check can be and is used independently from the
+ASTImporter, e.g. the ``clang::Sema`` class uses it also.
+
+The equivalence of nodes may depend on the equivalency of other pairs of nodes.
+Thus, the check is implemented as a parallel graph traversal. We traverse
+through the nodes of both graphs at the same time. The actual implementation is
+similar to breadth-first-search. Let's say we start the traverse with the <A,B>
+pair of nodes. Whenever the traversal reaches a pair <X,Y> then the following
+statements are true:
+
+- A and X are nodes from the same ASTContext.
+- B and Y are nodes from the same ASTContext.
+- A and B may or may not be from the same ASTContext.
+- if A == X and B == Y (pointer equivalency) then (there is a cycle during the
+  traverse)
+
+  - A and B are structurally equivalent if and only if
+
+    - All dependent nodes on the path from <A,B> to <X,Y> are structurally
+      equivalent.
+
+When we compare two classes or enums and one of them is incomplete or has
+unloaded external lexical declarations then we cannot descend to compare their
+contained declarations. So in these cases they are considered equal if they
+have the same names. This is the way how we compare forward declarations with
+definitions.
+
+.. TODO Should we elaborate the actual implementation of the graph traversal,
+.. which is a very weird BFS traversal?
+
+Redeclaration Chains
+^^^^^^^^^^^^^^^^^^^^
+
+The early version of the ``ASTImporter``'s merge mechanism squashed the
+declarations, i.e. it aimed to have only one declaration instead of maintaining
+a whole redeclaration chain. This early approach simply skipped importing a
+function prototype, but it imported a definition. To demonstrate the problem
+with this approach let's consider an empty "to" context and the following
+``virtual`` function declarations of ``f`` in the "from" context:
+
+.. code-block:: c++
+
+  struct B { virtual void f(); };
+  void B::f() {} // <-- let's import this definition
+
+If we imported the definition with the "squashing" approach then we would
+end-up having one declaration which is indeed a definition, but ``isVirtual()``
+returns ``false`` for it. The reason is that the definition is indeed not
+virtual, it is the property of the prototype!
+
+Consequently, we must either set the virtual flag for the definition (but then
+we create a malformed AST which the parser would never create), or we import
+the whole redeclaration chain of the function. The most recent version of the
+``ASTImporter`` uses the latter mechanism. We do import all function
+declarations - regardless if they are definitions or prototypes - in the order
+as they appear in the "from" context.
+
+.. One definition
+
+If we have an existing definition in the "to" context, then we cannot import
+another definition, we will use the existing definition. However, we can import
+prototype(s): we chain the newly imported prototype(s) to the existing
+definition. Whenever we import a new prototype from a third context, that will
+be added to the end of the redeclaration chain. This may result in long
+redeclaration chains in certain cases, e.g. if we import from several
+translation units which include the same header with the prototype.
+
+.. Squashing prototypes
+
+To mitigate the problem of long redeclaration chains of free functions, we
+could compare prototypes to see if they have the same properties and if yes
+then we could merge these prototypes. The implementation of squashing of
+prototypes for free functions is future work.
+
+.. Exception: Cannot have more than 1 prototype in-class
+
+Chaining functions this way ensures that we do copy all information from the
+source AST. Nonetheless, there is a problem with member functions: While we can
+have many prototypes for free functions, we must have only one prototype for a
+member function.
+
+.. code-block:: c++
+
+  void f(); // OK
+  void f(); // OK
+
+  struct X {
+    void f(); // OK
+    void f(); // ERROR
+  };
+  void X::f() {} // OK
+
+Thus, prototypes of member functions must be squashed, we cannot just simply
+attach a new prototype to the existing in-class prototype. Consider the
+following contexts:
+
+.. code-block:: c++
+
+  // "to" context
+  struct X {
+    void f(); // D0
+  };
+
+.. code-block:: c++
+
+  // "from" context
+  struct X {
+    void f(); // D1
+  };
+  void X::f() {} // D2
+
+When we import the prototype and the definition of ``f`` from the "from"
+context, then the resulting redecl chain will look like this ``D0 -> D2'``,
+where ``D2'`` is the copy of ``D2`` in the "to" context.
+
+.. Redecl chains of other declarations
+
+Generally speaking, when we import declarations (like enums and classes) we do
+attach the newly imported declaration to the existing redeclaration chain (if
+there is structural equivalency). We do not import, however, the whole
+redeclaration chain as we do in case of functions. Up till now, we haven't
+found any essential property of forward declarations which is similar to the
+case of the virtual flag in a member function prototype. In the future, this
+may change, though.
+
+Traversal during the Import
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The node specific import mechanisms are implemented in
+``ASTNodeImporter::VisitNode()`` functions, e.g. ``VisitFunctionDecl()``.
+When we import a declaration then first we import everything which is needed to
+call the constructor of that declaration node. Everything which can be set
+later is set after the node is created. For example, in case of  a
+``FunctionDecl`` we first import the declaration context in which the function
+is declared, then we create the ``FunctionDecl`` and only then we import the
+body of the function. This means there are implicit dependencies between AST
+nodes. These dependencies determine the order in which we visit nodes in the
+"from" context. As with the regular graph traversal algorithms like DFS, we
+keep track which nodes we have already visited in
+``ASTImporter::ImportedDecls``. Whenever we create a node then we immediately
+add that to the ``ImportedDecls``. We must not start the import of any other
+declarations before we keep track of the newly created one. This is essential,
+otherwise, we would not be able to handle circular dependencies. To enforce
+this, we wrap all constructor calls of all AST nodes in
+``GetImportedOrCreateDecl()``. This wrapper ensures that all newly created
+declarations are immediately marked as imported; also, if a declaration is
+already marked as imported then we just return its counterpart in the "to"
+context. Consequently, calling a declaration's ``::Create()`` function directly
+would lead to errors, please don't do that!
+
+Even with the use of ``GetImportedOrCreateDecl()`` there is still a
+probability of having an infinite import recursion if things are imported from
+each other in wrong way. Imagine that during the import of ``A``, the import of
+``B`` is requested before we could create the node for ``A`` (the constructor
+needs a reference to ``B``). And the same could be true for the import of ``B``
+(``A`` is requested to be imported before we could create the node for ``B``).
+In case of the :ref:`templated-described swing <templated>` we take
+extra attention to break the cyclical dependency: we import and set the
+described template only after the ``CXXRecordDecl`` is created. As a best
+practice, before creating the node in the "to" context, avoid importing of
+other nodes which are not needed for the constructor of node ``A``.
+
+Error Handling
+^^^^^^^^^^^^^^
+
+Every import function returns with either an ``llvm::Error`` or an
+``llvm::Expected<T>`` object. This enforces to check the return value of the
+import functions. If there was an error during one import then we return with
+that error. (Exception: when we import the members of a class, we collect the
+individual errors with each member and we concatenate them in one Error
+object.) We cache these errors in cases of declarations. During the next import
+call if there is an existing error we just return with that. So, clients of the
+library receive an Error object, which they must check.
+
+During import of a specific declaration, it may happen that some AST nodes had
+already been created before we recognize an error. In this case, we signal back
+the error to the caller, but the "to" context remains polluted with those nodes
+which had been created. Ideally, those nodes should not had been created, but
+that time we did not know about the error, the error happened later. Since the
+AST is immutable (most of the cases we can't remove existing nodes) we choose
+to mark these nodes as erroneous.
+
+We cache the errors associated with declarations in the "from" context in
+``ASTImporter::ImportDeclErrors`` and the ones which are associated with the
+"to" context in ``ASTImporterSharedState::ImportErrors``. Note that, there may
+be several ASTImporter objects which import into the same "to" context but from
+different "from" contexts; in this case, they have to share the associated
+errors of the "to" context.
+
+When an error happens, that propagates through the call stack, through all the
+dependant nodes. However, in case of dependency cycles, this is not enough,
+because we strive to mark the erroneous nodes so clients can act upon. In those
+cases, we have to keep track of the errors for those nodes which are
+intermediate nodes of a cycle.
+
+An **import path** is the list of the AST nodes which we visit during an Import
+call. If node ``A`` depends on node ``B`` then the path contains an ``A->B``
+edge. From the call stack of the import functions, we can read the very same
+path.
+
+Now imagine the following AST, where the ``->`` represents dependency in terms
+of the import (all nodes are declarations).
+
+.. code-block:: text
+
+  A->B->C->D
+     `->E
+
+We would like to import A.
+The import behaves like a DFS, so we will visit the nodes in this order: ABCDE.
+During the visitation we will have the following import paths:
+
+.. code-block:: text
+
+  A
+  AB
+  ABC
+  ABCD
+  ABC
+  AB
+  ABE
+  AB
+  A
+
+If during the visit of E there is an error then we set an error for E, then as
+the call stack shrinks for B, then for A:
+
+.. code-block:: text
+
+  A
+  AB
+  ABC
+  ABCD
+  ABC
+  AB
+  ABE // Error! Set an error to E
+  AB  // Set an error to B
+  A   // Set an error to A
+
+However, during the import we could import C and D without any error and they
+are independent of A,B and E. We must not set up an error for C and D. So, at
+the end of the import we have an entry in ``ImportDeclErrors`` for A,B,E but
+not for C,D.
+
+Now, what happens if there is a cycle in the import path? Let's consider this
+AST:
+
+.. code-block:: text
+
+  A->B->C->A
+     `->E
+
+During the visitation, we will have the below import paths and if during the
+visit of E there is an error then we will set up an error for E,B,A. But what's
+up with C?
+
+.. code-block:: text
+
+  A
+  AB
+  ABC
+  ABCA
+  ABC
+  AB
+  ABE // Error! Set an error to E
+  AB  // Set an error to B
+  A   // Set an error to A
+
+This time we know that both B and C are dependent on A. This means we must set
+up an error for C too. As the call stack reverses back we get to A and we must
+set up an error to all nodes which depend on A (this includes C). But C is no
+longer on the import path, it just had been previously. Such a situation can
+happen only if during the visitation we had a cycle. If we didn't have any
+cycle, then the normal way of passing an Error object through the call stack
+could handle the situation. This is why we must track cycles during the import
+process for each visited declaration.
+
+Lookup Problems
+^^^^^^^^^^^^^^^
+
+When we import a declaration from the source context then we check whether we
+already have a structurally equivalent node with the same name in the "to"
+context. If the "from" node is a definition and the found one is also a
+definition, then we do not create a new node, instead, we mark the found node
+as the imported node. If the found definition and the one we want to import
+have the same name but they are structurally in-equivalent, then we have an ODR
+violation in case of C++. If the "from" node is not a definition then we add
+that to the redeclaration chain of the found node. This behaviour is essential
+when we merge ASTs from different translation units which include the same
+header file(s). For example, we want to have only one definition for the class
+template ``std::vector``, even if we included ``<vector>`` in several
+translation units.
+
+To find a structurally equivalent node we can use the regular C/C++ lookup
+functions: ``DeclContext::noload_lookup()`` and
+``DeclContext::localUncachedLookup()``. These functions do respect the C/C++
+name hiding rules, thus you cannot find certain declarations in a given
+declaration context. For instance, unnamed declarations (anonymous structs),
+non-first ``friend`` declarations and template specializations are hidden. This
+is a problem, because if we use the regular C/C++ lookup then we create
+redundant AST nodes during the merge! Also, having two instances of the same
+node could result in false :ref:`structural in-equivalencies <structural-eq>`
+of other nodes which depend on the duplicated node. Because of these reasons,
+we created a lookup class which has the sole purpose to register all
+declarations, so later they can be looked up by subsequent import requests.
+This is the ``ASTImporterLookupTable`` class. This lookup table should be
+shared amongst the different ``ASTImporter`` instances if they happen to import
+to the very same "to" context. This is why we can use the importer specific
+lookup only via the ``ASTImporterSharedState`` class.
+
+ExternalASTSource
+~~~~~~~~~~~~~~~~~
+
+The ``ExternalASTSource`` is an abstract interface associated with the
+``ASTContext`` class. It provides the ability to read the declarations stored
+within a declaration context either for iteration or for name lookup. A
+declaration context with an external AST source may load its declarations
+on-demand. This means that the list of declarations (represented as a linked
+list, the head is ``DeclContext::FirstDecl``) could be empty. However, member
+functions like ``DeclContext::lookup()`` may initiate a load.
+
+Usually, external sources are associated with precompiled headers. For example,
+when we load a class from a PCH then the members are loaded only if we do want
+to look up something in the class' context.
+
+In case of LLDB, an implementation of the ``ExternalASTSource`` interface is
+attached to the AST context which is related to the parsed expression. This
+implementation of the ``ExternalASTSource`` interface is realized with the help
+of the ``ASTImporter`` class. This way, LLDB can reuse Clang's parsing
+machinery while synthesizing the underlying AST from the debug data (e.g. from
+DWARF). From the view of the ``ASTImporter`` this means both the "to" and the
+"from" context may have declaration contexts with external lexical storage. If
+a ``DeclContext`` in the "to" AST context has external lexical storage then we
+must take extra attention to work only with the already loaded declarations!
+Otherwise, we would end up with an uncontrolled import process. For instance,
+if we used the regular ``DeclContext::lookup()`` to find the existing
+declarations in the "to" context then the ``lookup()`` call itself would
+initiate a new import while we are in the middle of importing a declaration!
+(By the time we initiate the lookup we haven't registered yet that we already
+started to import the node of the "from" context.) This is why we use
+``DeclContext::noload_lookup()`` instead.
+
+Class Template Instantiations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Different translation units may have class template instantiations with the
+same template arguments, but with a different set of instantiated
+``MethodDecls`` and ``FieldDecls``. Consider the following files:
+
+.. code-block:: c++
+
+  // x.h
+  template <typename T>
+  struct X {
+      int a{0}; // FieldDecl with InitListExpr
+      X(char) : a(3) {}     // (1)
+      X(int) {}             // (2)
+  };
+
+  // foo.cpp
+  void foo() {
+      // ClassTemplateSpec with ctor (1): FieldDecl without InitlistExpr
+      X<char> xc('c');
+  }
+
+  // bar.cpp
+  void bar() {
+      // ClassTemplateSpec with ctor (2): FieldDecl WITH InitlistExpr
+      X<char> xc(1);
+  }
+
+In ``foo.cpp`` we use the constructor with number ``(1)``, which explicitly
+initializes the member ``a`` to ``3``, thus the ``InitListExpr`` ``{0}`` is not
+used here and the AST node is not instantiated. However, in the case of
+``bar.cpp`` we use the constructor with number ``(2)``, which does not
+explicitly initialize the ``a`` member, so the default ``InitListExpr`` is
+needed and thus instantiated. When we merge the AST of ``foo.cpp`` and
+``bar.cpp`` we must create an AST node for the class template instantiation of
+``X<char>`` which has all the required nodes. Therefore, when we find an
+existing ``ClassTemplateSpecializationDecl`` then we merge the fields of the
+``ClassTemplateSpecializationDecl`` in the "from" context in a way that the
+``InitListExpr`` is copied if not existent yet. The same merge mechanism should
+be done in the cases of instantiated default arguments and exception
+specifications of functions.
+
+.. _visibility:
+
+Visibility of Declarations
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+During import of a global variable with external visibility, the lookup will
+find variables (with the same name) but with static visibility (linkage).
+Clearly, we cannot put them into the same redeclaration chain. The same is true
+the in case of functions. Also, we have to take care of other kinds of
+declarations like enums, classes, etc. if they are in anonymous namespaces.
+Therefore, we filter the lookup results and consider only those which have the
+same visibility as the declaration we currently import.
+
+We consider two declarations in two anonymous namespaces to have the same
+visibility only if they are imported from the same AST context.
+
+Strategies to Handle Conflicting Names
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+During the import we lookup existing declarations with the same name. We filter
+the lookup results based on their :ref:`visibility <visibility>`. If any of the
+found declarations are not structurally equivalent then we bumped to a name
+conflict error (ODR violation in C++). In this case, we return with an
+``Error`` and we set up the ``Error`` object for the declaration. However, some
+clients of the ``ASTImporter`` may require a different, perhaps less
+conservative and more liberal error handling strategy.
+
+E.g. static analysis clients may benefit if the node is created even if there
+is a name conflict. During the CTU analysis of certain projects, we recognized
+that there are global declarations which collide with declarations from other
+translation units, but they are not referenced outside from their translation
+unit. These declarations should be in an unnamed namespace ideally. If we treat
+these collisions liberally then CTU analysis can find more results. Note, the
+feature be able to choose between name conflict handling strategies is still an
+ongoing work.
+
 .. _CFG:
 
 The ``CFG`` class
@@ -1342,7 +1938,7 @@ constructed for function bodies (usually an instance of ``CompoundStmt``), but
 can also be instantiated to represent the control-flow of any class that
 subclasses ``Stmt``, which includes simple expressions.  Control-flow graphs
 are especially useful for performing `flow- or path-sensitive
-<http://en.wikipedia.org/wiki/Data_flow_analysis#Sensitivities>`_ program
+<https://en.wikipedia.org/wiki/Data_flow_analysis#Sensitivities>`_ program
 analyses on a given function.
 
 Basic Blocks
@@ -1529,7 +2125,7 @@ about them.
 
 Finally, this is not just a problem for semantic analysis.  The code generator
 and other clients have to be able to fold constants (e.g., to initialize global
-variables) and has to handle a superset of what C99 allows.  Further, these
+variables) and have to handle a superset of what C99 allows.  Further, these
 clients can benefit from extended information.  For example, we know that
 "``foo() || 1``" always evaluates to ``true``, but we can't replace the
 expression with ``true`` because it has side effects.
@@ -1638,15 +2234,15 @@ and then the semantic handling of the attribute.
 Parsing of the attribute is determined by the various syntactic forms attributes
 can take, such as GNU, C++11, and Microsoft style attributes, as well as other
 information provided by the table definition of the attribute. Ultimately, the
-parsed representation of an attribute object is an ``AttributeList`` object.
+parsed representation of an attribute object is an ``ParsedAttr`` object.
 These parsed attributes chain together as a list of parsed attributes attached
 to a declarator or declaration specifier. The parsing of attributes is handled
 automatically by Clang, except for attributes spelled as keywords. When
 implementing a keyword attribute, the parsing of the keyword and creation of the
-``AttributeList`` object must be done manually.
+``ParsedAttr`` object must be done manually.
 
 Eventually, ``Sema::ProcessDeclAttributeList()`` is called with a ``Decl`` and
-an ``AttributeList``, at which point the parsed attribute can be transformed
+an ``ParsedAttr``, at which point the parsed attribute can be transformed
 into a semantic attribute. The process by which a parsed attribute is converted
 into a semantic attribute depends on the attribute definition and semantic
 requirements of the attribute. The end result, however, is that the semantic
@@ -1664,7 +2260,7 @@ semantic checking for some attributes, etc.
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The first step to adding a new attribute to Clang is to add its definition to
 `include/clang/Basic/Attr.td
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/Attr.td?view=markup>`_.
+<https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Basic/Attr.td>`_.
 This tablegen definition must derive from the ``Attr`` (tablegen, not
 semantic) type, or one of its derivatives. Most attributes will derive from the
 ``InheritableAttr`` type, which specifies that the attribute can be inherited by
@@ -1725,11 +2321,11 @@ 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
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Sema/AttributeList.h?view=markup>`_
+in `include/clang/Sema/ParsedAttr.h
+<https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Sema/ParsedAttr.h>`_
 If a previously unused Decl node is added to the ``SubjectList``, the logic used
 to automatically determine the diagnostic parameter in `utils/TableGen/ClangAttrEmitter.cpp
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/utils/TableGen/ClangAttrEmitter.cpp?view=markup>`_
+<https://github.com/llvm/llvm-project/blob/master/clang/utils/TableGen/ClangAttrEmitter.cpp>`_
 may need to be updated.
 
 By default, all subjects in the SubjectList must either be a Decl node defined
@@ -1751,7 +2347,7 @@ All attributes must have some form of documentation associated with them.
 Documentation is table generated on the public web server by a server-side
 process that runs daily. Generally, the documentation for an attribute is a
 stand-alone definition in `include/clang/Basic/AttrDocs.td 
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/AttdDocs.td?view=markup>`_
+<https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Basic/AttrDocs.td>`_
 that is named after the attribute being documented.
 
 If the attribute is not for public consumption, or is an implicitly-created
@@ -1802,7 +2398,7 @@ All arguments have a name and a flag that specifies whether the argument is
 optional. The associated C++ type of the argument is determined by the argument
 definition type. If the existing argument types are insufficient, new types can
 be created, but it requires modifying `utils/TableGen/ClangAttrEmitter.cpp
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/utils/TableGen/ClangAttrEmitter.cpp?view=markup>`_
+<https://github.com/llvm/llvm-project/blob/master/clang/utils/TableGen/ClangAttrEmitter.cpp>`_
 to properly support the type.
 
 Other Properties
@@ -1814,7 +2410,7 @@ document, however a few deserve mention.
 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()
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Parse/ParseDecl.cpp?view=markup>`_
+<https://github.com/llvm/llvm-project/blob/master/clang/lib/Parse/ParseDecl.cpp>`_
 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``.
@@ -1861,15 +2457,10 @@ requirements. To support this feature, an attribute inheriting from
 should be the same value between all arguments sharing a spelling, and
 corresponds to the parsed attribute's ``Kind`` enumerator. This allows
 attributes to share a parsed attribute kind, but have distinct semantic
-attribute classes. For instance, ``AttributeList::AT_Interrupt`` is the shared
+attribute classes. For instance, ``ParsedAttr`` 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), set
@@ -1882,7 +2473,7 @@ semantic attribute class object, with ``public`` access.
 Boilerplate
 ^^^^^^^^^^^
 All semantic processing of declaration attributes happens in `lib/Sema/SemaDeclAttr.cpp
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Sema/SemaDeclAttr.cpp?view=markup>`_,
+<https://github.com/llvm/llvm-project/blob/master/clang/lib/Sema/SemaDeclAttr.cpp>`_,
 and generally starts in the ``ProcessDeclAttribute()`` function. If the
 attribute is a "simple" attribute -- meaning that it requires no custom semantic
 processing aside from what is automatically  provided, add a call to
@@ -1898,11 +2489,11 @@ correct minimum number of arguments are passed, etc.
 
 If the attribute adds additional warnings, define a ``DiagGroup`` in
 `include/clang/Basic/DiagnosticGroups.td
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticGroups.td?view=markup>`_
+<https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Basic/DiagnosticGroups.td>`_
 named after the attribute's ``Spelling`` with "_"s replaced by "-"s. If there
 is only a single diagnostic, it is permissible to use ``InGroup<DiagGroup<"your-attribute">>``
 directly in `DiagnosticSemaKinds.td
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticSemaKinds.td?view=markup>`_
+<https://github.com/llvm/llvm-project/blob/master/clang/include/clang/Basic/DiagnosticSemaKinds.td>`_
 
 All semantic diagnostics generated for your attribute, including automatically-
 generated ones (such as subjects and argument counts), should have a
@@ -2054,7 +2645,7 @@ are similar.
      exception-handling directly.
    * Testing is extremely important in IR generation.  Use ``clang -cc1
      -emit-llvm`` and `FileCheck
-     <http://llvm.org/docs/CommandGuide/FileCheck.html>`_ to verify that you're
+     <https://llvm.org/docs/CommandGuide/FileCheck.html>`_ to verify that you're
      generating the right IR.
 
 #. Teach template instantiation how to cope with your AST node, which requires

docs/IntroductionToTheClangAST.rst

@@ -9,9 +9,9 @@ matchers.
 
 .. raw:: html
 
-  <center><iframe width="560" height="315" src="http://www.youtube.com/embed/VqCkCDFLSsc?vq=hd720" frameborder="0" allowfullscreen></iframe></center>
+  <center><iframe width="560" height="315" src="https://www.youtube.com/embed/VqCkCDFLSsc?vq=hd720" frameborder="0" allowfullscreen></iframe></center>
 
-`Slides <http://llvm.org/devmtg/2013-04/klimek-slides.pdf>`_
+`Slides <https://llvm.org/devmtg/2013-04/klimek-slides.pdf>`_
 
 Introduction
 ============
@@ -23,7 +23,7 @@ constants are available in an unreduced form in the AST. This makes
 Clang's AST a good fit for refactoring tools.
 
 Documentation for all Clang AST nodes is available via the generated
-`Doxygen <http://clang.llvm.org/doxygen>`_. The doxygen online
+`Doxygen <https://clang.llvm.org/doxygen>`_. The doxygen online
 documentation is also indexed by your favorite search engine, which will
 make a search for clang and the AST node's class name usually turn up
 the doxygen of the class you're looking for (for example, search for:
@@ -67,26 +67,26 @@ Let's look at a simple example AST:
 
 The toplevel declaration in
 a translation unit is always the `translation unit
-declaration <http://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html>`_.
+declaration <https://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html>`_.
 In this example, our first user written declaration is the `function
-declaration <http://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html>`_
+declaration <https://clang.llvm.org/doxygen/classclang_1_1FunctionDecl.html>`_
 of "``f``". The body of "``f``" is a `compound
-statement <http://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html>`_,
+statement <https://clang.llvm.org/doxygen/classclang_1_1CompoundStmt.html>`_,
 whose child nodes are a `declaration
-statement <http://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html>`_
+statement <https://clang.llvm.org/doxygen/classclang_1_1DeclStmt.html>`_
 that declares our result variable, and the `return
-statement <http://clang.llvm.org/doxygen/classclang_1_1ReturnStmt.html>`_.
+statement <https://clang.llvm.org/doxygen/classclang_1_1ReturnStmt.html>`_.
 
 AST Context
 ===========
 
 All information about the AST for a translation unit is bundled up in
 the class
-`ASTContext <http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html>`_.
+`ASTContext <https://clang.llvm.org/doxygen/classclang_1_1ASTContext.html>`_.
 It allows traversal of the whole translation unit starting from
-`getTranslationUnitDecl <http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#abd909fb01ef10cfd0244832a67b1dd64>`_,
+`getTranslationUnitDecl <https://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#abd909fb01ef10cfd0244832a67b1dd64>`_,
 or to access Clang's `table of
-identifiers <http://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#a4f95adb9958e22fbe55212ae6482feb4>`_
+identifiers <https://clang.llvm.org/doxygen/classclang_1_1ASTContext.html#a4f95adb9958e22fbe55212ae6482feb4>`_
 for the parsed translation unit.
 
 AST Nodes
@@ -95,32 +95,32 @@ AST Nodes
 Clang's AST nodes are modeled on a class hierarchy that does not have a
 common ancestor. Instead, there are multiple larger hierarchies for
 basic node types like
-`Decl <http://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_ and
-`Stmt <http://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_. Many
+`Decl <https://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_ and
+`Stmt <https://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_. Many
 important AST nodes derive from
-`Type <http://clang.llvm.org/doxygen/classclang_1_1Type.html>`_,
-`Decl <http://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_,
-`DeclContext <http://clang.llvm.org/doxygen/classclang_1_1DeclContext.html>`_
-or `Stmt <http://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_, with
+`Type <https://clang.llvm.org/doxygen/classclang_1_1Type.html>`_,
+`Decl <https://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_,
+`DeclContext <https://clang.llvm.org/doxygen/classclang_1_1DeclContext.html>`_
+or `Stmt <https://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_, with
 some classes deriving from both Decl and DeclContext.
 
 There are also a multitude of nodes in the AST that are not part of a
 larger hierarchy, and are only reachable from specific other nodes, like
-`CXXBaseSpecifier <http://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html>`_.
+`CXXBaseSpecifier <https://clang.llvm.org/doxygen/classclang_1_1CXXBaseSpecifier.html>`_.
 
 Thus, to traverse the full AST, one starts from the
-`TranslationUnitDecl <http://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html>`_
+`TranslationUnitDecl <https://clang.llvm.org/doxygen/classclang_1_1TranslationUnitDecl.html>`_
 and then recursively traverses everything that can be reached from that
 node - this information has to be encoded for each specific node type.
 This algorithm is encoded in the
-`RecursiveASTVisitor <http://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html>`_.
+`RecursiveASTVisitor <https://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html>`_.
 See the `RecursiveASTVisitor
-tutorial <http://clang.llvm.org/docs/RAVFrontendAction.html>`_.
+tutorial <https://clang.llvm.org/docs/RAVFrontendAction.html>`_.
 
 The two most basic nodes in the Clang AST are statements
-(`Stmt <http://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_) and
+(`Stmt <https://clang.llvm.org/doxygen/classclang_1_1Stmt.html>`_) and
 declarations
-(`Decl <http://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_). Note
+(`Decl <https://clang.llvm.org/doxygen/classclang_1_1Decl.html>`_). Note
 that expressions
-(`Expr <http://clang.llvm.org/doxygen/classclang_1_1Expr.html>`_) are
+(`Expr <https://clang.llvm.org/doxygen/classclang_1_1Expr.html>`_) are
 also statements in Clang's AST.

docs/JSONCompilationDatabase.rst

@@ -29,7 +29,7 @@ system is not necessarily the best solution:
 Supported Systems
 =================
 
-Currently `CMake <http://cmake.org>`_ (since 2.8.5) supports generation
+Currently `CMake <https://cmake.org>`_ (since 2.8.5) supports generation
 of compilation databases for Unix Makefile builds (Ninja builds in the
 works) with the option ``CMAKE_EXPORT_COMPILE_COMMANDS``.
 

docs/LTOVisibility.rst

@@ -11,9 +11,9 @@ linkage unit's LTO unit is empty. Each linkage unit has only a single LTO unit.
 
 The LTO visibility of a class is used by the compiler to determine which
 classes the whole-program devirtualization (``-fwhole-program-vtables``) and
-control flow integrity (``-fsanitize=cfi-vcall``) features apply to. These
-features use whole-program information, so they require the entire class
-hierarchy to be visible in order to work correctly.
+control flow integrity (``-fsanitize=cfi-vcall`` and ``-fsanitize=cfi-mfcall``)
+features apply to. These features use whole-program information, so they
+require the entire class hierarchy to be visible in order to work correctly.
 
 If any translation unit in the program uses either of the whole-program
 devirtualization or control flow integrity features, it is effectively an ODR

docs/LeakSanitizer.rst

@@ -17,7 +17,7 @@ detection phase.
 Usage
 =====
 
-LeakSanitizer is supported on x86\_64 Linux and OS X. In order to use it,
+LeakSanitizer is supported on x86\_64 Linux and macOS. In order to use it,
 simply build your program with :doc:`AddressSanitizer`:
 
 .. code-block:: console

docs/LibASTImporter.rst

@@ -0,0 +1,613 @@
+===============================
+ASTImporter: Merging Clang ASTs
+===============================
+
+The ``ASTImporter`` class is part of Clang's core library, the AST library.
+It imports nodes of an ``ASTContext`` into another ``ASTContext``.
+
+In this document, we assume basic knowledge about the Clang AST.  See the :doc:`Introduction
+to the Clang AST <IntroductionToTheClangAST>` if you want to learn more
+about how the AST is structured.
+Knowledge about :doc:`matching the Clang AST <LibASTMatchers>` and the `reference for the matchers <https://clang.llvm.org/docs/LibASTMatchersReference.html>`_ are also useful.
+
+.. contents::
+   :local:
+
+Introduction
+------------
+
+``ASTContext`` holds long-lived AST nodes (such as types and decls) that can be referred to throughout the semantic analysis of a file.
+In some cases it is preferable to work with more than one ``ASTContext``.
+For example, we'd like to parse multiple different files inside the same Clang tool.
+It may be convenient if we could view the set of the resulting ASTs as if they were one AST resulting from the parsing of each file together.
+``ASTImporter`` provides the way to copy types or declarations from one ``ASTContext`` to another.
+We refer to the context from which we import as the **"from" context** or *source context*; and the context into which we import as the **"to" context** or *destination context*.
+
+Existing clients of the ``ASTImporter`` library are Cross Translation Unit (CTU) static analysis and the LLDB expression parser.
+CTU static analysis imports a definition of a function if its definition is found in another translation unit (TU).
+This way the analysis can breach out from the single TU limitation.
+LLDB's ``expr`` command parses a user-defined expression, creates an ``ASTContext`` for that and then imports the missing definitions from the AST what we got from the debug information (DWARF, etc).
+
+Algorithm of the import
+-----------------------
+
+Importing one AST node copies that node into the destination ``ASTContext``.
+Why do we have to copy the node?
+Isn't enough to insert the pointer to that node into the destination context?
+One reason is that the "from" context may outlive the "to" context.
+Also, the Clang AST consider nodes (or certain properties of nodes) equivalent if they have the same address!
+
+The import algorithm has to ensure that the structurally equivalent nodes in the different translation units are not getting duplicated in the merged AST.
+E.g. if we include the definition of the vector template (``#include <vector>``) in two translation units, then their merged AST should have only one node which represents the template.
+Also, we have to discover *one definition rule* (ODR) violations.
+For instance, if there is a class definition with the same name in both translation units, but one of the definition contains a different number of fields.
+So, we look up existing definitions, and then we check the structural equivalency on those nodes.
+The following pseudo-code demonstrates the basics of the import mechanism:
+
+.. code-block:: cpp
+
+  // Pseudo-code(!) of import:
+  ErrorOrDecl Import(Decl *FromD) {
+    Decl *ToDecl = nullptr;
+    FoundDeclsList = Look up all Decls in the "to" Ctx with the same name of FromD;
+    for (auto FoundDecl : FoundDeclsList) {
+      if (StructurallyEquivalentDecls(FoundDecl, FromD)) {
+        ToDecl = FoundDecl;
+        Mark FromD as imported;
+        break;
+      } else {
+        Report ODR violation;
+        return error;
+      }
+    }
+    if (FoundDeclsList is empty) {
+      Import dependent declarations and types of ToDecl;
+      ToDecl = create a new AST node in "to" Ctx;
+      Mark FromD as imported;
+    }
+    return ToDecl;
+  }
+
+Two AST nodes are *structurally equivalent* if they are
+
+- builtin types and refer to the same type, e.g. ``int`` and ``int`` are structurally equivalent,
+- function types and all their parameters have structurally equivalent types,
+- record types and all their fields in order of their definition have the same identifier names and structurally equivalent types,
+- variable or function declarations and they have the same identifier name and their types are structurally equivalent.
+
+We could extend the definition of structural equivalency to templates similarly.
+
+If A and B are AST nodes and *A depends on B*, then we say that A is a **dependant** of B and B is a **dependency** of A.
+The words "dependant" and "dependency" are nouns in British English.
+Unfortunately, in American English, the adjective "dependent" is used for both meanings.
+In this document, with the "dependent" adjective we always address the dependencies, the B node in the example.
+
+API
+---
+
+Let's create a tool which uses the ASTImporter class!
+First, we build two ASTs from virtual files; the content of the virtual files are synthesized from string literals:
+
+.. code-block:: cpp
+
+  std::unique_ptr<ASTUnit> ToUnit = buildASTFromCode(
+      "", "to.cc"); // empty file
+  std::unique_ptr<ASTUnit> FromUnit = buildASTFromCode(
+      R"(
+      class MyClass {
+        int m1;
+        int m2;
+      };
+      )",
+      "from.cc");
+
+The first AST corresponds to the destination ("to") context - which is empty - and the second for the source ("from") context.
+Next, we define a matcher to match ``MyClass`` in the "from" context:
+
+.. code-block:: cpp
+
+  auto Matcher = cxxRecordDecl(hasName("MyClass"));
+  auto *From = getFirstDecl<CXXRecordDecl>(Matcher, FromUnit);
+
+Now we create the Importer and do the import:
+
+.. code-block:: cpp
+
+  ASTImporter Importer(ToUnit->getASTContext(), ToUnit->getFileManager(),
+                       FromUnit->getASTContext(), FromUnit->getFileManager(),
+                       /*MinimalImport=*/true);
+  llvm::Expected<Decl *> ImportedOrErr = Importer.Import(From);
+
+The ``Import`` call returns with ``llvm::Expected``, so, we must check for any error.
+Please refer to the `error handling <http://llvm.org/docs/ProgrammersManual.html#recoverable-errors>`_ documentation for details.
+
+.. code-block:: cpp
+
+  if (!ImportedOrErr) {
+    llvm::Error Err = ImportedOrErr.takeError();
+    llvm::errs() << "ERROR: " << Err << "\n";
+    consumeError(std::move(Err));
+    return 1;
+  }
+
+If there's no error then we can get the underlying value.
+In this example we will print the AST of the "to" context.
+
+.. code-block:: cpp
+
+  Decl *Imported = *ImportedOrErr;
+  Imported->getTranslationUnitDecl()->dump();
+
+Since we set **minimal import** in the constructor of the importer, the AST will not contain the declaration of the members (once we run the test tool).
+
+.. code-block:: bash
+
+  TranslationUnitDecl 0x68b9a8 <<invalid sloc>> <invalid sloc>
+  `-CXXRecordDecl 0x6c7e30 <line:2:7, col:13> col:13 class MyClass definition
+    `-DefinitionData pass_in_registers standard_layout trivially_copyable trivial literal
+      |-DefaultConstructor exists trivial needs_implicit
+      |-CopyConstructor simple trivial has_const_param needs_implicit implicit_has_const_param
+      |-MoveConstructor exists simple trivial needs_implicit
+      |-CopyAssignment trivial has_const_param needs_implicit implicit_has_const_param
+      |-MoveAssignment exists simple trivial needs_implicit
+      `-Destructor simple irrelevant trivial needs_implicit
+
+We'd like to get the members too, so, we use ``ImportDefinition`` to copy the whole definition of ``MyClass`` into the "to" context.
+Then we dump the AST again.
+
+.. code-block:: cpp
+
+  if (llvm::Error Err = Importer.ImportDefinition(From)) {
+    llvm::errs() << "ERROR: " << Err << "\n";
+    consumeError(std::move(Err));
+    return 1;
+  }
+  llvm::errs() << "Imported definition.\n";
+  Imported->getTranslationUnitDecl()->dump();
+
+This time the AST is going to contain the members too.
+
+.. code-block:: bash
+
+  TranslationUnitDecl 0x68b9a8 <<invalid sloc>> <invalid sloc>
+  `-CXXRecordDecl 0x6c7e30 <line:2:7, col:13> col:13 class MyClass definition
+    |-DefinitionData pass_in_registers standard_layout trivially_copyable trivial literal
+    | |-DefaultConstructor exists trivial needs_implicit
+    | |-CopyConstructor simple trivial has_const_param needs_implicit implicit_has_const_param
+    | |-MoveConstructor exists simple trivial needs_implicit
+    | |-CopyAssignment trivial has_const_param needs_implicit implicit_has_const_param
+    | |-MoveAssignment exists simple trivial needs_implicit
+    | `-Destructor simple irrelevant trivial needs_implicit
+    |-CXXRecordDecl 0x6c7f48 <col:7, col:13> col:13 implicit class MyClass
+    |-FieldDecl 0x6c7ff0 <line:3:9, col:13> col:13 m1 'int'
+    `-FieldDecl 0x6c8058 <line:4:9, col:13> col:13 m2 'int'
+
+We can spare the call for ``ImportDefinition`` if we set up the importer to do a "normal" (not minimal) import.
+
+.. code-block:: cpp
+
+  ASTImporter Importer( ....  /*MinimalImport=*/false);
+
+With **normal import**, all dependent declarations are imported normally.
+However, with minimal import, the dependent Decls are imported without definition, and we have to import their definition for each if we later need that.
+
+Putting this all together here is how the source of the tool looks like:
+
+.. code-block:: cpp
+
+  #include "clang/AST/ASTImporter.h"
+  #include "clang/ASTMatchers/ASTMatchFinder.h"
+  #include "clang/ASTMatchers/ASTMatchers.h"
+  #include "clang/Tooling/Tooling.h"
+
+  using namespace clang;
+  using namespace tooling;
+  using namespace ast_matchers;
+
+  template <typename Node, typename Matcher>
+  Node *getFirstDecl(Matcher M, const std::unique_ptr<ASTUnit> &Unit) {
+    auto MB = M.bind("bindStr"); // Bind the to-be-matched node to a string key.
+    auto MatchRes = match(MB, Unit->getASTContext());
+    // We should have at least one match.
+    assert(MatchRes.size() >= 1);
+    // Get the first matched and bound node.
+    Node *Result =
+        const_cast<Node *>(MatchRes[0].template getNodeAs<Node>("bindStr"));
+    assert(Result);
+    return Result;
+  }
+
+  int main() {
+    std::unique_ptr<ASTUnit> ToUnit = buildASTFromCode(
+        "", "to.cc");
+    std::unique_ptr<ASTUnit> FromUnit = buildASTFromCode(
+        R"(
+        class MyClass {
+          int m1;
+          int m2;
+        };
+        )",
+        "from.cc");
+    auto Matcher = cxxRecordDecl(hasName("MyClass"));
+    auto *From = getFirstDecl<CXXRecordDecl>(Matcher, FromUnit);
+
+    ASTImporter Importer(ToUnit->getASTContext(), ToUnit->getFileManager(),
+                         FromUnit->getASTContext(), FromUnit->getFileManager(),
+                         /*MinimalImport=*/true);
+    llvm::Expected<Decl *> ImportedOrErr = Importer.Import(From);
+    if (!ImportedOrErr) {
+      llvm::Error Err = ImportedOrErr.takeError();
+      llvm::errs() << "ERROR: " << Err << "\n";
+      consumeError(std::move(Err));
+      return 1;
+    }
+    Decl *Imported = *ImportedOrErr;
+    Imported->getTranslationUnitDecl()->dump();
+
+    if (llvm::Error Err = Importer.ImportDefinition(From)) {
+      llvm::errs() << "ERROR: " << Err << "\n";
+      consumeError(std::move(Err));
+      return 1;
+    }
+    llvm::errs() << "Imported definition.\n";
+    Imported->getTranslationUnitDecl()->dump();
+
+    return 0;
+  };
+
+We may extend the ``CMakeLists.txt`` under let's say ``clang/tools`` with the build and link instructions:
+
+.. code-block:: bash
+
+  add_clang_executable(astimporter-demo ASTImporterDemo.cpp)
+  clang_target_link_libraries(astimporter-demo
+    PRIVATE
+    LLVMSupport
+    clangAST
+    clangASTMatchers
+    clangBasic
+    clangFrontend
+    clangSerialization
+    clangTooling
+    )
+
+Then we can build and execute the new tool.
+
+.. code-block:: bash
+
+  $ ninja astimporter-demo && ./bin/astimporter-demo
+
+Errors during the import process
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Normally, either the source or the destination context contains the definition of a declaration.
+However, there may be cases when both of the contexts have a definition for a given symbol.
+If these definitions differ, then we have a name conflict, in C++ it is known as ODR (one definition rule) violation.
+Let's modify the previous tool we had written and try to import a ``ClassTemplateSpecializationDecl`` with a conflicting definition:
+
+.. code-block:: cpp
+
+  int main() {
+    std::unique_ptr<ASTUnit> ToUnit = buildASTFromCode(
+        R"(
+        // primary template
+        template <typename T>
+        struct X {};
+        // explicit specialization
+        template<>
+        struct X<int> { int i; };
+        )",
+        "to.cc");
+    ToUnit->enableSourceFileDiagnostics();
+    std::unique_ptr<ASTUnit> FromUnit = buildASTFromCode(
+        R"(
+        // primary template
+        template <typename T>
+        struct X {};
+        // explicit specialization
+        template<>
+        struct X<int> { int i2; };
+        // field mismatch:  ^^
+        )",
+        "from.cc");
+    FromUnit->enableSourceFileDiagnostics();
+    auto Matcher = classTemplateSpecializationDecl(hasName("X"));
+    auto *From = getFirstDecl<ClassTemplateSpecializationDecl>(Matcher, FromUnit);
+    auto *To = getFirstDecl<ClassTemplateSpecializationDecl>(Matcher, ToUnit);
+
+    ASTImporter Importer(ToUnit->getASTContext(), ToUnit->getFileManager(),
+                         FromUnit->getASTContext(), FromUnit->getFileManager(),
+                         /*MinimalImport=*/false);
+    llvm::Expected<Decl *> ImportedOrErr = Importer.Import(From);
+    if (!ImportedOrErr) {
+      llvm::Error Err = ImportedOrErr.takeError();
+      llvm::errs() << "ERROR: " << Err << "\n";
+      consumeError(std::move(Err));
+      To->getTranslationUnitDecl()->dump();
+      return 1;
+    }
+    return 0;
+  };
+
+When we run the tool we have the following warning:
+
+.. code-block:: bash
+
+  to.cc:7:14: warning: type 'X<int>' has incompatible definitions in different translation units [-Wodr]
+        struct X<int> { int i; };
+               ^
+  to.cc:7:27: note: field has name 'i' here
+        struct X<int> { int i; };
+                            ^
+  from.cc:7:27: note: field has name 'i2' here
+        struct X<int> { int i2; };
+                          ^
+
+Note, because of these diagnostics we had to call ``enableSourceFileDiagnostics`` on the ``ASTUnit`` objects.
+
+Since we could not import the specified declaration (``From``), we get an error in the return value.
+The AST does not contain the conflicting definition, so we are left with the original AST.
+
+.. code-block:: bash
+
+  ERROR: NameConflict
+  TranslationUnitDecl 0xe54a48 <<invalid sloc>> <invalid sloc>
+  |-ClassTemplateDecl 0xe91020 <to.cc:3:7, line:4:17> col:14 X
+  | |-TemplateTypeParmDecl 0xe90ed0 <line:3:17, col:26> col:26 typename depth 0 index 0 T
+  | |-CXXRecordDecl 0xe90f90 <line:4:7, col:17> col:14 struct X definition
+  | | |-DefinitionData empty aggregate standard_layout trivially_copyable pod trivial literal has_constexpr_non_copy_move_ctor can_const_default_init
+  | | | |-DefaultConstructor exists trivial constexpr needs_implicit defaulted_is_constexpr
+  | | | |-CopyConstructor simple trivial has_const_param needs_implicit implicit_has_const_param
+  | | | |-MoveConstructor exists simple trivial needs_implicit
+  | | | |-CopyAssignment trivial has_const_param needs_implicit implicit_has_const_param
+  | | | |-MoveAssignment exists simple trivial needs_implicit
+  | | | `-Destructor simple irrelevant trivial needs_implicit
+  | | `-CXXRecordDecl 0xe91270 <col:7, col:14> col:14 implicit struct X
+  | `-ClassTemplateSpecialization 0xe91340 'X'
+  `-ClassTemplateSpecializationDecl 0xe91340 <line:6:7, line:7:30> col:14 struct X definition
+    |-DefinitionData pass_in_registers aggregate standard_layout trivially_copyable pod trivial literal
+    | |-DefaultConstructor exists trivial needs_implicit
+    | |-CopyConstructor simple trivial has_const_param needs_implicit implicit_has_const_param
+    | |-MoveConstructor exists simple trivial needs_implicit
+    | |-CopyAssignment trivial has_const_param needs_implicit implicit_has_const_param
+    | |-MoveAssignment exists simple trivial needs_implicit
+    | `-Destructor simple irrelevant trivial needs_implicit
+    |-TemplateArgument type 'int'
+    |-CXXRecordDecl 0xe91558 <col:7, col:14> col:14 implicit struct X
+    `-FieldDecl 0xe91600 <col:23, col:27> col:27 i 'int'
+
+Error propagation
+"""""""""""""""""
+
+If there is a dependent node we have to import before we could import a given node then the import error associated to the dependency propagates to the dependant node.
+Let's modify the previous example and import a ``FieldDecl`` instead of the ``ClassTemplateSpecializationDecl``.
+
+.. code-block:: cpp
+
+  auto Matcher = fieldDecl(hasName("i2"));
+  auto *From = getFirstDecl<FieldDecl>(Matcher, FromUnit);
+
+In this case we can see that an error is associated (``getImportDeclErrorIfAny``) to the specialization also, not just to the field:
+
+.. code-block:: cpp
+
+  llvm::Expected<Decl *> ImportedOrErr = Importer.Import(From);
+  if (!ImportedOrErr) {
+    llvm::Error Err = ImportedOrErr.takeError();
+    consumeError(std::move(Err));
+
+    // check that the ClassTemplateSpecializationDecl is also marked as
+    // erroneous.
+    auto *FromSpec = getFirstDecl<ClassTemplateSpecializationDecl>(
+        classTemplateSpecializationDecl(hasName("X")), FromUnit);
+    assert(Importer.getImportDeclErrorIfAny(FromSpec));
+    // Btw, the error is also set for the FieldDecl.
+    assert(Importer.getImportDeclErrorIfAny(From));
+    return 1;
+  }
+
+Polluted AST
+""""""""""""
+
+We may recognize an error during the import of a dependent node. However, by that time, we had already created the dependant.
+In these cases we do not remove the existing erroneous node from the "to" context, rather we associate an error to that node.
+Let's extend the previous example with another class ``Y``.
+This class has a forward definition in the "to" context, but its definition is in the "from" context.
+We'd like to import the definition, but it contains a member whose type conflicts with the type in the "to" context:
+
+.. code-block:: cpp
+
+  std::unique_ptr<ASTUnit> ToUnit = buildASTFromCode(
+      R"(
+      // primary template
+      template <typename T>
+      struct X {};
+      // explicit specialization
+      template<>
+      struct X<int> { int i; };
+
+      class Y;
+      )",
+      "to.cc");
+  ToUnit->enableSourceFileDiagnostics();
+  std::unique_ptr<ASTUnit> FromUnit = buildASTFromCode(
+      R"(
+      // primary template
+      template <typename T>
+      struct X {};
+      // explicit specialization
+      template<>
+      struct X<int> { int i2; };
+      // field mismatch:  ^^
+
+      class Y { void f() { X<int> xi; } };
+      )",
+      "from.cc");
+  FromUnit->enableSourceFileDiagnostics();
+  auto Matcher = cxxRecordDecl(hasName("Y"));
+  auto *From = getFirstDecl<CXXRecordDecl>(Matcher, FromUnit);
+  auto *To = getFirstDecl<CXXRecordDecl>(Matcher, ToUnit);
+
+This time we create a shared_ptr for ``ASTImporterSharedState`` which owns the associated errors for the "to" context.
+Note, there may be several different ASTImporter objects which import into the same "to" context but from different "from" contexts; they should share the same ``ASTImporterSharedState``.
+(Also note, we have to include the corresponding ``ASTImporterSharedState.h`` header file.)
+
+.. code-block:: cpp
+
+  auto ImporterState = std::make_shared<ASTImporterSharedState>();
+  ASTImporter Importer(ToUnit->getASTContext(), ToUnit->getFileManager(),
+                       FromUnit->getASTContext(), FromUnit->getFileManager(),
+                       /*MinimalImport=*/false, ImporterState);
+  llvm::Expected<Decl *> ImportedOrErr = Importer.Import(From);
+  if (!ImportedOrErr) {
+    llvm::Error Err = ImportedOrErr.takeError();
+    consumeError(std::move(Err));
+
+    // ... but the node had been created.
+    auto *ToYDef = getFirstDecl<CXXRecordDecl>(
+        cxxRecordDecl(hasName("Y"), isDefinition()), ToUnit);
+    ToYDef->dump();
+    // An error is set for "ToYDef" in the shared state.
+    Optional<ImportError> OptErr =
+        ImporterState->getImportDeclErrorIfAny(ToYDef);
+    assert(OptErr);
+
+    return 1;
+  }
+
+If we take a look at the AST, then we can see that the Decl with the definition is created, but the field is missing.
+
+.. code-block:: bash
+
+  |-CXXRecordDecl 0xf66678 <line:9:7, col:13> col:13 class Y
+  `-CXXRecordDecl 0xf66730 prev 0xf66678 <:10:7, col:13> col:13 class Y definition
+    |-DefinitionData pass_in_registers empty aggregate standard_layout trivially_copyable pod trivial literal has_constexpr_non_copy_move_ctor can_const_default_init
+    | |-DefaultConstructor exists trivial constexpr needs_implicit defaulted_is_constexpr
+    | |-CopyConstructor simple trivial has_const_param needs_implicit implicit_has_const_param
+    | |-MoveConstructor exists simple trivial needs_implicit
+    | |-CopyAssignment trivial has_const_param needs_implicit implicit_has_const_param
+    | |-MoveAssignment exists simple trivial needs_implicit
+    | `-Destructor simple irrelevant trivial needs_implicit
+    `-CXXRecordDecl 0xf66828 <col:7, col:13> col:13 implicit class Y
+
+We do not remove the erroneous nodes because by the time when we recognize the error it is too late to remove the node, there may be additional references to that already in the AST.
+This is aligned with the overall `design principle of the Clang AST <InternalsManual.html#immutability>`_: Clang AST nodes (types, declarations, statements, expressions, and so on) are generally designed to be **immutable once created**.
+Thus, clients of the ASTImporter library should always check if there is any associated error for the node which they inspect in the destination context.
+We recommend skipping the processing of those nodes which have an error associated with them.
+
+Using the ``-ast-merge`` Clang front-end action
+-----------------------------------------------
+
+The ``-ast-merge <pch-file>`` command-line switch can be used to merge from the given serialized AST file.
+This file represents the source context.
+When this switch is present then each top-level AST node of the source context is being merged into the destination context.
+If the merge was successful then ``ASTConsumer::HandleTopLevelDecl`` is called for the Decl.
+This results that we can execute the original front-end action on the extended AST.
+
+Example for C
+^^^^^^^^^^^^^
+
+Let's consider the following three files:
+
+.. code-block:: c
+
+  // bar.h
+  #ifndef BAR_H
+  #define BAR_H
+  int bar();
+  #endif /* BAR_H */
+
+  // bar.c
+  #include "bar.h"
+  int bar() {
+    return 41;
+  }
+
+  // main.c
+  #include "bar.h"
+  int main() {
+      return bar();
+  }
+
+Let's generate the AST files for the two source files:
+
+.. code-block:: bash
+
+  $ clang -cc1 -emit-pch -o bar.ast bar.c
+  $ clang -cc1 -emit-pch -o main.ast main.c
+
+Then, let's check how the merged AST would look like if we consider only the ``bar()`` function:
+
+.. code-block:: bash
+
+  $ clang -cc1 -ast-merge bar.ast -ast-merge main.ast /dev/null -ast-dump
+  TranslationUnitDecl 0x12b0738 <<invalid sloc>> <invalid sloc>
+  |-FunctionDecl 0x12b1470 </path/bar.h:4:1, col:9> col:5 used bar 'int ()'
+  |-FunctionDecl 0x12b1538 prev 0x12b1470 </path/bar.c:3:1, line:5:1> line:3:5 used bar 'int ()'
+  | `-CompoundStmt 0x12b1608 <col:11, line:5:1>
+  |   `-ReturnStmt 0x12b15f8 <line:4:3, col:10>
+  |     `-IntegerLiteral 0x12b15d8 <col:10> 'int' 41
+  |-FunctionDecl 0x12b1648 prev 0x12b1538 </path/bar.h:4:1, col:9> col:5 used bar 'int ()'
+
+We can inspect that the prototype of the function and the definition of it is merged into the same redeclaration chain.
+What's more there is a third prototype declaration merged to the chain.
+The functions are merged in a way that prototypes are added to the redecl chain if they refer to the same type, but we can have only one definition.
+The first two declarations are from ``bar.ast``, the third is from ``main.ast``.
+
+Now, let's create an object file from the merged AST:
+
+.. code-block:: bash
+
+  $ clang -cc1 -ast-merge bar.ast -ast-merge main.ast /dev/null -emit-obj -o main.o
+
+Next, we may call the linker and execute the created binary file.
+
+.. code-block:: bash
+
+  $ clang -o a.out main.o
+  $ ./a.out
+  $ echo $?
+  41
+  $
+
+Example for C++
+^^^^^^^^^^^^^^^
+
+In the case of C++, the generation of the AST files and the way how we invoke the front-end is a bit different.
+Assuming we have these three files:
+
+.. code-block:: cpp
+
+  // foo.h
+  #ifndef FOO_H
+  #define FOO_H
+  struct foo {
+      virtual int fun();
+  };
+  #endif /* FOO_H */
+
+  // foo.cpp
+  #include "foo.h"
+  int foo::fun() {
+    return 42;
+  }
+
+  // main.cpp
+  #include "foo.h"
+  int main() {
+      return foo().fun();
+  }
+
+We shall generate the AST files, merge them, create the executable and then run it:
+
+.. code-block:: bash
+
+  $ clang++ -x c++-header -o foo.ast foo.cpp
+  $ clang++ -x c++-header -o main.ast main.cpp
+  $ clang++ -cc1 -x c++ -ast-merge foo.ast -ast-merge main.ast /dev/null -ast-dump
+  $ clang++ -cc1 -x c++ -ast-merge foo.ast -ast-merge main.ast /dev/null -emit-obj -o main.o
+  $ clang++ -o a.out main.o
+  $ ./a.out
+  $ echo $?
+  42
+  $

docs/LibASTMatchers.rst

@@ -81,7 +81,7 @@ To that end, matchers that match specific AST nodes (so called node matchers)
 are bindable; for example, ``recordDecl(hasName("MyClass")).bind("id")`` will
 bind the matched ``recordDecl`` node to the string "``id``", to be later
 retrieved in the `match callback
-<http://clang.llvm.org/doxygen/classclang_1_1ast__matchers_1_1MatchFinder_1_1MatchCallback.html>`_.
+<https://clang.llvm.org/doxygen/classclang_1_1ast__matchers_1_1MatchFinder_1_1MatchCallback.html>`_.
 
 ..  FIXME: Introduce link to ASTMatchersTutorial.html
 ..  FIXME: Introduce link to ASTMatchersCookbook.html
@@ -116,7 +116,7 @@ corresponding matcher.
 
 There are multiple matcher definition macros that deal with polymorphic return
 values and different parameter counts.  See `ASTMatchersMacros.h
-<http://clang.llvm.org/doxygen/ASTMatchersMacros_8h.html>`_.
+<https://clang.llvm.org/doxygen/ASTMatchersMacros_8h.html>`_.
 
 .. _astmatchers-writing:
 

docs/LibASTMatchersTutorial.rst

@@ -16,23 +16,16 @@ Step 0: Obtaining Clang
 =======================
 
 As Clang is part of the LLVM project, you'll need to download LLVM's
-source code first. Both Clang and LLVM are maintained as Subversion
-repositories, but we'll be accessing them through the git mirror. For
-further information, see the `getting started
-guide <http://llvm.org/docs/GettingStarted.html>`_.
+source code first. Both Clang and LLVM are in the same git repository,
+under different directories. For further information, see the `getting
+started guide <https://llvm.org/docs/GettingStarted.html>`_.
 
 .. code-block:: console
 
-      mkdir ~/clang-llvm && cd ~/clang-llvm
-      git clone http://llvm.org/git/llvm.git
-      cd llvm/tools
-      git clone http://llvm.org/git/clang.git
-      cd clang/tools
-      git clone http://llvm.org/git/clang-tools-extra.git extra
+      cd ~/clang-llvm
+      git clone https://github.com/llvm/llvm-project.git
 
-Next you need to obtain the CMake build system and Ninja build tool. You
-may already have CMake installed, but current binary versions of CMake
-aren't built with Ninja support.
+Next you need to obtain the CMake build system and Ninja build tool.
 
 .. code-block:: console
 
@@ -57,7 +50,7 @@ Okay. Now we'll build Clang!
 
       cd ~/clang-llvm
       mkdir build && cd build
-      cmake -G Ninja ../llvm -DLLVM_BUILD_TESTS=ON  # Enable tests; default is off.
+      cmake -G Ninja ../llvm -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -DLLVM_BUILD_TESTS=ON  # Enable tests; default is off.
       ninja
       ninja check       # Test LLVM only.
       ninja clang-test  # Test Clang only.
@@ -65,9 +58,7 @@ Okay. Now we'll build Clang!
 
 And we're live.
 
-All of the tests should pass, though there is a (very) small chance that
-you can catch LLVM and Clang out of sync. Running ``'git svn rebase'``
-in both the llvm and clang directories should fix any problems.
+All of the tests should pass.
 
 Finally, we want to set Clang as its own compiler.
 
@@ -94,14 +85,14 @@ going on.
 
 First, we'll need to create a new directory for our tool and tell CMake
 that it exists. As this is not going to be a core clang tool, it will
-live in the ``tools/extra`` repository.
+live in the ``clang-tools-extra`` repository.
 
 .. code-block:: console
 
-      cd ~/clang-llvm/llvm/tools/clang
-      mkdir tools/extra/loop-convert
-      echo 'add_subdirectory(loop-convert)' >> tools/extra/CMakeLists.txt
-      vim tools/extra/loop-convert/CMakeLists.txt
+      cd ~/clang-llvm
+      mkdir clang-tools-extra/loop-convert
+      echo 'add_subdirectory(loop-convert)' >> clang-tools-extra/CMakeLists.txt
+      vim clang-tools-extra/loop-convert/CMakeLists.txt
 
 CMakeLists.txt should have the following contents:
 
@@ -113,6 +104,7 @@ CMakeLists.txt should have the following contents:
         LoopConvert.cpp
         )
       target_link_libraries(loop-convert
+        PRIVATE
         clangTooling
         clangBasic
         clangASTMatchers
@@ -120,7 +112,7 @@ CMakeLists.txt should have the following contents:
 
 With that done, Ninja will be able to compile our tool. Let's give it
 something to compile! Put the following into
-``tools/extra/loop-convert/LoopConvert.cpp``. A detailed explanation of
+``clang-tools-extra/loop-convert/LoopConvert.cpp``. A detailed explanation of
 why the different parts are needed can be found in the `LibTooling
 documentation <LibTooling.html>`_.
 
@@ -146,7 +138,7 @@ documentation <LibTooling.html>`_.
       static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
 
       // A help message for this specific tool can be added afterwards.
-      static cl::extrahelp MoreHelp("\nMore help text...");
+      static cl::extrahelp MoreHelp("\nMore help text...\n");
 
       int main(int argc, const char **argv) {
         CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);

docs/LibFormat.rst

@@ -44,11 +44,11 @@ two style guides are hard-coded:
 
 .. code-block:: c++
 
-  /// \brief Returns a format style complying with the LLVM coding standards:
-  /// http://llvm.org/docs/CodingStandards.html.
+  /// Returns a format style complying with the LLVM coding standards:
+  /// https://llvm.org/docs/CodingStandards.html.
   FormatStyle getLLVMStyle();
 
-  /// \brief Returns a format style complying with Google's C++ style guide:
+  /// Returns a format style complying with Google's C++ style guide:
   /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml.
   FormatStyle getGoogleStyle();
 

docs/LibTooling.rst

@@ -34,7 +34,7 @@ looked for.  Let me give you an example:
   TEST(runToolOnCode, CanSyntaxCheckCode) {
     // runToolOnCode returns whether the action was correctly run over the
     // given code.
-    EXPECT_TRUE(runToolOnCode(new clang::SyntaxOnlyAction, "class X {};"));
+    EXPECT_TRUE(runToolOnCode(std::make_unique<clang::SyntaxOnlyAction>(), "class X {};"));
   }
 
 Writing a standalone tool
@@ -130,7 +130,7 @@ version of this example tool is also checked into the clang tree at
   static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
 
   // A help message for this specific tool can be added afterwards.
-  static cl::extrahelp MoreHelp("\nMore help text...");
+  static cl::extrahelp MoreHelp("\nMore help text...\n");
 
   int main(int argc, const char **argv) {
     CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
@@ -187,8 +187,8 @@ Clang tools need their builtin headers and search for them the same way Clang
 does.  Thus, the default location to look for builtin headers is in a path
 ``$(dirname /path/to/tool)/../lib/clang/3.3/include`` relative to the tool
 binary.  This works out-of-the-box for tools running from llvm's toplevel
-binary directory after building clang-headers, or if the tool is running from
-the binary directory of a clang install next to the clang binary.
+binary directory after building clang-resource-headers, or if the tool is
+running from the binary directory of a clang install next to the clang binary.
 
 Tips: if your tool fails to find ``stddef.h`` or similar headers, call the tool
 with ``-v`` and look at the search paths it looks through.
@@ -196,6 +196,6 @@ with ``-v`` and look at the search paths it looks through.
 Linking
 ^^^^^^^
 
-For a list of libraries to link, look at one of the tools' Makefiles (for
-example `clang-check/Makefile
-<http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/clang-check/Makefile?view=markup>`_).
+For a list of libraries to link, look at one of the tools' CMake files (for
+example `clang-check/CMakeList.txt
+<https://github.com/llvm/llvm-project/blob/master/clang/tools/clang-check/CMakeLists.txt>`_).

docs/MSVCCompatibility.rst

@@ -68,9 +68,9 @@ The status of major ABI-impacting C++ features:
   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
+  https://msdn.microsoft.com/en-us/library/83cch5a6.aspx
+.. _/vm: https://msdn.microsoft.com/en-us/library/yad46a6z.aspx
+.. _pointer to a member of a virtual base class: https://llvm.org/PR15713
 
 * Debug info: :good:`Mostly complete`.  Clang emits relatively complete CodeView
   debug information if ``/Z7`` or ``/Zi`` is passed. Microsoft's link.exe will
@@ -137,7 +137,7 @@ 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
+  https://clang.llvm.org/compatibility.html#dep_lookup
 
 .. code-block:: c++
 

docs/MemorySanitizer.rst

@@ -16,7 +16,7 @@ Typical slowdown introduced by MemorySanitizer is **3x**.
 How to build
 ============
 
-Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_.
+Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_.
 
 Usage
 =====
@@ -185,7 +185,11 @@ self-built instrumented libc++ (as a replacement for libstdc++).
 Supported Platforms
 ===================
 
-MemorySanitizer is supported on Linux x86\_64/MIPS64/AArch64.
+MemorySanitizer is supported on the following OS:
+
+* Linux
+* NetBSD
+* FreeBSD
 
 Limitations
 ===========
@@ -200,6 +204,9 @@ Limitations
   non-position-independent executables, and could fail on some Linux
   kernel versions with disabled ASLR. Refer to documentation for older versions
   for more details.
+* MemorySanitizer might be incompatible with position-independent executables
+  from FreeBSD 13 but there is a check done at runtime and throws a warning
+  in this case.
 
 Current Status
 ==============

docs/Modules.rst

@@ -225,6 +225,16 @@ Command-line parameters
 ``-fprebuilt-module-path=<directory>``
   Specify the path to the prebuilt modules. If specified, we will look for modules in this directory for a given top-level module name. We don't need a module map for loading prebuilt modules in this directory and the compiler will not try to rebuild these modules. This can be specified multiple times.
 
+-cc1 Options
+~~~~~~~~~~~~
+
+``-fmodules-strict-context-hash``
+  Enables hashing of all compiler options that could impact the semantics of a
+  module in an implicit build. This includes things such as header search paths
+  and diagnostics. Using this option may lead to an excessive number of modules
+  being built if the command line arguments are not homogeneous across your
+  build.
+
 Module Semantics
 ================
 
@@ -360,7 +370,7 @@ The *module-id* should consist of only a single *identifier*, which provides the
 
 The ``explicit`` qualifier can only be applied to a submodule, i.e., a module that is nested within another module. The contents of explicit submodules are only made available when the submodule itself was explicitly named in an import declaration or was re-exported from an imported module.
 
-The ``framework`` qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on Mac OS X and iOS) is contained entirely in directory ``Name.framework``, where ``Name`` is the name of the framework (and, therefore, the name of the module). That directory has the following layout:
+The ``framework`` qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on macOS and iOS) is contained entirely in directory ``Name.framework``, where ``Name`` is the name of the framework (and, therefore, the name of the module). That directory has the following layout:
 
 .. parsed-literal::
 
@@ -411,7 +421,7 @@ A *requires-declaration* specifies the requirements that an importing translatio
   *feature*:
     ``!``:sub:`opt` *identifier*
 
-The requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects or on certain platforms. The feature list is a set of identifiers, defined below. If any of the features is not available in a given translation unit, that translation unit shall not import the module. When building a module for use by a compilation, submodules requiring unavailable features are ignored. The optional ``!`` indicates that a feature is incompatible with the module.
+The requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects, platforms, environments and target specific features. The feature list is a set of identifiers, defined below. If any of the features is not available in a given translation unit, that translation unit shall not import the module. When building a module for use by a compilation, submodules requiring unavailable features are ignored. The optional ``!`` indicates that a feature is incompatible with the module.
 
 The following features are defined:
 
@@ -466,6 +476,11 @@ tls
 *target feature*
   A specific target feature (e.g., ``sse4``, ``avx``, ``neon``) is available.
 
+*platform/os*
+  A os/platform variant (e.g. ``freebsd``, ``win32``, ``windows``, ``linux``, ``ios``, ``macos``, ``iossimulator``) is available.
+
+*environment*
+  A environment variant (e.g. ``gnu``, ``gnueabi``, ``android``, ``msvc``) is available.
 
 **Example:** The ``std`` module can be extended to also include C++ and C++11 headers using a *requires-declaration*:
 

docs/OpenCLSupport.rst

@@ -0,0 +1,47 @@
+.. raw:: html
+
+  <style type="text/css">
+    .none { background-color: #FFCCCC }
+    .partial { background-color: #FFFF99 }
+    .good { background-color: #CCFF99 }
+  </style>
+
+.. role:: none
+.. role:: partial
+.. role:: good
+
+.. contents::
+   :local:
+
+==================
+OpenCL Support
+==================
+
+Clang fully supports all OpenCL C versions from 1.1 to 2.0.
+
+Please refer to `Bugzilla
+<https://bugs.llvm.org/buglist.cgi?component=OpenCL&list_id=172679&product=clang&resolution=--->`_
+for the most up to date bug reports.
+
+
+C++ for OpenCL Implementation Status
+====================================
+
+Bugzilla bugs for this functionality are typically prefixed
+with '[C++]'.
+
+Differences to OpenCL C
+-----------------------
+
+TODO!
+
+Missing features or with limited support
+----------------------------------------
+
+- Use of ObjC blocks is disabled.
+
+- Global destructor invocation is not generated correctly.
+
+- Initialization of objects in `__constant` address spaces is not guaranteed to work.
+
+- `addrspace_cast` operator is not supported.

docs/OpenMPSupport.rst

@@ -2,67 +2,258 @@
 
   <style type="text/css">
     .none { background-color: #FFCCCC }
-    .partial { background-color: #FFFF99 }
+    .part { background-color: #FFFF99 }
     .good { background-color: #CCFF99 }
   </style>
 
 .. role:: none
-.. role:: partial
+.. role:: part
 .. role:: good
 
+.. contents::
+   :local:
+
 ==================
 OpenMP Support
 ==================
 
-Clang fully supports OpenMP 3.1 + some elements of OpenMP 4.5. Clang supports offloading to X86_64, AArch64 and PPC64[LE] devices.
-Support for Cuda devices is not ready yet.
-The status of major OpenMP 4.5 features support in Clang.
+Clang supports the following OpenMP 5.0 features (see also `OpenMP implementation details`_):
+
+* The `reduction`-based clauses in the `task` and `target`-based directives.
+
+* Support relational-op != (not-equal) as one of the canonical forms of random
+  access iterator.
+
+* Support for mapping of the lambdas in target regions.
 
-Standalone directives
-=====================
+* Parsing/sema analysis for the requires directive.
 
-* #pragma omp [for] simd: :good:`Complete`.
+* Nested declare target directives.
 
-* #pragma omp declare simd: :partial:`Partial`.  We support parsing/semantic
+* Make the `this` pointer implicitly mapped as `map(this[:1])`.
+
+* The `close` *map-type-modifier*.
+
+Clang fully supports OpenMP 4.5. Clang supports offloading to X86_64, AArch64,
+PPC64[LE] and has `basic support for Cuda devices`_.
+
+* #pragma omp declare simd: :part:`Partial`.  We support parsing/semantic
   analysis + generation of special attributes for X86 target, but still
   missing the LLVM pass for vectorization.
 
-* #pragma omp taskloop [simd]: :good:`Complete`.
+In addition, the LLVM OpenMP runtime `libomp` supports the OpenMP Tools
+Interface (OMPT) on x86, x86_64, AArch64, and PPC64 on Linux, Windows, and macOS.
+
+General improvements
+--------------------
+- New collapse clause scheme to avoid expensive remainder operations.
+  Compute loop index variables after collapsing a loop nest via the
+  collapse clause by replacing the expensive remainder operation with
+  multiplications and additions.
+
+- The default schedules for the `distribute` and `for` constructs in a
+  parallel region and in SPMD mode have changed to ensure coalesced
+  accesses. For the `distribute` construct, a static schedule is used
+  with a chunk size equal to the number of threads per team (default
+  value of threads or as specified by the `thread_limit` clause if
+  present). For the `for` construct, the schedule is static with chunk
+  size of one.
+  
+- Simplified SPMD code generation for `distribute parallel for` when
+  the new default schedules are applicable.
+
+.. _basic support for Cuda devices:
+
+Cuda devices support
+====================
+
+Directives execution modes
+--------------------------
+
+Clang code generation for target regions supports two modes: the SPMD and
+non-SPMD modes. Clang chooses one of these two modes automatically based on the
+way directives and clauses on those directives are used. The SPMD mode uses a
+simplified set of runtime functions thus increasing performance at the cost of
+supporting some OpenMP features. The non-SPMD mode is the most generic mode and
+supports all currently available OpenMP features. The compiler will always
+attempt to use the SPMD mode wherever possible. SPMD mode will not be used if:
+
+   - The target region contains an `if()` clause that refers to a `parallel`
+     directive.
+
+   - The target region contains a `parallel` directive with a `num_threads()`
+     clause.
+
+   - The target region contains user code (other than OpenMP-specific
+     directives) in between the `target` and the `parallel` directives.
 
-* #pragma omp target [enter|exit] data: :good:`Complete`.
+Data-sharing modes
+------------------
 
-* #pragma omp target update: :good:`Complete`.
+Clang supports two data-sharing models for Cuda devices: `Generic` and `Cuda`
+modes. The default mode is `Generic`. `Cuda` mode can give an additional
+performance and can be activated using the `-fopenmp-cuda-mode` flag. In
+`Generic` mode all local variables that can be shared in the parallel regions
+are stored in the global memory. In `Cuda` mode local variables are not shared
+between the threads and it is user responsibility to share the required data
+between the threads in the parallel regions.
 
-* #pragma omp target: :good:`Complete`.
+Collapsed loop nest counter
+---------------------------
 
-* #pragma omp declare target: :partial:`Partial`.  No full codegen support.
+When using the collapse clause on a loop nest the default behavior is to
+automatically extend the representation of the loop counter to 64 bits for
+the cases where the sizes of the collapsed loops are not known at compile
+time. To prevent this conservative choice and use at most 32 bits,
+compile your program with the `-fopenmp-optimistic-collapse`.
 
-* #pragma omp teams: :good:`Complete`.
 
-* #pragma omp distribute [simd]: :good:`Complete`.
+Features not supported or with limited support for Cuda devices
+---------------------------------------------------------------
 
-* #pragma omp distribute parallel for [simd]: :good:`Complete`.
+- Cancellation constructs are not supported.
 
-Combined directives
-===================
+- Doacross loop nest is not supported.
 
-* #pragma omp parallel for simd: :good:`Complete`.
+- User-defined reductions are supported only for trivial types.
 
-* #pragma omp target parallel: :good:`Complete`.
+- Nested parallelism: inner parallel regions are executed sequentially.
 
-* #pragma omp target parallel for [simd]: :good:`Complete`.
+- Static linking of libraries containing device code is not supported yet.
 
-* #pragma omp target simd: :good:`Complete`.
+- Automatic translation of math functions in target regions to device-specific
+  math functions is not implemented yet.
 
-* #pragma omp target teams: :good:`Complete`.
+- Debug information for OpenMP target regions is supported, but sometimes it may
+  be required to manually specify the address class of the inspected variables.
+  In some cases the local variables are actually allocated in the global memory,
+  but the debug info may be not aware of it.
 
-* #pragma omp teams distribute [simd]: :good:`Complete`.
 
-* #pragma omp target teams distribute [simd]: :good:`Complete`.
+.. _OpenMP implementation details:
 
-* #pragma omp teams distribute parallel for [simd]: :good:`Complete`.
+OpenMP 5.0 Implementation Details
+---------------------------------
 
-* #pragma omp target teams distribute parallel for [simd]: :good:`Complete`.
+The following table provides a quick overview over various OpenMP 5.0 features
+and their implementation status. Please contact *openmp-dev* at
+*lists.llvm.org* for more information or if you want to help with the
+implementation.
 
-Clang does not support any constructs/updates from upcoming OpenMP 5.0 except for `reduction`-based clauses in the `task` and `target`-based directives.
-In addition, the LLVM OpenMP runtime `libomp` supports the OpenMP Tools Interface (OMPT) on x86, x86_64, AArch64, and PPC64 on Linux, Windows, and mac OS.
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+|Category                      | Feature                                                      | Status                   | Reviews                                                               |
++==============================+==============================================================+==========================+=======================================================================+
+| loop extension               | support != in the canonical loop form                        | :good:`done`             | D54441                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | #pragma omp loop (directive)                                 | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | collapse imperfectly nested loop                             | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | collapse non-rectangular nested loop                         | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | C++ range-base for loop                                      | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | clause: nosimd for SIMD directives                           | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | inclusive scan extension (matching C++17 PSTL)               | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| memory mangagement           | memory allocators                                            | :good:`done`             | r341687,r357929                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| memory mangagement           | allocate directive and allocate clause                       | :good:`done`             | r355614,r335952                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| OMPD                         | OMPD interfaces                                              | :part:`not upstream`     | https://github.com/OpenMPToolsInterface/LLVM-openmp/tree/ompd-tests   |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| OMPT                         | OMPT interfaces                                              | :part:`mostly done`      |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| thread affinity extension    | thread affinity extension                                    | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | taskloop reduction                                           | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | task affinity                                                | :part:`not upstream`     |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | clause: depend on the taskwait construct                     | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | depend objects and detachable tasks                          | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | mutexinoutset dependence-type for tasks                      | :good:`done`             | D53380,D57576                                                         |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | combined taskloop constructs                                 | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | master taskloop                                              | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | parallel master taskloop                                     | :none:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | master taskloop simd                                         | :none:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | parallel master taskloop simd                                | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| SIMD extension               | atomic and critical constructs inside SIMD code              | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| SIMD extension               | SIMD nontemporal                                             | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | infer target functions from initializers                     | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | infer target variables from initializers                     | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | OMP_TARGET_OFFLOAD environment variable                      | :good:`done`             | D50522                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | support full 'defaultmap' functionality                      | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | device specific functions                                    | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: device_type                                          | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: in_reduction                                         | :none:`unclaimed`        | r308768                                                               |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | omp_get_device_num()                                         | :part:`worked on`        | D54342                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | structure mapping of references                              | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | nested target declare                                        | :good:`done`             | D51378                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | implicitly map 'this' (this[:1])                             | :good:`done`             | D55982                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | allow access to the reference count (omp_target_is_present)  | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | requires directive (unified shared memory)                   | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: unified_address, unified_shared_memory               | :part:`worked on`        | D52625,D52359                                                         |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: reverse_offload                                      | :none:`unclaimed parts`  | D52780                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: atomic_default_mem_order                             | :none:`unclaimed parts`  | D53513                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: dynamic_allocators                                   | :none:`unclaimed parts`  | D53079                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | user-defined mappers                                         | :part:`worked on`        | D56326,D58638,D58523,D58074,D60972,D59474                             |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | mapping lambda expression                                    | :good:`done`             | D51107                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: use_device_addr for target data                      | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | map(replicate) or map(local) when requires unified_shared_me | :part:`worked on`        | D55719,D55892                                                         |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | teams construct on the host device                           | :part:`worked on`        | Clang part is done, r371553.                                          |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| atomic extension             | hints for the atomic construct                               | :part:`worked on`        | D51233                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| base language                | C11 support                                                  | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| base language                | C++11/14/17 support                                          | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| base language                | lambda support                                               | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extension               | array shaping                                                | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extension               | library shutdown (omp_pause_resource[_all])                  | :none:`unclaimed parts`  | D55078                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extension               | metadirectives                                               | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extension               | conditional modifier for lastprivate clause                  | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extension               | user-defined function variants                               | :part:`worked on`        | D67294, D64095                                                        |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extensions              | pointer/reference to pointer based array reductions          | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extensions              | prevent new type definitions in clauses                      | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+

docs/PCHInternals.rst

@@ -70,7 +70,7 @@ minimizes both creation time and the time required to initially load the AST
 file.  The AST file itself contains a serialized representation of Clang's
 abstract syntax trees and supporting data structures, stored using the same
 compressed bitstream as `LLVM's bitcode file format
-<http://llvm.org/docs/BitCodeFormat.html>`_.
+<https://llvm.org/docs/BitCodeFormat.html>`_.
 
 Clang's AST files are loaded "lazily" from disk.  When an AST file is initially
 loaded, Clang reads only a small amount of data from the AST file to establish
@@ -134,7 +134,7 @@ only contain the serialized AST.
 The ``clangast`` section is organized into several different blocks, each of
 which contains the serialized representation of a part of Clang's internal
 representation.  Each of the blocks corresponds to either a block or a record
-within `LLVM's bitstream format <http://llvm.org/docs/BitCodeFormat.html>`_.
+within `LLVM's bitstream format <https://llvm.org/docs/BitCodeFormat.html>`_.
 The contents of each of these logical blocks are described below.
 
 .. image:: PCHLayout.png
@@ -142,7 +142,7 @@ The contents of each of these logical blocks are described below.
 The ``llvm-objdump`` utility provides a ``-raw-clang-ast`` option to extract the
 binary contents of the AST section from an object file container.
 
-The `llvm-bcanalyzer <http://llvm.org/docs/CommandGuide/llvm-bcanalyzer.html>`_
+The `llvm-bcanalyzer <https://llvm.org/docs/CommandGuide/llvm-bcanalyzer.html>`_
 utility can be used to examine the actual structure of the bitstream for the AST
 section.  This information can be used both to help understand the structure of
 the AST section and to isolate areas where the AST representation can still be
@@ -332,7 +332,7 @@ expression is stored as a separate record (which keeps most records to a fixed
 size).  Within the AST file, the subexpressions of an expression are stored, in
 reverse order, prior to the expression that owns those expression, using a form
 of `Reverse Polish Notation
-<http://en.wikipedia.org/wiki/Reverse_Polish_notation>`_.  For example, an
+<https://en.wikipedia.org/wiki/Reverse_Polish_notation>`_. For example, an
 expression ``3 - 4 + 5`` would be represented as follows:
 
 +-----------------------+

docs/PTHInternals.rst

@@ -1,163 +0,0 @@
-==========================
-Pretokenized Headers (PTH)
-==========================
-
-This document first describes the low-level interface for using PTH and
-then briefly elaborates on its design and implementation. If you are
-interested in the end-user view, please see the :ref:`User's Manual
-<usersmanual-precompiled-headers>`.
-
-Using Pretokenized Headers with ``clang`` (Low-level Interface)
-===============================================================
-
-The Clang compiler frontend, ``clang -cc1``, supports three command line
-options for generating and using PTH files.
-
-To generate PTH files using ``clang -cc1``, use the option ``-emit-pth``:
-
-.. code-block:: console
-
-  $ clang -cc1 test.h -emit-pth -o test.h.pth
-
-This option is transparently used by ``clang`` when generating PTH
-files. Similarly, PTH files can be used as prefix headers using the
-``-include-pth`` option:
-
-.. code-block:: console
-
-  $ clang -cc1 -include-pth test.h.pth test.c -o test.s
-
-Alternatively, Clang's PTH files can be used as a raw "token-cache" (or
-"content" cache) of the source included by the original header file.
-This means that the contents of the PTH file are searched as substitutes
-for *any* source files that are used by ``clang -cc1`` to process a
-source file. This is done by specifying the ``-token-cache`` option:
-
-.. code-block:: console
-
-  $ cat test.h
-  #include <stdio.h>
-  $ clang -cc1 -emit-pth test.h -o test.h.pth
-  $ cat test.c
-  #include "test.h"
-  $ clang -cc1 test.c -o test -token-cache test.h.pth
-
-In this example the contents of ``stdio.h`` (and the files it includes)
-will be retrieved from ``test.h.pth``, as the PTH file is being used in
-this case as a raw cache of the contents of ``test.h``. This is a
-low-level interface used to both implement the high-level PTH interface
-as well as to provide alternative means to use PTH-style caching.
-
-PTH Design and Implementation
-=============================
-
-Unlike GCC's precompiled headers, which cache the full ASTs and
-preprocessor state of a header file, Clang's pretokenized header files
-mainly cache the raw lexer *tokens* that are needed to segment the
-stream of characters in a source file into keywords, identifiers, and
-operators. Consequently, PTH serves to mainly directly speed up the
-lexing and preprocessing of a source file, while parsing and
-type-checking must be completely redone every time a PTH file is used.
-
-Basic Design Tradeoffs
-----------------------
-
-In the long term there are plans to provide an alternate PCH
-implementation for Clang that also caches the work for parsing and type
-checking the contents of header files. The current implementation of PCH
-in Clang as pretokenized header files was motivated by the following
-factors:
-
-**Language independence**
-   PTH files work with any language that
-   Clang's lexer can handle, including C, Objective-C, and (in the early
-   stages) C++. This means development on language features at the
-   parsing level or above (which is basically almost all interesting
-   pieces) does not require PTH to be modified.
-
-**Simple design**
-   Relatively speaking, PTH has a simple design and
-   implementation, making it easy to test. Further, because the
-   machinery for PTH resides at the lower-levels of the Clang library
-   stack it is fairly straightforward to profile and optimize.
-
-Further, compared to GCC's PCH implementation (which is the dominate
-precompiled header file implementation that Clang can be directly
-compared against) the PTH design in Clang yields several attractive
-features:
-
-**Architecture independence**
-   In contrast to GCC's PCH files (and
-   those of several other compilers), Clang's PTH files are architecture
-   independent, requiring only a single PTH file when building a
-   program for multiple architectures.
-
-   For example, on Mac OS X one may wish to compile a "universal binary"
-   that runs on PowerPC, 32-bit Intel (i386), and 64-bit Intel
-   architectures. In contrast, GCC requires a PCH file for each
-   architecture, as the definitions of types in the AST are
-   architecture-specific. Since a Clang PTH file essentially represents
-   a lexical cache of header files, a single PTH file can be safely used
-   when compiling for multiple architectures. This can also reduce
-   compile times because only a single PTH file needs to be generated
-   during a build instead of several.
-
-**Reduced memory pressure**
-   Similar to GCC, Clang reads PTH files
-   via the use of memory mapping (i.e., ``mmap``). Clang, however,
-   memory maps PTH files as read-only, meaning that multiple invocations
-   of ``clang -cc1`` can share the same pages in memory from a
-   memory-mapped PTH file. In comparison, GCC also memory maps its PCH
-   files but also modifies those pages in memory, incurring the
-   copy-on-write costs. The read-only nature of PTH can greatly reduce
-   memory pressure for builds involving multiple cores, thus improving
-   overall scalability.
-
-**Fast generation**
-   PTH files can be generated in a small fraction
-   of the time needed to generate GCC's PCH files. Since PTH/PCH
-   generation is a serial operation that typically blocks progress
-   during a build, faster generation time leads to improved processor
-   utilization with parallel builds on multicore machines.
-
-Despite these strengths, PTH's simple design suffers some algorithmic
-handicaps compared to other PCH strategies such as those used by GCC.
-While PTH can greatly speed up the processing time of a header file, the
-amount of work required to process a header file is still roughly linear
-in the size of the header file. In contrast, the amount of work done by
-GCC to process a precompiled header is (theoretically) constant (the
-ASTs for the header are literally memory mapped into the compiler). This
-means that only the pieces of the header file that are referenced by the
-source file including the header are the only ones the compiler needs to
-process during actual compilation. While GCC's particular implementation
-of PCH mitigates some of these algorithmic strengths via the use of
-copy-on-write pages, the approach itself can fundamentally dominate at
-an algorithmic level, especially when one considers header files of
-arbitrary size.
-
-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
---------------------------
-
-While the main optimization employed by PTH is to reduce lexing time of
-header files by caching pre-lexed tokens, PTH also employs several other
-optimizations to speed up the processing of header files:
-
--  ``stat`` caching: PTH files cache information obtained via calls to
-   ``stat`` that ``clang -cc1`` uses to resolve which files are included
-   by ``#include`` directives. This greatly reduces the overhead
-   involved in context-switching to the kernel to resolve included
-   files.
-
--  Fast skipping of ``#ifdef`` ... ``#endif`` chains: PTH files
-   record the basic structure of nested preprocessor blocks. When the
-   condition of the preprocessor block is false, all of its tokens are
-   immediately skipped instead of requiring them to be handled by
-   Clang's preprocessor.
-
-

docs/RAVFrontendAction.rst

@@ -128,7 +128,7 @@ locations:
         if (Declaration->getQualifiedNameAsString() == "n::m::C") {
           // getFullLoc uses the ASTContext's SourceManager to resolve the source
           // location and break it up into its line and column parts.
-          FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+          FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getBeginLoc());
           if (FullLocation.isValid())
             llvm::outs() << "Found declaration at "
                          << FullLocation.getSpellingLineNumber() << ":"
@@ -160,7 +160,7 @@ Now we can combine all of the above into a small example program:
 
         bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
           if (Declaration->getQualifiedNameAsString() == "n::m::C") {
-            FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+            FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getBeginLoc());
             if (FullLocation.isValid())
               llvm::outs() << "Found declaration at "
                            << FullLocation.getSpellingLineNumber() << ":"
@@ -196,7 +196,7 @@ Now we can combine all of the above into a small example program:
 
       int main(int argc, char **argv) {
         if (argc > 1) {
-          clang::tooling::runToolOnCode(new FindNamedClassAction, argv[1]);
+          clang::tooling::runToolOnCode(std::make_unique<FindNamedClassAction>(), argv[1]);
         }
       }
 

docs/ReleaseNotes.rst

@@ -1,42 +1,42 @@
-=======================================
-Clang 7.0.0 (In-Progress) Release Notes
-=======================================
+========================================
+Clang 10.0.0 (In-Progress) Release Notes
+========================================
 
 .. contents::
    :local:
    :depth: 2
 
-Written by the `LLVM Team <http://llvm.org/>`_
+Written by the `LLVM Team <https://llvm.org/>`_
 
 .. warning::
 
-   These are in-progress notes for the upcoming Clang 7 release.
+   These are in-progress notes for the upcoming Clang 10 release.
    Release notes for previous releases can be found on
-   `the Download Page <http://releases.llvm.org/download.html>`_.
+   `the Download Page <https://releases.llvm.org/download.html>`_.
 
 Introduction
 ============
 
 This document contains the release notes for the Clang C/C++/Objective-C
-frontend, part of the LLVM Compiler Infrastructure, release 7.0.0. Here we
+frontend, part of the LLVM Compiler Infrastructure, release 10.0.0. 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
-documentation <http://llvm.org/docs/ReleaseNotes.html>`_. All LLVM
+documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM
 releases may be downloaded from the `LLVM releases web
-site <http://llvm.org/releases/>`_.
+site <https://llvm.org/releases/>`_.
 
 For more information about Clang or LLVM, including information about the
-latest release, please see the `Clang Web Site <http://clang.llvm.org>`_ or the
-`LLVM Web Site <http://llvm.org>`_.
+latest release, please see the `Clang Web Site <https://clang.llvm.org>`_ or the
+`LLVM Web Site <https://llvm.org>`_.
 
 Note that if you are reading this file from a Subversion checkout or the
 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 <http://llvm.org/releases/>`_.
+see the `releases page <https://llvm.org/releases/>`_.
 
-What's New in Clang 7.0.0?
-==========================
+What's New in Clang 10.0.0?
+===========================
 
 Some of the major new features and improvements to Clang are listed
 here. Generic improvements to Clang as a whole or to its underlying
@@ -46,53 +46,52 @@ sections with improvements to Clang's support for those languages.
 Major New Features
 ------------------
 
--  ...
+- ...
 
 Improvements to Clang's diagnostics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- ``-Wc++98-compat-extra-semi`` is a new flag, which was previously inseparable
-  from ``-Wc++98-compat-pedantic``. The latter still controls the new flag.
-
-- ``-Wextra-semi`` now also controls ``-Wc++98-compat-extra-semi``.
-  Please do note that if you pass ``-Wno-c++98-compat-pedantic``, it implies
-  ``-Wno-c++98-compat-extra-semi``, so if you want that diagnostic, you need
-  to explicitly re-enable it (e.g. by appending ``-Wextra-semi``).
-
-- ``-Wself-assign`` and ``-Wself-assign-field`` were extended to diagnose
-  self-assignment operations using overloaded operators (i.e. classes).
-  If you are doing such an assignment intentionally, e.g. in a unit test for
-  a data structure, the first warning can be disabled by passing
-  ``-Wno-self-assign-overloaded``, also the warning can be suppressed by adding
-  ``*&`` to the right-hand side or casting it to the appropriate reference type.
+- -Wtautological-overlap-compare will warn on negative numbers and non-int
+  types.
+- -Wtautological-compare for self comparisons and
+  -Wtautological-overlap-compare will now look through member and array
+  access to determine if two operand expressions are the same.
+- -Wtautological-bitwise-compare is a new warning group.  This group has the
+  current warning which diagnoses the tautological comparison of a bitwise
+  operation and a constant.  The group also has the new warning which diagnoses
+  when a bitwise-or with a non-negative value is converted to a bool, since
+  that bool will always be true.
+- -Wbitwise-conditional-parentheses will warn on operator precedence issues
+  when mixing bitwise-and (&) and bitwise-or (|) operator with the
+  conditional operator (?:).
 
 Non-comprehensive list of changes in this release
 -------------------------------------------------
 
-- Clang binary and libraries have been renamed from 7.0 to 7.
-  For example, the ``clang`` binary will be called ``clang-7``
-  instead of ``clang-7.0``.
-
-- Clang implements a collection of recent fixes to the C++ standard's definition
-  of "standard-layout". In particular, a class is only considered to be
-  standard-layout if all base classes and the first data member (or bit-field)
-  can be laid out at offset zero.
-
-- ...
+* In both C and C++ (C17 ``6.5.6p8``, C++ ``[expr.add]``), pointer arithmetic is
+  only permitted within arrays. In particular, the behavior of a program is not
+  defined if it adds a non-zero offset (or in C, any offset) to a null pointer,
+  or if it forms a null pointer by subtracting an integer from a non-null
+  pointer, and the LLVM optimizer now uses those guarantees for transformations.
+  This may lead to unintended behavior in code that performs these operations.
+  The Undefined Behavior Sanitizer ``-fsanitize=pointer-overflow`` check has
+  been extended to detect these cases, so that code relying on them can be
+  detected and fixed.
+
+- For X86 target, -march=skylake-avx512, -march=icelake-client,
+  -march=icelake-server, -march=cascadelake, -march=cooperlake will default to
+  not using 512-bit zmm registers in vectorized code unless 512-bit intrinsics
+  are used in the source code. 512-bit operations are known to cause the CPUs
+  to run at a lower frequency which can impact performance. This behavior can be
+  changed by passing -mprefer-vector-width=512 on the command line.
 
 New Compiler Flags
 ------------------
 
-- :option:`-ffp-cast-overflow-workaround` and
-  :option:`-fno-fp-cast-overflow-workaround`
-  enable (disable) a workaround for code that casts floating-point values to
-  integers and back to floating-point. If the floating-point value is not
-  representable in the intermediate integer type, the code is incorrect
-  according to the language standard. This flag will attempt to generate code
-  as if the result of an overflowing conversion matches the overflowing behavior
-  of a target's native float-to-int conversion instructions.
-
-- ...
+- The -fgnuc-version= flag now controls the value of ``__GNUC__`` and related
+  macros. This flag does not enable or disable any GCC extensions implemented in
+  Clang. Setting the version to zero causes Clang to leave ``__GNUC__`` and
+  other GNU-namespaced macros, such as ``__GXX_WEAK__``, undefined.
 
 Deprecated Compiler Flags
 -------------------------
@@ -100,40 +99,41 @@ Deprecated Compiler Flags
 The following options are deprecated and ignored. They will be removed in
 future versions of Clang.
 
+- -mmpx used to enable the __MPX__ preprocessor define for the Intel MPX
+  instructions. There were no MPX intrinsics.
+- -mno-mpx used to disable -mmpx and is the default behavior.
+
 - ...
 
 Modified Compiler Flags
 -----------------------
 
-- Before Clang 7, we prepended the `#` character to the `--autocomplete`
-  argument to enable cc1 flags. For example, when the `-cc1` or `-Xclang` flag
-  is in the :program:`clang` invocation, the shell executed
-  `clang --autocomplete=#-<flag to be completed>`. Clang 7 now requires the
-  whole invocation including all flags to be passed to the `--autocomplete` like
-  this: `clang --autocomplete=-cc1,-xc++,-fsyn`.
+- ...
 
 New Pragmas in Clang
------------------------
-
-Clang now supports the ...
+--------------------
 
+- ...
 
 Attribute Changes in Clang
 --------------------------
 
-- Clang now supports function multiversioning with attribute 'target' on ELF
-  based x86/x86-64 environments by using indirect functions. This implementation
-  has a few minor limitations over the GCC implementation for the sake of AST
-  sanity, however it is otherwise compatible with existing code using this
-  feature for GCC. Consult the documentation for the target attribute for more
-  information.
-
 - ...
 
 Windows Support
 ---------------
 
-Clang's support for building native Windows programs ...
+- Previous Clang versions contained a work-around to avoid an issue with the
+  standard library headers in Visual Studio 2019 versions prior to 16.3. This
+  work-around has now been removed, and users of Visual Studio 2019 are
+  encouraged to upgrade to 16.3 or later, otherwise they may see link errors as
+  below:
+
+  .. code-block:: console
+
+    error LNK2005: "bool const std::_Is_integral<int>" (??$_Is_integral@H@std@@3_NB) already defined
+
+
 
 
 C Language Changes in Clang
@@ -141,8 +141,6 @@ C Language Changes in Clang
 
 - ...
 
-...
-
 C11 Feature Support
 ^^^^^^^^^^^^^^^^^^^
 
@@ -151,7 +149,10 @@ C11 Feature Support
 C++ Language Changes in Clang
 -----------------------------
 
-- ...
+- The behaviour of the `gnu_inline` attribute now matches GCC, for cases
+  where used without the `extern` keyword. As this is a change compared to
+  how it behaved in previous Clang versions, a warning is emitted for this
+  combination.
 
 C++1z Feature Support
 ^^^^^^^^^^^^^^^^^^^^^
@@ -161,38 +162,66 @@ C++1z Feature Support
 Objective-C Language Changes in Clang
 -------------------------------------
 
-...
+- ...
 
 OpenCL C Language Changes in Clang
 ----------------------------------
 
 ...
 
+ABI Changes in Clang
+--------------------
+
+- gcc passes vectors of __int128 in memory on X86-64. Clang historically
+  broke the vectors into multiple scalars using two 64-bit values for each
+  element. Clang now matches the gcc behavior on Linux and NetBSD. You can
+  switch back to old API behavior with flag: -fclang-abi-compat=9.0.
+
 OpenMP Support in Clang
-----------------------------------
+-----------------------
 
 - ...
 
 CUDA Support in Clang
 ---------------------
 
-- Clang will now try to locate the CUDA installation next to :program:`ptxas`
-  in the `PATH` environment variable. This behavior can be turned off by passing
-  the new flag `--cuda-path-ignore-env`.
-
-- Clang now supports generating object files with relocatable device code. This
-  feature needs to be enabled with `-fcuda-rdc` and my result in performance
-  penalties compared to whole program compilation. Please note that NVIDIA's
-  :program:`nvcc` must be used for linking.
+- ...
 
 Internal API Changes
 --------------------
 
-These are major API changes that have happened since the 6.0.0 release of
+These are major API changes that have happened since the 9.0.0 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.
 
--  ...
+- libTooling APIs that transfer ownership of `FrontendAction` objects now pass
+  them by `unique_ptr`, making the ownership transfer obvious in the type
+  system. `FrontendActionFactory::create()` now returns a
+  `unique_ptr<FrontendAction>`. `runToolOnCode`, `runToolOnCodeWithArgs`,
+  `ToolInvocation::ToolInvocation()` now take a `unique_ptr<FrontendAction>`.
+
+Build System Changes
+--------------------
+
+These are major changes to the build system that have happened since the 9.0.0
+release of Clang. Users of the build system should adjust accordingly.
+
+- In 8.0.0 and below, the install-clang-headers target would install clang's
+  resource directory headers. This installation is now performed by the
+  install-clang-resource-headers target. Users of the old install-clang-headers
+  target should switch to the new install-clang-resource-headers target. The
+  install-clang-headers target now installs clang's API headers (corresponding
+  to its libraries), which is consistent with the install-llvm-headers target.
+
+- In 9.0.0 and later Clang added a new target, clang-cpp, which generates a
+  shared library comprised of all the clang component libraries and exporting
+  the clang C++ APIs. Additionally the build system gained the new
+  "CLANG_LINK_CLANG_DYLIB" option, which defaults Off, and when set to On, will
+  force clang (and clang-based tools) to link the clang-cpp library instead of
+  statically linking clang's components. This option will reduce the size of
+  binary distributions at the expense of compiler performance.
+
+- ...
 
 AST Matchers
 ------------
@@ -202,25 +231,71 @@ AST Matchers
 clang-format
 ------------
 
-- ...
+- The ``Standard`` style option specifies which version of C++ should be used
+  when parsing and formatting C++ code. The set of allowed values has changed:
+
+  - ``Latest`` will always enable new C++ language features.
+  - ``c++03``, ``c++11``, ``c++14``, ``c++17``, ``c++20`` will pin to exactly
+    that language version.
+  - ``Auto`` is the default and detects style from the code (this is unchanged).
+
+  The previous values of ``Cpp03`` and ``Cpp11`` are deprecated. Note that
+  ``Cpp11`` is treated as ``Latest``, as this was always clang-format's behavior.
+  (One motivation for this change is the new name describes the behavior better).
 
 libclang
 --------
 
-...
+- ...
 
 
 Static Analyzer
 ---------------
 
+- The Clang analyzer checker ``DeadStores`` gets a new option called
+  ``WarnForDeadNestedAssignments`` to detect nested dead assignments
+  (enabled by default).
 - ...
 
-...
+.. _release-notes-ubsan:
 
 Undefined Behavior Sanitizer (UBSan)
 ------------------------------------
 
-* ...
+- * The ``pointer-overflow`` check was extended added to catch the cases where
+    a non-zero offset is applied to a null pointer, or the result of
+    applying the offset is a null pointer.
+
+    .. code-block:: c++
+
+      #include <cstdint> // for intptr_t
+
+      static char *getelementpointer_inbounds(char *base, unsigned long offset) {
+        // Potentially UB.
+        return base + offset;
+      }
+
+      char *getelementpointer_unsafe(char *base, unsigned long offset) {
+        // Always apply offset. UB if base is ``nullptr`` and ``offset`` is not
+        // zero, or if ``base`` is non-``nullptr`` and ``offset`` is
+        // ``-reinterpret_cast<intptr_t>(base)``.
+        return getelementpointer_inbounds(base, offset);
+      }
+
+      char *getelementpointer_safe(char *base, unsigned long offset) {
+        // Cast pointer to integer, perform usual arithmetic addition,
+        // and cast to pointer. This is legal.
+        char *computed =
+            reinterpret_cast<char *>(reinterpret_cast<intptr_t>(base) + offset);
+        // If either the pointer becomes non-``nullptr``, or becomes
+        // ``nullptr``, we must use ``computed`` result.
+        if (((base == nullptr) && (computed != nullptr)) ||
+            ((base != nullptr) && (computed == nullptr)))
+          return computed;
+        // Else we can use ``getelementpointer_inbounds()``.
+        return getelementpointer_inbounds(base, offset);
+      }
+
 
 Core Analysis Improvements
 ==========================
@@ -246,7 +321,7 @@ Additional Information
 ======================
 
 A wide variety of additional information is available on the `Clang web
-page <http://clang.llvm.org/>`_. The web page contains versions of the
+page <https://clang.llvm.org/>`_. The web page contains versions of the
 API documentation which are up-to-date with the Subversion version of
 the source code. You can access versions of these documents specific to
 this release by going into the "``clang/docs/``" directory in the Clang
@@ -254,4 +329,4 @@ tree.
 
 If you have any questions or comments about Clang, please feel free to
 contact us via the `mailing
-list <http://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
+list <https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.

docs/SafeStack.rst

@@ -18,14 +18,14 @@ buffer overflows on the unsafe stack cannot be used to overwrite anything
 on the safe stack.
 
 SafeStack is a part of the `Code-Pointer Integrity (CPI) Project
-<http://dslab.epfl.ch/proj/cpi/>`_.
+<https://dslab.epfl.ch/proj/cpi/>`_.
 
 Performance
 -----------
 
 The performance overhead of the SafeStack instrumentation is less than 0.1% on
 average across a variety of benchmarks (see the `Code-Pointer Integrity
-<http://dslab.epfl.ch/pubs/cpi.pdf>`__ paper for details). This is mainly
+<https://dslab.epfl.ch/pubs/cpi.pdf>`__ paper for details). This is mainly
 because most small functions do not have any variables that require the unsafe
 stack and, hence, do not need unsafe stack frames to be created. The cost of
 creating unsafe stack frames for large functions is amortized by the cost of
@@ -84,9 +84,9 @@ Known security limitations
 A complete protection against control-flow hijack attacks requires combining
 SafeStack with another mechanism that enforces the integrity of code pointers
 that are stored on the heap or the unsafe stack, such as `CPI
-<http://dslab.epfl.ch/proj/cpi/>`_, or a forward-edge control flow integrity
+<https://dslab.epfl.ch/proj/cpi/>`_, or a forward-edge control flow integrity
 mechanism that enforces correct calling conventions at indirect call sites,
-such as `IFCC <http://research.google.com/pubs/archive/42808.pdf>`_ with arity
+such as `IFCC <https://research.google.com/pubs/archive/42808.pdf>`_ with arity
 checks. Clang has control-flow integrity protection scheme for :doc:`C++ virtual
 calls <ControlFlowIntegrity>`, but not non-virtual indirect calls. With
 SafeStack alone, an attacker can overwrite a function pointer on the heap or
@@ -106,7 +106,7 @@ prevented by adjusting such functions to either encrypt the stack pointer when
 storing it in the heap (as already done e.g., by ``setjmp``/``longjmp``
 implementation in glibc), or store it in a safe region instead.
 
-The `CPI paper <http://dslab.epfl.ch/pubs/cpi.pdf>`_ describes two alternative,
+The `CPI paper <https://dslab.epfl.ch/pubs/cpi.pdf>`_ describes two alternative,
 stronger safe stack protection mechanisms, that rely on software fault
 isolation, or hardware segmentation (as available on x86-32 and some x86-64
 CPUs).
@@ -126,7 +126,7 @@ and link command lines.
 Supported Platforms
 -------------------
 
-SafeStack was tested on Linux, FreeBSD and MacOSX.
+SafeStack was tested on Linux, NetBSD, FreeBSD and macOS.
 
 Low-level API
 -------------
@@ -165,23 +165,35 @@ never be stored on the heap, as it would leak the location of the SafeStack.
 This builtin function returns current unsafe stack pointer of the current
 thread.
 
+``__builtin___get_unsafe_stack_bottom()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This builtin function returns a pointer to the bottom of the unsafe stack of the
+current thread.
+
+``__builtin___get_unsafe_stack_top()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This builtin function returns a pointer to the top of the unsafe stack of the
+current thread.
+
 ``__builtin___get_unsafe_stack_start()``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This builtin function returns a pointer to the start of the unsafe stack of the
-current thread.
+Deprecated: This builtin function is an alias for
+``__builtin___get_unsafe_stack_bottom()``.
 
 Design
 ======
 
-Please refer to the `Code-Pointer Integrity <http://dslab.epfl.ch/proj/cpi/>`__
+Please refer to the `Code-Pointer Integrity <https://dslab.epfl.ch/proj/cpi/>`__
 project page for more information about the design of the SafeStack and its
 related technologies.
 
 setjmp and exception handling
 -----------------------------
 
-The `OSDI'14 paper <http://dslab.epfl.ch/pubs/cpi.pdf>`_ mentions that
+The `OSDI'14 paper <https://dslab.epfl.ch/pubs/cpi.pdf>`_ mentions that
 on Linux the instrumentation pass finds calls to setjmp or functions that
 may throw an exception, and inserts required instrumentation at their call
 sites. Specifically, the instrumentation pass saves the shadow stack pointer
@@ -192,7 +204,7 @@ in the function ``SafeStack::createStackRestorePoints``.
 Publications
 ------------
 
-`Code-Pointer Integrity <http://dslab.epfl.ch/pubs/cpi.pdf>`__.
+`Code-Pointer Integrity <https://dslab.epfl.ch/pubs/cpi.pdf>`__.
 Volodymyr Kuznetsov, Laszlo Szekeres, Mathias Payer, George Candea, R. Sekar, Dawn Song.
 USENIX Symposium on Operating Systems Design and Implementation
 (`OSDI <https://www.usenix.org/conference/osdi14>`_), Broomfield, CO, October 2014

docs/SanitizerCoverage.rst

@@ -144,6 +144,11 @@ PC-Table
 
 **Experimental, may change or disappear in future**
 
+**Note:** this instrumentation might be incompatible with dead code stripping
+(``-Wl,-gc-sections``) for linkers other than LLD, thus resulting in a
+significant binary size overhead. For more information, see
+`Bug 34636 <https://bugs.llvm.org/show_bug.cgi?id=34636>`_.
+
 With ``-fsanitize-coverage=pc-table`` the compiler will create a table of
 instrumented PCs. Requires either ``-fsanitize-coverage=inline-8bit-counters`` or
 ``-fsanitize-coverage=trace-pc-guard``.
@@ -222,9 +227,9 @@ It contains 3 basic blocks, let's name them A, B, C:
 If blocks A, B, and C are all covered we know for certain that the edges A=>B
 and B=>C were executed, but we still don't know if the edge A=>C was executed.
 Such edges of control flow graph are called
-`critical <http://en.wikipedia.org/wiki/Control_flow_graph#Special_edges>`_. The
-edge-level coverage simply splits all critical
-edges by introducing new dummy blocks and then instruments those blocks:
+`critical <https://en.wikipedia.org/wiki/Control_flow_graph#Special_edges>`_.
+The edge-level coverage simply splits all critical edges by introducing new
+dummy blocks and then instruments those blocks:
 
 .. code-block:: none
 
@@ -245,9 +250,12 @@ around comparison instructions and switch statements.
 Similarly, with ``-fsanitize-coverage=trace-div`` the compiler will instrument
 integer division instructions (to capture the right argument of division)
 and with  ``-fsanitize-coverage=trace-gep`` --
-the `LLVM GEP instructions <http://llvm.org/docs/GetElementPtr.html>`_
+the `LLVM GEP instructions <https://llvm.org/docs/GetElementPtr.html>`_
 (to capture array indices).
 
+Unless ``no-prune`` option is provided, some of the comparison instructions
+will not be instrumented.
+
 .. code-block:: c++
 
   // Called before a comparison instruction.

docs/SanitizerStats.rst

@@ -56,7 +56,7 @@ Example:
         10   A a;
         11   g(&a);
         12 }
-    $ clang++ -fsanitize=cfi -flto -fuse-ld=gold vcall.cc -fsanitize-stats -g
+    $ clang++ -fsanitize=cfi -fvisibility=hidden -flto -fuse-ld=gold vcall.cc -fsanitize-stats -g
     $ SANITIZER_STATS_PATH=a.stats ./a.out
     $ sanstats a.stats
     vcall.cc:6 _Z1gP1A cfi-vcall 1

docs/ShadowCallStack.rst

@@ -8,28 +8,43 @@ ShadowCallStack
 Introduction
 ============
 
-ShadowCallStack is an **experimental** instrumentation pass, currently only
-implemented for x86_64 and aarch64, that protects programs against return
-address overwrites (e.g. stack buffer overflows.) It works by saving a
-function's return address to a separately allocated 'shadow call stack'
-in the function prolog and checking the return address on the stack against
-the shadow call stack in the function epilog.
+ShadowCallStack is an instrumentation pass, currently only implemented for
+aarch64, that protects programs against return address overwrites
+(e.g. stack buffer overflows.) It works by saving a function's return address
+to a separately allocated 'shadow call stack' in the function prolog in
+non-leaf functions and loading the return address from the shadow call stack
+in the function epilog. The return address is also stored on the regular stack
+for compatibility with unwinders, but is otherwise unused.
+
+The aarch64 implementation is considered production ready, and
+an `implementation of the runtime`_ has been added to Android's libc
+(bionic). An x86_64 implementation was evaluated using Chromium and was found
+to have critical performance and security deficiencies--it was removed in
+LLVM 9.0. Details on the x86_64 implementation can be found in the
+`Clang 7.0.1 documentation`_.
+
+.. _`implementation of the runtime`: https://android.googlesource.com/platform/bionic/+/808d176e7e0dd727c7f929622ec017f6e065c582/libc/bionic/pthread_create.cpp#128
+.. _`Clang 7.0.1 documentation`: https://releases.llvm.org/7.0.1/tools/clang/docs/ShadowCallStack.html
 
 Comparison
 ----------
 
-To optimize for memory consumption and cache locality, the shadow call stack
-stores an index followed by an array of return addresses. This is in contrast
-to other schemes, like :doc:`SafeStack`, that mirror the entire stack and
-trade-off consuming more memory for shorter function prologs and epilogs with
-fewer memory accesses. Similarly, `Return Flow Guard`_ consumes more memory with
-shorter function prologs and epilogs than ShadowCallStack but suffers from the
-same race conditions (see `Security`_). Intel `Control-flow Enforcement Technology`_
-(CET) is a proposed hardware extension that would add native support to
-use a shadow stack to store/check return addresses at call/return time. It
-would not suffer from race conditions at calls and returns and not incur the
-overhead of function instrumentation, but it does require operating system
-support.
+To optimize for memory consumption and cache locality, the shadow call
+stack stores only an array of return addresses. This is in contrast to other
+schemes, like :doc:`SafeStack`, that mirror the entire stack and trade-off
+consuming more memory for shorter function prologs and epilogs with fewer
+memory accesses.
+
+`Return Flow Guard`_ is a pure software implementation of shadow call stacks
+on x86_64. Like the previous implementation of ShadowCallStack on x86_64, it is
+inherently racy due to the architecture's use of the stack for calls and
+returns.
+
+Intel `Control-flow Enforcement Technology`_ (CET) is a proposed hardware
+extension that would add native support to use a shadow stack to store/check
+return addresses at call/return time. Being a hardware implementation, it
+would not suffer from race conditions and would not incur the overhead of
+function instrumentation, but it does require operating system support.
 
 .. _`Return Flow Guard`: https://xlab.tencent.com/en/2016/11/02/return-flow-guard/
 .. _`Control-flow Enforcement Technology`: https://software.intel.com/sites/default/files/managed/4d/2a/control-flow-enforcement-technology-preview.pdf
@@ -37,57 +52,96 @@ support.
 Compatibility
 -------------
 
-ShadowCallStack currently only supports x86_64 and aarch64. A runtime is not
-currently provided in compiler-rt so one must be provided by the compiled
-application.
-
-On aarch64, the instrumentation makes use of the platform register ``x18``.
-On some platforms, ``x18`` is reserved, and on others, it is designated as
-a scratch register.  This generally means that any code that may run on the
-same thread as code compiled with ShadowCallStack must either target one
-of the platforms whose ABI reserves ``x18`` (currently Darwin, Fuchsia and
-Windows) or be compiled with the flag ``-ffixed-x18``.
+A runtime is not provided in compiler-rt so one must be provided by the
+compiled application or the operating system. Integrating the runtime into
+the operating system should be preferred since otherwise all thread creation
+and destruction would need to be intercepted by the application.
+
+The instrumentation makes use of the platform register ``x18``.  On some
+platforms, ``x18`` is reserved, and on others, it is designated as a scratch
+register.  This generally means that any code that may run on the same thread
+as code compiled with ShadowCallStack must either target one of the platforms
+whose ABI reserves ``x18`` (currently Android, Darwin, Fuchsia and Windows)
+or be compiled with the flag ``-ffixed-x18``. If absolutely necessary, code
+compiled without ``-ffixed-x18`` may be run on the same thread as code that
+uses ShadowCallStack by saving the register value temporarily on the stack
+(`example in Android`_) but this should be done with care since it risks
+leaking the shadow call stack address.
+
+.. _`example in Android`: https://android-review.googlesource.com/c/platform/frameworks/base/+/803717
+
+Because of the use of register ``x18``, the ShadowCallStack feature is
+incompatible with any other feature that may use ``x18``. However, there
+is no inherent reason why ShadowCallStack needs to use register ``x18``
+specifically; in principle, a platform could choose to reserve and use another
+register for ShadowCallStack, but this would be incompatible with the AAPCS64.
+
+Special unwind information is required on functions that are compiled
+with ShadowCallStack and that may be unwound, i.e. functions compiled with
+``-fexceptions`` (which is the default in C++). Some unwinders (such as the
+libgcc 4.9 unwinder) do not understand this unwind info and will segfault
+when encountering it. LLVM libunwind processes this unwind info correctly,
+however. This means that if exceptions are used together with ShadowCallStack,
+the program must use a compatible unwinder.
 
 Security
 ========
 
 ShadowCallStack is intended to be a stronger alternative to
 ``-fstack-protector``. It protects from non-linear overflows and arbitrary
-memory writes to the return address slot; however, similarly to
-``-fstack-protector`` this protection suffers from race conditions because of
-the call-return semantics on x86_64. There is a short race between the call
-instruction and the first instruction in the function that reads the return
-address where an attacker could overwrite the return address and bypass
-ShadowCallStack. Similarly, there is a time-of-check-to-time-of-use race in the
-function epilog where an attacker could overwrite the return address after it
-has been checked and before it has been returned to. Modifying the call-return
-semantics to fix this on x86_64 would incur an unacceptable performance overhead
-due to return branch prediction.
-
-The instrumentation makes use of the ``gs`` segment register on x86_64,
-or the ``x18`` register on aarch64, to reference the shadow call stack
-meaning that references to the shadow call stack do not have to be stored in
-memory. This makes it possible to implement a runtime that avoids exposing
-the address of the shadow call stack to attackers that can read arbitrary
-memory. However, attackers could still try to exploit side channels exposed
-by the operating system `[1]`_ `[2]`_ or processor `[3]`_ to discover the
-address of the shadow call stack.
+memory writes to the return address slot.
+
+The instrumentation makes use of the ``x18`` register to reference the shadow
+call stack, meaning that references to the shadow call stack do not have
+to be stored in memory. This makes it possible to implement a runtime that
+avoids exposing the address of the shadow call stack to attackers that can
+read arbitrary memory. However, attackers could still try to exploit side
+channels exposed by the operating system `[1]`_ `[2]`_ or processor `[3]`_
+to discover the address of the shadow call stack.
 
 .. _`[1]`: https://eyalitkin.wordpress.com/2017/09/01/cartography-lighting-up-the-shadows/
 .. _`[2]`: https://www.blackhat.com/docs/eu-16/materials/eu-16-Goktas-Bypassing-Clangs-SafeStack.pdf
 .. _`[3]`: https://www.vusec.net/projects/anc/
 
-On x86_64, leaf functions are optimized to store the return address in a
-free register and avoid writing to the shadow call stack if a register is
-available. Very short leaf functions are uninstrumented if their execution
-is judged to be shorter than the race condition window intrinsic to the
-instrumentation.
-
-On aarch64, the architecture's call and return instructions (``bl`` and
-``ret``) operate on a register rather than the stack, which means that
-leaf functions are generally protected from return address overwrites even
-without ShadowCallStack. It also means that ShadowCallStack on aarch64 is not
-vulnerable to the same types of time-of-check-to-time-of-use races as x86_64.
+Unless care is taken when allocating the shadow call stack, it may be
+possible for an attacker to guess its address using the addresses of
+other allocations. Therefore, the address should be chosen to make this
+difficult. One way to do this is to allocate a large guard region without
+read/write permissions, randomly select a small region within it to be
+used as the address of the shadow call stack and mark only that region as
+read/write. This also mitigates somewhat against processor side channels.
+The intent is that the Android runtime `will do this`_, but the platform will
+first need to be `changed`_ to avoid using ``setrlimit(RLIMIT_AS)`` to limit
+memory allocations in certain processes, as this also limits the number of
+guard regions that can be allocated.
+
+.. _`will do this`: https://android-review.googlesource.com/c/platform/bionic/+/891622
+.. _`changed`: https://android-review.googlesource.com/c/platform/frameworks/av/+/837745
+
+The runtime will need the address of the shadow call stack in order to
+deallocate it when destroying the thread. If the entire program is compiled
+with ``-ffixed-x18``, this is trivial: the address can be derived from the
+value stored in ``x18`` (e.g. by masking out the lower bits). If a guard
+region is used, the address of the start of the guard region could then be
+stored at the start of the shadow call stack itself. But if it is possible
+for code compiled without ``-ffixed-x18`` to run on a thread managed by the
+runtime, which is the case on Android for example, the address must be stored
+somewhere else instead. On Android we store the address of the start of the
+guard region in TLS and deallocate the entire guard region including the
+shadow call stack at thread exit. This is considered acceptable given that
+the address of the start of the guard region is already somewhat guessable.
+
+One way in which the address of the shadow call stack could leak is in the
+``jmp_buf`` data structure used by ``setjmp`` and ``longjmp``. The Android
+runtime `avoids this`_ by only storing the low bits of ``x18`` in the
+``jmp_buf``, which requires the address of the shadow call stack to be
+aligned to its size.
+
+.. _`avoids this`: https://android.googlesource.com/platform/bionic/+/808d176e7e0dd727c7f929622ec017f6e065c582/libc/arch-arm64/bionic/setjmp.S#49
+
+The architecture's call and return instructions (``bl`` and ``ret``) operate on
+a register rather than the stack, which means that leaf functions are generally
+protected from return address overwrites even without ShadowCallStack.
 
 Usage
 =====
@@ -132,17 +186,7 @@ The following example code:
       return bar() + 1;
     }
 
-Generates the following x86_64 assembly when compiled with ``-O2``:
-
-.. code-block:: gas
-
-    push   %rax
-    callq  foo
-    add    $0x1,%eax
-    pop    %rcx
-    retq
-
-or the following aarch64 assembly:
+Generates the following aarch64 assembly when compiled with ``-O2``:
 
 .. code-block:: none
 
@@ -153,33 +197,7 @@ or the following aarch64 assembly:
     ldp     x29, x30, [sp], #16
     ret
 
-
-Adding ``-fsanitize=shadow-call-stack`` would output the following x86_64
-assembly:
-
-.. code-block:: gas
-
-    mov    (%rsp),%r10
-    xor    %r11,%r11
-    addq   $0x8,%gs:(%r11)
-    mov    %gs:(%r11),%r11
-    mov    %r10,%gs:(%r11)
-    push   %rax
-    callq  foo
-    add    $0x1,%eax
-    pop    %rcx
-    xor    %r11,%r11
-    mov    %gs:(%r11),%r10
-    mov    %gs:(%r10),%r10
-    subq   $0x8,%gs:(%r11)
-    cmp    %r10,(%rsp)
-    jne    trap
-    retq
-
-    trap:
-    ud2
-
-or the following aarch64 assembly:
+Adding ``-fsanitize=shadow-call-stack`` would output the following assembly:
 
 .. code-block:: none
 

docs/SourceBasedCodeCoverage.rst

@@ -156,7 +156,7 @@ line-oriented report, try:
 The ``llvm-cov`` tool supports specifying a custom demangler, writing out
 reports in a directory structure, and generating html reports. For the full
 list of options, please refer to the `command guide
-<http://llvm.org/docs/CommandGuide/llvm-cov.html>`_.
+<https://llvm.org/docs/CommandGuide/llvm-cov.html>`_.
 
 A few final notes:
 

docs/ThinLTO.rst

@@ -47,7 +47,7 @@ The 3.9 release of clang includes ThinLTO support. However, ThinLTO
 is under active development, and new features, improvements and bugfixes
 are being added for the next release. For the latest ThinLTO support,
 `build a recent version of clang and LLVM
-<http://llvm.org/docs/CMake.html>`_.
+<https://llvm.org/docs/CMake.html>`_.
 
 Linkers
 -------
@@ -59,7 +59,7 @@ ThinLTO is currently supported for the following linkers:
 - **gold (via the gold-plugin)**:
   Similar to monolithic LTO, this requires using
   a `gold linker configured with plugins enabled
-  <http://llvm.org/docs/GoldPlugin.html>`_.
+  <https://llvm.org/docs/GoldPlugin.html>`_.
 - **ld64**:
   Starting with `Xcode 8 <https://developer.apple.com/xcode/>`_.
 - **lld**:
@@ -99,13 +99,15 @@ With gold, if you see an error during the link of the form:
 Then either gold was not configured with plugins enabled, or clang
 was not built with ``-DLLVM_BINUTILS_INCDIR`` set properly. See
 the instructions for the
-`LLVM gold plugin <http://llvm.org/docs/GoldPlugin.html#how-to-build-it>`_.
+`LLVM gold plugin <https://llvm.org/docs/GoldPlugin.html#how-to-build-it>`_.
 
 Controlling Backend Parallelism
 -------------------------------
 .. _parallelism:
 
-By default, the ThinLTO link step will launch up to
+By default, the ThinLTO link step will launch as many
+threads in parallel as there are cores. If the number of
+cores can't be computed for the architecture, then it will launch
 ``std::thread::hardware_concurrency`` number of threads in parallel.
 For machines with hyper-threading, this is the total number of
 virtual cores. For some applications and machine configurations this
@@ -196,9 +198,9 @@ To bootstrap clang/LLVM with ThinLTO, follow these steps:
 
 1. The host compiler_ must be a version of clang that supports ThinLTO.
 #. The host linker_ must support ThinLTO (and in the case of gold, must be
-   `configured with plugins enabled <http://llvm.org/docs/GoldPlugin.html>`_.
+   `configured with plugins enabled <https://llvm.org/docs/GoldPlugin.html>`_).
 #. Use the following additional `CMake variables
-   <http://llvm.org/docs/CMake.html#options-and-variables>`_
+   <https://llvm.org/docs/CMake.html#options-and-variables>`_
    when configuring the bootstrap compiler build:
 
   * ``-DLLVM_ENABLE_LTO=Thin``
@@ -223,6 +225,10 @@ To bootstrap clang/LLVM with ThinLTO, follow these steps:
    ``CMAKE_EXE_LINKER_FLAGS:STRING=``. Note the configure may fail if
    linker plugin options are instead specified directly in the previous step.
 
+The `BOOTSTRAP_LLVM_ENABLE_LTO=Thin`` will enable ThinLTO for stage 2 and
+stage 3 in case the compiler used for stage 1 does not support the ThinLTO
+option.
+
 More Information
 ================
 

docs/ThreadSanitizer.rst

@@ -12,12 +12,19 @@ ThreadSanitizer is about **5x-10x**.
 How to build
 ------------
 
-Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_.
+Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_.
 
 Supported Platforms
 -------------------
 
-ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 12.04).
+ThreadSanitizer is supported on the following OS:
+
+* Android aarch64, x86_64
+* Darwin arm64, x86_64
+* FreeBSD
+* Linux aarch64, x86_64, powerpc64, powerpc64le
+* NetBSD
+
 Support for other 64-bit architectures is possible, contributions are welcome.
 Support for 32-bit platforms is problematic and is not planned.
 

docs/Toolchain.rst

@@ -100,14 +100,14 @@ currently-supported languages are:
 
 In each case, GCC will be invoked to compile the input.
 
-Assember
---------
+Assembler
+---------
 
 Clang can either use LLVM's integrated assembler or an external system-specific
 tool (for instance, the GNU Assembler on GNU OSes) to produce machine code from
 assembly.
 By default, Clang uses LLVM's integrated assembler on all targets where it is
-supported. If you wish to use the system assember instead, use the
+supported. If you wish to use the system assembler instead, use the
 ``-fno-integrated-as`` option.
 
 Linker
@@ -117,11 +117,11 @@ Clang can be configured to use one of several different linkers:
 
 * GNU ld
 * GNU gold
-* LLVM's `lld <http://lld.llvm.org>`_
+* LLVM's `lld <https://lld.llvm.org>`_
 * MSVC's link.exe
 
 Link-time optimization is natively supported by lld, and supported via
-a `linker plugin <http://llvm.org/docs/GoldPlugin.html>`_ when using gold.
+a `linker plugin <https://llvm.org/docs/GoldPlugin.html>`_ when using gold.
 
 The default linker varies between targets, and can be overridden via the
 ``-fuse-ld=<linker name>`` flag.
@@ -164,7 +164,7 @@ other targets, compiler-rt is used by default.
 compiler-rt (LLVM)
 ^^^^^^^^^^^^^^^^^^
 
-`LLVM's compiler runtime library <http://compiler-rt.llvm.org/>`_ provides a
+`LLVM's compiler runtime library <https://compiler-rt.llvm.org/>`_ provides a
 complete set of runtime library functions containing all functions that
 Clang will implicitly call, in ``libclang_rt.builtins.<arch>.a``.
 
@@ -222,21 +222,15 @@ Unwind library
 
 The unwind library provides a family of ``_Unwind_*`` functions implementing
 the language-neutral stack unwinding portion of the Itanium C++ ABI
-(`Level I <http://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#base-abi>`_).
+(`Level I <https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#base-abi>`_).
 It is a dependency of the C++ ABI library, and sometimes is a dependency
 of other runtimes.
 
 libunwind (LLVM)
 ^^^^^^^^^^^^^^^^
 
-LLVM's unwinder library can be obtained from subversion:
-
-.. code-block:: console
-
-  llvm-src$ svn co http://llvm.org/svn/llvm-project/libunwind/trunk projects/libunwind
-
-When checked out into projects/libunwind within an LLVM checkout,
-it should be automatically picked up by the LLVM build system.
+LLVM's unwinder library is part of the llvm-project git repository. To
+build it, pass ``-DLLVM_ENABLE_PROJECTS=libunwind`` to the cmake invocation.
 
 If using libc++abi, you may need to configure it to use libunwind
 rather than libgcc_s by passing ``-DLIBCXXABI_USE_LLVM_UNWINDER=YES``
@@ -254,7 +248,7 @@ libunwind (nongnu.org)
 ^^^^^^^^^^^^^^^^^^^^^^
 
 This is another implementation of the libunwind specification.
-See `libunwind (nongnu.org) <http://www.nongnu.org/libunwind>`_.
+See `libunwind (nongnu.org) <https://www.nongnu.org/libunwind>`_.
 
 libunwind (PathScale)
 ^^^^^^^^^^^^^^^^^^^^^
@@ -279,7 +273,7 @@ C standard library
 ------------------
 
 Clang supports a wide variety of
-`C standard library <http://en.cppreference.com/w/c>`_
+`C standard library <https://en.cppreference.com/w/c>`_
 implementations.
 
 C++ ABI library
@@ -288,9 +282,9 @@ C++ ABI library
 The C++ ABI library provides an implementation of the library portion of
 the Itanium C++ ABI, covering both the
 `support functionality in the main Itanium C++ ABI document
-<http://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_ and
+<https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_ and
 `Level II of the exception handling support
-<http://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#cxx-abi>`_.
+<https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#cxx-abi>`_.
 References to the functions and objects in this library are implicitly
 generated by Clang when compiling C++ code.
 
@@ -306,7 +300,7 @@ available:
 libc++abi (LLVM)
 ^^^^^^^^^^^^^^^^
 
-`libc++abi <http://libcxxabi.llvm.org/>`_ is LLVM's implementation of this
+`libc++abi <https://libcxxabi.llvm.org/>`_ is LLVM's implementation of this
 specification.
 
 libsupc++ (GNU)
@@ -332,12 +326,12 @@ C++ standard library
 --------------------
 
 Clang supports use of either LLVM's libc++ or GCC's libstdc++ implementation
-of the `C++ standard library <http://en.cppreference.com/w/cpp>`_.
+of the `C++ standard library <https://en.cppreference.com/w/cpp>`_.
 
 libc++ (LLVM)
 ^^^^^^^^^^^^^
 
-`libc++ <http://libcxx.llvm.org/>`_ is LLVM's implementation of the C++
+`libc++ <https://libcxx.llvm.org/>`_ is LLVM's implementation of the C++
 standard library, aimed at being a complete implementation of the C++
 standards from C++11 onwards.
 

docs/Tooling.rst

@@ -9,7 +9,7 @@ the different ways to write clang tools, and their pros and cons.
 LibClang
 --------
 
-`LibClang <http://clang.llvm.org/doxygen/group__CINDEX.html>`_ is a stable high
+`LibClang <https://clang.llvm.org/doxygen/group__CINDEX.html>`_ is a stable high
 level C interface to clang.  When in doubt LibClang is probably the interface
 you want to use.  Consider the other interfaces only when you have a good
 reason not to use LibClang.

docs/UndefinedBehaviorSanitizer.rst

@@ -25,7 +25,7 @@ The checks have small runtime cost and no impact on address space layout or ABI.
 How to build
 ============
 
-Build LLVM/Clang with `CMake <http://llvm.org/docs/CMake.html>`_.
+Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_.
 
 Usage
 =====
@@ -72,7 +72,7 @@ Available checks
 Available checks are:
 
   -  ``-fsanitize=alignment``: Use of a misaligned pointer or creation
-     of a misaligned reference.
+     of a misaligned reference. Also sanitizes assume_aligned-like attributes.
   -  ``-fsanitize=bool``: Load of a ``bool`` value which is neither
      ``true`` nor ``false``.
   -  ``-fsanitize=builtin``: Passing invalid values to compiler builtins.
@@ -83,12 +83,33 @@ Available checks are:
      type.
   -  ``-fsanitize=float-cast-overflow``: Conversion to, from, or
      between floating-point types which would overflow the
-     destination.
+     destination. Because the range of representable values for all
+     floating-point types supported by Clang is [-inf, +inf], the only
+     cases detected are conversions from floating point to integer types.
   -  ``-fsanitize=float-divide-by-zero``: Floating point division by
-     zero.
+     zero. This is undefined per the C and C++ standards, but is defined
+     by Clang (and by ISO/IEC/IEEE 60559 / IEEE 754) as producing either an
+     infinity or NaN value, so is not included in ``-fsanitize=undefined``.
   -  ``-fsanitize=function``: Indirect call of a function through a
      function pointer of the wrong type (Darwin/Linux, C++ and x86/x86_64
      only).
+  -  ``-fsanitize=implicit-unsigned-integer-truncation``,
+     ``-fsanitize=implicit-signed-integer-truncation``: Implicit conversion from
+     integer of larger bit width to smaller bit width, if that results in data
+     loss. That is, if the demoted value, after casting back to the original
+     width, is not equal to the original value before the downcast.
+     The ``-fsanitize=implicit-unsigned-integer-truncation`` handles conversions
+     between two ``unsigned`` types, while
+     ``-fsanitize=implicit-signed-integer-truncation`` handles the rest of the
+     conversions - when either one, or both of the types are signed.
+     Issues caught by these sanitizers are not undefined behavior,
+     but are often unintentional.
+  -  ``-fsanitize=implicit-integer-sign-change``: Implicit conversion between
+     integer types, if that changes the sign of the value. That is, if the the
+     original value was negative and the new value is positive (or zero),
+     or the original value was positive, and the new value is negative.
+     Issues caught by this sanitizer are not undefined behavior,
+     but are often unintentional.
   -  ``-fsanitize=integer-divide-by-zero``: Integer division by zero.
   -  ``-fsanitize=nonnull-attribute``: Passing null pointer as a function
      parameter which is declared to never be null.
@@ -109,7 +130,8 @@ Available checks are:
      ``__builtin_object_size``, and consequently may be able to detect more
      problems at higher optimization levels.
   -  ``-fsanitize=pointer-overflow``: Performing pointer arithmetic which
-     overflows.
+     overflows, or where either the old or new pointer value is a null pointer
+     (or in C, when they both are).
   -  ``-fsanitize=return``: In C++, reaching the end of a
      value-returning function without returning a value.
   -  ``-fsanitize=returns-nonnull-attribute``: Returning null pointer
@@ -121,15 +143,21 @@ Available checks are:
      unsigned overflow in C++. You can use ``-fsanitize=shift-base`` or
      ``-fsanitize=shift-exponent`` to check only left-hand side or
      right-hand side of shift operation, respectively.
-  -  ``-fsanitize=signed-integer-overflow``: Signed integer overflow,
-     including all the checks added by ``-ftrapv``, and checking for
-     overflow in signed division (``INT_MIN / -1``).
+  -  ``-fsanitize=signed-integer-overflow``: Signed integer overflow, where the
+     result of a signed integer computation cannot be represented in its type.
+     This includes all the checks covered by ``-ftrapv``, as well as checks for
+     signed division overflow (``INT_MIN/-1``), but not checks for
+     lossy implicit conversions performed before the computation
+     (see ``-fsanitize=implicit-conversion``). Both of these two issues are
+     handled by ``-fsanitize=implicit-conversion`` group of checks.
   -  ``-fsanitize=unreachable``: If control flow reaches an unreachable
      program point.
-  -  ``-fsanitize=unsigned-integer-overflow``: Unsigned integer
-     overflows. Note that unlike signed integer overflow, unsigned integer
-     is not undefined behavior. However, while it has well-defined semantics,
-     it is often unintentional, so UBSan offers to catch it.
+  -  ``-fsanitize=unsigned-integer-overflow``: Unsigned integer overflow, where
+     the result of an unsigned integer computation cannot be represented in its
+     type. Unlike signed integer overflow, this is not undefined behavior, but
+     it is often unintentional. This sanitizer does not check for lossy implicit
+     conversions performed before such a computation
+     (see ``-fsanitize=implicit-conversion``).
   -  ``-fsanitize=vla-bound``: A variable-length array whose bound
      does not evaluate to a positive value.
   -  ``-fsanitize=vptr``: Use of an object whose vptr indicates that it is of
@@ -140,11 +168,28 @@ Available checks are:
 
 You can also use the following check groups:
   -  ``-fsanitize=undefined``: All of the checks listed above other than
-     ``unsigned-integer-overflow`` and the ``nullability-*`` checks.
+     ``float-divide-by-zero``, ``unsigned-integer-overflow``,
+     ``implicit-conversion``, and the ``nullability-*`` group of checks.
   -  ``-fsanitize=undefined-trap``: Deprecated alias of
      ``-fsanitize=undefined``.
+  -  ``-fsanitize=implicit-integer-truncation``: Catches lossy integral
+     conversions. Enables ``implicit-signed-integer-truncation`` and
+     ``implicit-unsigned-integer-truncation``.
+  -  ``-fsanitize=implicit-integer-arithmetic-value-change``: Catches implicit
+     conversions that change the arithmetic value of the integer. Enables
+     ``implicit-signed-integer-truncation`` and ``implicit-integer-sign-change``.
+  -  ``-fsanitize=implicit-conversion``: Checks for suspicious
+     behavior of implicit conversions. Enables
+     ``implicit-unsigned-integer-truncation``,
+     ``implicit-signed-integer-truncation``, and
+     ``implicit-integer-sign-change``.
   -  ``-fsanitize=integer``: Checks for undefined or suspicious integer
      behavior (e.g. unsigned integer overflow).
+     Enables ``signed-integer-overflow``, ``unsigned-integer-overflow``,
+     ``shift``, ``integer-divide-by-zero``,
+     ``implicit-unsigned-integer-truncation``,
+     ``implicit-signed-integer-truncation``, and
+     ``implicit-integer-sign-change``.
   -  ``-fsanitize=nullability``: Enables ``nullability-arg``,
      ``nullability-assign``, and ``nullability-return``. While violating
      nullability does not have undefined behavior, it is often unintentional,
@@ -161,8 +206,8 @@ Minimal Runtime
 
 There is a minimal UBSan runtime available suitable for use in production
 environments. This runtime has a small attack surface. It only provides very
-basic issue logging and deduplication, and does not support ``-fsanitize=vptr``
-checking.
+basic issue logging and deduplication, and does not support
+``-fsanitize=function`` and ``-fsanitize=vptr`` checking.
 
 To use the minimal runtime, add ``-fsanitize-minimal-runtime`` to the clang
 command line options. For example, if you're used to compiling with
@@ -180,6 +225,19 @@ will need to:
    ``UBSAN_OPTIONS=print_stacktrace=1``.
 #. Make sure ``llvm-symbolizer`` binary is in ``PATH``.
 
+Logging
+=======
+
+The default log file for diagnostics is "stderr". To log diagnostics to another
+file, you can set ``UBSAN_OPTIONS=log_path=...``.
+
+Silencing Unsigned Integer Overflow
+===================================
+To silence reports from unsigned integer overflow, you can set
+``UBSAN_OPTIONS=silence_unsigned_overflow=1``.  This feature, combined with
+``-fsanitize-recover=unsigned-integer-overflow``, is particularly useful for
+providing fuzzing signal without blowing up logs.
+
 Issue Suppression
 =================
 
@@ -241,20 +299,19 @@ There are several limitations:
 Supported Platforms
 ===================
 
-UndefinedBehaviorSanitizer is supported on the following OS:
+UndefinedBehaviorSanitizer is supported on the following operating systems:
 
 * Android
 * Linux
+* NetBSD
 * FreeBSD
-* OS X 10.6 onwards
+* OpenBSD
+* macOS
+* Windows
 
-and for the following architectures:
-
-* i386/x86\_64
-* ARM
-* AArch64
-* PowerPC64
-* MIPS/MIPS64
+The runtime library is relatively portable and platform independent. If the OS
+you need is not listed above, UndefinedBehaviorSanitizer may already work for
+it, or could be made to work with a minor porting effort.
 
 Current Status
 ==============
@@ -277,6 +334,7 @@ Example
 -------
 
 For a file called ``/code/library/file.cpp``, here is what would be emitted:
+
 * Default (No flag, or ``-fsanitize-undefined-strip-path-components=0``): ``/code/library/file.cpp``
 * ``-fsanitize-undefined-strip-path-components=1``: ``code/library/file.cpp``
 * ``-fsanitize-undefined-strip-path-components=2``: ``library/file.cpp``
@@ -291,4 +349,4 @@ More Information
   <http://blog.llvm.org/2011/05/what-every-c-programmer-should-know.html>`_
 * From John Regehr's *Embedded in Academia* blog:
   `A Guide to Undefined Behavior in C and C++
-  <http://blog.regehr.org/archives/213>`_
+  <https://blog.regehr.org/archives/213>`_

docs/UsersManual.rst

@@ -15,14 +15,14 @@ programming languages, aiming to be the best in class implementation of
 these languages. Clang builds on the LLVM optimizer and code generator,
 allowing it to provide high-quality optimization and code generation
 support for many targets. For more general information, please see the
-`Clang Web Site <http://clang.llvm.org>`_ or the `LLVM Web
-Site <http://llvm.org>`_.
+`Clang Web Site <https://clang.llvm.org>`_ or the `LLVM Web
+Site <https://llvm.org>`_.
 
 This document describes important notes about using Clang as a compiler
 for an end-user, documenting the supported features, command line
 options, etc. If you are interested in using Clang to build a tool that
 processes code, please see :doc:`InternalsManual`. If you are interested in the
-`Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web
+`Clang Static Analyzer <https://clang-analyzer.llvm.org>`_, please see its web
 page.
 
 Clang is one component in a complete toolchain for C family languages.
@@ -324,13 +324,21 @@ output format of the diagnostics that it generates.
 
 .. _opt_fsave-optimization-record:
 
-**-fsave-optimization-record**
-   Write optimization remarks to a YAML file.
+.. option:: -fsave-optimization-record[=<format>]
+
+   Write optimization remarks to a separate file.
 
    This option, which defaults to off, controls whether Clang writes
-   optimization reports to a YAML file. By recording diagnostics in a file,
-   using a structured YAML format, users can parse or sort the remarks in a
-   convenient way.
+   optimization reports to a separate file. By recording diagnostics in a file,
+   users can parse or sort the remarks in a convenient way.
+
+   By default, the serialization format is YAML.
+
+   The supported serialization formats are:
+
+   -  .. _opt_fsave_optimization_record_yaml:
+
+      ``-fsave-optimization-record=yaml``: A structured YAML format.
 
 .. _opt_foptimization-record-file:
 
@@ -343,7 +351,21 @@ output format of the diagnostics that it generates.
 
    If this option is not used, optimization records are output to a file named
    after the primary file being compiled. If that's "foo.c", for example,
-   optimization records are output to "foo.opt.yaml".
+   optimization records are output to "foo.opt.yaml". If a specific
+   serialization format is specified, the file will be named
+   "foo.opt.<format>".
+
+.. _opt_foptimization-record-passes:
+
+**-foptimization-record-passes**
+   Only include passes which match a specified regular expression.
+
+   When optimization reports are being output (see
+   :ref:`-fsave-optimization-record <opt_fsave-optimization-record>`), this
+   option controls the passes that will be included in the final report.
+
+   If this option is not used, all the passes are included in the optimization
+   record.
 
 .. _opt_fdiagnostics-show-hotness:
 
@@ -587,7 +609,7 @@ Options to Control Clang Crash Diagnostics
 
 As unbelievable as it may sound, Clang does crash from time to time.
 Generally, this only occurs to those living on the `bleeding
-edge <http://llvm.org/releases/download.html#svn>`_. Clang goes to great
+edge <https://llvm.org/releases/download.html#svn>`_. Clang goes to great
 lengths to assist you in filing a bug report. Specifically, Clang
 generates preprocessed source file(s) and associated run script(s) upon
 a crash. These files should be attached to a bug report to ease
@@ -679,6 +701,13 @@ Other Options
 -------------
 Clang options that don't fit neatly into other categories.
 
+.. option:: -fgnuc-version=
+
+  This flag controls the value of ``__GNUC__`` and related macros. This flag
+  does not enable or disable any GCC extensions implemented in Clang. Setting
+  the version to zero causes Clang to leave ``__GNUC__`` and other
+  GNU-namespaced macros, such as ``__GXX_WEAK__``, undefined.
+
 .. option:: -MV
 
   When emitting a dependency file, use formatting conventions appropriate
@@ -970,23 +999,34 @@ is treated as a system header.
 Enabling All Diagnostics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In addition to the traditional ``-W`` flags, one can enable **all**
-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
-flag wins.
+In addition to the traditional ``-W`` flags, one can enable **all** diagnostics
+by passing :option:`-Weverything`. This works as expected with
+:option:`-Werror`, and also includes the warnings from :option:`-pedantic`. Some
+diagnostics contradict each other, therefore, users of :option:`-Weverything`
+often disable many diagnostics such as `-Wno-c++98-compat` and `-Wno-c++-compat`
+because they contradict recent C++ standards.
+
+Since :option:`-Weverything` enables every diagnostic, we generally don't
+recommend using it. `-Wall` `-Wextra` are a better choice for most projects.
+Using :option:`-Weverything` means that updating your compiler is more difficult
+because you're exposed to experimental diagnostics which might be of lower
+quality than the default ones. If you do use :option:`-Weverything` then we
+advise that you address all new compiler diagnostics as they get added to Clang,
+either by fixing everything they find or explicitly disabling that diagnostic
+with its corresponding `Wno-` option.
+
+Note that when combined with :option:`-w` (which disables all warnings),
+disabling all warnings wins.
 
 Controlling Static Analyzer Diagnostics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 While not strictly part of the compiler, the diagnostics from Clang's
-`static analyzer <http://clang-analyzer.llvm.org>`_ can also be
+`static analyzer <https://clang-analyzer.llvm.org>`_ can also be
 influenced by the user via changes to the source code. See the available
-`annotations <http://clang-analyzer.llvm.org/annotations.html>`_ and the
+`annotations <https://clang-analyzer.llvm.org/annotations.html>`_ and the
 analyzer's `FAQ
-page <http://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
+page <https://clang-analyzer.llvm.org/faq.html#exclude_code>`_ for more
 information.
 
 .. _usersmanual-precompiled-headers:
@@ -994,7 +1034,7 @@ information.
 Precompiled Headers
 -------------------
 
-`Precompiled headers <http://en.wikipedia.org/wiki/Precompiled_header>`__
+`Precompiled headers <https://en.wikipedia.org/wiki/Precompiled_header>`_
 are a general approach employed by many compilers to reduce compilation
 time. The underlying motivation of the approach is that it is common for
 the same (and often large) header files to be included by multiple
@@ -1006,7 +1046,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., macOS).
 
 Generating a PCH File
 ^^^^^^^^^^^^^^^^^^^^^
@@ -1095,6 +1135,185 @@ number of cases where the compilation environment is tightly controlled
 and the precompiled header cannot be generated after headers have been
 installed.
 
+.. _controlling-fp-behavior:
+
+Controlling Floating Point Behavior
+-----------------------------------
+
+Clang provides a number of ways to control floating point behavior. The options
+are listed below.
+
+.. option:: -ffast-math
+
+   Enable fast-math mode.  This option lets the
+   compiler make aggressive, potentially-lossy assumptions about
+   floating-point math.  These include:
+
+   * Floating-point math obeys regular algebraic rules for real numbers (e.g.
+     ``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and
+     ``(a + b) * c == a * c + b * c``),
+   * Operands to floating-point operations are not equal to ``NaN`` and
+     ``Inf``, and
+   * ``+0`` and ``-0`` are interchangeable.
+
+   ``-ffast-math`` also defines the ``__FAST_MATH__`` preprocessor
+   macro. Some math libraries recognize this macro and change their behavior.
+   With the exception of ``-ffp-contract=fast``, using any of the options
+   below to disable any of the individual optimizations in ``-ffast-math``
+   will cause ``__FAST_MATH__`` to no longer be set.
+
+  This option implies:
+
+   * ``-fno-honor-infinities``
+
+   * ``-fno-honor-nans``
+
+   * ``-fno-math-errno``
+
+   * ``-ffinite-math``
+
+   * ``-fassociative-math``
+
+   * ``-freciprocal-math``
+
+   * ``-fno-signed-zeros``
+
+   * ``-fno-trapping-math``
+
+   * ``-ffp-contract=fast``
+
+.. option:: -fdenormal-fp-math=<value>
+
+   Select which denormal numbers the code is permitted to require.
+
+   Valid values are: 
+
+   * ``ieee`` - IEEE 754 denormal numbers
+   * ``preserve-sign`` - the sign of a flushed-to-zero number is preserved in the sign of 0
+   * ``positive-zero`` - denormals are flushed to positive zero
+
+   Defaults to ``ieee``.
+
+.. _opt_fstrict-float-cast-overflow:
+
+**-f[no-]strict-float-cast-overflow**
+
+   When a floating-point value is not representable in a destination integer 
+   type, the code has undefined behavior according to the language standard.
+   By default, Clang will not guarantee any particular result in that case.
+   With the 'no-strict' option, Clang attempts to match the overflowing behavior
+   of the target's native float-to-int conversion instructions.
+
+.. _opt_fmath-errno:
+
+**-f[no-]math-errno**
+
+   Require math functions to indicate errors by setting errno.
+   The default varies by ToolChain.  ``-fno-math-errno`` allows optimizations
+   that might cause standard C math functions to not set ``errno``.
+   For example, on some systems, the math function ``sqrt`` is specified
+   as setting ``errno`` to ``EDOM`` when the input is negative. On these
+   systems, the compiler cannot normally optimize a call to ``sqrt`` to use
+   inline code (e.g. the x86 ``sqrtsd`` instruction) without additional
+   checking to ensure that ``errno`` is set appropriately.
+   ``-fno-math-errno`` permits these transformations.
+
+   On some targets, math library functions never set ``errno``, and so
+   ``-fno-math-errno`` is the default. This includes most BSD-derived
+   systems, including Darwin.
+
+.. _opt_ftrapping-math:
+
+**-f[no-]trapping-math**
+
+   ``-fno-trapping-math`` allows optimizations that assume that
+   floating point operations cannot generate traps such as divide-by-zero,
+   overflow and underflow. Defaults to ``-ftrapping-math``.
+   Currently this option has no effect.
+
+.. option:: -ffp-contract=<value>
+
+   Specify when the compiler is permitted to form fused floating-point
+   operations, such as fused multiply-add (FMA). Fused operations are
+   permitted to produce more precise results than performing the same
+   operations separately.
+
+   The C standard permits intermediate floating-point results within an
+   expression to be computed with more precision than their type would
+   normally allow. This permits operation fusing, and Clang takes advantage
+   of this by default. This behavior can be controlled with the
+   ``FP_CONTRACT`` pragma. Please refer to the pragma documentation for a
+   description of how the pragma interacts with this option.
+
+   Valid values are:
+
+   * ``fast`` (everywhere)
+   * ``on`` (according to FP_CONTRACT pragma, default)
+   * ``off`` (never fuse)
+
+.. _opt_fhonor-infinities:
+
+**-f[no-]honor-infinities**
+
+   If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
+   has the same effect as specifying ``-ffinite-math``.
+
+.. _opt_fhonor-nans:
+
+**-f[no-]honor-nans**
+
+   If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
+   has the same effect as specifying ``-ffinite-math``.
+
+.. _opt_fsigned-zeros:
+
+**-f[no-]signed-zeros**
+
+   Allow optimizations that ignore the sign of floating point zeros.
+   Defaults to ``-fno-signed-zeros``.
+
+.. _opt_fassociative-math:
+
+**-f[no-]associative-math**
+
+  Allow floating point operations to be reassociated.
+  Defaults to ``-fno-associative-math``.
+
+.. _opt_freciprocal-math:
+
+**-f[no-]reciprocal-math**
+
+  Allow division operations to be transformed into multiplication by a
+  reciprocal. This can be significantly faster than an ordinary division
+  but can also have significantly less precision. Defaults to
+  ``-fno-reciprocal-math``.
+
+.. _opt_funsafe-math-optimizations:
+
+**-f[no-]unsafe-math-optimizations**
+
+   Allow unsafe floating-point optimizations. Also implies:
+
+   * ``-fassociative-math``
+   * ``-freciprocal-math``
+   * ``-fno-signed-zeroes``
+   * ``-fno-trapping-math``.
+
+   Defaults to ``-fno-unsafe-math-optimizations``.
+
+.. _opt_ffinite-math:
+
+**-f[no-]finite-math**
+
+   Allow floating-point optimizations that assume arguments and results are
+   not NaNs or +-Inf.  This defines the ``__FINITE_MATH_ONLY__`` preprocessor macro.
+   Also implies:
+
+   * ``-fno-honor-infinities``
+   * ``-fno-honor-nans``
+
+   Defaults to ``-fno-finite-math``.
+
 .. _controlling-code-generation:
 
 Controlling Code Generation
@@ -1233,44 +1452,18 @@ are listed below.
    This enables better devirtualization. Turned off by default, because it is
    still experimental.
 
-.. option:: -ffast-math
-
-   Enable fast-math mode. This defines the ``__FAST_MATH__`` preprocessor
-   macro, and lets the compiler make aggressive, potentially-lossy assumptions
-   about floating-point math.  These include:
-
-   * Floating-point math obeys regular algebraic rules for real numbers (e.g.
-     ``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and
-     ``(a + b) * c == a * c + b * c``),
-   * operands to floating-point operations are not equal to ``NaN`` and
-     ``Inf``, and
-   * ``+0`` and ``-0`` are interchangeable.
-
-.. option:: -fdenormal-fp-math=[values]
-
-   Select which denormal numbers the code is permitted to require.
-
-   Valid values are: ``ieee``, ``preserve-sign``, and ``positive-zero``,
-   which correspond to IEEE 754 denormal numbers, the sign of a
-   flushed-to-zero number is preserved in the sign of 0, denormals are
-   flushed to positive zero, respectively.
-
-.. option:: -f[no-]fp-cast-overflow-workaround
-
-   Enable a workaround for code that casts floating-point values to 
-   integers and back to floating-point. If the floating-point value 
-   is not representable in the intermediate integer type, the code is
-   incorrect according to the language standard. This flag will attempt 
-   to generate code as if the result of an overflowing conversion matches
-   the overflowing behavior of a target's native float-to-int conversion
-   instructions.
-
 .. option:: -fwhole-program-vtables
 
    Enable whole-program vtable optimizations, such as single-implementation
    devirtualization and virtual constant propagation, for classes with
    :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``.
 
+.. option:: -fforce-emit-vtables
+
+   In order to improve devirtualization, forces emitting of vtables even in
+   modules where it isn't necessary. It causes more inline virtual functions
+   to be emitted.
+
 .. option:: -fno-assume-sane-operator-new
 
    Don't assume that the C++'s new operator is sane.
@@ -1378,6 +1571,15 @@ are listed below.
         // value of -fmax-type-align.
       }
 
+.. option:: -faddrsig, -fno-addrsig
+
+   Controls whether Clang emits an address-significance table into the object
+   file. Address-significance tables allow linkers to implement `safe ICF
+   <https://research.google.com/pubs/archive/36912.pdf>`_ without the false
+   positives that can result from other implementation techniques such as
+   relocation scanning. Address-significance tables are enabled by default
+   on ELF targets when using the integrated assembler. This flag currently
+   only has an effect on ELF targets.
 
 Profile Guided Optimization
 ---------------------------
@@ -1469,7 +1671,7 @@ usual build cycle when using sample profilers for optimization:
 
 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
+   It is available at https://github.com/google/autofdo. Once built and
    installed, you can convert the ``perf.data`` file to LLVM using
    the command:
 
@@ -1508,12 +1710,12 @@ read by the backend. LLVM supports three different sample profile formats:
 
 2. Binary encoding. This uses a more efficient encoding that yields smaller
    profile files. This is the format generated by the ``create_llvm_prof`` tool
-   in http://github.com/google/autofdo.
+   in https://github.com/google/autofdo.
 
 3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It
    is only interesting in environments where GCC and Clang co-exist. This
    encoding is only generated by the ``create_gcov`` tool in
-   http://github.com/google/autofdo. It can be read by LLVM and
+   https://github.com/google/autofdo. It can be read by LLVM and
    ``llvm-profdata``, but it cannot be generated by either.
 
 If you are using Linux Perf to generate sampling profiles, you can use the
@@ -1732,16 +1934,17 @@ controlled by the GCC-compatible flags ``-fprofile-generate`` and
 ``-fprofile-use``. Although these flags are semantically equivalent to
 their GCC counterparts, they *do not* handle GCC-compatible profiles.
 They are only meant to implement GCC's semantics with respect to
-profile creation and use.
+profile creation and use. Flag ``-fcs-profile-generate`` also instruments
+programs using the same instrumentation method as ``-fprofile-generate``.
 
 .. option:: -fprofile-generate[=<dirname>]
 
   The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use
-  an alterantive instrumentation method for profile generation. When
+  an alternative instrumentation method for profile generation. When
   given a directory name, it generates the profile file
   ``default_%m.profraw`` in the directory named ``dirname`` if specified.
   If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier
-  will be substibuted with a unique id documented in step 2 above. In other words,
+  will be substituted with a unique id documented in step 2 above. In other words,
   with ``-fprofile-generate[=<dirname>]`` option, the "raw" profile data automatic
   merging is turned on by default, so there will no longer any risk of profile
   clobbering from different running processes.  For example,
@@ -1765,6 +1968,45 @@ profile creation and use.
  ``LLVM_PROFILE_FILE`` can still be used to override
  the directory and filename for the profile file at runtime.
 
+.. option:: -fcs-profile-generate[=<dirname>]
+
+  The ``-fcs-profile-generate`` and ``-fcs-profile-generate=`` flags will use
+  the same instrumentation method, and generate the same profile as in the
+  ``-fprofile-generate`` and ``-fprofile-generate=`` flags. The difference is
+  that the instrumentation is performed after inlining so that the resulted
+  profile has a better context sensitive information. They cannot be used
+  together with ``-fprofile-generate`` and ``-fprofile-generate=`` flags.
+  They are typically used in conjunction with ``-fprofile-use`` flag.
+  The profile generated by ``-fcs-profile-generate`` and ``-fprofile-generate``
+  can be merged by llvm-profdata. A use example:
+
+  .. code-block:: console
+
+    $ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
+    $ ./code
+    $ llvm-profdata merge -output=code.profdata yyy/zzz/
+
+  The first few steps are the same as that in ``-fprofile-generate``
+  compilation. Then perform a second round of instrumentation.
+
+  .. code-block:: console
+
+    $ clang++ -O2 -fprofile-use=code.profdata -fcs-profile-generate=sss/ttt \
+      -o cs_code
+    $ ./cs_code
+    $ llvm-profdata merge -output=cs_code.profdata sss/ttt code.profdata
+
+  The resulted ``cs_code.prodata`` combines ``code.profdata`` and the profile
+  generated from binary ``cs_code``. Profile ``cs_code.profata`` can be used by
+  ``-fprofile-use`` compilaton.
+
+  .. code-block:: console
+
+    $ clang++ -O2 -fprofile-use=cs_code.profdata
+
+  The above command will read both profiles to the compiler at the identical
+  point of instrumenations.
+
 .. option:: -fprofile-use[=<pathname>]
 
   Without any other arguments, ``-fprofile-use`` behaves identically to
@@ -1786,6 +2028,127 @@ In these cases, you can use the flag ``-fno-profile-instr-generate`` (or
 Note that these flags should appear after the corresponding profile
 flags to have an effect.
 
+Profile remapping
+^^^^^^^^^^^^^^^^^
+
+When the program is compiled after a change that affects many symbol names,
+pre-existing profile data may no longer match the program. For example:
+
+ * switching from libstdc++ to libc++ will result in the mangled names of all
+   functions taking standard library types to change
+ * renaming a widely-used type in C++ will result in the mangled names of all
+   functions that have parameters involving that type to change
+ * moving from a 32-bit compilation to a 64-bit compilation may change the
+   underlying type of ``size_t`` and similar types, resulting in changes to
+   manglings
+
+Clang allows use of a profile remapping file to specify that such differences
+in mangled names should be ignored when matching the profile data against the
+program.
+
+.. option:: -fprofile-remapping-file=<file>
+
+  Specifies a file containing profile remapping information, that will be
+  used to match mangled names in the profile data to mangled names in the
+  program.
+
+The profile remapping file is a text file containing lines of the form
+
+.. code-block:: text
+
+  fragmentkind fragment1 fragment2
+
+where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``,
+indicating whether the following mangled name fragments are
+<`name <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s,
+<`type <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or
+<`encoding <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s,
+respectively.
+Blank lines and lines starting with ``#`` are ignored.
+
+For convenience, built-in <substitution>s such as ``St`` and ``Ss``
+are accepted as <name>s (even though they technically are not <name>s).
+
+For example, to specify that ``absl::string_view`` and ``std::string_view``
+should be treated as equivalent when matching profile data, the following
+remapping file could be used:
+
+.. code-block:: text
+
+  # absl::string_view is considered equivalent to std::string_view
+  type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE
+
+  # std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
+  name 3std St3__1
+  name 3std St7__cxx11
+
+Matching profile data using a profile remapping file is supported on a
+best-effort basis. For example, information regarding indirect call targets is
+currently not remapped. For best results, you are encouraged to generate new
+profile data matching the updated program, or to remap the profile data
+using the ``llvm-cxxmap`` and ``llvm-profdata merge`` tools.
+
+.. note::
+
+  Profile data remapping support is currently only implemented for LLVM's
+  new pass manager, which can be enabled with
+  ``-fexperimental-new-pass-manager``.
+
+.. note::
+
+  Profile data remapping is currently only supported for C++ mangled names
+  following the Itanium C++ ABI mangling scheme. This covers all C++ targets
+  supported by Clang other than Windows.
+
+GCOV-based Profiling
+--------------------
+
+GCOV is a test coverage program, it helps to know how often a line of code
+is executed. When instrumenting the code with ``--coverage`` option, some
+counters are added for each edge linking basic blocks.
+
+At compile time, gcno files are generated containing information about
+blocks and edges between them. At runtime the counters are incremented and at
+exit the counters are dumped in gcda files.
+
+The tool ``llvm-cov gcov`` will parse gcno, gcda and source files to generate
+a report ``.c.gcov``.
+
+.. option:: -fprofile-filter-files=[regexes]
+
+  Define a list of regexes separated by a semi-colon.
+  If a file name matches any of the regexes then the file is instrumented.
+
+   .. code-block:: console
+
+     $ clang --coverage -fprofile-filter-files=".*\.c$" foo.c
+
+  For example, this will only instrument files finishing with ``.c``, skipping ``.h`` files.
+
+.. option:: -fprofile-exclude-files=[regexes]
+
+  Define a list of regexes separated by a semi-colon.
+  If a file name doesn't match all the regexes then the file is instrumented.
+
+  .. code-block:: console
+
+     $ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" foo.c
+
+  For example, this will instrument all the files except the ones in ``/usr/include``.
+
+If both options are used then a file is instrumented if its name matches any
+of the regexes from ``-fprofile-filter-list`` and doesn't match all the regexes
+from ``-fprofile-exclude-list``.
+
+.. code-block:: console
+
+   $ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" \
+           -fprofile-filter-files="^/usr/.*$"
+          
+In that case ``/usr/foo/oof.h`` is instrumented since it matches the filter regex and
+doesn't match the exclude regex, but ``/usr/include/foo.h`` doesn't since it matches
+the exclude regex.
+
 Controlling Debug Information
 -----------------------------
 
@@ -2073,7 +2436,7 @@ comment(lib)`` are well supported.
 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
-<http://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
+<https://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
 a common compatibility issue with clang. This flag is enabled by default
 for Windows targets.
 
@@ -2112,10 +2475,15 @@ Controlling implementation limits
   Sets the limit for recursive constexpr function invocations to N.  The
   default is 512.
 
+.. option:: -fconstexpr-steps=N
+
+  Sets the limit for the number of full-expressions evaluated in a single
+  constant expression evaluation.  The default is 1048576.
+
 .. option:: -ftemplate-depth=N
 
   Sets the limit for recursively nested template instantiations to N.  The
-  default is 256.
+  default is 1024.
 
 .. option:: -foperator-arrow-depth=N
 
@@ -2137,13 +2505,8 @@ Objective-C++ Language Features
 OpenMP Features
 ===============
 
-Clang supports all OpenMP 3.1 directives and clauses.  In addition, some
-features of OpenMP 4.0 are supported.  For example, ``#pragma omp simd``,
-``#pragma omp for simd``, ``#pragma omp parallel for simd`` directives, extended
-set of atomic constructs, ``proc_bind`` clause for all parallel-based
-directives, ``depend`` clause for ``#pragma omp task`` directive (except for
-array sections), ``#pragma omp cancel`` and ``#pragma omp cancellation point``
-directives, and ``#pragma omp taskgroup`` directive.
+Clang supports all OpenMP 4.5 directives and clauses. See :doc:`OpenMPSupport`
+for additional details.
 
 Use `-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with
 `-fno-openmp`.
@@ -2201,7 +2564,8 @@ Compiling to bitcode can be done as follows:
 This will produce a generic test.bc file that can be used in vendor toolchains
 to perform machine code generation.
 
-Clang currently supports OpenCL C language standards up to v2.0.
+Clang currently supports OpenCL C language standards up to v2.0. Starting from
+clang 9 a C++ mode is available for OpenCL (see :ref:`C++ for OpenCL <opencl_cpp>`).
 
 OpenCL Specific Options
 -----------------------
@@ -2560,6 +2924,46 @@ There are some standard OpenCL functions that are implemented as Clang builtins:
   enqueue query functions from `section 6.13.17.5
   <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171>`_.
 
+.. _opencl_cpp:
+
+C++ for OpenCL
+--------------
+
+Starting from clang 9 kernel code can contain C++17 features: classes, templates,
+function overloading, type deduction, etc. Please note that this is not an
+implementation of `OpenCL C++
+<https://www.khronos.org/registry/OpenCL/specs/2.2/pdf/OpenCL_Cxx.pdf>`_ and
+there is no plan to support it in clang in any new releases in the near future.
+
+For detailed information about restrictions to allowed C++ features please
+refer to :doc:`LanguageExtensions`.
+
+Since C++ features are to be used on top of OpenCL C functionality, all existing
+restrictions from OpenCL C v2.0 will inherently apply. All OpenCL C builtin types
+and function libraries are supported and can be used in this mode.
+
+To enable the C++ for OpenCL mode, pass one of following command line options when
+compiling ``.cl`` file ``-cl-std=clc++``, ``-cl-std=CLC++``, ``-std=clc++`` or
+``-std=CLC++``.
+
+   .. code-block:: c++
+
+     template<class T> T add( T x, T y )
+     {
+       return x + y;
+     }
+
+     __kernel void test( __global float* a, __global float* b)
+     {
+       auto index = get_global_id(0);
+       a[index] = add(b[index], b[index+1]);
+     }
+
+
+   .. code-block:: console
+
+     clang -cl-std=clc++ test.cl
+
 .. _target_features:
 
 Target-Specific Features and Limitations
@@ -2572,7 +2976,7 @@ 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 (macOS), Linux, FreeBSD, and Dragonfly BSD: it has been tested
 to correctly compile many large C, C++, Objective-C, and Objective-C++
 codebases.
 
@@ -2627,8 +3031,8 @@ backend.
 Operating System Features and Limitations
 -----------------------------------------
 
-Darwin (Mac OS X)
-^^^^^^^^^^^^^^^^^
+Darwin (macOS)
+^^^^^^^^^^^^^^
 
 Thread Sanitizer is not supported.
 
@@ -2695,19 +3099,20 @@ compatibility with the Visual C++ compiler, cl.exe.
 To enable clang-cl to find system headers, libraries, and the linker when run
 from the command-line, it should be executed inside a Visual Studio Native Tools
 Command Prompt or a regular Command Prompt where the environment has been set
-up using e.g. `vcvarsall.bat <http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
+up using e.g. `vcvarsall.bat <https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
 
 clang-cl can also be used from inside Visual Studio by selecting the LLVM
-Platform Toolset. The toolset is installed by the LLVM installer, which can be
-downloaded from the `LLVM release <http://releases.llvm.org/download.html>`_ or
-`snapshot build <http://llvm.org/builds/>`_ web pages. To use the toolset,
-select a project in Solution Explorer, open its Property Page (Alt+F7), and in
-the "General" section of "Configuration Properties" change "Platform Toolset"
-to e.g. LLVM-vs2014.
+Platform Toolset. The toolset is not part of the installer, but may be installed
+separately from the
+`Visual Studio Marketplace <https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.llvm-toolchain>`_.
+To use the toolset, select a project in Solution Explorer, open its Property
+Page (Alt+F7), and in the "General" section of "Configuration Properties"
+change "Platform Toolset" to LLVM.  Doing so enables an additional Property
+Page for selecting the clang-cl executable to use for builds.
 
 To use the toolset with MSBuild directly, invoke it with e.g.
-``/p:PlatformToolset=LLVM-vs2014``. This allows trying out the clang-cl
-toolchain without modifying your project files.
+``/p:PlatformToolset=LLVM``. This allows trying out the clang-cl toolchain
+without modifying your project files.
 
 It's also possible to point MSBuild at clang-cl without changing toolset by
 passing ``/p:CLToolPath=c:\llvm\bin /p:CLToolExe=clang-cl.exe``.
@@ -2716,7 +3121,7 @@ When using CMake and the Visual Studio generators, the toolset can be set with t
 
   ::
 
-    cmake -G"Visual Studio 15 2017" -T LLVM-vs2014 ..
+    cmake -G"Visual Studio 15 2017" -T LLVM ..
 
 When using CMake with the Ninja generator, set the ``CMAKE_C_COMPILER`` and
 ``CMAKE_CXX_COMPILER`` variables to clang-cl:
@@ -2763,8 +3168,10 @@ Execute ``clang-cl /?`` to see a list of supported options:
       /arch:<value>           Set architecture for code generation
       /Brepro-                Emit an object file which cannot be reproduced over time
       /Brepro                 Emit an object file which can be reproduced over time
+      /clang:<arg>            Pass <arg> to the clang driver
       /C                      Don't discard comments when preprocessing
       /c                      Compile only
+      /d1PP                   Retain macro definitions in /E mode
       /d1reportAllClassLayout Dump record layout information
       /diagnostics:caret      Enable caret and column diagnostics (on by default)
       /diagnostics:classic    Disable column and caret diagnostics
@@ -2791,19 +3198,23 @@ Execute ``clang-cl /?`` to see a list of supported options:
       /GA                     Assume thread-local variables are defined in the executable
       /Gd                     Set __cdecl as a default calling convention
       /GF-                    Disable string pooling
+      /GF                     Enable string pooling (default)
       /GR-                    Disable emission of RTTI data
       /Gregcall               Set __regcall as a default calling convention
       /GR                     Enable emission of RTTI data
       /Gr                     Set __fastcall as a default calling convention
       /GS-                    Disable buffer security check
-      /GS                     Enable buffer security check
-      /Gs<value>              Set stack probe size
+      /GS                     Enable buffer security check (default)
+      /Gs                     Use stack probes (default)
+      /Gs<value>              Set stack probe size (default 4096)
+      /guard:<value>          Enable Control Flow Guard with /guard:cf,
+                              or only the table with /guard:cf,nochecks
       /Gv                     Set __vectorcall as a default calling convention
       /Gw-                    Don't put each data item in its own section
       /Gw                     Put each data item in its own section
       /GX-                    Disable exception handling
       /GX                     Enable exception handling
-      /Gy-                    Don't put each function in its own section
+      /Gy-                    Don't put each function in its own section (default)
       /Gy                     Put each function in its own section
       /Gz                     Set __stdcall as a default calling convention
       /help                   Display available options
@@ -2817,16 +3228,28 @@ Execute ``clang-cl /?`` to see a list of supported options:
       /MD                     Use DLL run-time
       /MTd                    Use static debug run-time
       /MT                     Use static run-time
+      /O0                     Disable optimization
+      /O1                     Optimize for size  (same as /Og     /Os /Oy /Ob2 /GF /Gy)
+      /O2                     Optimize for speed (same as /Og /Oi /Ot /Oy /Ob2 /GF /Gy)
+      /Ob0                    Disable function inlining
+      /Ob1                    Only inline functions which are (explicitly or implicitly) marked inline
+      /Ob2                    Inline functions as deemed beneficial by the compiler
       /Od                     Disable optimization
+      /Og                     No effect
       /Oi-                    Disable use of builtin functions
       /Oi                     Enable use of builtin functions
       /Os                     Optimize for size
       /Ot                     Optimize for speed
-      /O<value>               Optimization level
+      /Ox                     Deprecated (same as /Og /Oi /Ot /Oy /Ob2); use /O2 instead
+      /Oy-                    Disable frame pointer omission (x86 only, default)
+      /Oy                     Enable frame pointer omission (x86 only)
+      /O<flags>               Set multiple /O flags at once; e.g. '/O2y-' for '/O2 /Oy-'
       /o <file or directory>  Set output file or directory (ends in / or \)
       /P                      Preprocess to file
       /Qvec-                  Disable the loop vectorization passes
       /Qvec                   Enable the loop vectorization passes
+      /showFilenames-         Don't print the name of each compiled file (default)
+      /showFilenames          Print the name of each compiled file
       /showIncludes           Print info about included files to stderr
       /source-charset:<value> Source encoding, supports only UTF-8
       /std:<value>            Language standard to compile for
@@ -2853,10 +3276,15 @@ Execute ``clang-cl /?`` to see a list of supported options:
       /WX-                    Do not treat warnings as errors
       /WX                     Treat warnings as errors
       /w                      Disable all warnings
+      /X                      Don't add %INCLUDE% to the include search path
       /Y-                     Disable precompiled headers, overrides /Yc and /Yu
       /Yc<filename>           Generate a pch file for all code up to and including <filename>
       /Yu<filename>           Load a pch file and use it instead of all code up to and including <filename>
       /Z7                     Enable CodeView debug information in object files
+      /Zc:char8_t             Enable C++2a char8_t type
+      /Zc:char8_t-            Disable C++2a char8_t type
+      /Zc:dllexportInlines-   Don't dllexport/dllimport inline member functions of dllexport/import classes
+      /Zc:dllexportInlines    dllexport/dllimport inline member functions of dllexport/import classes (default)
       /Zc:sizedDealloc-       Disable C++14 sized global deallocation functions
       /Zc:sizedDealloc        Enable C++14 sized global deallocation functions
       /Zc:strictStrings       Treat string literals as const
@@ -2876,8 +3304,15 @@ Execute ``clang-cl /?`` to see a list of supported options:
     OPTIONS:
       -###                    Print (but do not run) the commands to run for this compilation
       --analyze               Run the static analyzer
+      -faddrsig               Emit an address-significance table
       -fansi-escape-codes     Use ANSI escape codes for diagnostics
+      -fblocks                Enable the 'blocks' language feature
+      -fcf-protection=<value> Instrument control-flow architecture protection. Options: return, branch, full, none.
+      -fcf-protection         Enable cf-protection in 'full' mode
       -fcolor-diagnostics     Use colors in diagnostics
+      -fcomplete-member-pointers
+                              Require member pointer base types to be complete if they would be significant under the Microsoft ABI
+      -fcoverage-mapping      Generate coverage mapping to enable code coverage analysis
       -fdebug-macro           Emit macro debug information
       -fdelayed-template-parsing
                               Parse templated function definitions at the end of the translation unit
@@ -2887,6 +3322,7 @@ Execute ``clang-cl /?`` to see a list of supported options:
                               Print fix-its in machine parseable form
       -flto=<value>           Set LTO mode to either 'full' or 'thin'
       -flto                   Enable LTO in 'full' mode
+      -fmerge-all-constants   Allow merging of constants
       -fms-compatibility-version=<value>
                               Dot-separated value representing the Microsoft compiler version
                               number to report in _MSC_VER (0 = don't define it (default))
@@ -2894,11 +3330,22 @@ Execute ``clang-cl /?`` to see a list of supported options:
       -fms-extensions         Accept some non-standard constructs supported by the Microsoft compiler
       -fmsc-version=<value>   Microsoft compiler version number to report in _MSC_VER
                               (0 = don't define it (default))
+      -fno-addrsig            Don't emit an address-significance table
+      -fno-builtin-<value>    Disable implicit builtin knowledge of a specific function
+      -fno-builtin            Disable implicit builtin knowledge of functions
+      -fno-complete-member-pointers
+                              Do not require member pointer base types to be complete if they would be significant under the Microsoft ABI
+      -fno-coverage-mapping   Disable code coverage analysis
+      -fno-crash-diagnostics  Disable auto-generation of preprocessed source files and a script for reproduction during a clang crash
       -fno-debug-macro        Do not emit macro debug information
       -fno-delayed-template-parsing
                               Disable delayed template parsing
+      -fno-sanitize-address-poison-custom-array-cookie
+                              Disable poisoning array cookies when using custom operator new[] in AddressSanitizer
       -fno-sanitize-address-use-after-scope
                               Disable use-after-scope detection in AddressSanitizer
+      -fno-sanitize-address-use-odr-indicator
+                              Disable ODR indicator globals
       -fno-sanitize-blacklist Don't use blacklist file for sanitizers
       -fno-sanitize-cfi-cross-dso
                               Disable control flow integrity (CFI) checks for cross-DSO calls.
@@ -2920,6 +3367,11 @@ Execute ``clang-cl /?`` to see a list of supported options:
       -fno-sanitize-trap=<value>
                               Disable trapping for specified sanitizers
       -fno-standalone-debug   Limit debug information produced to reduce size of debug binary
+      -fobjc-runtime=<value>  Specify the target Objective-C runtime kind and version
+      -fprofile-exclude-files=<value>
+                              Instrument only functions from files where names don't match all the regexes separated by a semi-colon
+      -fprofile-filter-files=<value>
+                              Instrument only functions from files where names match any regex separated by a semi-colon
       -fprofile-instr-generate=<file>
                               Generate instrumented code to collect execution counts into <file>
                               (overridden by LLVM_PROFILE_FILE env var)
@@ -2928,12 +3380,18 @@ Execute ``clang-cl /?`` to see a list of supported options:
                               (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
       -fprofile-instr-use=<value>
                               Use instrumentation data for profile-guided optimization
+      -fprofile-remapping-file=<file>
+                              Use the remappings described in <file> to match the profile data against names in the program
       -fsanitize-address-field-padding=<value>
                               Level of field padding for AddressSanitizer
       -fsanitize-address-globals-dead-stripping
                               Enable linker dead stripping of globals in AddressSanitizer
+      -fsanitize-address-poison-custom-array-cookie
+                              Enable poisoning array cookies when using custom operator new[] in AddressSanitizer
       -fsanitize-address-use-after-scope
                               Enable use-after-scope detection in AddressSanitizer
+      -fsanitize-address-use-odr-indicator
+                              Enable ODR indicator globals to avoid false ODR violation reports in partially sanitized programs at the cost of an increase in binary size
       -fsanitize-blacklist=<value>
                               Path to blacklist file for sanitizers
       -fsanitize-cfi-cross-dso
@@ -2942,6 +3400,8 @@ Execute ``clang-cl /?`` to see a list of supported options:
                               Generalize pointers in CFI indirect call type signature checks
       -fsanitize-coverage=<value>
                               Specify the type of coverage instrumentation for Sanitizers
+      -fsanitize-hwaddress-abi=<value>
+                              Select the HWAddressSanitizer ABI to target (interceptor or platform, default interceptor)
       -fsanitize-memory-track-origins=<value>
                               Enable origins tracking in MemorySanitizer
       -fsanitize-memory-track-origins
@@ -2962,9 +3422,12 @@ Execute ``clang-cl /?`` to see a list of supported options:
                               Strip (or keep only, if negative) a given number of path components when emitting check metadata.
       -fsanitize=<check>      Turn on runtime checks for various forms of undefined or suspicious
                               behavior. See user manual for available checks
+      -fsplit-lto-unit        Enables splitting of the LTO unit.
       -fstandalone-debug      Emit full debug info for all types used by the program
       -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto
+      -gcodeview-ghash        Emit type record hashes in a .debug$H section
       -gcodeview              Generate CodeView debug information
+      -gline-directives-only  Emit debug line info directives only
       -gline-tables-only      Emit debug line number tables only
       -miamcu                 Use Intel MCU ABI
       -mllvm <value>          Additional arguments to forward to LLVM's option processing
@@ -2977,6 +3440,92 @@ Execute ``clang-cl /?`` to see a list of supported options:
       -W<warning>             Enable the specified warning
       -Xclang <arg>           Pass <arg> to the clang compiler
 
+The /clang: Option
+^^^^^^^^^^^^^^^^^^
+
+When clang-cl is run with a set of ``/clang:<arg>`` options, it will gather all
+of the ``<arg>`` arguments and process them as if they were passed to the clang
+driver. This mechanism allows you to pass flags that are not exposed in the
+clang-cl options or flags that have a different meaning when passed to the clang
+driver. Regardless of where they appear in the command line, the ``/clang:``
+arguments are treated as if they were passed at the end of the clang-cl command
+line.
+
+The /Zc:dllexportInlines- Option
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This causes the class-level `dllexport` and `dllimport` attributes to not apply
+to inline member functions, as they otherwise would. For example, in the code
+below `S::foo()` would normally be defined and exported by the DLL, but when
+using the ``/Zc:dllexportInlines-`` flag it is not:
+
+.. code-block:: c
+
+  struct __declspec(dllexport) S {
+    void foo() {}
+  }
+
+This has the benefit that the compiler doesn't need to emit a definition of
+`S::foo()` in every translation unit where the declaration is included, as it
+would otherwise do to ensure there's a definition in the DLL even if it's not
+used there. If the declaration occurs in a header file that's widely used, this
+can save significant compilation time and output size. It also reduces the
+number of functions exported by the DLL similarly to what
+``-fvisibility-inlines-hidden`` does for shared objects on ELF and Mach-O.
+Since the function declaration comes with an inline definition, users of the
+library can use that definition directly instead of importing it from the DLL.
+
+Note that the Microsoft Visual C++ compiler does not support this option, and
+if code in a DLL is compiled with ``/Zc:dllexportInlines-``, the code using the
+DLL must be compiled in the same way so that it doesn't attempt to dllimport
+the inline member functions. The reverse scenario should generally work though:
+a DLL compiled without this flag (such as a system library compiled with Visual
+C++) can be referenced from code compiled using the flag, meaning that the
+referencing code will use the inline definitions instead of importing them from
+the DLL.
+
+Also note that like when using ``-fvisibility-inlines-hidden``, the address of
+`S::foo()` will be different inside and outside the DLL, breaking the C/C++
+standard requirement that functions have a unique address.
+
+The flag does not apply to explicit class template instantiation definitions or
+declarations, as those are typically used to explicitly provide a single
+definition in a DLL, (dllexported instantiation definition) or to signal that
+the definition is available elsewhere (dllimport instantiation declaration). It
+also doesn't apply to inline members with static local variables, to ensure
+that the same instance of the variable is used inside and outside the DLL.
+
+Using this flag can cause problems when inline functions that would otherwise
+be dllexported refer to internal symbols of a DLL. For example:
+
+.. code-block:: c
+
+  void internal();
+
+  struct __declspec(dllimport) S {
+    void foo() { internal(); }
+  }
+
+Normally, references to `S::foo()` would use the definition in the DLL from
+which it was exported, and which presumably also has the definition of
+`internal()`. However, when using ``/Zc:dllexportInlines-``, the inline
+definition of `S::foo()` is used directly, resulting in a link error since
+`internal()` is not available. Even worse, if there is an inline definition of
+`internal()` containing a static local variable, we will now refer to a
+different instance of that variable than in the DLL:
+
+.. code-block:: c
+
+  inline int internal() { static int x; return x++; }
+
+  struct __declspec(dllimport) S {
+    int foo() { return internal(); }
+  }
+
+This could lead to very subtle bugs. Using ``-fvisibility-inlines-hidden`` can
+lead to the same issue. To avoid it in this case, make `S::foo()` or
+`internal()` non-inline, or mark them `dllimport/dllexport` explicitly.
+
 The /fallback Option
 ^^^^^^^^^^^^^^^^^^^^
 

docs/analyzer/checkers.rst

@@ -0,0 +1,2350 @@
+==================
+Available Checkers
+==================
+
+The analyzer performs checks that are categorized into families or "checkers".
+
+The default set of checkers covers a variety of checks targeted at finding security and API usage bugs,
+dead code, and other logic errors. See the :ref:`default-checkers` checkers list below.
+
+In addition to these, the analyzer contains a number of :ref:`alpha-checkers` (aka *alpha* checkers).
+These checkers are under development and are switched off by default. They may crash or emit a higher number of false positives.
+
+The :ref:`debug-checkers` package contains checkers for analyzer developers for debugging purposes.
+
+.. contents:: Table of Contents
+   :depth: 4
+
+
+.. _default-checkers:
+
+Default Checkers
+----------------
+
+.. _core-checkers:
+
+core
+^^^^
+Models core language features and contains general-purpose checkers such as division by zero,
+null pointer dereference, usage of uninitialized values, etc.
+*These checkers must be always switched on as other checker rely on them.*
+
+.. _core-CallAndMessage:
+
+core.CallAndMessage (C, C++, ObjC)
+""""""""""""""""""""""""""""""""""
+ Check for logical errors for function calls and Objective-C message expressions (e.g., uninitialized arguments, null function pointers).
+
+.. literalinclude:: checkers/callandmessage_example.c
+    :language: objc
+
+.. _core-DivideZero:
+
+core.DivideZero (C, C++, ObjC)
+""""""""""""""""""""""""""""""
+ Check for division by zero.
+
+.. literalinclude:: checkers/dividezero_example.c
+    :language: c
+
+.. _core-NonNullParamChecker:
+
+core.NonNullParamChecker (C, C++, ObjC)
+"""""""""""""""""""""""""""""""""""""""
+Check for null pointers passed as arguments to a function whose arguments are references or marked with the 'nonnull' attribute.
+
+.. code-block:: cpp
+
+ int f(int *p) __attribute__((nonnull));
+
+ void test(int *p) {
+   if (!p)
+     f(p); // warn
+ }
+
+.. _core-NullDereference:
+
+core.NullDereference (C, C++, ObjC)
+"""""""""""""""""""""""""""""""""""
+Check for dereferences of null pointers.
+
+.. code-block:: objc
+
+ // C
+ void test(int *p) {
+   if (p)
+     return;
+
+   int x = p[0]; // warn
+ }
+
+ // C
+ void test(int *p) {
+   if (!p)
+     *p = 0; // warn
+ }
+
+ // C++
+ class C {
+ public:
+   int x;
+ };
+
+ void test() {
+   C *pc = 0;
+   int k = pc->x; // warn
+ }
+
+ // Objective-C
+ @interface MyClass {
+ @public
+   int x;
+ }
+ @end
+
+ void test() {
+   MyClass *obj = 0;
+   obj->x = 1; // warn
+ }
+
+.. _core-StackAddressEscape:
+
+core.StackAddressEscape (C)
+"""""""""""""""""""""""""""
+Check that addresses to stack memory do not escape the function.
+
+.. code-block:: c
+
+ char const *p;
+
+ void test() {
+   char const str[] = "string";
+   p = str; // warn
+ }
+
+ void* test() {
+    return __builtin_alloca(12); // warn
+ }
+
+ void test() {
+   static int *x;
+   int y;
+   x = &y; // warn
+ }
+
+
+.. _core-UndefinedBinaryOperatorResult:
+
+core.UndefinedBinaryOperatorResult (C)
+""""""""""""""""""""""""""""""""""""""
+Check for undefined results of binary operators.
+
+.. code-block:: c
+
+ void test() {
+   int x;
+   int y = x + 1; // warn: left operand is garbage
+ }
+
+.. _core-VLASize:
+
+core.VLASize (C)
+""""""""""""""""
+Check for declarations of Variable Length Arrays of undefined or zero size.
+
+ Check for declarations of VLA of undefined or zero size.
+
+.. code-block:: c
+
+ void test() {
+   int x;
+   int vla1[x]; // warn: garbage as size
+ }
+
+ void test() {
+   int x = 0;
+   int vla2[x]; // warn: zero size
+ }
+
+.. _core-uninitialized-ArraySubscript:
+
+core.uninitialized.ArraySubscript (C)
+"""""""""""""""""""""""""""""""""""""
+Check for uninitialized values used as array subscripts.
+
+.. code-block:: c
+
+ void test() {
+   int i, a[10];
+   int x = a[i]; // warn: array subscript is undefined
+ }
+
+.. _core-uninitialized-Assign:
+
+core.uninitialized.Assign (C)
+"""""""""""""""""""""""""""""
+Check for assigning uninitialized values.
+
+.. code-block:: c
+
+ void test() {
+   int x;
+   x |= 1; // warn: left expression is uninitialized
+ }
+
+.. _core-uninitialized-Branch:
+
+core.uninitialized.Branch (C)
+"""""""""""""""""""""""""""""
+Check for uninitialized values used as branch conditions.
+
+.. code-block:: c
+
+ void test() {
+   int x;
+   if (x) // warn
+     return;
+ }
+
+.. _core-uninitialized-CapturedBlockVariable:
+
+core.uninitialized.CapturedBlockVariable (C)
+""""""""""""""""""""""""""""""""""""""""""""
+Check for blocks that capture uninitialized values.
+
+.. code-block:: c
+
+ void test() {
+   int x;
+   ^{ int y = x; }(); // warn
+ }
+
+.. _core-uninitialized-UndefReturn:
+
+core.uninitialized.UndefReturn (C)
+""""""""""""""""""""""""""""""""""
+Check for uninitialized values being returned to the caller.
+
+.. code-block:: c
+
+ int test() {
+   int x;
+   return x; // warn
+ }
+
+.. _cplusplus-checkers:
+
+
+cplusplus
+^^^^^^^^^
+
+C++ Checkers.
+
+.. _cplusplus-InnerPointer:
+
+cplusplus.InnerPointer (C++)
+""""""""""""""""""""""""""""
+Check for inner pointers of C++ containers used after re/deallocation.
+
+Many container methods in the C++ standard library are known to invalidate
+"references" (including actual references, iterators and raw pointers) to
+elements of the container. Using such references after they are invalidated
+causes undefined behavior, which is a common source of memory errors in C++ that
+this checker is capable of finding.
+
+The checker is currently limited to ``std::string`` objects and doesn't
+recognize some of the more sophisticated approaches to passing unowned pointers
+around, such as ``std::string_view``.
+
+.. code-block:: cpp
+
+ void deref_after_assignment() {
+   std::string s = "llvm";
+   const char *c = s.data(); // note: pointer to inner buffer of 'std::string' obtained here
+   s = "clang"; // note: inner buffer of 'std::string' reallocated by call to 'operator='
+   consume(c); // warn: inner pointer of container used after re/deallocation
+ }
+
+ const char *return_temp(int x) {
+   return std::to_string(x).c_str(); // warn: inner pointer of container used after re/deallocation
+   // note: pointer to inner buffer of 'std::string' obtained here
+   // note: inner buffer of 'std::string' deallocated by call to destructor
+ }
+
+.. _cplusplus-NewDelete:
+
+cplusplus.NewDelete (C++)
+"""""""""""""""""""""""""
+Check for double-free and use-after-free problems. Traces memory managed by new/delete.
+
+.. literalinclude:: checkers/newdelete_example.cpp
+    :language: cpp
+
+.. _cplusplus-NewDeleteLeaks:
+
+cplusplus.NewDeleteLeaks (C++)
+""""""""""""""""""""""""""""""
+Check for memory leaks. Traces memory managed by new/delete.
+
+.. code-block:: cpp
+
+ void test() {
+   int *p = new int;
+ } // warn
+
+
+.. _cplusplus-SelfAssignment:
+
+cplusplus.SelfAssignment (C++)
+""""""""""""""""""""""""""""""
+Checks C++ copy and move assignment operators for self assignment.
+
+.. _deadcode-checkers:
+
+deadcode
+^^^^^^^^
+
+Dead Code Checkers.
+
+.. _deadcode-DeadStores:
+
+deadcode.DeadStores (C)
+"""""""""""""""""""""""
+Check for values stored to variables that are never read afterwards.
+
+.. code-block:: c
+
+ void test() {
+   int x;
+   x = 1; // warn
+ }
+
+The ``WarnForDeadNestedAssignments`` option enables the checker to emit
+warnings for nested dead assignments. You can disable with the
+``-analyzer-config deadcode.DeadStores:WarnForDeadNestedAssignments=false``.
+*Defaults to true*.
+
+Would warn for this e.g.:
+if ((y = make_int())) {
+}
+
+.. _nullability-checkers:
+
+nullability
+^^^^^^^^^^^
+
+Objective C checkers that warn for null pointer passing and dereferencing errors.
+
+.. _nullability-NullPassedToNonnull:
+
+nullability.NullPassedToNonnull (ObjC)
+""""""""""""""""""""""""""""""""""""""
+Warns when a null pointer is passed to a pointer which has a _Nonnull type.
+
+.. code-block:: objc
+
+ if (name != nil)
+   return;
+ // Warning: nil passed to a callee that requires a non-null 1st parameter
+ NSString *greeting = [@"Hello " stringByAppendingString:name];
+
+.. _nullability-NullReturnedFromNonnull:
+
+nullability.NullReturnedFromNonnull (ObjC)
+""""""""""""""""""""""""""""""""""""""""""
+Warns when a null pointer is returned from a function that has _Nonnull return type.
+
+.. code-block:: objc
+
+ - (nonnull id)firstChild {
+   id result = nil;
+   if ([_children count] > 0)
+     result = _children[0];
+
+   // Warning: nil returned from a method that is expected
+   // to return a non-null value
+   return result;
+ }
+
+.. _nullability-NullableDereferenced:
+
+nullability.NullableDereferenced (ObjC)
+"""""""""""""""""""""""""""""""""""""""
+Warns when a nullable pointer is dereferenced.
+
+.. code-block:: objc
+
+ struct LinkedList {
+   int data;
+   struct LinkedList *next;
+ };
+
+ struct LinkedList * _Nullable getNext(struct LinkedList *l);
+
+ void updateNextData(struct LinkedList *list, int newData) {
+   struct LinkedList *next = getNext(list);
+   // Warning: Nullable pointer is dereferenced
+   next->data = 7;
+ }
+
+.. _nullability-NullablePassedToNonnull:
+
+nullability.NullablePassedToNonnull (ObjC)
+""""""""""""""""""""""""""""""""""""""""""
+Warns when a nullable pointer is passed to a pointer which has a _Nonnull type.
+
+.. code-block:: objc
+
+ typedef struct Dummy { int val; } Dummy;
+ Dummy *_Nullable returnsNullable();
+ void takesNonnull(Dummy *_Nonnull);
+
+ void test() {
+   Dummy *p = returnsNullable();
+   takesNonnull(p); // warn
+ }
+
+.. _nullability-NullableReturnedFromNonnull:
+
+nullability.NullableReturnedFromNonnull (ObjC)
+""""""""""""""""""""""""""""""""""""""""""""""
+Warns when a nullable pointer is returned from a function that has _Nonnull return type.
+
+.. _optin-checkers:
+
+optin
+^^^^^
+
+Checkers for portability, performance or coding style specific rules.
+
+.. _optin-cplusplus-UninitializedObject:
+
+optin.cplusplus.UninitializedObject (C++)
+"""""""""""""""""""""""""""""""""""""""""
+
+This checker reports uninitialized fields in objects created after a constructor
+call. It doesn't only find direct uninitialized fields, but rather makes a deep
+inspection of the object, analyzing all of it's fields subfields.
+The checker regards inherited fields as direct fields, so one will recieve
+warnings for uninitialized inherited data members as well.
+
+.. code-block:: cpp
+
+ // With Pedantic and CheckPointeeInitialization set to true
+
+ struct A {
+   struct B {
+     int x; // note: uninitialized field 'this->b.x'
+     // note: uninitialized field 'this->bptr->x'
+     int y; // note: uninitialized field 'this->b.y'
+     // note: uninitialized field 'this->bptr->y'
+   };
+   int *iptr; // note: uninitialized pointer 'this->iptr'
+   B b;
+   B *bptr;
+   char *cptr; // note: uninitialized pointee 'this->cptr'
+
+   A (B *bptr, char *cptr) : bptr(bptr), cptr(cptr) {}
+ };
+
+ void f() {
+   A::B b;
+   char c;
+   A a(&b, &c); // warning: 6 uninitialized fields
+  //          after the constructor call
+ }
+
+ // With Pedantic set to false and
+ // CheckPointeeInitialization set to true
+ // (every field is uninitialized)
+
+ struct A {
+   struct B {
+     int x;
+     int y;
+   };
+   int *iptr;
+   B b;
+   B *bptr;
+   char *cptr;
+
+   A (B *bptr, char *cptr) : bptr(bptr), cptr(cptr) {}
+ };
+
+ void f() {
+   A::B b;
+   char c;
+   A a(&b, &c); // no warning
+ }
+
+ // With Pedantic set to true and
+ // CheckPointeeInitialization set to false
+ // (pointees are regarded as initialized)
+
+ struct A {
+   struct B {
+     int x; // note: uninitialized field 'this->b.x'
+     int y; // note: uninitialized field 'this->b.y'
+   };
+   int *iptr; // note: uninitialized pointer 'this->iptr'
+   B b;
+   B *bptr;
+   char *cptr;
+
+   A (B *bptr, char *cptr) : bptr(bptr), cptr(cptr) {}
+ };
+
+ void f() {
+   A::B b;
+   char c;
+   A a(&b, &c); // warning: 3 uninitialized fields
+  //          after the constructor call
+ }
+
+
+**Options**
+
+This checker has several options which can be set from command line (e.g.
+``-analyzer-config optin.cplusplus.UninitializedObject:Pedantic=true``):
+
+* ``Pedantic`` (boolean). If to false, the checker won't emit warnings for
+  objects that don't have at least one initialized field. Defaults to false.
+
+* ``NotesAsWarnings``  (boolean). If set to true, the checker will emit a
+  warning for each uninitalized field, as opposed to emitting one warning per
+  constructor call, and listing the uninitialized fields that belongs to it in
+  notes. *Defaults to false*.
+
+* ``CheckPointeeInitialization`` (boolean). If set to false, the checker will
+  not analyze the pointee of pointer/reference fields, and will only check
+  whether the object itself is initialized. *Defaults to false*.
+
+* ``IgnoreRecordsWithField`` (string). If supplied, the checker will not analyze
+  structures that have a field with a name or type name that matches  the given
+  pattern. *Defaults to ""*.
+
+.. _optin-cplusplus-VirtualCall:
+
+optin.cplusplus.VirtualCall (C++)
+"""""""""""""""""""""""""""""""""
+Check virtual function calls during construction or destruction.
+
+.. code-block:: cpp
+
+ class A {
+ public:
+   A() {
+     f(); // warn
+   }
+   virtual void f();
+ };
+
+ class A {
+ public:
+   ~A() {
+     this->f(); // warn
+   }
+   virtual void f();
+ };
+
+.. _optin-mpi-MPI-Checker:
+
+optin.mpi.MPI-Checker (C)
+"""""""""""""""""""""""""
+Checks MPI code.
+
+.. code-block:: c
+
+ void test() {
+   double buf = 0;
+   MPI_Request sendReq1;
+   MPI_Ireduce(MPI_IN_PLACE, &buf, 1, MPI_DOUBLE, MPI_SUM,
+       0, MPI_COMM_WORLD, &sendReq1);
+ } // warn: request 'sendReq1' has no matching wait.
+
+ void test() {
+   double buf = 0;
+   MPI_Request sendReq;
+   MPI_Isend(&buf, 1, MPI_DOUBLE, 0, 0, MPI_COMM_WORLD, &sendReq);
+   MPI_Irecv(&buf, 1, MPI_DOUBLE, 0, 0, MPI_COMM_WORLD, &sendReq); // warn
+   MPI_Isend(&buf, 1, MPI_DOUBLE, 0, 0, MPI_COMM_WORLD, &sendReq); // warn
+   MPI_Wait(&sendReq, MPI_STATUS_IGNORE);
+ }
+
+ void missingNonBlocking() {
+   int rank = 0;
+   MPI_Comm_rank(MPI_COMM_WORLD, &rank);
+   MPI_Request sendReq1[10][10][10];
+   MPI_Wait(&sendReq1[1][7][9], MPI_STATUS_IGNORE); // warn
+ }
+
+.. _optin-osx-cocoa-localizability-EmptyLocalizationContextChecker:
+
+optin.osx.cocoa.localizability.EmptyLocalizationContextChecker (ObjC)
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Check that NSLocalizedString macros include a comment for context.
+
+.. code-block:: objc
+
+ - (void)test {
+   NSString *string = NSLocalizedString(@"LocalizedString", nil); // warn
+   NSString *string2 = NSLocalizedString(@"LocalizedString", @" "); // warn
+   NSString *string3 = NSLocalizedStringWithDefaultValue(
+     @"LocalizedString", nil, [[NSBundle alloc] init], nil,@""); // warn
+ }
+
+.. _optin-osx-cocoa-localizability-NonLocalizedStringChecker:
+
+optin.osx.cocoa.localizability.NonLocalizedStringChecker (ObjC)
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Warns about uses of non-localized NSStrings passed to UI methods expecting localized NSStrings.
+
+.. code-block:: objc
+
+ NSString *alarmText =
+   NSLocalizedString(@"Enabled", @"Indicates alarm is turned on");
+ if (!isEnabled) {
+   alarmText = @"Disabled";
+ }
+ UILabel *alarmStateLabel = [[UILabel alloc] init];
+
+ // Warning: User-facing text should use localized string macro
+ [alarmStateLabel setText:alarmText];
+
+.. _optin-performance-GCDAntipattern:
+
+optin.performance.GCDAntipattern
+""""""""""""""""""""""""""""""""
+Check for performance anti-patterns when using Grand Central Dispatch.
+
+.. _optin-performance-Padding:
+
+optin.performance.Padding
+"""""""""""""""""""""""""
+Check for excessively padded structs.
+
+.. _optin-portability-UnixAPI:
+
+optin.portability.UnixAPI
+"""""""""""""""""""""""""
+Finds implementation-defined behavior in UNIX/Posix functions.
+
+
+.. _security-checkers:
+
+security
+^^^^^^^^
+
+Security related checkers.
+
+.. _security-FloatLoopCounter:
+
+security.FloatLoopCounter (C)
+"""""""""""""""""""""""""""""
+Warn on using a floating point value as a loop counter (CERT: FLP30-C, FLP30-CPP).
+
+.. code-block:: c
+
+ void test() {
+   for (float x = 0.1f; x <= 1.0f; x += 0.1f) {} // warn
+ }
+
+.. _security-insecureAPI-UncheckedReturn:
+
+security.insecureAPI.UncheckedReturn (C)
+""""""""""""""""""""""""""""""""""""""""
+Warn on uses of functions whose return values must be always checked.
+
+.. code-block:: c
+
+ void test() {
+   setuid(1); // warn
+ }
+
+.. _security-insecureAPI-bcmp:
+
+security.insecureAPI.bcmp (C)
+"""""""""""""""""""""""""""""
+Warn on uses of the 'bcmp' function.
+
+.. code-block:: c
+
+ void test() {
+   bcmp(ptr0, ptr1, n); // warn
+ }
+
+.. _security-insecureAPI-bcopy:
+
+security.insecureAPI.bcopy (C)
+""""""""""""""""""""""""""""""
+Warn on uses of the 'bcopy' function.
+
+.. code-block:: c
+
+ void test() {
+   bcopy(src, dst, n); // warn
+ }
+
+.. _security-insecureAPI-bzero:
+
+security.insecureAPI.bzero (C)
+""""""""""""""""""""""""""""""
+Warn on uses of the 'bzero' function.
+
+.. code-block:: c
+
+ void test() {
+   bzero(ptr, n); // warn
+ }
+
+.. _security-insecureAPI-getpw:
+
+security.insecureAPI.getpw (C)
+""""""""""""""""""""""""""""""
+Warn on uses of the 'getpw' function.
+
+.. code-block:: c
+
+ void test() {
+   char buff[1024];
+   getpw(2, buff); // warn
+ }
+
+.. _security-insecureAPI-gets:
+
+security.insecureAPI.gets (C)
+"""""""""""""""""""""""""""""
+Warn on uses of the 'gets' function.
+
+.. code-block:: c
+
+ void test() {
+   char buff[1024];
+   gets(buff); // warn
+ }
+
+.. _security-insecureAPI-mkstemp:
+
+security.insecureAPI.mkstemp (C)
+""""""""""""""""""""""""""""""""
+Warn when 'mkstemp' is passed fewer than 6 X's in the format string.
+
+.. code-block:: c
+
+ void test() {
+   mkstemp("XX"); // warn
+ }
+
+.. _security-insecureAPI-mktemp:
+
+security.insecureAPI.mktemp (C)
+"""""""""""""""""""""""""""""""
+Warn on uses of the ``mktemp`` function.
+
+.. code-block:: c
+
+ void test() {
+   char *x = mktemp("/tmp/zxcv"); // warn: insecure, use mkstemp
+ }
+
+.. _security-insecureAPI-rand:
+
+security.insecureAPI.rand (C)
+"""""""""""""""""""""""""""""
+Warn on uses of inferior random number generating functions (only if arc4random function is available):
+``drand48, erand48, jrand48, lcong48, lrand48, mrand48, nrand48, random, rand_r``.
+
+.. code-block:: c
+
+ void test() {
+   random(); // warn
+ }
+
+.. _security-insecureAPI-strcpy:
+
+security.insecureAPI.strcpy (C)
+"""""""""""""""""""""""""""""""
+Warn on uses of the ``strcpy`` and ``strcat`` functions.
+
+.. code-block:: c
+
+ void test() {
+   char x[4];
+   char *y = "abcd";
+
+   strcpy(x, y); // warn
+ }
+
+
+.. _security-insecureAPI-vfork:
+
+security.insecureAPI.vfork (C)
+""""""""""""""""""""""""""""""
+ Warn on uses of the 'vfork' function.
+
+.. code-block:: c
+
+ void test() {
+   vfork(); // warn
+ }
+
+.. _security-insecureAPI-DeprecatedOrUnsafeBufferHandling:
+
+security.insecureAPI.DeprecatedOrUnsafeBufferHandling (C)
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+ Warn on occurrences of unsafe or deprecated buffer handling functions, which now have a secure variant: ``sprintf, vsprintf, scanf, wscanf, fscanf, fwscanf, vscanf, vwscanf, vfscanf, vfwscanf, sscanf, swscanf, vsscanf, vswscanf, swprintf, snprintf, vswprintf, vsnprintf, memcpy, memmove, strncpy, strncat, memset``
+
+.. code-block:: c
+
+ void test() {
+   char buf [5];
+   strncpy(buf, "a", 1); // warn
+ }
+
+.. _unix-checkers:
+
+unix
+^^^^
+POSIX/Unix checkers.
+
+.. _unix-API:
+
+unix.API (C)
+""""""""""""
+Check calls to various UNIX/Posix functions: ``open, pthread_once, calloc, malloc, realloc, alloca``.
+
+.. literalinclude:: checkers/unix_api_example.c
+    :language: c
+
+.. _unix-Malloc:
+
+unix.Malloc (C)
+"""""""""""""""
+Check for memory leaks, double free, and use-after-free problems. Traces memory managed by malloc()/free().
+
+.. literalinclude:: checkers/unix_malloc_example.c
+    :language: c
+
+.. _unix-MallocSizeof:
+
+unix.MallocSizeof (C)
+"""""""""""""""""""""
+Check for dubious ``malloc`` arguments involving ``sizeof``.
+
+.. code-block:: c
+
+ void test() {
+   long *p = malloc(sizeof(short));
+     // warn: result is converted to 'long *', which is
+     // incompatible with operand type 'short'
+   free(p);
+ }
+
+.. _unix-MismatchedDeallocator:
+
+unix.MismatchedDeallocator (C, C++)
+"""""""""""""""""""""""""""""""""""
+Check for mismatched deallocators.
+
+.. literalinclude:: checkers/mismatched_deallocator_example.cpp
+    :language: c
+
+.. _unix-Vfork:
+
+unix.Vfork (C)
+""""""""""""""
+Check for proper usage of ``vfork``.
+
+.. code-block:: c
+
+ int test(int x) {
+   pid_t pid = vfork(); // warn
+   if (pid != 0)
+     return 0;
+
+   switch (x) {
+   case 0:
+     pid = 1;
+     execl("", "", 0);
+     _exit(1);
+     break;
+   case 1:
+     x = 0; // warn: this assignment is prohibited
+     break;
+   case 2:
+     foo(); // warn: this function call is prohibited
+     break;
+   default:
+     return 0; // warn: return is prohibited
+   }
+
+   while(1);
+ }
+
+.. _unix-cstring-BadSizeArg:
+
+unix.cstring.BadSizeArg (C)
+"""""""""""""""""""""""""""
+Check the size argument passed into C string functions for common erroneous patterns. Use ``-Wno-strncat-size`` compiler option to mute other ``strncat``-related compiler warnings.
+
+.. code-block:: c
+
+ void test() {
+   char dest[3];
+   strncat(dest, """""""""""""""""""""""""*", sizeof(dest));
+     // warn: potential buffer overflow
+ }
+
+.. _unix-cstrisng-NullArg:
+
+unix.cstrisng.NullArg (C)
+"""""""""""""""""""""""""
+Check for null pointers being passed as arguments to C string functions:
+``strlen, strnlen, strcpy, strncpy, strcat, strncat, strcmp, strncmp, strcasecmp, strncasecmp``.
+
+.. code-block:: c
+
+ int test() {
+   return strlen(0); // warn
+ }
+
+.. _osx-checkers:
+
+osx
+^^^
+macOS checkers.
+
+.. _osx-API:
+
+osx.API (C)
+"""""""""""
+Check for proper uses of various Apple APIs.
+
+.. code-block:: objc
+
+ void test() {
+   dispatch_once_t pred = 0;
+   dispatch_once(&pred, ^(){}); // warn: dispatch_once uses local
+ }
+
+.. _osx-NumberObjectConversion:
+
+osx.NumberObjectConversion (C, C++, ObjC)
+"""""""""""""""""""""""""""""""""""""""""
+Check for erroneous conversions of objects representing numbers into numbers.
+
+.. code-block:: objc
+
+ NSNumber *photoCount = [albumDescriptor objectForKey:@"PhotoCount"];
+ // Warning: Comparing a pointer value of type 'NSNumber *'
+ // to a scalar integer value
+ if (photoCount > 0) {
+   [self displayPhotos];
+ }
+
+.. _osx-ObjCProperty:
+
+osx.ObjCProperty (ObjC)
+"""""""""""""""""""""""
+Check for proper uses of Objective-C properties.
+
+.. code-block:: objc
+
+ NSNumber *photoCount = [albumDescriptor objectForKey:@"PhotoCount"];
+ // Warning: Comparing a pointer value of type 'NSNumber *'
+ // to a scalar integer value
+ if (photoCount > 0) {
+   [self displayPhotos];
+ }
+
+
+.. _osx-SecKeychainAPI:
+
+osx.SecKeychainAPI (C)
+""""""""""""""""""""""
+Check for proper uses of Secure Keychain APIs.
+
+.. literalinclude:: checkers/seckeychainapi_example.m
+    :language: objc
+
+.. _osx-cocoa-AtSync:
+
+osx.cocoa.AtSync (ObjC)
+"""""""""""""""""""""""
+Check for nil pointers used as mutexes for @synchronized.
+
+.. code-block:: objc
+
+ void test(id x) {
+   if (!x)
+     @synchronized(x) {} // warn: nil value used as mutex
+ }
+
+ void test() {
+   id y;
+   @synchronized(y) {} // warn: uninitialized value used as mutex
+ }
+
+.. _osx-cocoa-AutoreleaseWrite:
+
+osx.cocoa.AutoreleaseWrite
+""""""""""""""""""""""""""
+Warn about potentially crashing writes to autoreleasing objects from different autoreleasing pools in Objective-C.
+
+.. _osx-cocoa-ClassRelease:
+
+osx.cocoa.ClassRelease (ObjC)
+"""""""""""""""""""""""""""""
+Check for sending 'retain', 'release', or 'autorelease' directly to a Class.
+
+.. code-block:: objc
+
+ @interface MyClass : NSObject
+ @end
+
+ void test(void) {
+   [MyClass release]; // warn
+ }
+
+.. _osx-cocoa-Dealloc:
+
+osx.cocoa.Dealloc (ObjC)
+""""""""""""""""""""""""
+Warn about Objective-C classes that lack a correct implementation of -dealloc
+
+.. literalinclude:: checkers/dealloc_example.m
+    :language: objc
+
+.. _osx-cocoa-IncompatibleMethodTypes:
+
+osx.cocoa.IncompatibleMethodTypes (ObjC)
+""""""""""""""""""""""""""""""""""""""""
+Warn about Objective-C method signatures with type incompatibilities.
+
+.. code-block:: objc
+
+ @interface MyClass1 : NSObject
+ - (int)foo;
+ @end
+
+ @implementation MyClass1
+ - (int)foo { return 1; }
+ @end
+
+ @interface MyClass2 : MyClass1
+ - (float)foo;
+ @end
+
+ @implementation MyClass2
+ - (float)foo { return 1.0; } // warn
+ @end
+
+.. _osx-cocoa-Loops:
+
+osx.cocoa.Loops
+"""""""""""""""
+Improved modeling of loops using Cocoa collection types.
+
+.. _osx-cocoa-MissingSuperCall:
+
+osx.cocoa.MissingSuperCall (ObjC)
+"""""""""""""""""""""""""""""""""
+Warn about Objective-C methods that lack a necessary call to super.
+
+.. code-block:: objc
+
+ @interface Test : UIViewController
+ @end
+ @implementation test
+ - (void)viewDidLoad {} // warn
+ @end
+
+
+.. _osx-cocoa-NSAutoreleasePool:
+
+osx.cocoa.NSAutoreleasePool (ObjC)
+""""""""""""""""""""""""""""""""""
+Warn for suboptimal uses of NSAutoreleasePool in Objective-C GC mode.
+
+.. code-block:: objc
+
+ void test() {
+   NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
+   [pool release]; // warn
+ }
+
+.. _osx-cocoa-NSError:
+
+osx.cocoa.NSError (ObjC)
+""""""""""""""""""""""""
+Check usage of NSError parameters.
+
+.. code-block:: objc
+
+ @interface A : NSObject
+ - (void)foo:(NSError """""""""""""""""""""""")error;
+ @end
+
+ @implementation A
+ - (void)foo:(NSError """""""""""""""""""""""")error {
+   // warn: method accepting NSError"""""""""""""""""""""""" should have a non-void
+   // return value
+ }
+ @end
+
+ @interface A : NSObject
+ - (BOOL)foo:(NSError """""""""""""""""""""""")error;
+ @end
+
+ @implementation A
+ - (BOOL)foo:(NSError """""""""""""""""""""""")error {
+   *error = 0; // warn: potential null dereference
+   return 0;
+ }
+ @end
+
+.. _osx-cocoa-NilArg:
+
+osx.cocoa.NilArg (ObjC)
+"""""""""""""""""""""""
+Check for prohibited nil arguments to ObjC method calls.
+
+ - caseInsensitiveCompare:
+ - compare:
+ - compare:options:
+ - compare:options:range:
+ - compare:options:range:locale:
+ - componentsSeparatedByCharactersInSet:
+ - initWithFormat:
+
+.. code-block:: objc
+
+ NSComparisonResult test(NSString *s) {
+   NSString *aString = nil;
+   return [s caseInsensitiveCompare:aString];
+     // warn: argument to 'NSString' method
+     // 'caseInsensitiveCompare:' cannot be nil
+ }
+
+
+.. _osx-cocoa-NonNilReturnValue:
+
+osx.cocoa.NonNilReturnValue
+"""""""""""""""""""""""""""
+Models the APIs that are guaranteed to return a non-nil value.
+
+.. _osx-cocoa-ObjCGenerics:
+
+osx.cocoa.ObjCGenerics (ObjC)
+"""""""""""""""""""""""""""""
+Check for type errors when using Objective-C generics.
+
+.. code-block:: objc
+
+ NSMutableArray *names = [NSMutableArray array];
+ NSMutableArray *birthDates = names;
+
+ // Warning: Conversion from value of type 'NSDate *'
+ // to incompatible type 'NSString *'
+ [birthDates addObject: [NSDate date]];
+
+.. _osx-cocoa-RetainCount:
+
+osx.cocoa.RetainCount (ObjC)
+""""""""""""""""""""""""""""
+Check for leaks and improper reference count management
+
+.. code-block:: objc
+
+ void test() {
+   NSString *s = [[NSString alloc] init]; // warn
+ }
+
+ CFStringRef test(char *bytes) {
+   return CFStringCreateWithCStringNoCopy(
+            0, bytes, NSNEXTSTEPStringEncoding, 0); // warn
+ }
+
+
+.. _osx-cocoa-RunLoopAutoreleaseLeak:
+
+osx.cocoa.RunLoopAutoreleaseLeak
+""""""""""""""""""""""""""""""""
+Check for leaked memory in autorelease pools that will never be drained.
+
+.. _osx-cocoa-SelfInit:
+
+osx.cocoa.SelfInit (ObjC)
+"""""""""""""""""""""""""
+Check that 'self' is properly initialized inside an initializer method.
+
+.. code-block:: objc
+
+ @interface MyObj : NSObject {
+   id x;
+ }
+ - (id)init;
+ @end
+
+ @implementation MyObj
+ - (id)init {
+   [super init];
+   x = 0; // warn: instance variable used while 'self' is not
+          // initialized
+   return 0;
+ }
+ @end
+
+ @interface MyObj : NSObject
+ - (id)init;
+ @end
+
+ @implementation MyObj
+ - (id)init {
+   [super init];
+   return self; // warn: returning uninitialized 'self'
+ }
+ @end
+
+.. _osx-cocoa-SuperDealloc:
+
+osx.cocoa.SuperDealloc (ObjC)
+"""""""""""""""""""""""""""""
+Warn about improper use of '[super dealloc]' in Objective-C.
+
+.. code-block:: objc
+
+ @interface SuperDeallocThenReleaseIvarClass : NSObject {
+   NSObject *_ivar;
+ }
+ @end
+
+ @implementation SuperDeallocThenReleaseIvarClass
+ - (void)dealloc {
+   [super dealloc];
+   [_ivar release]; // warn
+ }
+ @end
+
+.. _osx-cocoa-UnusedIvars:
+
+osx.cocoa.UnusedIvars (ObjC)
+""""""""""""""""""""""""""""
+Warn about private ivars that are never used.
+
+.. code-block:: objc
+
+ @interface MyObj : NSObject {
+ @private
+   id x; // warn
+ }
+ @end
+
+ @implementation MyObj
+ @end
+
+.. _osx-cocoa-VariadicMethodTypes:
+
+osx.cocoa.VariadicMethodTypes (ObjC)
+""""""""""""""""""""""""""""""""""""
+Check for passing non-Objective-C types to variadic collection
+initialization methods that expect only Objective-C types.
+
+.. code-block:: objc
+
+ void test() {
+   [NSSet setWithObjects:@"Foo", "Bar", nil];
+     // warn: argument should be an ObjC pointer type, not 'char *'
+ }
+
+.. _osx-coreFoundation-CFError:
+
+osx.coreFoundation.CFError (C)
+""""""""""""""""""""""""""""""
+Check usage of CFErrorRef* parameters
+
+.. code-block:: c
+
+ void test(CFErrorRef *error) {
+   // warn: function accepting CFErrorRef* should have a
+   // non-void return
+ }
+
+ int foo(CFErrorRef *error) {
+   *error = 0; // warn: potential null dereference
+   return 0;
+ }
+
+.. _osx-coreFoundation-CFNumber:
+
+osx.coreFoundation.CFNumber (C)
+"""""""""""""""""""""""""""""""
+Check for proper uses of CFNumber APIs.
+
+.. code-block:: c
+
+ CFNumberRef test(unsigned char x) {
+   return CFNumberCreate(0, kCFNumberSInt16Type, &x);
+    // warn: 8 bit integer is used to initialize a 16 bit integer
+ }
+
+.. _osx-coreFoundation-CFRetainRelease:
+
+osx.coreFoundation.CFRetainRelease (C)
+""""""""""""""""""""""""""""""""""""""
+Check for null arguments to CFRetain/CFRelease/CFMakeCollectable.
+
+.. code-block:: c
+
+ void test(CFTypeRef p) {
+   if (!p)
+     CFRetain(p); // warn
+ }
+
+ void test(int x, CFTypeRef p) {
+   if (p)
+     return;
+
+   CFRelease(p); // warn
+ }
+
+.. _osx-coreFoundation-containers-OutOfBounds:
+
+osx.coreFoundation.containers.OutOfBounds (C)
+"""""""""""""""""""""""""""""""""""""""""""""
+Checks for index out-of-bounds when using 'CFArray' API.
+
+.. code-block:: c
+
+ void test() {
+   CFArrayRef A = CFArrayCreate(0, 0, 0, &kCFTypeArrayCallBacks);
+   CFArrayGetValueAtIndex(A, 0); // warn
+ }
+
+.. _osx-coreFoundation-containers-PointerSizedValues:
+
+osx.coreFoundation.containers.PointerSizedValues (C)
+""""""""""""""""""""""""""""""""""""""""""""""""""""
+Warns if 'CFArray', 'CFDictionary', 'CFSet' are created with non-pointer-size values.
+
+.. code-block:: c
+
+ void test() {
+   int x[] = { 1 };
+   CFArrayRef A = CFArrayCreate(0, (const void """""""""""""""""""""""")x, 1,
+                                &kCFTypeArrayCallBacks); // warn
+ }
+
+
+.. _alpha-checkers:
+
+Experimental Checkers
+---------------------
+
+*These are checkers with known issues or limitations that keep them from being on by default. They are likely to have false positives. Bug reports and especially patches are welcome.*
+
+alpha.clone
+^^^^^^^^^^^
+
+.. _alpha-clone-CloneChecker:
+
+alpha.clone.CloneChecker (C, C++, ObjC)
+"""""""""""""""""""""""""""""""""""""""
+Reports similar pieces of code.
+
+.. code-block:: c
+
+ void log();
+
+ int max(int a, int b) { // warn
+   log();
+   if (a > b)
+     return a;
+   return b;
+ }
+
+ int maxClone(int x, int y) { // similar code here
+   log();
+   if (x > y)
+     return x;
+   return y;
+ }
+
+.. _alpha-core-BoolAssignment:
+
+alpha.core.BoolAssignment (ObjC)
+""""""""""""""""""""""""""""""""
+Warn about assigning non-{0,1} values to boolean variables.
+
+.. code-block:: objc
+
+ void test() {
+   BOOL b = -1; // warn
+ }
+
+alpha.core
+^^^^^^^^^^
+
+.. _alpha-core-CallAndMessageUnInitRefArg:
+
+alpha.core.CallAndMessageUnInitRefArg (C,C++, ObjC)
+"""""""""""""""""""""""""""""""""""""""""""""""""""
+Check for logical errors for function calls and Objective-C
+message expressions (e.g., uninitialized arguments, null function pointers, and pointer to undefined variables).
+
+.. code-block:: c
+
+ void test(void) {
+   int t;
+   int &p = t;
+   int &s = p;
+   int &q = s;
+   foo(q); // warn
+ }
+
+ void test(void) {
+   int x;
+   foo(&x); // warn
+ }
+
+.. _alpha-core-CastSize:
+
+alpha.core.CastSize (C)
+"""""""""""""""""""""""
+Check when casting a malloc'ed type ``T``, whether the size is a multiple of the size of ``T``.
+
+.. code-block:: c
+
+ void test() {
+   int *x = (int *) malloc(11); // warn
+ }
+
+.. _alpha-core-CastToStruct:
+
+alpha.core.CastToStruct (C, C++)
+""""""""""""""""""""""""""""""""
+Check for cast from non-struct pointer to struct pointer.
+
+.. code-block:: cpp
+
+ // C
+ struct s {};
+
+ void test(int *p) {
+   struct s *ps = (struct s *) p; // warn
+ }
+
+ // C++
+ class c {};
+
+ void test(int *p) {
+   c *pc = (c *) p; // warn
+ }
+
+.. _alpha-core-Conversion:
+
+alpha.core.Conversion (C, C++, ObjC)
+""""""""""""""""""""""""""""""""""""
+Loss of sign/precision in implicit conversions.
+
+.. code-block:: c
+
+ void test(unsigned U, signed S) {
+   if (S > 10) {
+     if (U < S) {
+     }
+   }
+   if (S < -10) {
+     if (U < S) { // warn (loss of sign)
+     }
+   }
+ }
+
+ void test() {
+   long long A = 1LL << 60;
+   short X = A; // warn (loss of precision)
+ }
+
+.. _alpha-core-DynamicTypeChecker:
+
+alpha.core.DynamicTypeChecker (ObjC)
+""""""""""""""""""""""""""""""""""""
+Check for cases where the dynamic and the static type of an object are unrelated.
+
+
+.. code-block:: objc
+
+ id date = [NSDate date];
+
+ // Warning: Object has a dynamic type 'NSDate *' which is
+ // incompatible with static type 'NSNumber *'"
+ NSNumber *number = date;
+ [number doubleValue];
+
+.. _alpha-core-FixedAddr:
+
+alpha.core.FixedAddr (C)
+""""""""""""""""""""""""
+Check for assignment of a fixed address to a pointer.
+
+.. code-block:: c
+
+ void test() {
+   int *p;
+   p = (int *) 0x10000; // warn
+ }
+
+.. _alpha-core-IdenticalExpr:
+
+alpha.core.IdenticalExpr (C, C++)
+"""""""""""""""""""""""""""""""""
+Warn about unintended use of identical expressions in operators.
+
+.. code-block:: cpp
+
+ // C
+ void test() {
+   int a = 5;
+   int b = a | 4 | a; // warn: identical expr on both sides
+ }
+
+ // C++
+ bool f(void);
+
+ void test(bool b) {
+   int i = 10;
+   if (f()) { // warn: true and false branches are identical
+     do {
+       i--;
+     } while (f());
+   } else {
+     do {
+       i--;
+     } while (f());
+   }
+ }
+
+.. _alpha-core-PointerArithm:
+
+alpha.core.PointerArithm (C)
+""""""""""""""""""""""""""""
+Check for pointer arithmetic on locations other than array elements.
+
+.. code-block:: c
+
+ void test() {
+   int x;
+   int *p;
+   p = &x + 1; // warn
+ }
+
+.. _alpha-core-PointerSub:
+
+alpha.core.PointerSub (C)
+"""""""""""""""""""""""""
+Check for pointer subtractions on two pointers pointing to different memory chunks.
+
+.. code-block:: c
+
+ void test() {
+   int x, y;
+   int d = &y - &x; // warn
+ }
+
+.. _alpha-core-SizeofPtr:
+
+alpha.core.SizeofPtr (C)
+""""""""""""""""""""""""
+Warn about unintended use of ``sizeof()`` on pointer expressions.
+
+.. code-block:: c
+
+ struct s {};
+
+ int test(struct s *p) {
+   return sizeof(p);
+     // warn: sizeof(ptr) can produce an unexpected result
+ }
+
+.. _alpha-core-StackAddressAsyncEscape:
+
+alpha.core.StackAddressAsyncEscape (C)
+""""""""""""""""""""""""""""""""""""""
+Check that addresses to stack memory do not escape the function that involves dispatch_after or dispatch_async.
+This checker is a part of ``core.StackAddressEscape``, but is temporarily disabled until some false positives are fixed.
+
+.. code-block:: c
+
+ dispatch_block_t test_block_inside_block_async_leak() {
+   int x = 123;
+   void (^inner)(void) = ^void(void) {
+     int y = x;
+     ++y;
+   };
+   void (^outer)(void) = ^void(void) {
+     int z = x;
+     ++z;
+     inner();
+   };
+   return outer; // warn: address of stack-allocated block is captured by a
+                 //       returned block
+ }
+
+.. _alpha-core-TestAfterDivZero:
+
+alpha.core.TestAfterDivZero (C)
+"""""""""""""""""""""""""""""""
+Check for division by variable that is later compared against 0.
+Either the comparison is useless or there is division by zero.
+
+.. code-block:: c
+
+ void test(int x) {
+   var = 77 / x;
+   if (x == 0) { } // warn
+ }
+
+alpha.cplusplus
+^^^^^^^^^^^^^^^
+
+.. _alpha-cplusplus-DeleteWithNonVirtualDtor:
+
+alpha.cplusplus.DeleteWithNonVirtualDtor (C++)
+""""""""""""""""""""""""""""""""""""""""""""""
+Reports destructions of polymorphic objects with a non-virtual destructor in their base class.
+
+.. code-block:: cpp
+
+ NonVirtual *create() {
+   NonVirtual *x = new NVDerived(); // note: conversion from derived to base
+                                    //       happened here
+   return x;
+ }
+
+ void sink(NonVirtual *x) {
+   delete x; // warn: destruction of a polymorphic object with no virtual
+             //       destructor
+ }
+
+.. _alpha-cplusplus-EnumCastOutOfRange:
+
+alpha.cplusplus.EnumCastOutOfRange (C++)
+""""""""""""""""""""""""""""""""""""""""
+Check for integer to enumeration casts that could result in undefined values.
+
+.. code-block:: cpp
+
+ enum TestEnum {
+   A = 0
+ };
+
+ void foo() {
+   TestEnum t = static_cast(-1);
+       // warn: the value provided to the cast expression is not in
+                the valid range of values for the enum
+
+.. _alpha-cplusplus-InvalidatedIterator:
+
+alpha.cplusplus.InvalidatedIterator (C++)
+"""""""""""""""""""""""""""""""""""""""""
+Check for use of invalidated iterators.
+
+.. code-block:: cpp
+
+ void bad_copy_assign_operator_list1(std::list &L1,
+                                     const std::list &L2) {
+   auto i0 = L1.cbegin();
+   L1 = L2;
+   *i0; // warn: invalidated iterator accessed
+ }
+
+
+.. _alpha-cplusplus-IteratorRange:
+
+alpha.cplusplus.IteratorRange (C++)
+"""""""""""""""""""""""""""""""""""
+Check for iterators used outside their valid ranges.
+
+.. code-block:: cpp
+
+ void simple_bad_end(const std::vector &v) {
+   auto i = v.end();
+   *i; // warn: iterator accessed outside of its range
+ }
+
+.. _alpha-cplusplus-MismatchedIterator:
+
+alpha.cplusplus.MismatchedIterator (C++)
+""""""""""""""""""""""""""""""""""""""""
+Check for use of iterators of different containers where iterators of the same container are expected.
+
+.. code-block:: cpp
+
+ void bad_insert3(std::vector &v1, std::vector &v2) {
+   v2.insert(v1.cbegin(), v2.cbegin(), v2.cend()); // warn: container accessed
+                                                   //       using foreign
+                                                   //       iterator argument
+   v1.insert(v1.cbegin(), v1.cbegin(), v2.cend()); // warn: iterators of
+                                                   //       different containers
+                                                   //       used where the same
+                                                   //       container is
+                                                   //       expected
+   v1.insert(v1.cbegin(), v2.cbegin(), v1.cend()); // warn: iterators of
+                                                   //       different containers
+                                                   //       used where the same
+                                                   //       container is
+                                                   //       expected
+ }
+
+.. _alpha-cplusplus-MisusedMovedObject:
+
+alpha.cplusplus.MisusedMovedObject (C++)
+""""""""""""""""""""""""""""""""""""""""
+Method calls on a moved-from object and copying a moved-from object will be reported.
+
+
+.. code-block:: cpp
+
+  struct A {
+   void foo() {}
+ };
+
+ void f() {
+   A a;
+   A b = std::move(a); // note: 'a' became 'moved-from' here
+   a.foo();            // warn: method call on a 'moved-from' object 'a'
+ }
+
+alpha.deadcode
+^^^^^^^^^^^^^^
+.. _alpha-deadcode-UnreachableCode:
+
+alpha.deadcode.UnreachableCode (C, C++)
+"""""""""""""""""""""""""""""""""""""""
+Check unreachable code.
+
+.. code-block:: cpp
+
+ // C
+ int test() {
+   int x = 1;
+   while(x);
+   return x; // warn
+ }
+
+ // C++
+ void test() {
+   int a = 2;
+
+   while (a > 1)
+     a--;
+
+   if (a > 1)
+     a++; // warn
+ }
+
+ // Objective-C
+ void test(id x) {
+   return;
+   [x retain]; // warn
+ }
+
+alpha.llvm
+^^^^^^^^^^
+
+.. _alpha-llvm-Conventions:
+
+alpha.llvm.Conventions
+""""""""""""""""""""""
+
+Check code for LLVM codebase conventions:
+
+* A StringRef should not be bound to a temporary std::string whose lifetime is shorter than the StringRef's.
+* Clang AST nodes should not have fields that can allocate memory.
+
+
+alpha.osx
+^^^^^^^^^
+
+.. _alpha-osx-cocoa-DirectIvarAssignment:
+
+alpha.osx.cocoa.DirectIvarAssignment (ObjC)
+"""""""""""""""""""""""""""""""""""""""""""
+Check for direct assignments to instance variables.
+
+
+.. code-block:: objc
+
+ @interface MyClass : NSObject {}
+ @property (readonly) id A;
+ - (void) foo;
+ @end
+
+ @implementation MyClass
+ - (void) foo {
+   _A = 0; // warn
+ }
+ @end
+
+.. _alpha-osx-cocoa-DirectIvarAssignmentForAnnotatedFunctions:
+
+alpha.osx.cocoa.DirectIvarAssignmentForAnnotatedFunctions (ObjC)
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Check for direct assignments to instance variables in
+the methods annotated with ``objc_no_direct_instance_variable_assignment``.
+
+.. code-block:: objc
+
+ @interface MyClass : NSObject {}
+ @property (readonly) id A;
+ - (void) fAnnotated __attribute__((
+     annotate("objc_no_direct_instance_variable_assignment")));
+ - (void) fNotAnnotated;
+ @end
+
+ @implementation MyClass
+ - (void) fAnnotated {
+   _A = 0; // warn
+ }
+ - (void) fNotAnnotated {
+   _A = 0; // no warn
+ }
+ @end
+
+
+.. _alpha-osx-cocoa-InstanceVariableInvalidation:
+
+alpha.osx.cocoa.InstanceVariableInvalidation (ObjC)
+"""""""""""""""""""""""""""""""""""""""""""""""""""
+Check that the invalidatable instance variables are
+invalidated in the methods annotated with objc_instance_variable_invalidator.
+
+.. code-block:: objc
+
+ @protocol Invalidation <NSObject>
+ - (void) invalidate
+   __attribute__((annotate("objc_instance_variable_invalidator")));
+ @end
+
+ @interface InvalidationImpObj : NSObject <Invalidation>
+ @end
+
+ @interface SubclassInvalidationImpObj : InvalidationImpObj {
+   InvalidationImpObj *var;
+ }
+ - (void)invalidate;
+ @end
+
+ @implementation SubclassInvalidationImpObj
+ - (void) invalidate {}
+ @end
+ // warn: var needs to be invalidated or set to nil
+
+.. _alpha-osx-cocoa-MissingInvalidationMethod:
+
+alpha.osx.cocoa.MissingInvalidationMethod (ObjC)
+""""""""""""""""""""""""""""""""""""""""""""""""
+Check that the invalidation methods are present in classes that contain invalidatable instance variables.
+
+.. code-block:: objc
+
+ @protocol Invalidation <NSObject>
+ - (void)invalidate
+   __attribute__((annotate("objc_instance_variable_invalidator")));
+ @end
+
+ @interface NeedInvalidation : NSObject <Invalidation>
+ @end
+
+ @interface MissingInvalidationMethodDecl : NSObject {
+   NeedInvalidation *Var; // warn
+ }
+ @end
+
+ @implementation MissingInvalidationMethodDecl
+ @end
+
+.. _alpha-osx-cocoa-localizability-PluralMisuseChecker:
+
+alpha.osx.cocoa.localizability.PluralMisuseChecker (ObjC)
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Warns against using one vs. many plural pattern in code when generating localized strings.
+
+.. code-block:: objc
+
+ NSString *reminderText =
+   NSLocalizedString(@"None", @"Indicates no reminders");
+ if (reminderCount == 1) {
+   // Warning: Plural cases are not supported across all languages.
+   // Use a .stringsdict file instead
+   reminderText =
+     NSLocalizedString(@"1 Reminder", @"Indicates single reminder");
+ } else if (reminderCount >= 2) {
+   // Warning: Plural cases are not supported across all languages.
+   // Use a .stringsdict file instead
+   reminderText =
+     [NSString stringWithFormat:
+       NSLocalizedString(@"%@ Reminders", @"Indicates multiple reminders"),
+         reminderCount];
+ }
+
+alpha.security
+^^^^^^^^^^^^^^
+.. _alpha-security-ArrayBound:
+
+alpha.security.ArrayBound (C)
+"""""""""""""""""""""""""""""
+Warn about buffer overflows (older checker).
+
+.. code-block:: c
+
+ void test() {
+   char *s = "";
+   char c = s[1]; // warn
+ }
+
+ struct seven_words {
+   int c[7];
+ };
+
+ void test() {
+   struct seven_words a, *p;
+   p = &a;
+   p[0] = a;
+   p[1] = a;
+   p[2] = a; // warn
+ }
+
+ // note: requires unix.Malloc or
+ // alpha.unix.MallocWithAnnotations checks enabled.
+ void test() {
+   int *p = malloc(12);
+   p[3] = 4; // warn
+ }
+
+ void test() {
+   char a[2];
+   int *b = (int*)a;
+   b[1] = 3; // warn
+ }
+
+.. _alpha-security-ArrayBoundV2:
+
+alpha.security.ArrayBoundV2 (C)
+"""""""""""""""""""""""""""""""
+Warn about buffer overflows (newer checker).
+
+.. code-block:: c
+
+ void test() {
+   char *s = "";
+   char c = s[1]; // warn
+ }
+
+ void test() {
+   int buf[100];
+   int *p = buf;
+   p = p + 99;
+   p[1] = 1; // warn
+ }
+
+ // note: compiler has internal check for this.
+ // Use -Wno-array-bounds to suppress compiler warning.
+ void test() {
+   int buf[100][100];
+   buf[0][-1] = 1; // warn
+ }
+
+ // note: requires alpha.security.taint check turned on.
+ void test() {
+   char s[] = "abc";
+   int x = getchar();
+   char c = s[x]; // warn: index is tainted
+ }
+
+.. _alpha-security-MallocOverflow:
+
+alpha.security.MallocOverflow (C)
+"""""""""""""""""""""""""""""""""
+Check for overflows in the arguments to malloc().
+
+.. code-block:: c
+
+ void test(int n) {
+   void *p = malloc(n * sizeof(int)); // warn
+ }
+
+.. _alpha-security-MmapWriteExec:
+
+alpha.security.MmapWriteExec (C)
+""""""""""""""""""""""""""""""""
+Warn on mmap() calls that are both writable and executable.
+
+.. code-block:: c
+
+ void test(int n) {
+   void *c = mmap(NULL, 32, PROT_READ | PROT_WRITE | PROT_EXEC,
+                  MAP_PRIVATE | MAP_ANON, -1, 0);
+   // warn: Both PROT_WRITE and PROT_EXEC flags are set. This can lead to
+   //       exploitable memory regions, which could be overwritten with malicious
+   //       code
+ }
+
+.. _alpha-security-ReturnPtrRange:
+
+alpha.security.ReturnPtrRange (C)
+"""""""""""""""""""""""""""""""""
+Check for an out-of-bound pointer being returned to callers.
+
+.. code-block:: c
+
+ static int A[10];
+
+ int *test() {
+   int *p = A + 10;
+   return p; // warn
+ }
+
+ int test(void) {
+   int x;
+   return x; // warn: undefined or garbage returned
+ }
+
+.. _alpha-security-taint-TaintPropagation:
+
+alpha.security.taint.TaintPropagation (C, C++)
+""""""""""""""""""""""""""""""""""""""""""""""
+Generate taint information used by other checkers.
+A data is tainted when it comes from an unreliable source.
+
+.. code-block:: c
+
+ void test() {
+   char x = getchar(); // 'x' marked as tainted
+   system(&x); // warn: untrusted data is passed to a system call
+ }
+
+ // note: compiler internally checks if the second param to
+ // sprintf is a string literal or not.
+ // Use -Wno-format-security to suppress compiler warning.
+ void test() {
+   char s[10], buf[10];
+   fscanf(stdin, "%s", s); // 's' marked as tainted
+
+   sprintf(buf, s); // warn: untrusted data as a format string
+ }
+
+ void test() {
+   size_t ts;
+   scanf("%zd", &ts); // 'ts' marked as tainted
+   int *p = (int *)malloc(ts * sizeof(int));
+     // warn: untrusted data as buffer size
+ }
+
+alpha.unix
+^^^^^^^^^^^
+
+.. _alpha-unix-BlockInCriticalSection:
+
+alpha.unix.BlockInCriticalSection (C)
+"""""""""""""""""""""""""""""""""""""
+Check for calls to blocking functions inside a critical section.
+Applies to: ``lock, unlock, sleep, getc, fgets, read, recv, pthread_mutex_lock,``
+`` pthread_mutex_unlock, mtx_lock, mtx_timedlock, mtx_trylock, mtx_unlock, lock_guard, unique_lock``
+
+.. code-block:: c
+
+ void test() {
+   std::mutex m;
+   m.lock();
+   sleep(3); // warn: a blocking function sleep is called inside a critical
+             //       section
+   m.unlock();
+ }
+
+.. _alpha-unix-Chroot:
+
+alpha.unix.Chroot (C)
+"""""""""""""""""""""
+Check improper use of chroot.
+
+.. code-block:: c
+
+ void f();
+
+ void test() {
+   chroot("/usr/local");
+   f(); // warn: no call of chdir("/") immediately after chroot
+ }
+
+.. _alpha-unix-PthreadLock:
+
+alpha.unix.PthreadLock (C)
+""""""""""""""""""""""""""
+Simple lock -> unlock checker.
+Applies to: ``pthread_mutex_lock, pthread_rwlock_rdlock, pthread_rwlock_wrlock, lck_mtx_lock, lck_rw_lock_exclusive``
+``lck_rw_lock_shared, pthread_mutex_trylock, pthread_rwlock_tryrdlock, pthread_rwlock_tryrwlock, lck_mtx_try_lock,
+lck_rw_try_lock_exclusive, lck_rw_try_lock_shared, pthread_mutex_unlock, pthread_rwlock_unlock, lck_mtx_unlock, lck_rw_done``.
+
+
+.. code-block:: c
+
+ pthread_mutex_t mtx;
+
+ void test() {
+   pthread_mutex_lock(&mtx);
+   pthread_mutex_lock(&mtx);
+     // warn: this lock has already been acquired
+ }
+
+ lck_mtx_t lck1, lck2;
+
+ void test() {
+   lck_mtx_lock(&lck1);
+   lck_mtx_lock(&lck2);
+   lck_mtx_unlock(&lck1);
+     // warn: this was not the most recently acquired lock
+ }
+
+ lck_mtx_t lck1, lck2;
+
+ void test() {
+   if (lck_mtx_try_lock(&lck1) == 0)
+     return;
+
+   lck_mtx_lock(&lck2);
+   lck_mtx_unlock(&lck1);
+     // warn: this was not the most recently acquired lock
+ }
+
+.. _alpha-unix-SimpleStream:
+
+alpha.unix.SimpleStream (C)
+"""""""""""""""""""""""""""
+Check for misuses of stream APIs. Check for misuses of stream APIs: ``fopen, fclose``
+(demo checker, the subject of the demo (`Slides <http://llvm.org/devmtg/2012-11/Zaks-Rose-Checker24Hours.pdf>`_ ,
+`Video <https://youtu.be/kdxlsP5QVPw>`_) by Anna Zaks and Jordan Rose presented at the
+`2012 LLVM Developers' Meeting <http://llvm.org/devmtg/2012-11/>`_).
+
+.. code-block:: c
+
+ void test() {
+   FILE *F = fopen("myfile.txt", "w");
+ } // warn: opened file is never closed
+
+ void test() {
+   FILE *F = fopen("myfile.txt", "w");
+
+   if (F)
+     fclose(F);
+
+   fclose(F); // warn: closing a previously closed file stream
+ }
+
+.. _alpha-unix-Stream:
+
+alpha.unix.Stream (C)
+"""""""""""""""""""""
+Check stream handling functions: ``fopen, tmpfile, fclose, fread, fwrite, fseek, ftell, rewind, fgetpos,``
+``fsetpos, clearerr, feof, ferror, fileno``.
+
+.. code-block:: c
+
+ void test() {
+   FILE *p = fopen("foo", "r");
+ } // warn: opened file is never closed
+
+ void test() {
+   FILE *p = fopen("foo", "r");
+   fseek(p, 1, SEEK_SET); // warn: stream pointer might be NULL
+   fclose(p);
+ }
+
+ void test() {
+   FILE *p = fopen("foo", "r");
+
+   if (p)
+     fseek(p, 1, 3);
+      // warn: third arg should be SEEK_SET, SEEK_END, or SEEK_CUR
+
+   fclose(p);
+ }
+
+ void test() {
+   FILE *p = fopen("foo", "r");
+   fclose(p);
+   fclose(p); // warn: already closed
+ }
+
+ void test() {
+   FILE *p = tmpfile();
+   ftell(p); // warn: stream pointer might be NULL
+   fclose(p);
+ }
+
+
+.. _alpha-unix-cstring-BufferOverlap:
+
+alpha.unix.cstring.BufferOverlap (C)
+""""""""""""""""""""""""""""""""""""
+Checks for overlap in two buffer arguments. Applies to:  ``memcpy, mempcpy``.
+
+.. code-block:: c
+
+ void test() {
+   int a[4] = {0};
+   memcpy(a + 2, a + 1, 8); // warn
+ }
+
+.. _alpha-unix-cstring-NotNullTerminated:
+
+alpha.unix.cstring.NotNullTerminated (C)
+""""""""""""""""""""""""""""""""""""""""
+Check for arguments which are not null-terminated strings; applies to: ``strlen, strnlen, strcpy, strncpy, strcat, strncat``.
+
+.. code-block:: c
+
+ void test() {
+   int y = strlen((char *)&test); // warn
+ }
+
+.. _alpha-unix-cstring-OutOfBounds:
+
+alpha.unix.cstring.OutOfBounds (C)
+""""""""""""""""""""""""""""""""""
+Check for out-of-bounds access in string functions; applies to:`` strncopy, strncat``.
+
+
+.. code-block:: c
+
+ void test() {
+   int y = strlen((char *)&test); // warn
+ }
+
+.. _alpha-nondeterminism-PointerIteration:
+
+alpha.nondeterminism.PointerIteration (C++)
+"""""""""""""""""""""""""""""""""""""""""""
+Check for non-determinism caused by iterating unordered containers of pointers.
+
+.. code-block:: c
+
+ void test() {
+  int a = 1, b = 2;
+  std::unordered_set<int *> UnorderedPtrSet = {&a, &b};
+
+  for (auto i : UnorderedPtrSet) // warn
+    f(i);
+ }
+
+.. _alpha-nondeterminism-PointerSorting:
+
+alpha.nondeterminism.PointerSorting (C++)
+"""""""""""""""""""""""""""""""""""""""""
+Check for non-determinism caused by sorting of pointers.
+
+.. code-block:: c
+
+ void test() {
+  int a = 1, b = 2;
+  std::vector<int *> V = {&a, &b};
+  std::sort(V.begin(), V.end()); // warn
+ }
+
+
+Debug Checkers
+---------------
+
+.. _debug-checkers:
+
+
+debug
+^^^^^
+
+Checkers used for debugging the analyzer.
+:doc:`developer-docs/DebugChecks` page contains a detailed description.
+
+.. _debug-AnalysisOrder:
+
+debug.AnalysisOrder
+"""""""""""""""""""
+Print callbacks that are called during analysis in order.
+
+.. _debug-ConfigDumper:
+
+debug.ConfigDumper
+""""""""""""""""""
+Dump config table.
+
+.. _debug-DumpCFG Display:
+
+debug.DumpCFG Display
+"""""""""""""""""""""
+Control-Flow Graphs.
+
+.. _debug-DumpCallGraph:
+
+debug.DumpCallGraph
+"""""""""""""""""""
+Display Call Graph.
+
+.. _debug-DumpCalls:
+
+debug.DumpCalls
+"""""""""""""""
+Print calls as they are traversed by the engine.
+
+.. _debug-DumpDominators:
+
+debug.DumpDominators
+""""""""""""""""""""
+Print the dominance tree for a given CFG.
+
+.. _debug-DumpLiveVars:
+
+debug.DumpLiveVars
+""""""""""""""""""
+Print results of live variable analysis.
+
+.. _debug-DumpTraversal:
+
+debug.DumpTraversal
+"""""""""""""""""""
+Print branch conditions as they are traversed by the engine.
+
+.. _debug-ExprInspection:
+
+debug.ExprInspection
+""""""""""""""""""""
+Check the analyzer's understanding of expressions.
+
+.. _debug-Stats:
+
+debug.Stats
+"""""""""""
+Emit warnings with analyzer statistics.
+
+.. _debug-TaintTest:
+
+debug.TaintTest
+"""""""""""""""
+Mark tainted symbols as such.
+
+.. _debug-ViewCFG:
+
+debug.ViewCFG
+"""""""""""""
+View Control-Flow Graphs using GraphViz.
+
+.. _debug-ViewCallGraph:
+
+debug.ViewCallGraph
+"""""""""""""""""""
+View Call Graph using GraphViz.
+
+.. _debug-ViewExplodedGraph:
+
+debug.ViewExplodedGraph
+"""""""""""""""""""""""
+View Exploded Graphs using GraphViz.
+

docs/analyzer/checkers/callandmessage_example.c

@@ -0,0 +1,66 @@
+//C
+void test() {
+   void (*foo)(void);
+   foo = 0;
+   foo(); // warn: function pointer is null
+ }
+
+ // C++
+ class C {
+ public:
+   void f();
+ };
+
+ void test() {
+   C *pc;
+   pc->f(); // warn: object pointer is uninitialized
+ }
+
+ // C++
+ class C {
+ public:
+   void f();
+ };
+
+ void test() {
+   C *pc = 0;
+   pc->f(); // warn: object pointer is null
+ }
+
+ // Objective-C
+ @interface MyClass : NSObject
+ @property (readwrite,assign) id x;
+ - (long double)longDoubleM;
+ @end
+
+ void test() {
+   MyClass *obj1;
+   long double ld1 = [obj1 longDoubleM];
+     // warn: receiver is uninitialized
+ }
+
+ // Objective-C
+ @interface MyClass : NSObject
+ @property (readwrite,assign) id x;
+ - (long double)longDoubleM;
+ @end
+
+ void test() {
+   MyClass *obj1;
+   id i = obj1.x; // warn: uninitialized object pointer
+ }
+
+ // Objective-C
+ @interface Subscriptable : NSObject
+ - (id)objectAtIndexedSubscript:(unsigned int)index;
+ @end
+
+ @interface MyClass : Subscriptable
+ @property (readwrite,assign) id x;
+ - (long double)longDoubleM;
+ @end
+
+ void test() {
+   MyClass *obj1;
+   id i = obj1[0]; // warn: uninitialized object pointer
+ }

docs/analyzer/checkers/dealloc_example.m

@@ -0,0 +1,49 @@
+
+
+@interface MyObject : NSObject {
+  id _myproperty;
+}
+@end
+
+@implementation MyObject // warn: lacks 'dealloc'
+@end
+
+@interface MyObject : NSObject {}
+@property(assign) id myproperty;
+@end
+
+@implementation MyObject // warn: does not send 'dealloc' to super
+- (void)dealloc {
+  self.myproperty = 0;
+}
+@end
+
+@interface MyObject : NSObject {
+  id _myproperty;
+}
+@property(retain) id myproperty;
+@end
+
+@implementation MyObject
+@synthesize myproperty = _myproperty;
+  // warn: var was retained but wasn't released
+- (void)dealloc {
+  [super dealloc];
+}
+@end
+
+@interface MyObject : NSObject {
+  id _myproperty;
+}
+@property(assign) id myproperty;
+@end
+
+@implementation MyObject
+@synthesize myproperty = _myproperty;
+  // warn: var wasn't retained but was released
+- (void)dealloc {
+  [_myproperty release];
+  [super dealloc];
+}
+@end
+

docs/analyzer/checkers/dividezero_example.c

@@ -0,0 +1,9 @@
+void test(int z) {
+  if (z == 0)
+    int x = 1 / z; // warn
+}
+
+void test() {
+  int x = 1;
+  int y = x % 0; // warn
+}