FAQ

FAQ

Why is compile_commands.json empty?

This is the most common problem. See Troubleshooting: The output is empty for all causes and fixes.

The short version: clean your build (make clean) and re-run with Bear. If still empty, check that your compiler is recognized and that you are using the right interception mode.

Which compilers does Bear recognize?

Bear recognizes the following compiler families by executable filename, including versioned variants (e.g. gcc-11, clang-17) and cross-compilation prefixes (e.g. arm-linux-gnueabihf-gcc) where applicable:

Compiler	Executables	Flag style
GCC	gcc, g++, cc, c++, gfortran, f95	-flag
Clang	clang, clang++	-flag
MSVC	cl	/flag
clang-cl	clang-cl	/flag and -flag
Intel C/C++	icx, icpx, icc, icpc	-flag
Intel Fortran	ifort, ifx	-flag
NVIDIA CUDA	nvcc	-flag
NVIDIA HPC SDK	nvc, nvc++, nvfortran, pgcc, pgc++, pgfortran	-flag
Flang	flang, flang-new	-flag
ARM Compiler 6	armclang, armclang++	-flag
IBM Open XL	ibm-clang, ibm-clang++, xlclang, xlclang++	-flag
Cray Fortran	crayftn, ftn	-flag
Wrappers	ccache, distcc, sccache	(transparent)

Why does Bear not recognize my compiler?

Bear matches compiler executables by filename. If your compiler has a non-standard name or is a renamed version of a known compiler, add it to a configuration file:

schema: "4.1"
compilers:
  - path: /usr/local/bin/my-cc
    as: gcc

Do I need Bear if I use CMake?

No. CMake can generate the compilation database natively:

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..

The same applies to Meson and Bazel, which have built-in support.

Can I use Bear with Docker?

Yes, but Bear must run inside the container. Running bear -- docker exec ... on the host does not work. See Platform notes: Docker.

Can I use Bear with ccache / distcc / sccache?

Yes. Bear recognizes these as compiler wrappers and handles them correctly. The output will contain the real compiler call, not the wrapper call.

How do I get verbose output for debugging?

RUST_LOG=debug bear -- <your-build-command>

This prints detailed information about interception, compiler recognition, and output generation.

How do I switch between preload and wrapper mode?

Create a configuration file:

schema: "4.1"
intercept:
  mode: wrapper   # or: preload

Then run:

bear -c bear.yml -- make

Preload is the default on Linux/BSD. Wrapper is the default on macOS and Windows.

Bear worked with v3.x but broke after upgrading to v4.x

See Migrating from 3.x for a summary of what changed and how to adapt.

Can I use Bear with a build system that does not use CC/CXX?

In wrapper mode, Bear prepends a .bear/ directory to PATH. If the build system looks up compilers via PATH (even without using CC/CXX), Bear will intercept them.

In preload mode, Bear intercepts all exec* calls regardless of how the build system finds compilers. This mode is more transparent but does not work with static binaries or on platforms with SIP (macOS).

Can I filter which files appear in the output?

Yes. Use the sources section in the configuration file:

schema: "4.1"
sources:
  directories:
    - path: /project/src
      action: include
    - path: /project/src/generated
      action: exclude

Can I get command instead of arguments in the output?

Yes. Use the format section in the configuration file:

schema: "4.1"
format:
  entries:
    use_array_format: false

Note: The arguments array format is preferred because it avoids shell escaping ambiguity.

Where does Bear store temporary files?

In wrapper mode, Bear creates a .bear/ directory in the current working directory. This directory contains wrapper executables and a configuration file. It is cleaned up after the build completes.

In preload mode, no temporary directory is created. The preload library (libexec.so) is loaded from the installation directory.