1CLANG(1) Clang Tools Documentation CLANG(1)
2
6 clang - the Clang C and Objective-C compiler
7
9 clang [-c|-S|-E] -std=standard -g
10 [-O0|-O1|-O2|-Os|-O3|-O4]
11 -Wwarnings... -pedantic
12 -Idir... -Ldir...
13 -Dmacro[=defn]
14 -ffeature-option...
15 -mmachine-option...
16 -o output-file
17 input-filenames
18
20 clang is a C and Objective-C compiler which encompasses preprocessing,
21 parsing, optimization, code generation, assembly, and linking.
22 Depending on which high-level mode setting is passed, Clang will stop
23 before doing a full link. While Clang is highly integrated, it is
24 important to understand the stages of compilation, to understand how to
25 invoke it. These stages are:
26 Driver
28 The clang executable is actually a small driver which controls the
29 overall execution of other tools such as the compiler, assembler
30 and linker. Typically you do not need to interact with the driver,
31 but you transparently use it to run the other tools.
32 Preprocessing
34 This stage handles tokenization of the input source file, macro
35 expansion, #include expansion and handling of other preprocessor
36 directives. The output of this stage is typically called a ".i"
37 (for C) or ".mi" (for Objective-C) file.
38 Parsing and Semantic Analysis
40 This stage parses the input file, translating preprocessor tokens
41 into a parse tree. Once in the form of a parser tree, it applies
42 semantic analysis to compute types for expressions as well and
43 determine whether the code is well formed. This stage is
44 responsible for generating most of the compiler warnings as well as
45 parse errors. The output of this stage is an "Abstract Syntax
46 Tree" (AST).
47 Code Generation and Optimization
49 This stage translates an AST into low-level intermediate code
50 (known as "LLVM IR") and ultimately to machine code. This phase is
51 responsible for optimizing the generated code and handling target-
52 specfic code generation. The output of this stage is typically
53 called a ".s" file or "assembly" file.
54 Clang also supports the use of an integrated assembler, in which
56 the code generator produces object files directly. This avoids the
57 overhead of generating the ".s" file and of calling the target
58 assembler.
59 Assembler
61 This stage runs the target assembler to translate the output of the
62 compiler into a target object file. The output of this stage is
63 typically called a ".o" file or "object" file.
64 Linker
66 This stage runs the target linker to merge multiple object files
67 into an executable or dynamic library. The output of this stage is
68 typically called an "a.out", ".dylib" or ".so" file.
69 The Clang compiler supports a large number of options to control each
71 of these stages. In addition to compilation of code, Clang also
72 supports other tools:
73 Clang Static Analyzer
75 The Clang Static Analyzer is a tool that scans source code to try to
77 find bugs though code analysis. This tool uses many parts of Clang and
78 is built into the same driver.
79
81 Stage Selection Options
82 -E Run the preprocessor stage.
83 -fsyntax-only
85 Run the preprocessor, parser and type checking stages.
86 -S Run the previous stages as well as LLVM generation and optimization
88 stages and target-specific code generation, producing an assembly
89 file.
90 -c Run all of the above, plus the assembler, generating a target ".o"
92 object file.
93 no stage selection option
95 If no stage selection option is specified, all stages above are
96 run, and the linker is run to combine the results into an
97 executable or shared library.
98 --analyze
100 Run the Clang Static Analyzer.
101 Language Selection and Mode Options
103 -x language
104 Treat subsequent input files as having type language.
105 -std=language
107 Specify the language standard to compile for.
108 -ansi
110 Same as -std=c89.
111 -ObjC++
113 Treat source input files as Objective-C++ inputs.
114 -ObjC
116 Treat source input files as Objective-C inputs.
117 -trigraphs
119 Enable trigraphs.
120 -ffreestanding
122 Indicate that the file should be compiled for a freestanding, not a
123 hosted, environment.
124 -fno-builtin
126 Disable special handling and optimizations of builtin functions
127 like strlen and malloc.
128 -fmath-errno
130 Indicate that math functions should be treated as updating errno.
131 -fpascal-strings
133 Enable support for Pascal-style strings with "\pfoo".
134 -fms-extensions
136 Enable support for Microsoft extensions.
137 -fborland-extensions
139 Enable support for Borland extensions.
140 -fwritable-strings
142 Make all string literals default to writable. This disables
143 uniquing of strings and other optimizations.
144 -flax-vector-conversions
146 Allow loose type checking rules for implicit vector conversions.
147 -fblocks
149 Enable the "Blocks" language feature.
150 -fobjc-gc-only
152 Indicate that Objective-C code should be compiled in GC-only mode,
153 which only works when Objective-C Garbage Collection is enabled.
154 -fobjc-gc
156 Indicate that Objective-C code should be compiled in hybrid-GC
157 mode, which works with both GC and non-GC mode.
158 Target Selection Options
160 Clang fully supports cross compilation as an inherent part of its
161 design. Depending on how your version of Clang is configured, it may
162 have support for a number of cross compilers, or may only support a
163 native target.
164 -arch architecture
166 Specify the architecture to build for.
167 -mmacosx-version-min=version
169 When building for Mac OS/X, specify the minimum version supported
170 by your application.
171 -miphoneos-version-min
173 When building for iPhone OS, specify the minimum version supported
174 by your application.
175 -march=cpu
177 Specify that Clang should generate code for a specific processor
178 family member and later. For example, if you specify -march=i486,
179 the compiler is allowed to generate instructions that are valid on
180 i486 and later processors, but which may not exist on earlier ones.
181 Code Generation Options
183 -O0 -O1 -O2 -Os -O3 -O4
184 Specify which optimization level to use. -O0 means "no
185 optimization": this level compiles the fastest and generates the
186 most debuggable code. -O2 is a moderate level of optimization
187 which enables most optimizations. -Os is like -O2 with extra
188 optimizations to reduce code size. -O3 is like -O2, except that it
189 enables optimizations that take longer to perform or that may
190 generate larger code (in an attempt to make the program run
191 faster). On supported platforms, -O4 enables link-time
192 optimization; object files are stored in the LLVM bitcode file
193 format and whole program optimization is done at link time. -O1 is
194 somewhere between -O0 and -O2.
195 -g Generate debug information. Note that Clang debug information
197 works best at -O0. At higher optimization levels, only line number
198 information is currently available.
199 -fexceptions
201 Enable generation of unwind information, this allows exceptions to
202 be thrown through Clang compiled stack frames. This is on by
203 default in x86-64.
204 -ftrapv
206 Generate code to catch integer overflow errors. Signed integer
207 overflow is undefined in C, with this flag, extra code is generated
208 to detect this and abort when it happens.
209 -fvisibility
211 This flag sets the default visibility level.
212 -fcommon
214 This flag specifies that variables without initializers get common
215 linkage. It can be disabled with -fno-common.
216 -flto -emit-llvm
218 Generate output files in LLVM formats, suitable for link time
219 optimization. When used with -S this generates LLVM intermediate
220 language assembly files, otherwise this generates LLVM bitcode
221 format object files (which may be passed to the linker depending on
222 the stage selection options).
223 Driver Options
225 -###
226 Print the commands to run for this compilation.
227 --help
229 Display available options.
230 -Qunused-arguments
232 Don't emit warning for unused driver arguments.
233 -Wa,args
235 Pass the comma separated arguments in args to the assembler.
236 -Wl,args
238 Pass the comma separated arguments in args to the linker.
239 -Wp,args
241 Pass the comma separated arguments in args to the preprocessor.
242 -Xanalyzer arg
244 Pass arg to the static analyzer.
245 -Xassembler arg
247 Pass arg to the assembler.
248 -Xclang arg
250 Pass arg to the clang compiler frontend.
251 -Xlinker arg
253 Pass arg to the linker.
254 -mllvm arg
256 Pass arg to the LLVM backend.
257 -Xpreprocessor arg
259 Pass arg to the preprocessor.
260 -o file
262 Write output to file.
263 -print-file-name=file
265 Print the full library path of file.
266 -print-libgcc-file-name
268 Print the library path for "libgcc.a".
269 -print-prog-name=name
271 Print the full program path of name.
272 -print-search-dirs
274 Print the paths used for finding libraries and programs.
275 -save-temps
277 Save intermediate compilation results.
278 -integrated-as -no-integrated-as
280 Used to enable and disable, respectively, the use of the integrated
281 assembler. Whether the integrated assembler is on by default is
282 target dependent.
283 -time
285 Time individual commands.
286 -ftime-report
288 Print timing summary of each stage of compilation.
289 -v Show commands to run and use verbose output.
291 Diagnostics Options
293 -fshow-column -fshow-source-location -fcaret-diagnostics
294 -fdiagnostics-fixit-info -fdiagnostics-parseable-fixits
295 -fdiagnostics-print-source-range-info -fprint-source-range-info
296 -fdiagnostics-show-option -fmessage-length
297 These options control how Clang prints out information about
298 diagnostics (errors and warnings). Please see the Clang User's
299 Manual for more information.
300 Preprocessor Options
302 -Dmacroname=value
303 Adds an implicit #define into the predefines buffer which is read
304 before the source file is preprocessed.
305 -Umacroname
307 Adds an implicit #undef into the predefines buffer which is read
308 before the source file is preprocessed.
309 -include filename
311 Adds an implicit #include into the predefines buffer which is read
312 before the source file is preprocessed.
313 -Idirectory
315 Add the specified directory to the search path for include files.
316 -Fdirectory
318 Add the specified directory to the search path for framework
319 include files.
320 -nostdinc
322 Do not search the standard system directories for include files.
323 -nobuiltininc
325 Do not search clang's builtin directory for include files.
326
328 TMPDIR, TEMP, TMP
329 These environment variables are checked, in order, for the location
330 to write temporary files used during the compilation process.
331 CPATH
333 If this environment variable is present, it is treated as a
334 delimited list of paths to be added to the default system include
335 path list. The delimiter is the platform dependent delimitor, as
336 used in the PATH environment variable.
337 Empty components in the environment variable are ignored.
339 C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH,
341 OBJCPLUS_INCLUDE_PATH
342 These environment variables specify additional paths, as for CPATH,
343 which are only used when processing the appropriate language.
344 MACOSX_DEPLOYMENT_TARGET
346 If -mmacosx-version-min is unspecified, the default deployment
347 target is read from this environment variable. This option only
348 affects darwin targets.
349
351 To report bugs, please visit <http://llvm.org/bugs/>. Most bug reports
352 should include preprocessed source files (use the -E option) and the
353 full output of the compiler, along with information to reproduce.
354
356 as(1), ld(1)
357
359 Maintained by the Clang / LLVM Team (<http://clang.llvm.org>).
360clang 2.8 2010-09-02 CLANG(1)