circle [options] input...
circle --driver-mode=unix [Unix-style options] input...
circle --driver-mode=cl [CL-style options] input...
Driver mode
Default platforms
Response-file quoting
--driver-mode=unix
Linux, macOS
GNU
--driver-mode=cl
Windows
Windows command line
--driver-mode=unix or --driver-mode=cl must
be the first argument, before any @file response files.
Each mode accepts its own option set. In option values, |
separates alternatives.
Compiler identification
macros
Macro
Value
__CIRCLE_LANG__
1
__circle_build__
Circle build number.
__CIRCLE_CUDA_SINGLE_PASS__
1 for CUDA compilation without
-cuda-multi-pass.
__CIRCLE_CUDA_MULTI_PASS__
1 with -cuda-multi-pass or
/cuda-multi-pass.
Environment variables
Variable
Meaning
CUDA_PATH
CUDA toolkit root. Overridden by -cuda-path.
CUDA_TOOLS
CUDA tools directory. Overridden by -cuda-tools.
Default is the selected toolkit's tools.
SDKROOT
macOS SDK. Overridden by -isysroot.
DEVELOPER_DIR
Additional macOS SDK and runtime discovery location.
INCLUDE, LIB
Windows header/library paths, separated by semicolons. Default is
automatic toolchain discovery.
ProgramFiles
Additional LLVM runtime search root on Windows.
TMPDIR
Temporary directory on macOS.
TMP, TEMP, USERPROFILE
Windows temporary directory, in priority order. Fallback
C:\Temp.
CIRCLE_JIT_PATH
Circle executable used by the runtime JIT resolver.
LLVM_PROFILE_FILE
PGO output filename. Default default_%m.profraw.
%m identifies the binary and enables merging.
%p inserts the process ID.
ASAN_OPTIONS
AddressSanitizer runtime options.
MSAN_OPTIONS
MemorySanitizer runtime options.
TSAN_OPTIONS
ThreadSanitizer runtime options.
UBSAN_OPTIONS
UndefinedBehaviorSanitizer runtime options.
Unix-style options
Ignored options are accepted for compatibility and have no
effect.
Inputs, actions, and output
Option
Meaning
file
Source, object, or library input. Order is preserved.
file.s
Assemble for the host target. Preprocessed assembly
(.S) is unsupported.
--
End option processing; all following arguments are inputs.
@file
Expand a GNU-quoted response file.
--help
Print Unix-style help.
--version, -version
Print Circle and LLVM version information.
-dumpversion
Print the Circle compiler version.
-dumpmachine
Print the compiler target.
-print-target-triple
Print the target triple.
-###
Print the resolved driver plan without executing it.
-c
Compile without linking.
-S
Emit assembly, or LLVM/SPIR-V text with the corresponding emit
flag.
-E
Preprocess to standard output.
-shared
Build a shared library.
-dynamiclib
Alias for -shared.
-bundle
Build a Darwin bundle.
-fsyntax-only
Parse and check without code generation.
-emit-llvm
Emit LLVM IR: .ll with -S,
.bc with -c.
-emit-spirv
Emit SPIR-V: .spvasm with -S,
.spv with -c.
-filetype=<kind>
Select s, ll, bc,
o, so, exe, ast,
ptx, ltoir, cubin,
sass, or fatbin.
-o file, -ofile
Set the primary output path.
-x c, -x c++
Set the input language.
-jit
Run through the JIT path.
-console
Write textual output to the console.
-save-temps
Preserve temporary files.
-save-temps=<dir>
Preserve temporary files in dir.
-icase
Use case-insensitive file lookup.
Preprocessor and
dependencies
Joined forms such as -Idir are also accepted.
Option
Meaning
-I dir
Add a normal include directory. Repeatable.
-iquote dir
Add a quote-only include directory. Repeatable.
-isystem dir
Add a system include directory. Repeatable.
-include file
Force an include before the source. Repeatable.
-D macro
Define a macro. Repeatable and ordered with -U.
-U macro
Undefine a macro. Repeatable and ordered with -D.
-nostdinc
Do not search standard C include directories.
-nostdinc++
Do not search standard C++ include directories.
-dM
Dump macro definitions.
-dump-paths
Dump resolved include paths.
-M
Emit user and system dependencies; implies preprocessing only.
-MM
Emit user dependencies; implies preprocessing only.
Enable/disable trap mode. Accepts all. Unsupported for
ASan, MSan, and TSan.
-fsanitize-recover
Alias for -fsanitize-recover=undefined.
-fno-sanitize-recover
Alias for -fno-sanitize-recover=all.
--sanitizer-runtime-path=<dir>
Set the sanitizer runtime search directory.
Check
Detects
address
Invalid memory accesses.
memory
Uninitialized values.
thread
Data races.
undefined
Supported undefined behavior checks.
signed-integer-overflow
Signed integer overflow.
integer-divide-by-zero
Integer division by zero.
shift
Invalid shifts.
alignment
Misaligned accesses.
null
Invalid null-pointer use.
cfi-icall
Function-pointer call type mismatches.
cfi-vcall
Invalid virtual-call targets.
cfi-derived-cast
Invalid base-to-derived casts.
cfi-unrelated-cast
Invalid casts to polymorphic types.
MemorySanitizer
Linux AArch64 and x86-64 only. Requires instrumented dependencies,
including the C++ standard library. No fully static executables, ASan
combination, or device instrumentation.
Option
Meaning
-fsanitize-memory-track-origins=0|1|2
Track no origins, allocations, or allocations and stores. Default
0.
-fsanitize-memory-track-origins
Enable origin tracking at level 2.
-fno-sanitize-memory-track-origins
Disable origin tracking.
-fsanitize-memory-param-retval
Check arguments and return values. Default on.
-fno-sanitize-memory-param-retval
Disable argument and return checks.
-fsanitize-recover=memory
Enable recovery. Also requires
MSAN_OPTIONS=halt_on_error=0.
__has_feature(memory_sanitizer) identifies MSan builds.
__attribute__((no_sanitize("memory"))) suppresses function
checks.
ThreadSanitizer
Linux AArch64 and x86-64, and macOS AArch64. Linux executables
default to PIE. No fully static executables, ASan/MSan combination, or
device instrumentation.
Requires LTO at compile and link time. Virtual-call and cast checks
require hidden visibility or internal linkage. No cross-DSO checks or
device instrumentation.
Option
Meaning
-fsanitize-cfi-icall-generalize-pointers
Relax pointer type matching while preserving const and
volatile.
-fno-sanitize-cfi-icall-generalize-pointers
Restore strict pointer type matching.
-fno-sanitize-trap=<checks>
Report failures through compiler-rt.
-fsanitize-recover=<checks>
Enable recovery in reporting mode.
__attribute__((no_sanitize("cfi"))) suppresses CFI
checks per function.
Profile Guided Optimization
Option
Meaning
-fprofile-generate[=<dir>]
Instrument host code. Write default_%m.profraw to
<dir> or the working directory.
-fprofile-use[=<path>]
Read an indexed profile or
<path>/default.profdata. Default
./default.profdata.
-fprofile-update=single|atomic|prefer-atomic
Select counter updates. Default single.
-fno-profile-generate
Cancel profile generation.
-fno-profile-use
Cancel profile use.
--profile-runtime-path=<path>
Set the profiling runtime search directory.
Merge raw profiles with llvm-profdata before use.
Generation requires a compatible Clang compiler-rt runtime and flags at
compile and link time. Profile-use flags apply at compile time.
Generation and use are mutually exclusive. Host code only.
Diagnostics, tracing, and
dumps
Option
Meaning
-Werror
Treat warnings as errors.
-Wreturn-type
Warn about missing C++ return values. Default on.
-Wno-return-type
Disable missing-return warnings, including under
-Werror.
-Wunknown-attributes
Warn about unknown C++ attributes. Default off.
-Wno-unknown-attributes
Disable unknown-attribute warnings, including under
-Werror.
-Wall
Enable the supported general warning group.
-Wformat
Enable the supported format warning group.
-Wno-deprecated
Disable supported deprecation warnings.
-Wno-unknown-warning-option
Suppress unknown-warning-option diagnostics.
-W<name>
Other warning names are accepted but currently have no effect.
-w
Accepted and ignored.
-pedantic
Accepted and ignored.
-v, -verbose
Enable verbose output.
-ferror-limit=<n>
Set the diagnostic error limit.
-ftemplate-backtrace-limit=<n>
Accepted and ignored.
-fmacro-backtrace-limit=<n>
Accepted and ignored.
-fcolor-diagnostics
Accepted and ignored.
-tabsize=<n>
Set diagnostic tab width.
-warn-unknown-declspec
Warn about unknown declaration specifiers.
-stat
Print statistics.
-ftime-report
Print a timing report.
-mllvm <arg>
Forward an option to LLVM. Repeatable.
-ftime-log=<file>
Write timing data to a file.
-print-deferred
Print deferred-definition information.
-dump-templates-simple,
-dump-templates-full
Dump template information.
-dump-calls-simple, -dump-calls-full
Dump call information.
-dump-functions-simple,
-dump-functions-full
Dump function information.
-dump-llvm
Dump generated LLVM IR.
-fdump-record-layouts
Dump record layouts.
-print-paths
Print compiler resource paths.
Linking and libraries
Option
Meaning
-stdlib=libc++|libstdc++|msstl
Select the C++ standard library.
-libstdc++=<version>
Select the libstdc++ version.
-gcc-toolchain=<dir>
Select a GCC toolchain root.
-L dir, -Ldir
Add a library search directory. Repeatable and ordered.
-F dir
Add a framework search directory.
-framework <name>
Link a framework.
-isysroot <dir>
Set the SDK root.
-dynamic
Request dynamic linking on Darwin. Ignored elsewhere.
-undefined <policy>
Set linker undefined-symbol policy.
-install_name <name>
Set library install name.
-compatibility_version <version>
Set library compatibility version.
-current_version <version>
Set library current version.
-l name, -lname
Add a named library. Repeatable and ordered.
-Wl,a,b,...
Forward comma-separated arguments to the linker in order.
-Xlinker arg
Forward one argument to the linker.
-static
Request static linking.
-pthread
Enable pthread compile/link policy.
-rdynamic
Export executable symbols dynamically.
-nodefaultlibs
Omit default runtime libraries.
-nolibc
Omit libc.
-nostdlib
Omit startup files and standard libraries.
-nostdlib++
Omit the C++ standard library.
-fuse-ld=lld|gold|mold|bfd
Select the linker implementation.
-no-demangle
Disable linker diagnostic demangling.
-ML file
Load a meta-programming support library. Repeatable.