BEAR(1) General Commands Manual BEAR(1) NAME Bear - a tool to generate compilation database for Clang tooling. SYNOPSIS bear [OPTIONS] [-] [BUILD_COMMAND...] bear intercept [OPTIONS] [-] BUILD_COMMAND... bear semantic [OPTIONS] DESCRIPTION Bear is a tool that generates a JSON compilation database for Clang tooling by intercepting command executions during the build process. The JSON com- pilation database is used in the Clang project to provide information about how individual compilation units were processed, enabling tools like clang-tidy, clangd, and other Clang-based analysis tools to understand your project's build configuration. Bear operates by intercepting system calls during the build process to cap- ture compilation commands. It supports two main interception methods: dy- namic library preloading (on Unix-like systems) and wrapper executables (cross-platform). The captured commands are then filtered through semantic analysis to identify actual compiler invocations and generate the final compilation database. Bear can operate in three modes: * Combined mode (default): Runs both interception and semantic analysis in sequence * Intercept mode: Only captures build events to an intermediate file * Semantic mode: Processes previously captured events to generate the com- pilation database OPTIONS -c, -config FILE Specify a configuration file path. The configuration file controls output formatting, compiler recognition, source filtering, and du- plicate handling. -o, -output FILE Specify the output file path (default: compile_commands.json). The output is a JSON compilation database. -a, -append Append results to an existing output file instead of overwriting it. This allows incremental updates to the compilation database. -h, -help Print help information. -V, -version Print version information. COMMANDS Calling bear without commands will execute the combined mode, and will in- tercept the compiler calls and generate a compilation database as output. bear intercept Intercepts command execution events during the build process and saves them to an events file for later processing. bear intercept [OPTIONS] [-] BUILD_COMMAND... bear semantic Processes previously captured events to generate a compilation database through semantic analysis. bear semantic [OPTIONS] OUTPUT Bear generates a JSON compilation database conforming to the Clang JSON Compilation Database specification. The output is a JSON array of compila- tion entry objects. Entry Format Each compilation database entry contains the following fields: directory The working directory of the compilation (absolute path) file The main translation unit source file (absolute path) arguments The compilation command as an array of strings (preferred format) command The compilation command as a single shell-escaped string (alterna- tive to arguments) output The output file produced by compilation (optional, absolute path) Output Formatting The output format can be controlled through the configuration file: * Path resolution: Paths can be formatted as absolute, relative, canonical, or as-is * Entry format: Choose between arguments array (preferred) or command string * Field inclusion: Control whether the output field is included * Source filtering: Include/exclude files based on directory rules * Duplicate filtering: Remove duplicate entries based on configurable field matching Bear generates entries where all paths are absolute by default, and uses the arguments field instead of command to avoid shell escaping issues. CONFIG FILE Bear uses a YAML configuration file to control its behavior. The configu- ration file follows a structured schema with several main sections. Configuration Schema schema: "4.1" intercept: mode: wrapper compilers: - path: /usr/bin/cc as: gcc - path: /usr/local/bin/gcc ignore: true sources: directories: - path: /project/tests action: exclude duplicates: match_on: - file - arguments format: paths: directory: canonical file: canonical entries: use_array_format: true include_output_field: true This example configuration file: sets the interception mode to wrapper, hints the /usr/bin/cc to be the main compiler in this project, which is the GNU compiler, hints to ignore the /usr/local/bin/gcc compilers from the project, instructs to ignore files from /project/tests, instructs to detect duplicates based on the file and arguments fields of the output file, in- structs to format the output to use canonical path for the file and direc- tory fields of the output file, instructs to use the arguments over the command field in the output file, instructs to include the output field in the output file. Configuration Sections The configuration file uses schema version 4.1 and has the following struc- ture: intercept Controls the command interception method: * mode: preload (Unix) or wrapper (cross-platform) compilers Contains hints about what compiler needs to be recognized and what that compiler is. * path: Path to the compiler executable * as: Compiler type hint for semantic analysis. Valid values are: gcc, clang, flang, intel-fortran, cray-fortran, cuda, msvc, clang-cl, in- tel_cc, nvidia-hpc, armclang, ibm_xl. * ignore: Whether to ignore this compiler. The generic compiler names cc and c++ default to GCC semantics. On plat- forms where these map to a different compiler (macOS, FreeBSD, OpenBSD), use the as field to override: compilers: - path: /usr/bin/cc as: clang - path: /usr/bin/c++ as: clang sources Filtering functionality based on the source file location. * directories: List of directory-based inclusion/exclusion rules Directory rules are evaluated in order, with the last matching rule deter- mining inclusion/exclusion. Empty directories list means include every- thing. duplicates Filtering functionality based on duplicate detection. Here you can define which fields of the output file should be used in the duplicate detection. * match_on: List of fields to use for duplicate detection (file, arguments, directory, command, output) format Output formatting configuration: * paths.directory and paths.file: How to format paths of these fields. The allowed values are: * as-is: No transformation, * canonical: Resolve to canonical path, * relative: Make relative to directory field, * absolute: Convert to absolute path, * entries.use_array_format: Use arguments array instead of command string * entries.include_output_field: Include output field in entries Default Configuration If no configuration file is specified, Bear uses built-in defaults opti- mized for most use cases. ENVIRONMENT RUST_LOG Controls the logging level for Bear's internal operations. This en- vironment variable is essential for troubleshooting and debugging Bear's behavior. Supported log levels (in order of verbosity): * error - Only show critical errors * warn - Show warnings and errors * info - Show informational messages, warnings, and errors * debug - Show detailed debugging information Examples: RUST_LOG=debug bear -- make all RUST_LOG=info bear intercept -- cmake --build . FILES The configuration file bear.yml is searched in the following locations, in order: ./bear.yml The current working directory. $XDG_CONFIG_HOME/bear.yml, $XDG_CONFIG_HOME/Bear/bear.yml (Unix) When $XDG_CONFIG_HOME is set. $HOME/.config/bear.yml, $HOME/.config/Bear/bear.yml (Unix) When $XDG_CONFIG_HOME is unset. %LOCALAPPDATA%\bear.yml, %LOCALAPPDATA%\Bear\bear.yml (Windows) When %LOCALAPPDATA% is set. %APPDATA%\bear.yml, %APPDATA%\Bear\bear.yml (Windows) When %APPDATA% is set. The first file found is loaded; remaining locations are not consulted. EXIT STATUS Bear returns the exit status of the executed build command when running in combined or intercept mode. When the build command succeeds, Bear returns 0. When the build command fails, Bear returns the same non-zero exit code. In semantic mode, Bear returns 0 on success and a non-zero exit code if se- mantic analysis fails. If Bear itself encounters an internal error or crashes, it returns a non-zero exit code regardless of the build command's status. TROUBLESHOOTING The potential problems you can face with are: the build with and without Bear behaves differently or the output is empty. Debug Logging Before reporting any issues, always run Bear with debug logging enabled: RUST_LOG=debug bear -- your-build-command This will provide detailed information about Bear's internal operations. And the debug output is essential for diagnosing problems and must be in- cluded in any bug reports. Common Issues The most common cause for empty outputs is that the build command did not execute any commands. The reason for that could be, because incremental builds not running the compilers if everything is up-to-date. Remember, Bear does not understand the build file (eg.: makefile), but intercepts the executed commands. The other common cause for empty output is that the build has a "configure" step, which captures the compiler to build the project. In case of Bear is using the wrapper mode, it needs to run the configure step with Bear too (and discard that output), before run the build with Bear. Compiler Env Vars With Flags In wrapper mode, Bear accepts compiler environment variables that carry a trailing flag or two, matching the GNU Make convention: CC="gcc -std=c11" make CXX="clang++ -stdlib=libc++" make CC="/usr/local/bin/gcc -m32" make Bear splits the value on whitespace, resolves the first token as the com- piler, and rewrites the variable so the build still sees the flags (CC=<wrapper_path> -std=c11). This convention is a Unix / GNU Make inheritance; it applies when bear -- make runs under sh/bash (including MSYS2, Git Bash, WSL on Windows), not under native Windows build systems (MSBuild, nmake, cmd, PowerShell), which do not consume CC/CXX from the environment. For anything beyond simple whitespace-separated tokens (flags containing spaces, shell quoting, metacharacters, command substitutions), use CFLAGS, CXXFLAGS, or LDFLAGS instead of packing it into CC. Those variables are the portable channel for compilation flags and every build system expects them. Bear does not parse or rewrite them; they reach the compiler un- touched. Getting Help There could be many reasons for any of these failures. When seeking help: 1. Always include debug logs (RUST_LOG=debug) in your report 2. Consult the project wiki page for known problems 3. Search existing issues before opening a new bug report 4. Follow the bug report template, provide the requested fields COPYRIGHT Copyright (C) 2012-2026 by LA!szlA^3 Nagy https://github.com/rizsotto/Bear AUTHORS LA!szlA^3 Nagy. Bear User Manuals June 2, 2026 BEAR(1)
NAME | SYNOPSIS | DESCRIPTION | COMMANDS | OUTPUT | CONFIG FILE | ENVIRONMENT | FILES | EXIT STATUS | TROUBLESHOOTING | COPYRIGHT | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=bear&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>