compnerd created this revision. compnerd added reviewers: hans, rnk, mstorsjo. Herald added a project: All. compnerd requested review of this revision. Herald added a project: clang.
Add some documentation on the flags and the process by which clang identifies the headers and libraries for the Windows environment. It should identify the flags and their interactions as well as the order in which the various sources of information are consulted. Repository: rG LLVM Github Monorepo https://reviews.llvm.org/D146165 Files: clang/docs/UsersManual.rst
Index: clang/docs/UsersManual.rst =================================================================== --- clang/docs/UsersManual.rst +++ clang/docs/UsersManual.rst @@ -4487,3 +4487,99 @@ to produce DLLs and EXEs. To link a DLL, pass ``clang_rt.asan_dll_thunk-x86_64.lib``. To link an EXE, pass ``-wholearchive:clang_rt.asan-x86_64.lib``. + +Windows System Headers and Library Lookup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +clang-cl uses a set of different approaches to locate the right system libraries +to link against when building code. The Windows environment uses libraries from +three distinct sources: + +1. Windows SDK +2. UCRT (Universal C Runtime) +3. Visual C++ Tools (VCRuntime) + +The Windows SDK provides the import libraries and headers required to build +programs against the Windows system packages. Underlying the Windows SDK is the +UCRT, the universal C runtime. + +There are various controls that allow the user control over where clang-cl will +locate these headers. The default behaviour for the Windows SDK and UCRT is as +follows: + +1. Consult the command line. + + Anything the user specifies is always given precedence. The following + extensions are part of the clang-cl toolset: + + - `/winsysroot:` + + The `/winsysroot:` is used as an equivalent to `-sysroot` on Unix + environments. It allows the control of an alternate location to be treated + as a system root. When specified, it will be used as the root where the + `Windows Kits` is located. + + - `/winsdkversion:` + - `/winsdkdir:` + + If `/winsysroot:` is not specified, the `/winsdkdir:` argument is consulted + as a location to identify where the Windows SDK is located. Contrary to + `/winsysroot:`, `/winsdkdir:` is expected to be the complete path rather + than a root to locate `Windows Kits`. + + The `/winsdkversion:` flag allows the user to specify a version identifier + for the SDK to prefer. When this is specified, no additional validation is + performed and this version is preferred. If the version is not specified, + the highest detected version number will be used. + +2. Consult the environment. + + TODO: This is not yet implemented. + + This will consult the environment variables: + - `WindowsSdkDir` + - `UCRTVersion` + +3. Fallback to the registry. + + If no arguments are used to indicate where the SDK is present, and the + compiler is running on Windows, the registry is consulted to locate the + installation. + +The Visual C++ Toolset has a slightly more elaborate mechanism for detection. + +1. Consult the command line. + + - `/winsysroot:` + + The `/winsysroot:` is used as an equivalent to `-sysroot` on Unix + environments. It allows the control of an alternate location to be treated + as a system root. When specified, it will be used as the root where the + `VC` directory is located. + + - `/vctoolsdir:` + - `/vctoolsversion:` + + If `/winsysroot:` is not specified, the `/vctoolsdir:` argument is consulted + as a location to identify where the Visual C++ Tools are located. If + `/vctoolsversion:` is specified, that version is preferred, otherwise, the + highest version detected is used. + +2. Consult the environment. + + This will consult the environment variables: + - `VCToolsInstallDir + - `VCINSTALLDIR` + - `Path` + +3. Consult `ISetupConfiguration` [Windows Only] + + Assuming that the toolchain is built with `USE_MSVC_SETUP_API` defined and + is running on Windows, the Visual Studio COM interface `ISetupConfiguration` + will be used to locate the installation of the MSVC toolset. + +4. Fallback to the registry [DEPRECATED] + + The registry information is used to help locate the installation as a final + fallback. This is only possible for pre-VS2017 installations and is + considered deprecated.
_______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
