bear - Man Page

Combined mode (default)

bear -- <build command> runs the build, captures and analyzes in one step, and writes the database. This is the recommended way to use Bear: it observes the commands the build actually executes, so the result is exact. Use it whenever you can run the build.

Intercept mode

bear intercept runs the build but only captures, writing the raw event stream to a file. Useful when the build is expensive and you want to run it once and process the events several times, for example to try different output configurations.

Semantic mode

bear semantic runs no build: it is a filter that reads an event stream (from bear intercept, or any producer of the documented event format) and writes the compilation database. Combine it with intercept mode to re-generate the database without rebuilding.

Parse-sh mode

bear parse-sh produces the compilation database from shell command text, without executing anything. Typical input is a build system’s dry run (make -n) or a saved build log. It is a text parser and inherently lower fidelity than interception; reach for it when the build cannot be run, for example to recover a database from a CI log. See its limitations under Commands.

Interception itself has two methods, selectable in the configuration file. Preload (the default on Linux and the BSDs) injects a small library into every process the build starts and observes its exec() calls. Wrapper (the default on macOS and Windows) substitutes the known compilers with a reporting wrapper executable. Preload is transparent to the build but cannot observe statically linked executables, and it is unavailable on Windows and on macOS while System Integrity Protection is enabled; forcing it there is a startup error that names wrapper mode, not a silent fallback. Wrapper mode works on every platform, but the build has to pick the wrapper up: a “configure” step that discovers compilers must itself run under Bear (see Troubleshooting).

-c,  --config FILE

Path of the configuration file. It controls the interception method, compiler recognition, source filtering, duplicate handling, and output formatting (see Configuration). Given before a subcommand it applies to that subcommand too.

-o,  --output FILE

Path of the compilation database to write (default: compile_commands.json). - is not accepted here, because in combined mode standard output belongs to the build. To stream the database, use bear semantic --output - (see Commands).

-a,  --append

Append to an existing output file instead of overwriting it. New entries are placed before the existing ones, so a rebuilt file’s newest invocation survives duplicate filtering and replaces the stale entry (see duplicates under Configuration).

-h,  --help

Print help.

-V,  --version

Print version.

Runs the build and captures execution events to a file, without analyzing them.

bear intercept [Options] --output FILE -- BUILD_COMMAND...

-o, --output FILE

Path of the event file to write. Required, and - is not accepted: the build owns standard output, and there is no default event-file name.

Reads an event stream and writes the compilation database. It runs no build, so it behaves as a plain filter: diagnostics go to standard error, and both ends can be standard streams.

bear semantic [Options]

-i, --input FILE

Path of the event file to read (default: -, standard input). Any producer of a conforming event stream can pipe into it. When standard input is a terminal, or the stream turns out to be empty, a notice is printed on standard error.

-o, --output FILE

Path of the compilation database to write (default: compile_commands.json). Pass - to write to standard output; that write is neither atomic nor appendable, so --output - together with --append is rejected.

-a, --append

Same as in combined mode: place new entries before the existing ones in the output file.

Produces the compilation database from shell command text, without running anything. Typical input is a build system’s dry-run output, such as make -n, or a saved build log:

make -n | bear parse-sh

bear parse-sh [Options]

-i, --input FILE

Path of the shell text to parse (default: -, standard input).

-o, --output FILE

Path of the compilation database to write (default: compile_commands.json). Pass - to write to standard output; that write is neither atomic nor appendable, so --output - together with --append is rejected.

-a, --append

Same as in combined mode: place new entries before the existing ones in the output file.

-C, --directory DIR

Initial working directory for the parsed commands. Use it for input captured elsewhere (a CI log, a dry run from another checkout). Give an absolute path; the directory need not exist on this machine.

The commands recognized in the text go through the same semantic analysis and output stage as an intercepted build, so the configuration applies exactly as in combined mode. Parsed commands that are not compiler invocations (ar, mv, mkdir) simply produce no entries.

It understands a documented subset of POSIX shell syntax: word splitting and quoting; the ;, &&, ||, &, and | separators; comments; redirections; cd; brace groups ({ ...; }, whose cd persists past the closing brace); and make’s Entering directory / Leaving directory markers, which track the working directory across a recursive build. Sub-makes print these markers by default; run make -nw to have the top-level make print them too, so the log itself names the build root. A line using anything outside that subset is skipped and reported on standard error with its line number and reason. This covers subshells, command substitution, parameter expansion, globs in the executable position, here-documents, unterminated quotes, and shell keywords such as if or for. The run succeeds as long as at least one line parsed as a command.

Interception remains the higher-fidelity default: it observes the exec() calls a build really makes, while bear parse-sh reconstructs approximate events from text the build system chose to print. A dry run can omit commands (recursive make does not always propagate -n, and commands behind not-yet-generated sources never print); the environment and PATH used to resolve bare executable names are the parse-time ones, not the real build’s; and only POSIX sh text is supported. Prefer bear -- <build command> whenever the build can actually be run.

The source files named in the parsed commands need not exist: entries are reconstructed from the text alone. The one exception is the canonical path format, which resolves symlinks on disk; when the sources are absent, configure absolute instead (see format.paths under Configuration).

Controls the interception method (see Description for the trade-offs):

• mode: preload (default on Linux and the BSDs) or wrapper (default on macOS and Windows; works everywhere).

Hints for compiler recognition. Bear recognizes GCC- and Clang-compatible drivers (including cross-compiler prefixed names), the common vendor compiler drivers and standalone assemblers, swiftc and valac, compiler launchers, and MPI compiler wrappers. Run bear semantic --print-compilers for the full list of recognized compiler names, each with the as value it maps to.

A few recognition behaviors are worth knowing. Compiler launchers (ccache, distcc, sccache, icecc) are dropped from the recorded command: ccache gcc -c main.c produces an entry for gcc -c main.c. MPI compiler wrappers are recorded as invoked, not expanded to the compiler they wrap; Clang tooling that needs the wrapper’s baked-in include paths can point at it directly, for example with clangd’s --query-driver. C++20 module-interface units (.cppm, .ixx, and similar) are recognized as sources, while precompiled .pcm artifacts never appear as an entry’s file.

Use this section when a compiler at a given path is not recognized, or is recognized wrongly:

• path: Path of the compiler executable. Required.
• as: Compiler type hint for semantic analysis. Optional; when omitted, Bear guesses the family from the executable’s filename and falls back to gcc when nothing matches. The accepted values are the as names shown by bear semantic --print-compilers, plus wrapper for a compiler launcher.
• ignore: Exclude this executable’s invocations from the database. Optional, default false.

The generic names cc, c++, and the HPE Cray PrgEnv wrapper CC are classified by probing the executable’s --version output, since the same basename can be a different compiler depending on the platform or the loaded environment module. When the probe cannot classify the executable, override it:

compilers:
  - path: /usr/bin/cc
    as: clang

Filters entries by source file location and filename.

• directories: List of directory-based rules, each with a path and an action (include or exclude).
• files: List of filename-glob rules, each with a pattern and an action (include or exclude).

Rules of each list are evaluated in order, the last matching rule wins, and an entry matched by no rule is included; an empty list includes everything. The two lists compose: an entry is emitted only when both accept it. A file pattern without a path separator matches the source file’s basename; a pattern containing a separator matches the full source path as it appears in the entry, so use the same path format as configured in format.paths.file. An invalid pattern is rejected during configuration validation with an error naming the offending rule. Typical use for file patterns is dropping machine-generated sources (Qt moc output, protobuf stubs) so that linters and editors act only on hand-written code; see Examples.

Controls duplicate detection.

• match_on: List of entry fields to compare (file, arguments, directory, command, output). Two entries are duplicates when all of the configured fields match; the first occurrence is kept. The default is directory and file, so one entry is kept per source file per directory, regardless of arguments; when a build compiles the same file with different flags, add arguments to keep an entry per configuration. Combined with --append (new entries first), the default means a rebuilt file’s newest invocation replaces its stale entry.

Controls output formatting.

• paths.directory, paths.file: How to format these fields’ paths: as-is (default, no transformation), canonical (resolve symlinks; requires the path to exist), relative (to the directory field), or absolute.
• entries.use_array_format: Use the arguments array (default) instead of the command string. Set to false for consumers that read only the command field.
• entries.include_output_field: Include the output field in entries.
• arguments.from_response_files: Replace @file response-file references with the file’s tokenized contents (resolved relative to the compilation’s working directory, expanded recursively, using the compiler’s quoting convention). Disabled by default, in which case an @file argument is recorded verbatim; a missing or unreadable file is left literal with a warning.
• arguments.from_environment: Fold compiler environment variables that act as implicit flags into the arguments. GCC/Clang header-search paths (CPATH, C_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC_INCLUDE_PATH) become include flags, and MSVC’s CL / _CL_ become leading / trailing options. Enabled by default; set to false to record only the command-line flags. (Unrelated to the CC="gcc -std=c11" convention handled during interception; see Troubleshooting.)

Editors and linters often need compile flags for header files, not only for the translation units that were compiled. When enabled, Bear synthesizes an entry for a header by cloning the arguments of a compiled C/C++/Objective-C translation unit, with the source path replaced by the header path and the output flag removed. Off by default.

• enabled: Turn header-entry synthesis on or off. Default false.

• strategy: How headers are discovered and which translation unit donates the flags:

  • siblings (default): headers receive an entry cloned from a compiled source in the same directory. Zero prerequisites, but the flags are approximate, and headers in directories without compiled sources (the split include/ + src/ layout) get nothing.
  • dependency-files: reads the make-style .d dependency files the build already emitted (for example via -MMD) and synthesizes an entry for each header prerequisite that resolves inside the compilation’s working directory. Accurate, and reaches headers in other directories, but requires the build to have left dependency files on disk.

The header extension set is fixed (the built-in C-family headers). Synthesized entries pass through duplicate detection like any other entry, so a header with a real compilation entry is not duplicated.

Before reporting any issue, run Bear with debug logging enabled and include the output in the report:

RUST_LOG=debug bear -- <build command>

The most common cause is that the build executed no compiler: an incremental build with everything up to date runs nothing. Bear intercepts executed commands only; it does not read the build files. Run a clean build.

In wrapper mode, a “configure” step that detects compilers captures the real compiler path before Bear can substitute the wrapper. Run the configure step under Bear too (discarding that output), then run the build under Bear.

In wrapper mode Bear accepts the GNU Make convention of a compiler variable carrying a trailing flag or two (CC="gcc -std=c11" make): it splits the value on whitespace, resolves the first token as the compiler, and rewrites the variable so the build still sees the flags. This is a Unix / GNU Make convention; native Windows build systems (MSBuild, nmake) do not consume CC/CXX from the environment. For anything beyond simple whitespace-separated tokens (quoting, metacharacters, substitutions), use CFLAGS / CXXFLAGS / LDFLAGS instead; Bear passes those through untouched.

An error like version 'GLIBC_2.33' not found (required by .../libexec.so) means Bear’s preload library was built against a newer glibc than the one the SDK’s compilers load: the library must be ABI-compatible with the libc of the intercepted process, not only with the host’s. Use a Bear build linked against a glibc no newer than the SDK’s. The project wiki’s Troubleshooting page lists diagnostic commands.

vala-language-server reads the command field and ignores the arguments array; build the database with format.entries.use_array_format: false. In a mixed C/Vala project, clangd also indexes the valac entries and emits unknown-argument noise on them; suppress it with a .clangd file:

If:
  PathMatch: .*\.vala
Diagnostics:
  Suppress: '*'

Consult the documentation site for known problems and search existing issues before opening a new report. Follow the bug report template, and always include the RUST_LOG=debug output.