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 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
