Configuration

Configuration

Bear uses a YAML configuration file to control interception mode, compiler recognition, source filtering, duplicate handling, and output formatting.

Loading

Pass a config file explicitly:

bear -c bear.yml -- make

If no -c flag is given, Bear searches for bear.yml in standard locations. If no file is found, built-in defaults are used.

Schema

The configuration file must declare schema: "4.1". Bear rejects files with any other schema version.

Full example

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

Sections

intercept

Controls the command interception method.

intercept:
  mode: preload   # or: wrapper

Mode	Default on	How it works
preload	Linux, BSD	Injects libexec.so via LD_PRELOAD to intercept exec* calls
wrapper	macOS, Windows	Creates wrapper executables in .bear/ and prepends to PATH

If omitted, the default depends on the operating system.

compilers

Hints about which executables are compilers and what type they are.

compilers:
  - path: /usr/bin/arm-linux-gnueabi-gcc
    as: gcc
  - path: /opt/cuda/bin/nvcc
    as: cuda
  - path: /usr/bin/distcc
    as: wrapper
  - path: /usr/local/bin/some-tool
    ignore: true

Field	Required	Description
path	yes	Path to the compiler executable
as	no	Compiler type: gcc, clang, flang, intel-fortran, cray-fortran, cuda, wrapper
ignore	no	If true, exclude this compiler from the output

Without configuration hints, Bear recognizes compilers by filename pattern matching. It recognizes:

• GCC family: gcc, g++, cc, c++, gfortran, including versioned variants (gcc-11) and cross-compilation prefixes (arm-linux-gnueabi-gcc)
• Clang family: clang, clang++, including versioned variants
• Fortran: flang, flang-new, ifort, ifx, crayftn, ftn
• CUDA: nvcc
• Wrappers: ccache, distcc, sccache

If your compiler has a non-standard name, add it to the compilers list.

sources

Filter which source files appear in the output based on directory.

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

Rules are evaluated in order. The last matching rule wins. An empty list means include everything.

duplicates

Control how duplicate entries are detected and removed.

duplicates:
  match_on:
    - file
    - arguments

Available fields: file, directory, arguments, command, output.

Two entries are considered duplicates if all listed fields match. Only the first occurrence is kept.

format

Control the output format.

format:
  paths:
    directory: canonical
    file: canonical
  entries:
    use_array_format: true
    include_output_field: true

Path resolution options (for paths.directory and paths.file):

Value	Description
as-is	No transformation
canonical	Resolve symlinks and normalize
relative	Make relative to the directory field
absolute	Convert to absolute path

Entry format options:

Field	Default	Description
use_array_format	true	true = arguments array, false = command string
include_output_field	true	Include the output field in entries

Defaults

If no configuration file is provided, Bear uses sensible defaults:

• Interception mode: preload on Linux/BSD, wrapper on macOS/Windows
• Compiler recognition: all built-in patterns enabled
• No source filtering
• No duplicate filtering
• Paths as-is, arguments format, output field included