https://github.com/basisworks created https://github.com/llvm/llvm-project/pull/213542
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) >From c3d23980daf4dbd397aa4c9fda431ffedf23e687 Mon Sep 17 00:00:00 2001 From: basisworks <[email protected]> Date: Sun, 2 Aug 2026 09:09:00 -0400 Subject: [PATCH] [clang][docs] Document language selection and high-level driver options The "Command Line Options" section of the Clang User's Manual states that "the first part introduces the language selection and other high level options like -c, -g, etc.", then goes straight into diagnostic options. No such introduction has ever existed; the sentence has been dangling since the text was written. Add the section it promises, covering stage selection, how the driver infers an input's language from its extension, -x and -x none, -std= and the other high-level options, with pointers to the clang manual page for the exhaustive lists. Documentation only. Fixes #10796 --- clang/docs/UsersManual.md | 92 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) 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 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
