Bear is a tool that generates a compilation database for clang tooling.
The JSON compilation database is used in the clang projectto provide information on how a single compilation unit is processed.With this, it is easy to re-run the compilation with alternateprograms.
One way to get a compilation database is to use cmake as the buildtool. Passing -DCMAKE_EXPORT_COMPILE_COMMANDS=ON to cmake generatesthe compile_commands.json file into the current directory.
For non-cmake projects, Bear generates the JSON file during the build process.
The concept behind Bear is: to execute the original build command andintercept the exec calls issued by the build tool. To achieve that,Bear uses the LD_PRELOAD or DYLD_INSERT_LIBRARIES mechanisms providedby the dynamic linker.
Bear has two components: the library and the binary. The libraryredefines the exec methods to be used by all child processes. Theexecutable enables the use of the library for child processes andwrites the output file.
How to install
Bear is packaged for many distributions. Check out your package manager.Or build it from source.
How to build
Bear should be quite portable on UNIX operating systems. It has beentested on FreeBSD, GNU/Linux and OS X.
Prerequisites
- an ANSI C compiler, to compile the sources.
- cmake, to configure the build process.
- make, to run the build. The makefiles are generated by
cmake. - python is a runtime dependency. The
bearcommand is written inPython. (version >= 2.7) - lit is an optional dependency to run the functional tests
Build commands(need root)
Ideally, you should build Bear in a separate build directory.
cmake $BEAR_SOURCE_DIRmake allmake install # to installmake check # to run testsmake package # to make packages
You can configure the build process with passing arguments to cmake.
Build commands(without root)
cmake -DCMAKE_INSTALL_PREFIX=$INSTALL_PATHmake allmake install # to installmake check # to run testsmake package # to make packages
if make install err, you can mark cmake_install.cmake as fellows
# include("/home/longway/Downloads/Bear-2.4.3/shell-completion/cmake_install.cmake")Attention:you can Transfer the files in the release folder to the directory you want and set $PATH
How to use
After installation the usage is like this:
bear <your-build-command>The output file called compile_commands.json is saved in the current directory.
For more options you can check the man page or pass --help parameter.
Side note: Since bear is executing the build command only those commandswill be recorded which were actually executed. Which means if you have alreadybuilt your project and you re-run the build command with Bear you probably endup to have an empty output. (Practically it means you need to run make cleanbefore you run bear make.)
Known issues
Environment overriding caused problems
Because Bear uses LD_PRELOAD or DYLD_INSERT_LIBRARIES environment variables,it does not append to it, but overrides it. So builds which are using thesevariables might not work. (I don't know any build tool which does that, butplease let me know if you do.)
Build with multiple architecture support
Multilib is one of the solutions allowing users to run applications builtfor various application binary interfaces (ABIs) of the same architecture.The most common use of multilib is to run 32-bit applications on 64-bitkernel.
For OSX this is not an issue. The build commands from previous section willwork, Bear will intercept compiler calls for 32-bit and 64-bit applications.
For Linux, a small tune is needed at build time. Need to compile libear.solibrary for 32-bit and for 64-bit too. Then install these libraries to the OSpreferred multilib directories. And replace the libear.so path defaultvalue with a single path, which matches both. (The match can be achieved bythe $LIB token expansion from the dynamic loader. See man ld.so for more.)
Debian derivatives are using lib/i386-linux-gnu and lib/x86_64-linux-gnu,while many other distributions are simple lib and lib64. Here comes anexample build script to install a multilib capable Bear. It will install Bearunder /opt/bear on a non Debian system.
(cd ~/build32; cmake "$BEAR_SOURCE_DIR" -DCMAKE_C_COMPILER_ARG1="-m32"; VERBOSE=1 make all;)(cd ~/build64; cmake "$BEAR_SOURCE_DIR" -DCMAKE_C_COMPILER_ARG1="-m64" -DDEFAULT_PRELOAD_FILE='/opt/bear/$LIB/libear.so'; VERBOSE=1 make all;)sudo install -m 0644 ~/build32/libear/libear.so /opt/bear/lib/libear.sosudo install -m 0644 ~/build64/libear/libear.so /opt/bear/lib64/libear.sosudo install -m 0555 ~/build64/bear/bear" /opt/bear/bin/bear
To check you installation, install lit and run the test suite.
PATH=/opt/bear/bin:$PATH lit -v testPATH=/opt/bear/bin:$PATH lit -v test -DMULTILIB=true
Empty compilation database on OS X / macOS or Fedora
Security extension/modes on different operating systems might disable librarypreloads. In this case Bear behaves normally, but the result compilation databasewill be empty. (Please make sure it's not the case when reporting bugs.)Notable examples for enabled security modes are: OS X 10.11 (check withcsrutil status | grep 'System Integrity Protection'), and Fedora, CentOS, RHEL(check with sestatus | grep 'SELinux status').
Workaround could be to disable the security feature while running Bear. (Thismight involve reboot of your computer, so might be heavy workaround.) Anotheroption if the build tool is not installed under certain directories.Or use tools which are using compiler wrappers. (It injects a fake compilerwhich does record the compiler invocation and calls the real compiler too.)An example for such tool might be scan-build. The build systemshall respect CC and CXX environment variables.
Bazel builds produce empty outputs
The two main constraints to intercept compiler execution from bazel builds are:bazel runs a daemon which runs the compilations, and it creates an isolatedenvironment to run the compiler. These problems are not just hard to circumvent,but the workaround would not be stable to support it by this tool.
The good news is: there are extensions for bazel to generate the compilationdatabase.
Static build tool produce empty output
Currently Bear based on dynamic linker load mechanism, executions made bystatically linked binaries are not captured. It means, if the build tool isstatically linked binary, compiler calls won't be recorded by Bear.
Problem reports
If you find a bug in this documentation or elsewhere in the program or wouldlike to propose an improvement, please use the project's github issuetracker. Please describing the bug and where you found it. If youhave a suggestion how to fix it, include that as well. Patches are alsowelcome.
Please follow the contribution guide when you do this.
