Skip to content

[Clang][Docs][NFC] Correct documentation for the CPATH environment variable #129113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 6, 2025
Merged

[Clang][Docs][NFC] Correct documentation for the CPATH environment variable #129113

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b274bb5
[Clang][Docs][NFC] Correct documentation for the CPATH environment va…
tahonermann Feb 27, 2025
3998ad4
Squash: Addressed review comments from Erich Keane.
tahonermann Mar 6, 2025
d78fccd
Squash: Correct documentation regardling the handling of empty entrie…
tahonermann Mar 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions clang/docs/CommandGuide/clang.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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\<directory\>` option at
the end of the driver command line. Paths are delimited by the platform
dependent delimiter as used in the ``PATH`` environment variable. Empty
components in the environment variable are ignored.
Copy link
Collaborator

@erichkeane erichkeane Feb 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I realize this is pre-existing, but 'empty components' is a little awkward? Anyone got a thesaurus for this :D ? Perhaps 'empty directories' (though perhaps inaccurate?).

Copy link
Contributor Author

@tahonermann tahonermann Feb 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also found that wording a little awkward, but I wasn't able to come up with anything better. We could say something like "empty entries in the delimited path list are ignored". Is that an improvement? I dunno.

Separately, and interestingly, gcc treats such empty components/entries as if "." were specified. I find that horrifying and am glad that clang doesn't emulate that behavior! We could document this deviation from gcc behavior though.

Copy link
Collaborator

@erichkeane erichkeane Feb 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'entries' is actually way nicer I think, I'd prefer that instead. components makes me wonder whether that means parts of a path/etc.

Documenting that deviation is a good idea too IMO.

Copy link
Contributor Author

@tahonermann tahonermann Mar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @erichkeane, I switched to "entries" and that does read better. I also documented the deviation from GCC as discussed. But then I discovered #49742, validated that it was correct, and instead fixed another case of blatantly incorrect documentation. Clang does do the awful thing that GCC does.

In the Clang Language WG meeting yesterday, we briefly discussed whether, e.g., paths set by C_INCLUDE_PATH are used when compiling for C++. I tested all of the environment variables with both Clang and GCC across all of C, C++, Objective-C, and Objective-C++. GCC consistently applies paths only with the associated language (e.g., paths nominated by C_INCLUDE_PATH are not used for C++, Objective-C, or Objective-C++ compilation). Clang does similarly with one exception for which there is a FIXME comment in the relevant code (see here). I chose not to document that deviation due to the FIXME comment.

Finally, I observed that GCC doesn't document the OBJCPLUS_INCLUDE_PATH environment variable. So I checked whether GCC supports it and found that it does and has since at least 2003 and filed a documentation bug for GCC maintainers (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=119146).

Copy link
Contributor Author

@tahonermann tahonermann Mar 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For historical reference, that FIXME was introduced by 559865c by @d0k.


.. 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

Expand Down