[clang] 893ce57 - docs: add some documentation on Windows SDK search
Saleem Abdulrasool via cfe-commits
cfe-commits at lists.llvm.org
Wed Mar 22 06:46:52 PDT 2023
Author: Saleem Abdulrasool
Date: 2023-03-22T09:46:36-04:00
New Revision: 893ce5759fe2e450dc637d4c76e779f883535882
URL: https://github.com/llvm/llvm-project/commit/893ce5759fe2e450dc637d4c76e779f883535882
DIFF: https://github.com/llvm/llvm-project/commit/893ce5759fe2e450dc637d4c76e779f883535882.diff
LOG: docs: add some documentation on Windows SDK search
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.
Differential Revision: https://reviews.llvm.org/D146165
Reviewed By: hans, mstorjo
Added:
Modified:
clang/docs/UsersManual.rst
Removed:
################################################################################
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 77b1c938c6ad4..031d8a9b624d5 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -4487,3 +4487,126 @@ If the user is using the static CRT (``/MT``), then
diff erent runtimes are used
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
diff erent 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.
+
+This
diff erence is best illustrated by the various headers that one would find
+in the
diff erent categories. The WinSDK would contain headers such as
+`WinSock2.h` which is part of the Windows API surface, providing the Windows
+socketing interfaces for networking. UCRT provides the C library headers,
+including e.g. `stdio.h`. Finally, the Visual C++ tools provides the underlying
+Visual C++ Runtime headers such as `stdint.h` or `crtdefs.h`.
+
+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.
+
+ - `/external:[VARIABLE]`
+
+ This specifies a user identified environment variable which is treated as
+ a path delimiter (`;`) separated list of paths to map into `-imsvc`
+ arguments which are treated as `-isystem`.
+
+ - `INCLUDE` and `EXTERNAL_INCLUDE`
+
+ The path delimiter (`;`) separated list of paths will be mapped to
+ `-imsvc` arguments which are treated as `-isystem`.
+
+ - `LIB` (indirectly)
+
+ The linker `link.exe` or `lld-link.exe` will honour the environment
+ variable `LIB` which is a path delimiter (`;`) set of paths to consult for
+ the import libraries to use when linking the final target.
+
+ The following environment variables will be consulted and used to form paths
+ to validate and load content from as appropriate:
+
+ - `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.
More information about the cfe-commits
mailing list