summaryrefslogtreecommitdiff
path: root/clang/docs/CommandGuide
AgeCommit message (Collapse)Author
2025-07-29[Clang][Docs] Fix typo in clang.rst (#150907)Tomer Shafir
2025-06-19Reapply "[Clang] Enable -fextend-variable-liveness at -Og (#118026)"Stephen Tozer
Relands this feature after several fixes: * Force fake uses to be emitted before musttail calls (#136867) * Added soften-float legalization for fake uses (#142714) * Treat fake uses as size-less instructions in a SystemZ assert (#144390) If further issues with fake uses are found then this may be reverted again, but all currently-known issues are resolved. This reverts commit 2dc6e98169baeb1f73036da0ea50fd828d8323d0.
2025-05-06[clang][doc] Document C2y flags (#138521)Raul Tambre
As discussed at https://github.com/llvm/llvm-project/pull/138459#issuecomment-2850716184
2025-05-05[clang] Alias iso9899:2024 to C23, update documentation (#138459)Raul Tambre
2025-04-25Revert "[Clang] Enable -fextend-lifetimes at -Og (#118026)"Stephen Tozer
Reverted following several issues appearing related to fake uses, reported on the github PR. This reverts commit a9dff35ad251cd20376ab25b26d1e5394e18ff4c.
2025-04-17[Clang] Enable -fextend-lifetimes at -Og (#118026)Stephen Tozer
Recently, a new flag -fextend-variable-liveness was added that prevents optimizations from removing the values of source variables in some cases, improving the quality of debugging for optimized builds where it is enabled. Following the inclusion of the flag, this patch enables it by default when `-Og` is set. Currently, `-Og` is equivalent to `-O1` - it is effectively just an alias. By enabling `-fextend-lifetimes`, this patch changes the code generated by Clang with `-Og` to have reduced optimization and greater debuggability than `-O1`, differentiating the two according to their respective purposes. This idea was discussed previously on Discourse where there was general agreement with the principle of this change: https://discourse.llvm.org/t/rfc-redefine-og-o1-and-add-a-new-level-of-og
2025-03-27[Docs] Document freestanding requirements (#132232)Aaron Ballman
This adds some initial documentation about freestanding requirements for Clang. The most critical part of the documentation is spelling out that a conforming freestanding C Standard Library is required; Clang will not be providing the headers for <string.h> in C23 which expose a number of symbols in freestanding mode. The docs also make it clear that in addition to a conforming freestanding C standard library, the library must provide some additional symbols which LLVM requires. These docs are not comprehensive, this is just getting the bare bones in place so that they can be expanded later. This also updates the C status page to make it clear that we don't have anything to do for WG14 N2524 which adds string interfaces to freestanding mode.
2025-03-06[Clang][Docs][NFC] Correct documentation for the CPATH environment variable ↵Tom Honermann
(#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.
2024-08-07[clang][docs] Update Include Options Help (#101192)Sam Elliott
This adds HelpTexts for some clang options that relate to include directory handling, to sync them up with what's in clang.rst (and therefore the man page).
2024-08-02Ofast deprecation clarifications (#101005)Sjoerd Meijer
Following up on the RFC discussion, this is clarifying that the main purpose and effect of the -Ofast deprecation is to discourage its usage and that everything else is more or less open for discussion, e.g. there is no timeline yet for removal. --------- Co-authored-by: Aaron Ballman <aaron@aaronballman.com>
2024-07-18[clang] Add deprecation warning for `-Ofast` driver option (#98736)Vlad Serebrennikov
This patch implements consensus on the corresponding RFC documented here: https://discourse.llvm.org/t/rfc-deprecate-ofast/78687/72 Specifically, I added a deprecation warning for `-Ofast`, that suggests to use `-O3` or `-O3` with `-ffast-math`, and a new diagnostic group for aforementioned warning. Deprecation period is going to be lengthy, so I hope this PR can be merged in time for Clang 19.
2024-07-15[AArch64][RISCV] Document option --print-supported-extensions (#98698)Jonathan Thackray
Add documentation for the `--print-supported-extensions` option which appears to be missing at present.
2024-07-10[RISCV] Add ability to list extensions enabled for a target (#98207)Michael Maitland
bb83a3d introduced `--print-enabled-extensions` command line option for AArch64. This patch introduces RISC-V support for this option. This patch adds documentation for this option. `riscvExtensionsHelp` is renamed to `printSupportedExtensions` to by synonymous with AArch64 and so it is clear what that function does.
2024-06-16[clang] Clean up macOS version flags (#95374)Gábor Horváth
The -mmacos-version-min flag is preferred over -mmacosx-version-min. This patch updates the tests and documentation to make this clear and also adds the missing logic to scan build to handle the new flag. Fixes #86376. Co-authored-by: Gabor Horvath <gaborh@apple.com>
2024-01-16[clang-cl] document correct defaults for `-fms-compatibility-version` / ↵h-vetinari
`-fmsc-version` (#76418) The UserManual states wrongly (AFAICT) that these default are not being defined for clang-cl, whereas further up the opposite is stated: https://github.com/llvm/llvm-project/blob/c86fe3ee0b92934f5d18394d9a0cdc1d3f0eef64/clang/docs/UsersManual.rst#L3375-L3382 I've chosen to follow that wording, as it's the latest related update. CC @RIscRIpt who recently touched this in b3e6ff331925dde24a4707452d657da0fdf7f588 CC @AaronBallman who cared about this, c.f. 8fc0dcf036bf199b2af2e10a4f81215dbd706daf
2023-10-06Add -fkeep-system-includes modifier for -EPaul Robinson
This option will cause -E to preserve the #include directives for system headers, rather than expanding them into the output. This can greatly reduce the volume of preprocessed source text in a test case, making test case reduction simpler. Note that -fkeep-system-includes is not always appropriate. For example, if the problem you want to reproduce is induced by a system header file, it's better to expand those headers fully. If your source defines symbols that influence the content of a system header (e.g., _POSIX_SOURCE) then -E will eliminate the definition, potentially changing the meaning of the preprocessed source. If you use -isystem to point to non-system headers, for example to suppress warnings in third-party software, those will not be expanded and might make the preprocessed source less useful as a test case.
2023-05-23Correct stale documentation for default MSVC version numbersAaron Ballman
We documented -fmsc-version as defaulting to 1300 and -fms-compatibility-version as defaulting to 1800, neither of which were accurate. We currently default to 1920. See MSVCToolChain::computeMSVCVersion() for details.
2023-05-15Add C++26 compile flags.Erich Keane
Now that we've updated to C++23, we need to add C++26/C++2c command line flags, as discussed in https://discourse.llvm.org/t/rfc-lets-just-call-it-c-26-and-forget-about-the-c-2c-business-at-least-internally/70383 Differential Revision: https://reviews.llvm.org/D150450
2023-05-04[clang] Use -std=c++23 instead of -std=c++2bMark de Wever
During the ISO C++ Committee meeting plenary session the C++23 Standard has been voted as technical complete. This updates the reference to c++2b to c++23 and updates the __cplusplus macro. Drive-by fixes c++1z -> c++17 and c++2a -> c++20 when seen. Reviewed By: aaron.ballman Differential Revision: https://reviews.llvm.org/D149553
2023-03-16[Driver] Allow to collect `-save-stats` data to a file specified in the ↵Volodymyr Sapsai
environment variable. Using two environment variables `CC_PRINT_INTERNAL_STAT` and `CC_PRINT_INTERNAL_STAT_FILE` to work like `CC_PRINT_PROC_STAT`. The purpose of the change is to allow collecting the internal stats without modifying the build scripts. Write all stats to a single file to simplify aggregating the data. Differential Revision: https://reviews.llvm.org/D144981
2023-03-14[clang][docs] Clarify the semantics of -fexceptionsAlex Bradbury
As noted in <https://github.com/llvm/llvm-project/issues/61216>, the documentation for -fexceptions appears to imply that unwind information is always generated, which isn't the case. Differential Revision: https://reviews.llvm.org/D145564
2023-02-28[Clang][Driver] Add -mcpu=help and -mtune=help to clangMichael Maitland
Clang currently uses `-mcpu=?` and `-mtune=?`. The `?` causes errors on some shells such as zsh since it is a special character. In order for it to work on shells such as zsh, the option must be passed in quotes or escaped. This patch adds `-mcpu=help` and `-mtune=help` as another alias for `--print-supported-cpus`. In llc, `-mcpu=help` is an alias to print supported cpus. Differential Revision: https://reviews.llvm.org/D144914
2022-10-29[docs] clang.rst: gnu++14 => gnu++17Fangrui Song
2022-08-19[clang,flang] Add help text for -fsyntax-onlyAlexander Malkov
Fix for the problem with displaying options `-fsyntax-only` in clang and flang-new in help Fix https://github.com/llvm/llvm-project/issues/57033 Before: ``` $ clang -help | grep syntax -objcmt-migrate-property-dot-syntax Enable migration of setter/getter messages to property-dot syntax ``` After: ``` $ clang -help | grep syntax -fsyntax-only Run the preprocessor, parser and semantic analysis stages -objcmt-migrate-property-dot-syntax Enable migration of setter/getter messages to property-dot syntax ``` Reviewed By: vzakhari, awarzynski, MaskRay, alexiprof Differential Revision: https://reviews.llvm.org/D131808
2022-06-09[docs] Update supported language standards list for C++Yuki Okushi
Differential Revision: https://reviews.llvm.org/D127065
2022-04-20Treat `std::move`, `forward`, etc. as builtins.Richard Smith
This is extended to all `std::` functions that take a reference to a value and return a reference (or pointer) to that same value: `move`, `forward`, `move_if_noexcept`, `as_const`, `addressof`, and the libstdc++-specific function `__addressof`. We still require these functions to be declared before they can be used, but don't instantiate their definitions unless their addresses are taken. Instead, code generation, constant evaluation, and static analysis are given direct knowledge of their effect. This change aims to reduce various costs associated with these functions -- per-instantiation memory costs, compile time and memory costs due to creating out-of-line copies and inlining them, code size at -O0, and so on -- so that they are not substantially more expensive than a cast. Most of these improvements are very small, but I measured a 3% decrease in -O0 object file size for a simple C++ source file using the standard library after this change. We now automatically infer the `const` and `nothrow` attributes on these now-builtin functions, in particular meaning that we get a warning for an unused call to one of these functions. In C++20 onwards, we disallow taking the addresses of these functions, per the C++20 "addressable function" rule. In earlier language modes, a compatibility warning is produced but the address can still be taken. The same infrastructure is extended to the existing MSVC builtin `__GetExceptionInfo`, which is now only recognized in namespace `std` like it always should have been. This is a re-commit of fc3090109643af8d2da9822d0f99c84742b9c877, a571f82a50416b767fd3cce0fb5027bb5dfec58c, 64c045e25b8471bbb572bd29159c294a82a86a2, and de6ddaeef3aaa8a9ae3663c12cdb57d9afc0f906, and reverts aa643f455a5362de7189eac630050d2c8aefe8f2. This change also includes a workaround for users using libc++ 3.1 and earlier (!!), as apparently happens on AIX, where std::move sometimes returns by value. Reviewed By: aaron.ballman Differential Revision: https://reviews.llvm.org/D123345 Revert "Fixup D123950 to address revert of D123345" This reverts commit aa643f455a5362de7189eac630050d2c8aefe8f2.
2022-04-20Revert "Treat `std::move`, `forward`, etc. as builtins."David Tenty
This reverts commit b27430f9f46b88bcd54d992debc8d72e131e1bd0 as the parent https://reviews.llvm.org/D123345 breaks the AIX CI: https://lab.llvm.org/buildbot/#/builders/214/builds/819
2022-04-17Treat `std::move`, `forward`, etc. as builtins.Richard Smith
This is extended to all `std::` functions that take a reference to a value and return a reference (or pointer) to that same value: `move`, `forward`, `move_if_noexcept`, `as_const`, `addressof`, and the libstdc++-specific function `__addressof`. We still require these functions to be declared before they can be used, but don't instantiate their definitions unless their addresses are taken. Instead, code generation, constant evaluation, and static analysis are given direct knowledge of their effect. This change aims to reduce various costs associated with these functions -- per-instantiation memory costs, compile time and memory costs due to creating out-of-line copies and inlining them, code size at -O0, and so on -- so that they are not substantially more expensive than a cast. Most of these improvements are very small, but I measured a 3% decrease in -O0 object file size for a simple C++ source file using the standard library after this change. We now automatically infer the `const` and `nothrow` attributes on these now-builtin functions, in particular meaning that we get a warning for an unused call to one of these functions. In C++20 onwards, we disallow taking the addresses of these functions, per the C++20 "addressable function" rule. In earlier language modes, a compatibility warning is produced but the address can still be taken. The same infrastructure is extended to the existing MSVC builtin `__GetExceptionInfo`, which is now only recognized in namespace `std` like it always should have been. This is a re-commit of fc3090109643af8d2da9822d0f99c84742b9c877, a571f82a50416b767fd3cce0fb5027bb5dfec58c, and 64c045e25b8471bbb572bd29159c294a82a86a25 which were reverted in e75d8b70370435b0ad10388afba0df45fcf9bfcc due to a crasher bug where CodeGen would emit a builtin glvalue as an rvalue if it constant-folds. Reviewed By: aaron.ballman Differential Revision: https://reviews.llvm.org/D123345
2022-04-16Revert "Treat `std::move`, `forward`, and `move_if_noexcept` as builtins."Vitaly Buka
Revert "Extend support for std::move etc to also cover std::as_const and" Revert "Update test to handle opaque pointers flag flip." It crashes on libcxx tests https://lab.llvm.org/buildbot/#/builders/85/builds/8174 This reverts commit fc3090109643af8d2da9822d0f99c84742b9c877. This reverts commit a571f82a50416b767fd3cce0fb5027bb5dfec58c. This reverts commit 64c045e25b8471bbb572bd29159c294a82a86a25.
2022-04-15Treat `std::move`, `forward`, and `move_if_noexcept` as builtins.Richard Smith
We still require these functions to be declared before they can be used, but don't instantiate their definitions unless their addresses are taken. Instead, code generation, constant evaluation, and static analysis are given direct knowledge of their effect. This change aims to reduce various costs associated with these functions -- per-instantiation memory costs, compile time and memory costs due to creating out-of-line copies and inlining them, code size at -O0, and so on -- so that they are not substantially more expensive than a cast. Most of these improvements are very small, but I measured a 3% decrease in -O0 object file size for a simple C++ source file using the standard library after this change. We now automatically infer the `const` and `nothrow` attributes on these now-builtin functions, in particular meaning that we get a warning for an unused call to one of these functions. In C++20 onwards, we disallow taking the addresses of these functions, per the C++20 "addressable function" rule. In earlier language modes, a compatibility warning is produced but the address can still be taken. The same infrastructure is extended to the existing MSVC builtin `__GetExceptionInfo`, which is now only recognized in namespace `std` like it always should have been. Reviewed By: aaron.ballman Differential Revision: https://reviews.llvm.org/D123345
2022-02-02Also document -arch as -arch is mac specificSylvestre Ledru
Reviewed By: serge-sans-paille Differential Revision: https://reviews.llvm.org/D60380
2022-01-06Update Bug report URL to Github IssuesChuanqi Xu
Although we moved to Github Issues. The bug report message refers to Bugzilla still. This patch tries to update these URLs. Reviewed By: MaskRay, Quuxplusone, jhenderson, libunwind, libc++ Differential Revision: https://reviews.llvm.org/D116351
2020-09-17[clang][docs] Fix documentation of -OJessica Clarke
D79916 changed the behaviour from -O2 to -O1 but the documentation was not updated to reflect this.
2020-09-13[Docs] Fix --print-supported-cpus option renderingTravis Finkenauer
Adds link/code sample to avoid rendering two dashes as non-ASCII "en dash". Also make wording a complete sentence. Reviewed By: nickdesaulniers, tmfink Differential Revision: https://reviews.llvm.org/D85596
2020-08-10[Clang] implement -fno-eliminate-unused-debug-typesNick Desaulniers
Fixes pr/11710. Signed-off-by: Nick Desaulniers <ndesaulniers@google.com> Resubmit after breaking Windows and OSX builds. Reviewed By: dblaikie Differential Revision: https://reviews.llvm.org/D80242
2020-08-07Revert "[Clang] implement -fno-eliminate-unused-debug-types"Nick Desaulniers
This reverts commit e486921fd6cf96ae9114adac455f7c0b5c1088a7. Breaks windows builds and osx builds.
2020-08-07[Clang] implement -fno-eliminate-unused-debug-typesNick Desaulniers
Fixes pr/11710. Signed-off-by: Nick Desaulniers <ndesaulniers@google.com> Reviewed By: dblaikie Differential Revision: https://reviews.llvm.org/D80242
2020-07-13Fix a missing update that C compiles default to gnu17.Stephen Hines
https://reviews.llvm.org/D75383 switched the C default to gnu17, but missed this instance. Differential Revision: https://reviews.llvm.org/D83726
2020-06-30[clang][docs] Add note about using `-flto` with `-g` on macOSPhilippe Blain
If -Wl,object_path_lto,<lto-filename>.o is not passed at link time when compiling and linking in separate steps with -flto and -g, the temporary file used for Link Time Optimization is deleted by the linker, so the executable is missing debug symbols and can't be easily debugged, and dsymutil can't be run. Document this behaviour. Differential revision: https://reviews.llvm.org/D82733
2020-05-26[clang][docs] Document additional bits of libc that -ffreestanding envs must ↵Jon Roelofs
provide Differential Revision: https://reviews.llvm.org/D80436
2020-01-23Re-add documentation for -flax-vector-conversions= removed inRichard Smith
edd4398f4cd33a305afbca76ac4e6590e9337f4d. The documentation remains correct despite the revert of the patch.
2020-01-20Revert "PR17164: Change clang's default behavior from ↵Mitch Phillips
-flax-vector-conversions=all to -flax-vector-conversions=integer." This patch broke the Sanitizer buildbots. Please see the commit's differential revision for more information (https://reviews.llvm.org/D67678). This reverts commit b72a8c65e4e34779b6bc9e466203f553f5294486.
2020-01-15PR17164: Change clang's default behavior from -flax-vector-conversions=all ↵Richard Smith
to -flax-vector-conversions=integer. Summary: See proposal on cfe-dev: http://lists.llvm.org/pipermail/cfe-dev/2019-April/062030.html Reviewers: SjoerdMeijer, eli.friedman Subscribers: kristof.beyls, cfe-commits Tags: #clang Differential Revision: https://reviews.llvm.org/D67678
2019-08-16[Test Commit] Fix typo in diagtool.rstTroy A. Johnson
Test commit after obtaining commit access. llvm-svn: 369148
2019-06-25print-supported-cpus quality of life patch.Ziang Wan
Claim all input files so that clang does not give a warning. Add two short-cut aliases: -mcpu=? and -mtune=?. llvm-svn: 364362
2019-06-14Fixed the --print-supported-cpus testZiang Wan
Add constraints for the test that require specific backend targets to be registered. Remove trailing whitespace in the doc. Differential Revision: https://reviews.llvm.org/D63105 llvm-svn: 363475
2019-06-14Add --print-supported-cpus flag for clang.Ziang Wan
This patch allows clang users to print out a list of supported CPU models using clang [--target=<target triple>] --print-supported-cpus Then, users can select the CPU model to compile to using clang --target=<triple> -mcpu=<model> a.c It is a handy feature to help cross compilation. llvm-svn: 363464
2019-05-30[Docs] Modernize references to macOSJ. Ryan Stinnett
Summary: This updates all places in documentation that refer to "Mac OS X", "OS X", etc. to instead use the modern name "macOS" when no specific version number is mentioned. If a specific version is mentioned, this attempts to use the OS name at the time of that version: * Mac OS X for 10.0 - 10.7 * OS X for 10.8 - 10.11 * macOS for 10.12 - present Reviewers: JDevlieghere Subscribers: mgorny, christof, arphaman, cfe-commits, lldb-commits, libcxx-commits, llvm-commits Tags: #clang, #lldb, #libc, #llvm Differential Revision: https://reviews.llvm.org/D62654 llvm-svn: 362113
2018-11-04Update our URLs in clang doc to use httpsSylvestre Ledru
llvm-svn: 346101
2018-05-16[diagtool] Add diagtool to install target.Jonas Devlieghere
Although not very well known, diagtool is an incredibly convenient utility for dealing with diagnostics. Particularly useful are the "tree" and "show-enabled" commands: - The former prints the hierarchy of diagnostic (warning) flags and which of them are enabled by default. - The latter can be used to replace an invocation to clang and will print which diagnostics are disabled, warnings or errors. For instance: `diagtool show-enabled -Wall -Werror /tmp/test.c` will print that -Wunused-variable (warn_unused_variable) will be treated as an error. This patch adds them to the install target so it gets shipped with the LLVM release. It also adds a very basic man page and mentions this change in the release notes. Differential revision: https://reviews.llvm.org/D46694 llvm-svn: 332448