[clang] a907246 - [Clang][Docs][NFC] Correct documentation for the CPATH environment variable (#129113)

[via cfe-commits]

Author: Tom Honermann
Date: 2025-03-06T13:01:30-05:00
New Revision: a907246fb29bd74dc025beb87a2ef1858a8d0dae

URL: https://github.com/llvm/llvm-project/commit/a907246fb29bd74dc025beb87a2ef1858a8d0dae
DIFF: https://github.com/llvm/llvm-project/commit/a907246fb29bd74dc025beb87a2ef1858a8d0dae.diff

LOG: [Clang][Docs][NFC] Correct documentation for the CPATH environment variable (#129113)

Clang's prior documentation for the `CPATH` environment variable stated that
paths it specifies are added as system header search paths. The actual behavior
is that such paths are treated as though they were passed via `-I` options at
the end of the driver command line and are thus added as non-system (user)
header search paths.

The documentation additionally claimed that empty path entries in the `CPATH`
environment variable are ignored. This was also incorrect; Clang treats empty
entries as nominating the compiler's current working directory; as though `.`
was specified.

Clang's behavior is consistent with gcc as documented at
https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html#index-CPATH.

This change aligns Clang's documentation with the behavior actually observed.
Additional editorial changes are included to clarify that the related
`C_INCLUDE_PATH`, `CPLUS_INCLUDE_PATH`, `OBJC_INCLUDE_PATH`, and
`OBJCPLUS_INCLUDE_PATH` environment variables specify additional paths that
are treated as system header search paths (in contrast to `CPATH`).

Fixes issue #49742.

Added: 
    

Modified: 
    clang/docs/CommandGuide/clang.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/CommandGuide/clang.rst b/clang/docs/CommandGuide/clang.rst
index ca8176f854729..f0d94a4e628b0 100644
--- a/clang/docs/CommandGuide/clang.rst
+++ b/clang/docs/CommandGuide/clang.rst
@@ -733,16 +733,19 @@ ENVIRONMENT
 
 .. envvar:: CPATH
 
-  If this environment variable is present, it is treated as a delimited list of
-  paths to be added to the default system include path list. The delimiter is
-  the platform dependent delimiter, as used in the PATH environment variable.
-
-  Empty components in the environment variable are ignored.
+  This environment variable specifies additional (non-system) header search
+  paths to be used to find included header files. These paths are searched after
+  paths specified with the :option:`-I\<directory\>` option, but before any
+  system header search paths. Paths are delimited by the platform dependent
+  delimiter as used in the ``PATH`` environment variable. Empty entries in the
+  delimited path list, including those at the beginning or end of the list, are
+  treated as specifying the compiler's current working directory.
 
 .. envvar:: C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH
 
-  These environment variables specify additional paths, as for :envvar:`CPATH`, which are
-  only used when processing the appropriate language.
+  These environment variables specify additional system header file search
+  paths to be used when processing the corresponding language. Search paths are
+  delimited as for the :envvar:`CPATH` environment variable.
 
 .. envvar:: MACOSX_DEPLOYMENT_TARGET