Platform Notes

Platform notes

macOS

Bear defaults to wrapper mode on macOS because System Integrity Protection (SIP) blocks DYLD_INSERT_LIBRARIES for system binaries.

Known issues:

• Homebrew compilers with versioned names (e.g., g++-14, gcc-13) may not be recognized automatically. Add them to the configuration file:

  schema: "4.1"
  compilers:
    - path: /opt/homebrew/bin/g++-14
      as: gcc

• -arch flag handling: On Apple Silicon, some builds pass -arch arm64 or -arch x86_64. Bear preserves these flags in the output.

• Wrapper directory in /var/folders/: When Bear runs in wrapper mode, it creates a .bear/ directory in the current working directory. If you see errors about missing executables in /var/folders/, the temporary directory may have been cleaned up. Re-run Bear.

Windows (MSYS2)

Bear supports Windows through MSYS2 environments (UCRT64, CLANG64, CLANGARM64). Only wrapper mode is available.

Known issues:

• Wrapper directory creation: Bear creates a .bear/ directory with wrapper executables. On Windows, this requires the build system to find these wrappers via PATH.
• Packaging with DESTDIR: The install script supports DESTDIR for staged installations:

  DESTDIR="$pkgdir" PREFIX="$MINGW_PREFIX" ./scripts/install.sh

WSL2

Bear works in WSL2, but there is a known issue with certain network configurations.

networkingMode=mirrored breaks Bear: If your .wslconfig file sets networkingMode=mirrored, the TCP communication between Bear and its wrapper processes may fail. Symptoms include empty output or connection errors.

Workaround: Remove or change the networking mode in %USERPROFILE%\.wslconfig:

[wsl2]
# networkingMode=mirrored   # comment out or remove this line

Then restart WSL: wsl --shutdown.

Docker

Bear must run inside the container. Running bear -- docker exec ... on the host does not work because docker exec sends the command to the Docker daemon, which executes it in a separate process tree that Bear cannot intercept.

Correct usage:

# Inside the container
RUN apt-get install -y bear
RUN bear -- make -j$(nproc)

Or with docker exec:

docker exec my-container bash -c "bear -- make -j4"

Linux

Both preload and wrapper modes are fully supported. Preload mode is the default.

LD_PRELOAD errors: If you see messages like:

ERROR: ld.so: object '...libexec.so' from LD_PRELOAD cannot be preloaded: ignored.

The preload library is installed in the wrong directory. Bear expects libexec.so at a path relative to bear-driver. Check your installation layout matches what is described in INSTALL.md.

If you installed from source, ensure INTERCEPT_LIBDIR matches your system's library directory:

INTERCEPT_LIBDIR=lib64 cargo build --release
INTERCEPT_LIBDIR=lib64 ./scripts/install.sh

FreeBSD / OpenBSD / NetBSD / DragonFly BSD

Supported. Preload mode is the default. Available as packages on FreeBSD (pkg install bear).