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

[via cfe-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang

Author: Tom Honermann (tahonermann)

<details>
<summary>Changes</summary>

Clang's [current documentation for the `CPATH` environment variable](https://clang.llvm.org/docs/CommandGuide/clang.html#envvar-CPATH) states that paths it specifies are added as system header search paths. That documentation has been in place and incorrect since it was added in 2009 (via [this commit](https://github.com/llvm/llvm-project/commit/16af476c4229bc4fb66f0bbbe90168bbe9026625)). The actual behavior (see [here](https://github.com/llvm/llvm-project/blob/e5d93100b656df86854b58433816b0b03ef9f231/clang/lib/Driver/ToolChains/Clang.cpp#L1255-L1257)) 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; that has been the behavior since at least 2011 (see [this commit](https://github.com/llvm/llvm-project/commit/8404eb0badf2911f5afe5039c3887919875dcad5). 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`).

---
Full diff: https://github.com/llvm/llvm-project/pull/129113.diff


1 Files Affected:

- (modified) clang/docs/CommandGuide/clang.rst (+8-7) 


``````````diff
diff --git a/clang/docs/CommandGuide/clang.rst b/clang/docs/CommandGuide/clang.rst
index ca8176f854729..dc8ee3dacf895 100644
--- a/clang/docs/CommandGuide/clang.rst
+++ b/clang/docs/CommandGuide/clang.rst
@@ -733,16 +733,17 @@ 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 header file search paths which
+  behave as if they were specified with the :option:`-I` option at the end of
+  the driver command line. Paths are delimited by the platform dependent
+  delimiter as used in the :envvar:`PATH` environment variable. Empty components
+  in the environment variable are ignored.
 
 .. 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
 

``````````

</details>


https://github.com/llvm/llvm-project/pull/129113