| clang - the Clang C, C++, and Objective-C compiler |
| ================================================== |
| |
| SYNOPSIS |
| -------- |
| |
| :program:`clang` [*options*] *filename ...* |
| |
| DESCRIPTION |
| ----------- |
| |
| :program:`clang` is a C, C++, and Objective-C compiler which encompasses |
| preprocessing, parsing, optimization, code generation, assembly, and linking. |
| Depending on which high-level mode setting is passed, Clang will stop before |
| doing a full link. While Clang is highly integrated, it is important to |
| understand the stages of compilation, to understand how to invoke it. These |
| stages are: |
| |
| Driver |
| The clang executable is actually a small driver which controls the overall |
| execution of other tools such as the compiler, assembler and linker. |
| Typically you do not need to interact with the driver, but you |
| transparently use it to run the other tools. |
| |
| Preprocessing |
| This stage handles tokenization of the input source file, macro expansion, |
| #include expansion and handling of other preprocessor directives. The |
| output of this stage is typically called a ".i" (for C), ".ii" (for C++), |
| ".mi" (for Objective-C), or ".mii" (for Objective-C++) file. |
| |
| Parsing and Semantic Analysis |
| This stage parses the input file, translating preprocessor tokens into a |
| parse tree. Once in the form of a parse tree, it applies semantic |
| analysis to compute types for expressions as well and determine whether |
| the code is well formed. This stage is responsible for generating most of |
| the compiler warnings as well as parse errors. The output of this stage is |
| an "Abstract Syntax Tree" (AST). |
| |
| Code Generation and Optimization |
| This stage translates an AST into low-level intermediate code (known as |
| "LLVM IR") and ultimately to machine code. This phase is responsible for |
| optimizing the generated code and handling target-specific code generation. |
| The output of this stage is typically called a ".s" file or "assembly" file. |
| |
| Clang also supports the use of an integrated assembler, in which the code |
| generator produces object files directly. This avoids the overhead of |
| generating the ".s" file and of calling the target assembler. |
| |
| Assembler |
| This stage runs the target assembler to translate the output of the |
| compiler into a target object file. The output of this stage is typically |
| called a ".o" file or "object" file. |
| |
| Linker |
| This stage runs the target linker to merge multiple object files into an |
| executable or dynamic library. The output of this stage is typically called |
| an "a.out", ".dylib" or ".so" file. |
| |
| :program:`Clang Static Analyzer` |
| |
| The Clang Static Analyzer is a tool that scans source code to try to find bugs |
| through code analysis. This tool uses many parts of Clang and is built into |
| the same driver. Please see <https://clang-analyzer.llvm.org> for more details |
| on how to use the static analyzer. |
| |
| OPTIONS |
| ------- |
| |
| Stage Selection Options |
| ~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| .. option:: -E |
| |
| Run the preprocessor stage. |
| |
| .. option:: -fsyntax-only |
| |
| Run the preprocessor, parser and type checking stages. |
| |
| .. option:: -S |
| |
| Run the previous stages as well as LLVM generation and optimization stages |
| and target-specific code generation, producing an assembly file. |
| |
| .. option:: -c |
| |
| Run all of the above, plus the assembler, generating a target ".o" object file. |
| |
| .. option:: no stage selection option |
| |
| If no stage selection option is specified, all stages above are run, and the |
| linker is run to combine the results into an executable or shared library. |
| |
| Language Selection and Mode Options |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| .. option:: -x <language> |
| |
| Treat subsequent input files as having type language. |
| |
| .. option:: -std=<standard> |
| |
| Specify the language standard to compile for. |
| |
| Supported values for the C language are: |
| |
| | ``c89`` |
| | ``c90`` |
| | ``iso9899:1990`` |
| |
| ISO C 1990 |
| |
| | ``iso9899:199409`` |
| |
| ISO C 1990 with amendment 1 |
| |
| | ``gnu89`` |
| | ``gnu90`` |
| |
| ISO C 1990 with GNU extensions |
| |
| | ``c99`` |
| | ``iso9899:1999`` |
| |
| ISO C 1999 |
| |
| | ``gnu99`` |
| |
| ISO C 1999 with GNU extensions |
| |
| | ``c11`` |
| | ``iso9899:2011`` |
| |
| ISO C 2011 |
| |
| | ``gnu11`` |
| |
| ISO C 2011 with GNU extensions |
| |
| | ``c17`` |
| | ``iso9899:2017`` |
| |
| ISO C 2017 |
| |
| | ``gnu17`` |
| |
| ISO C 2017 with GNU extensions |
| |
| The default C language standard is ``gnu11``, except on PS4, where it is |
| ``gnu99``. |
| |
| Supported values for the C++ language are: |
| |
| | ``c++98`` |
| | ``c++03`` |
| |
| ISO C++ 1998 with amendments |
| |
| | ``gnu++98`` |
| | ``gnu++03`` |
| |
| ISO C++ 1998 with amendments and GNU extensions |
| |
| | ``c++11`` |
| |
| ISO C++ 2011 with amendments |
| |
| | ``gnu++11`` |
| |
| ISO C++ 2011 with amendments and GNU extensions |
| |
| | ``c++14`` |
| |
| ISO C++ 2014 with amendments |
| |
| | ``gnu++14`` |
| |
| ISO C++ 2014 with amendments and GNU extensions |
| |
| | ``c++17`` |
| |
| ISO C++ 2017 with amendments |
| |
| | ``gnu++17`` |
| |
| ISO C++ 2017 with amendments and GNU extensions |
| |
| | ``c++2a`` |
| |
| Working draft for ISO C++ 2020 |
| |
| | ``gnu++2a`` |
| |
| Working draft for ISO C++ 2020 with GNU extensions |
| |
| The default C++ language standard is ``gnu++14``. |
| |
| Supported values for the OpenCL language are: |
| |
| | ``cl1.0`` |
| |
| OpenCL 1.0 |
| |
| | ``cl1.1`` |
| |
| OpenCL 1.1 |
| |
| | ``cl1.2`` |
| |
| OpenCL 1.2 |
| |
| | ``cl2.0`` |
| |
| OpenCL 2.0 |
| |
| The default OpenCL language standard is ``cl1.0``. |
| |
| Supported values for the CUDA language are: |
| |
| | ``cuda`` |
| |
| NVIDIA CUDA(tm) |
| |
| .. option:: -stdlib=<library> |
| |
| Specify the C++ standard library to use; supported options are libstdc++ and |
| libc++. If not specified, platform default will be used. |
| |
| .. option:: -rtlib=<library> |
| |
| Specify the compiler runtime library to use; supported options are libgcc and |
| compiler-rt. If not specified, platform default will be used. |
| |
| .. option:: -ansi |
| |
| Same as -std=c89. |
| |
| .. option:: -ObjC, -ObjC++ |
| |
| Treat source input files as Objective-C and Object-C++ inputs respectively. |
| |
| .. option:: -trigraphs |
| |
| Enable trigraphs. |
| |
| .. option:: -ffreestanding |
| |
| Indicate that the file should be compiled for a freestanding, not a hosted, |
| environment. |
| |
| .. option:: -fno-builtin |
| |
| Disable special handling and optimizations of builtin functions like |
| :c:func:`strlen` and :c:func:`malloc`. |
| |
| .. option:: -fmath-errno |
| |
| Indicate that math functions should be treated as updating :c:data:`errno`. |
| |
| .. option:: -fpascal-strings |
| |
| Enable support for Pascal-style strings with "\\pfoo". |
| |
| .. option:: -fms-extensions |
| |
| Enable support for Microsoft extensions. |
| |
| .. option:: -fmsc-version= |
| |
| Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise. |
| |
| .. option:: -fborland-extensions |
| |
| Enable support for Borland extensions. |
| |
| .. option:: -fwritable-strings |
| |
| Make all string literals default to writable. This disables uniquing of |
| strings and other optimizations. |
| |
| .. option:: -flax-vector-conversions |
| |
| Allow loose type checking rules for implicit vector conversions. |
| |
| .. option:: -fblocks |
| |
| Enable the "Blocks" language feature. |
| |
| .. option:: -fobjc-abi-version=version |
| |
| Select the Objective-C ABI version to use. Available versions are 1 (legacy |
| "fragile" ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2). |
| |
| .. option:: -fobjc-nonfragile-abi-version=<version> |
| |
| Select the Objective-C non-fragile ABI version to use by default. This will |
| only be used as the Objective-C ABI when the non-fragile ABI is enabled |
| (either via :option:`-fobjc-nonfragile-abi`, or because it is the platform |
| default). |
| |
| .. option:: -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi |
| |
| Enable use of the Objective-C non-fragile ABI. On platforms for which this is |
| the default ABI, it can be disabled with :option:`-fno-objc-nonfragile-abi`. |
| |
| Target Selection Options |
| ~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Clang fully supports cross compilation as an inherent part of its design. |
| Depending on how your version of Clang is configured, it may have support for a |
| number of cross compilers, or may only support a native target. |
| |
| .. option:: -arch <architecture> |
| |
| Specify the architecture to build for. |
| |
| .. option:: -mmacosx-version-min=<version> |
| |
| When building for macOS, specify the minimum version supported by your |
| application. |
| |
| .. option:: -miphoneos-version-min |
| |
| When building for iPhone OS, specify the minimum version supported by your |
| application. |
| |
| .. option:: --print-supported-cpus |
| |
| Print out a list of supported processors for the given target (specified |
| through --target=<architecture> or -arch <architecture>). If no target is |
| specified, the system default target will be used. |
| |
| .. option:: -mcpu=?, -mtune=? |
| |
| Aliases of --print-supported-cpus |
| |
| .. option:: -march=<cpu> |
| |
| Specify that Clang should generate code for a specific processor family |
| member and later. For example, if you specify -march=i486, the compiler is |
| allowed to generate instructions that are valid on i486 and later processors, |
| but which may not exist on earlier ones. |
| |
| |
| Code Generation Options |
| ~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| .. option:: -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -Og, -O, -O4 |
| |
| Specify which optimization level to use: |
| |
| :option:`-O0` Means "no optimization": this level compiles the fastest and |
| generates the most debuggable code. |
| |
| :option:`-O1` Somewhere between :option:`-O0` and :option:`-O2`. |
| |
| :option:`-O2` Moderate level of optimization which enables most |
| optimizations. |
| |
| :option:`-O3` Like :option:`-O2`, except that it enables optimizations that |
| take longer to perform or that may generate larger code (in an attempt to |
| make the program run faster). |
| |
| :option:`-Ofast` Enables all the optimizations from :option:`-O3` along |
| with other aggressive optimizations that may violate strict compliance with |
| language standards. |
| |
| :option:`-Os` Like :option:`-O2` with extra optimizations to reduce code |
| size. |
| |
| :option:`-Oz` Like :option:`-Os` (and thus :option:`-O2`), but reduces code |
| size further. |
| |
| :option:`-Og` Like :option:`-O1`. In future versions, this option might |
| disable different optimizations in order to improve debuggability. |
| |
| :option:`-O` Equivalent to :option:`-O2`. |
| |
| :option:`-O4` and higher |
| |
| Currently equivalent to :option:`-O3` |
| |
| .. option:: -g, -gline-tables-only, -gmodules |
| |
| Control debug information output. Note that Clang debug information works |
| best at :option:`-O0`. When more than one option starting with `-g` is |
| specified, the last one wins: |
| |
| :option:`-g` Generate debug information. |
| |
| :option:`-gline-tables-only` Generate only line table debug information. This |
| allows for symbolicated backtraces with inlining information, but does not |
| include any information about variables, their locations or types. |
| |
| :option:`-gmodules` Generate debug information that contains external |
| references to types defined in Clang modules or precompiled headers instead |
| of emitting redundant debug type information into every object file. This |
| option transparently switches the Clang module format to object file |
| containers that hold the Clang module together with the debug information. |
| When compiling a program that uses Clang modules or precompiled headers, |
| this option produces complete debug information with faster compile |
| times and much smaller object files. |
| |
| This option should not be used when building static libraries for |
| distribution to other machines because the debug info will contain |
| references to the module cache on the machine the object files in the |
| library were built on. |
| |
| .. option:: -fstandalone-debug -fno-standalone-debug |
| |
| Clang supports a number of optimizations to reduce the size of debug |
| information in the binary. They work based on the assumption that the |
| debug type information can be spread out over multiple compilation units. |
| For instance, Clang will not emit type definitions for types that are not |
| needed by a module and could be replaced with a forward declaration. |
| Further, Clang will only emit type info for a dynamic C++ class in the |
| module that contains the vtable for the class. |
| |
| The :option:`-fstandalone-debug` option turns off these optimizations. |
| This is useful when working with 3rd-party libraries that don't come with |
| debug information. This is the default on Darwin. Note that Clang will |
| never emit type information for types that are not referenced at all by the |
| program. |
| |
| .. option:: -fexceptions |
| |
| Enable generation of unwind information. This allows exceptions to be thrown |
| through Clang compiled stack frames. This is on by default in x86-64. |
| |
| .. option:: -ftrapv |
| |
| Generate code to catch integer overflow errors. Signed integer overflow is |
| undefined in C. With this flag, extra code is generated to detect this and |
| abort when it happens. |
| |
| .. option:: -fvisibility |
| |
| This flag sets the default visibility level. |
| |
| .. option:: -fcommon, -fno-common |
| |
| This flag specifies that variables without initializers get common linkage. |
| It can be disabled with :option:`-fno-common`. |
| |
| .. option:: -ftls-model=<model> |
| |
| Set the default thread-local storage (TLS) model to use for thread-local |
| variables. Valid values are: "global-dynamic", "local-dynamic", |
| "initial-exec" and "local-exec". The default is "global-dynamic". The default |
| model can be overridden with the tls_model attribute. The compiler will try |
| to choose a more efficient model if possible. |
| |
| .. option:: -flto, -flto=full, -flto=thin, -emit-llvm |
| |
| Generate output files in LLVM formats, suitable for link time optimization. |
| When used with :option:`-S` this generates LLVM intermediate language |
| assembly files, otherwise this generates LLVM bitcode format object files |
| (which may be passed to the linker depending on the stage selection options). |
| |
| The default for :option:`-flto` is "full", in which the |
| LLVM bitcode is suitable for monolithic Link Time Optimization (LTO), where |
| the linker merges all such modules into a single combined module for |
| optimization. With "thin", :doc:`ThinLTO <../ThinLTO>` |
| compilation is invoked instead. |
| |
| Driver Options |
| ~~~~~~~~~~~~~~ |
| |
| .. option:: -### |
| |
| Print (but do not run) the commands to run for this compilation. |
| |
| .. option:: --help |
| |
| Display available options. |
| |
| .. option:: -Qunused-arguments |
| |
| Do not emit any warnings for unused driver arguments. |
| |
| .. option:: -Wa,<args> |
| |
| Pass the comma separated arguments in args to the assembler. |
| |
| .. option:: -Wl,<args> |
| |
| Pass the comma separated arguments in args to the linker. |
| |
| .. option:: -Wp,<args> |
| |
| Pass the comma separated arguments in args to the preprocessor. |
| |
| .. option:: -Xanalyzer <arg> |
| |
| Pass arg to the static analyzer. |
| |
| .. option:: -Xassembler <arg> |
| |
| Pass arg to the assembler. |
| |
| .. option:: -Xlinker <arg> |
| |
| Pass arg to the linker. |
| |
| .. option:: -Xpreprocessor <arg> |
| |
| Pass arg to the preprocessor. |
| |
| .. option:: -o <file> |
| |
| Write output to file. |
| |
| .. option:: -print-file-name=<file> |
| |
| Print the full library path of file. |
| |
| .. option:: -print-libgcc-file-name |
| |
| Print the library path for the currently used compiler runtime library |
| ("libgcc.a" or "libclang_rt.builtins.*.a"). |
| |
| .. option:: -print-prog-name=<name> |
| |
| Print the full program path of name. |
| |
| .. option:: -print-search-dirs |
| |
| Print the paths used for finding libraries and programs. |
| |
| .. option:: -save-temps |
| |
| Save intermediate compilation results. |
| |
| .. option:: -save-stats, -save-stats=cwd, -save-stats=obj |
| |
| Save internal code generation (LLVM) statistics to a file in the current |
| directory (:option:`-save-stats`/"-save-stats=cwd") or the directory |
| of the output file ("-save-state=obj"). |
| |
| .. option:: -integrated-as, -no-integrated-as |
| |
| Used to enable and disable, respectively, the use of the integrated |
| assembler. Whether the integrated assembler is on by default is target |
| dependent. |
| |
| .. option:: -time |
| |
| Time individual commands. |
| |
| .. option:: -ftime-report |
| |
| Print timing summary of each stage of compilation. |
| |
| .. option:: -v |
| |
| Show commands to run and use verbose output. |
| |
| |
| Diagnostics Options |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| .. option:: -fshow-column, -fshow-source-location, -fcaret-diagnostics, -fdiagnostics-fixit-info, -fdiagnostics-parseable-fixits, -fdiagnostics-print-source-range-info, -fprint-source-range-info, -fdiagnostics-show-option, -fmessage-length |
| |
| These options control how Clang prints out information about diagnostics |
| (errors and warnings). Please see the Clang User's Manual for more information. |
| |
| Preprocessor Options |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| .. option:: -D<macroname>=<value> |
| |
| Adds an implicit #define into the predefines buffer which is read before the |
| source file is preprocessed. |
| |
| .. option:: -U<macroname> |
| |
| Adds an implicit #undef into the predefines buffer which is read before the |
| source file is preprocessed. |
| |
| .. option:: -include <filename> |
| |
| Adds an implicit #include into the predefines buffer which is read before the |
| source file is preprocessed. |
| |
| .. option:: -I<directory> |
| |
| Add the specified directory to the search path for include files. |
| |
| .. option:: -F<directory> |
| |
| Add the specified directory to the search path for framework include files. |
| |
| .. option:: -nostdinc |
| |
| Do not search the standard system directories or compiler builtin directories |
| for include files. |
| |
| .. option:: -nostdlibinc |
| |
| Do not search the standard system directories for include files, but do |
| search compiler builtin include directories. |
| |
| .. option:: -nobuiltininc |
| |
| Do not search clang's builtin directory for include files. |
| |
| |
| ENVIRONMENT |
| ----------- |
| |
| .. envvar:: TMPDIR, TEMP, TMP |
| |
| These environment variables are checked, in order, for the location to write |
| temporary files used during the compilation process. |
| |
| .. 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. |
| |
| .. 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. |
| |
| .. envvar:: MACOSX_DEPLOYMENT_TARGET |
| |
| If :option:`-mmacosx-version-min` is unspecified, the default deployment |
| target is read from this environment variable. This option only affects |
| Darwin targets. |
| |
| BUGS |
| ---- |
| |
| To report bugs, please visit <https://bugs.llvm.org/>. Most bug reports should |
| include preprocessed source files (use the :option:`-E` option) and the full |
| output of the compiler, along with information to reproduce. |
| |
| SEE ALSO |
| -------- |
| |
| :manpage:`as(1)`, :manpage:`ld(1)` |