llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-clang Author: basisworks <details> <summary>Changes</summary> The `Command Line Options` section of the Clang User's Manual opens with: > This section is generally an index into other sections. It does not go into depth on the ones that are covered by other sections. However, the first part introduces the language selection and other high level options like `-c`, `-g`, etc. and then goes directly into `Options to Control Error and Warning Messages`. There is no first part. The promised introduction has never existed — this was reported as [PR10424](https://llvm.org/bz10424) in 2011, migrated here as #<!-- -->10796, and the sentence still dangles today. This adds the section it advertises, immediately after that paragraph. ### What it covers - **Stage selection** — `-E`, `-fsyntax-only`, `-S`, `-c`, and the default of running everything through the linker, as a table of "runs through / produces", plus the way `-o` attaches to whichever stage is last. - **Language inference** — the extension-to-language table, taken from `lookupTypeForExtension` in `clang/lib/Driver/Types.cpp` rather than from the older prose, so it includes the module-interface, CUDA/HIP, OpenCL and HLSL extensions. - **`-x`** — that it applies to inputs *after* it rather than to the whole command line, that it persists until the next `-x`, and that `-x none` restores inference. This is the part users most often get wrong and it is not stated anywhere else in the manual. Behaviour checked against `Driver::BuildInputs` in `clang/lib/Driver/Driver.cpp`, where `-x` sets `InputType` for subsequent inputs and `TY_Nothing` means "infer from the extension". - **`-std=`** — the `gnu` variants, the `gnu17`/`gnu++17` defaults (`gnu99` on PS4), and the interaction with `-x`. - **`-g`, `-O`, `-emit-llvm`, `-###`** — the remaining options the dangling sentence calls "high level". Depth is deliberately kept shallow, matching the section's own stated job of being an index: each subsection points at {doc}`clang <CommandGuide/clang>` for the complete lists rather than duplicating them. ### Notes for review - Documentation only. No functional change. - Option names that are already defined in `CommandGuide/clang.rst` are referenced with `{option}` roles; anything with an argument or a comma in its definition is left as plain monospace, matching the existing convention in this file (see the `-Werror` comment about duplicate Sphinx labels). - Formatting follows the surrounding file: `####` subheadings, pipe tables, and ```console fences are all already used in `UsersManual.md`. Created with: Claude (Anthropic) --- Full diff: https://github.com/llvm/llvm-project/pull/213542.diff 1 Files Affected: - (modified) clang/docs/UsersManual.md (+92) ``````````diff diff --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md index bce811eed283b..fabc8ff5ee50b 100644 --- a/clang/docs/UsersManual.md +++ b/clang/docs/UsersManual.md @@ -113,6 +113,98 @@ into depth on the ones that are covered by other sections. However, the first part introduces the language selection and other high level options like {option}`-c`, {option}`-g`, etc. +### Language Selection and High-Level Options + +`clang` is a compiler driver: one command that runs a sequence of stages over +its inputs and hands the results to the next tool. The options below select how +far down that sequence to go, and how the driver should interpret what it was +given. The {doc}`clang <CommandGuide/clang>` manual page is the complete +reference for each of them. + +#### Selecting a stage + +With no stage selection option, `clang` runs every stage and then runs the +linker, producing an executable or a shared library. Passing one of the +following stops it earlier: + +| Option | Runs through | Produces | +| ------ | ------------ | -------- | +| {option}`-E` | Preprocessing | Preprocessed source, on standard output | +| {option}`-fsyntax-only` | Semantic analysis | Nothing but diagnostics | +| {option}`-S` | Code generation | An assembly file, `.s` by default | +| {option}`-c` | Assembly | An object file, `.o` by default | +| *(none)* | Linking | An executable or shared library | + +{option}`-o` names the output file. It applies to whichever stage is last, so +`-E -o out.i`, `-S -o out.s` and `-c -o out.o` all write where you asked. + +#### Selecting the input language + +Clang infers a language for each input from its file extension: + +| Extension | Language | +| --------- | -------- | +| `.c` | C | +| `.i` | Preprocessed C | +| `.h` | C header | +| `.C`, `.cc`, `.CC`, `.cp`, `.cpp`, `.CPP`, `.c++`, `.cxx`, `.CXX` | C++ | +| `.ii` | Preprocessed C++ | +| `.H`, `.hh`, `.hpp`, `.hxx` | C++ header | +| `.ccm`, `.cppm`, `.cxxm`, `.c++m` | C++ module interface unit | +| `.m` | Objective-C | +| `.mi` | Preprocessed Objective-C | +| `.M`, `.mm` | Objective-C++ | +| `.mii` | Preprocessed Objective-C++ | +| `.cu` | CUDA | +| `.hip` | HIP | +| `.cl` | OpenCL C | +| `.clcpp` | C++ for OpenCL | +| `.hlsl` | HLSL | +| `.s` | Assembly | +| `.S` | Assembly, preprocessed first | +| `.ll` | LLVM IR | +| `.bc` | LLVM bitcode | +| `.o`, `.obj`, `.lib` | Passed straight to the linker | + +Use {option}`-x` to override that inference, most often to compile a file whose +extension does not match its contents, or to compile from standard input: + +```console +$ clang -x c++ header_only.h -fsyntax-only +$ echo 'int main() {}' | clang -x c - -o a.out +``` + +{option}`-x` applies to every input **after** it on the command line, not to the +whole invocation, and it persists until the next {option}`-x`. `-x none` +restores extension-based inference for the inputs that follow: + +```console +$ clang -x c++ a.h b.h -x none c.c +``` + +Here `a.h` and `b.h` are compiled as C++ and `c.c` as C. Naming a language +clang does not recognise is an error. + +#### Selecting the language standard + +`-std=<standard>` selects the language standard, for example `-std=c23` or +`-std=c++20`. Each standard also has a `gnu` variant that enables GNU +extensions, such as `gnu23` and `gnu++20`. The default is `gnu17` for C +(`gnu99` on PS4) and `gnu++17` for C++. The +{doc}`clang <CommandGuide/clang>` manual page lists every accepted value. + +Note that the standard is a property of the input language, so `-std=` and +{option}`-x` interact: `-std=c++20` has no effect on an input that clang is +treating as C. + +#### Other high-level options + +{option}`-g` requests debug information, `-O0` through `-O3`, `-Os` and `-Oz` +select an optimization level, and `-emit-llvm` makes {option}`-S` and +{option}`-c` emit LLVM IR and LLVM bitcode instead of assembly and object code. +`-###` prints the commands the driver would run, without running them, which is +the fastest way to see what a given set of options actually does. + ### Options to Control Error and Warning Messages :::{option} -Werror `````````` </details> https://github.com/llvm/llvm-project/pull/213542 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
