[clang] Document environment variables used by the driver

[mizvekov]

Summary

We also mention limitations with regards to character encoding support.

Signed-off-by: Matheus Izvekov <[e-mail]>

[aaron.ballman]

clang/docs/ClangCommandLineReference.rst

2–5

I think you might have missed this bit. ;-)

@jansvoboda11 -- do you know of an ergonomic way for people to associate extra documentation along with the command line reference to support adding documentation like this? This is the second time in the past hour I've seen people adding documentation directly to this file and the docs would be kind of onerous to put in HelpText<> directly. I'm wondering if the FE options can support something along the lines of AttrDocs.td where we can specify some out-of-line documentation in another .td for things that are nontrivial to document?

[mizvekov]

clang/docs/ClangCommandLineReference.rst

2–5

Ooops!

Why do we even commit this file then? :-)

[aaron.ballman]

clang/docs/ClangCommandLineReference.rst

2–5

+1 -- we automatically generate the document from the cmake sphinx target, so I think it's reasonable to remove this file from version control (same as we did for AttributeReference.rst and DiagnosticReference.rst).

[jansvoboda11]

clang/docs/ClangCommandLineReference.rst

2–5

We don't have good place for extra documentation. Doing something similar to AttrDocs.td for command-line options is a good direction IMO.

clang/docs/ClangCommandLineReference.rst

 ..
   -------------------------------------------------------------------
   NOTE: This file is automatically generated by running clang-tblgen
   -gen-opt-docs. Do not edit this file by hand!!
   -------------------------------------------------------------------
 
 =====================================
-Clang command line argument reference
+Clang command line reference
 =====================================
 .. contents::
    :local:
 
 Introduction
 ============
 
-This page lists the command line arguments currently supported by the
+This page lists the command line arguments and environment variables currently supported by the
 GCC-compatible ``clang`` and ``clang++`` drivers.
 
 
 .. program:: clang
 .. option:: -B<prefix>, --prefix <arg>, --prefix=<arg>
 
 Search $prefix$file for executables, libraries, and data files. If $prefix is a directory, search $prefix/$file
 
+.. envvar:: COMPILER_PATH=<paths>
+
+Search $paths for executables, libraries, and data files. The value is a list of paths separated by a system standard
+separator. On Windows and Unix, this separator should be colon, just like ``PATH``.
+
 .. option:: -F<arg>
 
 Add directory to framework include search path
 
 .. option:: -ObjC
 
 Treat source input files as Objective-C inputs
 

 .. option:: -mharden-sls=<arg>
 
 Select straight-line speculation hardening scope (ARM/AArch64/X86 only). <arg> must be: all, none, retbr(ARM/AArch64), blr(ARM/AArch64), comdat(ARM/AArch64), nocomdat(ARM/AArch64), return(X86), indirect-jmp(X86)
 
 .. option:: --migrate
 
 Run the migrator
 
+.. option:: -mmacosx-version-min=<arg>
+
+Sets the deployment target version (macOS only)
+
+.. evnvar:: MACOSX_DEPLOYMENT_TARGET
+
+Sets the deployment target version (macOS only).
+This variable might not correctly handle non-ASCII characters in some hosts.
+
 .. option:: -mios-simulator-version-min=<arg>, -miphonesimulator-version-min=<arg>
 
+Sets the deployment target version (iOS only)
+
+.. evnvar:: IPHONEOS_DEPLOYMENT_TARGET
+
+Sets the deployment target version (iOS only).
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. option:: -mtvos-version-min=<arg>
+
+Sets the deployment target version (tvOS only)
+
+.. evnvar:: TVOS_DEPLOYMENT_TARGET
+
+Sets the deployment target version (tvOS only).
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. option:: -mwatchos-version-min=<arg>
+
+Sets the deployment target version (watchOS only)
+
+.. evnvar:: WATCHOS_DEPLOYMENT_TARGET
+
+Sets the deployment target version (watchOS only).
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. option:: -mdriverkit-version-min=<arg>
+
+Sets the deployment target version (DriverKit only)
+
+.. evnvar:: DRIVERKIT_DEPLOYMENT_TARGET
+
+Sets the deployment target version (DriverKit only).
+This variable might not correctly handle non-ASCII characters in some hosts.
+
 .. option:: -mlinker-version=<arg>
 
 .. option:: -mlittle-endian, -EL
 
 .. option:: -mllvm <arg>
 
 Additional arguments to forward to LLVM's option processing
 

 
 Add directory to include search path. For C++ inputs, if
 there are multiple -I options, these directories are searched
 in the order they are given before the standard system directories
 are searched. If the same directory is in the SYSTEM include search
 paths, for example if also specified with -isystem, the -I option
 will be ignored
 
+.. envvar:: CPATH=<paths>
+
+Takes a list of paths to add to the include search path, like :option:`-I<dir>`.
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
+
 .. option:: -I-, --include-barrier
 
 Restrict all prior -I flags to double-quoted inclusion and remove current directory from include path
 
 .. option:: --amdgpu-arch-tool=<arg>
 
 Tool used for detecting AMD GPU arch in the system.
 
 .. option:: --cuda-path-ignore-env
 
 Ignore environment variables to detect CUDA installation
 
 .. option:: --cuda-path=<arg>
 
 CUDA installation path
 
-.. option:: -cxx-isystem<directory>
-
-Add directory to the C++ SYSTEM include search path
-
 .. option:: -fbuild-session-file=<file>
 
 Use the last modification time of <file> as the build session timestamp
 
 .. option:: -fbuild-session-timestamp=<time since Epoch in seconds>
 
 Time when the current build session started
 
 .. option:: -fmodule-file=\[<name>=\]<file>
 
 Specify the mapping of module name to precompiled module file, or load a module file if name is omitted.
 
 .. option:: -fmodules-cache-path=<directory>
 
 Specify the module cache path
 
+.. envvar:: CLANG_MODULE_CACHE_PATH=<directory>
+
+Specify the module cache path.
+Will be used as a fallback if ::option::`-fmodules-cache-path=<directory>` is not specified.
+This variable might not correctly handle non-ASCII characters in some hosts.
+
 .. option:: -fmodules-disable-diagnostic-validation
 
 Disable validation of the diagnostic options when loading the module
 
 .. option:: -fmodules-prune-after=<seconds>
 
 Specify the interval (in seconds) after which a module file will be considered unused
 

 .. option:: -iquote<directory>
 
 Add directory to QUOTE include search path
 
 .. option:: -isysroot<dir>
 
 Set the system root directory (usually /)
 
+.. envvar:: SDKROOT=<dir>
+
+Set the system root directory, with a lower precedence than :option:`-isysroot<dir>` (Darwin only).
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. envvar:: RC_DEBUG_OPTIONS=<val>
+
+Sets DWARF debug flag if $val is not empty (Darwin only).
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. envvar:: RC_DEBUG_PREFIX_MAP=<val>
+
+Sets debug path remapping (Darwin only).
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. envvar:: SCE_ORBIS_SDK_DIR=<path>
+
+Determine where to find the libraries (PS4 only).
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. envvar:: SCE_PROSPERO_SDK_DIR=<path>
+
+Determine where to find the libraries (PS5 only).
+This variable might not correctly handle non-ASCII characters in some hosts.
+
 .. option:: -isystem<directory>
 
 Add directory to SYSTEM include search path
 
 .. option:: -isystem-after<directory>
 
 Add directory to end of the SYSTEM include search path
 
+.. option:: -c-isystem<directory>
+
+Add directory to the C SYSTEM include search path
+
+.. envvar:: C_INCLUDE_PATH=<paths>
+
+Takes a list of paths to add to the C SYSTEM include search path, like :option:`-c-isystem<directory>`.
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. option:: -cxx-isystem<directory>
+
+Add directory to the C++ SYSTEM include search path
+
+.. envvar:: CPLUS_INCLUDE_PATH=<paths>
+
+Takes a list of paths to add to the C++ SYSTEM include search path, like :option:`-cxx-isystem<directory>`.
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. option:: -objc-isystem<directory>
+
+Add directory to the Objective-C SYSTEM include search path
+
+.. envvar:: OBJC_INCLUDE_PATH=<paths>
+
+Takes a list of paths to add to the Objective-C SYSTEM include search path, like :option:`-objc-isystem<directory>`.
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. option:: -objcxx-isystem<directory>
+
+Add directory to the Objective-C++ SYSTEM include search path
+
+.. envvar:: OBJCPLUS_INCLUDE_PATH=<paths>
+
+Takes a list of paths to add to the Objective-C++ SYSTEM include search path, like :option:`-objcxx-isystem<directory>`.
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. envvar:: NCC_C_INCLUDE_PATH=<paths>
+
+Takes a list of paths to add to the C SYSTEM include search path, like :option:`-c-isystem<directory>` (VE only).
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. envvar:: NCC_CPLUS_INCLUDE_PATH=<paths>
+
+Takes a list of paths to add to the C++ SYSTEM include search path, like :option:`-cxx-isystem<directory>` (VE only).
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. envvar:: XCC_C_INCLUDE_PATH=<paths>
+
+Takes a list of paths to add to the C SYSTEM include search path, like :option:`-c-isystem<directory>` (XCore only).
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. envvar:: XCC_CPLUS_INCLUDE_PATH=<paths>
+
+Takes a list of paths to add to the C++ SYSTEM include search path, like :option:`-cxx-isystem<directory>` (XCore only).
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
+
 .. option:: -ivfsoverlay<arg>
 
 Overlay the virtual filesystem described by file over the real file system
 
 .. option:: -iwithprefix<dir>, --include-with-prefix <arg>, --include-with-prefix-after <arg>, --include-with-prefix-after=<arg>, --include-with-prefix=<arg>
 
 Set directory to SYSTEM include search path with prefix
 

 Set Fuchsia API level
 
 .. option:: -inline-asm=<arg>
 
  <arg> must be 'att' or 'intel'.
 
 .. option:: -m16
 
+Generate code for a 16-bit environment.
+
 .. option:: -m32
 
+Generate code for a 32-bit environment.
+
 .. option:: -m64
 
+Generate code for a 64-bit environment.
+
+.. envvar:: OBJECT_MODE=<mode>
+
+Changes the code generation based on $mode (AIX only).
+Possible values are ``32``, for a 32-bit environment, and ``64`` for a 64-bit one.
+
 .. option:: -mabi=<arg>
 
 .. program:: clang1
 .. option:: -mabi=quadword-atomics
 .. program:: clang
 
 Enable quadword atomics ABI on AIX (AIX PPC64 only). Uses lqarx/stqcx. instructions.
 

 Linker flags
 ============
 Flags that are passed on to the linker
 
 .. option:: -L<dir>, --library-directory <arg>, --library-directory=<arg>
 
 Add directory to library search path
 
+.. envvar:: LIBRARY_PATH=<paths>
+
+Add $paths to the library search path. The value is a list of paths separated by a system standard
+separator. On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts under some circumstances.
+
 .. option:: -Mach
 
 .. option:: -T<script>
 
 Specify <script> as linker script
 
 .. option:: -Tbss<addr>
 

 Use the new offloading linker to perform the link job.
 
 .. option:: -pie
 
 .. option:: -r
 
 .. option:: -rdynamic
 
-.. option:: --rocm-device-lib-path=<arg>, --hip-device-lib-path=<arg>
+.. option:: --rocm-device-lib-path=<arg>
+
+ROCm device library path (ROCm only). Alternative to :option:`--rocm-path=<arg>`.
 
-ROCm device library path. Alternative to rocm-path.
+.. envvar:: ROCM_PATH=<paths>
+
+Takes a list of paths to add to the ROCm device library paths, like :option:`--rocm-path=<arg>` (ROCm only).
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
+
+.. option:: --hip-device-lib-path=<arg>
+
+HIP device library path (HIP and ROCm only). Alternative to :option:`--hip-path=<arg>`.
+
+.. envvar:: HIP_DEVICE_LIB_PATH=<paths>
+
+Takes a list of paths to add to the HIP device library paths, like :option:`--hip-path=<arg>` (HIP and ROCm only).
+The value is a list of paths separated by a system standard separator.
+On Windows and Unix, this separator should be colon, just like ``PATH``.
+
+This variable might not correctly handle non-ASCII characters in some hosts.
 
 .. option:: -rpath <arg>
 
 .. option:: -s
 
 .. option:: -shared, --shared
 
 .. option:: -specs=<arg>, --specs=<arg>

 
 .. option:: -z <arg>
 
 Pass -z <arg> to the linker
 
 <clang-cl options>
 ==================
 CL.EXE COMPATIBILITY OPTIONS
+.. program:: clang-cl
+
+.. envvar:: INCLUDE=<path>, EXTERNAL_INCLUDE=<path>
+
+Paths to the include subdirectory of visual studio.
+Normally set by ``vcvarsall.bat``.
+
+.. envvar:: LIB=<paths>
+
+Additional search paths to pass to the linker.
+The value is a list of paths separated by a system standard
+separator. On Windows and Unix, this separator should be colon, just like ``PATH``.
 
 <clang-cl compile-only options>
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 </M group>
 ----------
 </volatile group>
 -----------------
 <clang-cl ignored options>