Scroll to navigation

BEAR(1) General Commands Manual BEAR(1)

NAME

bear - build ear

SYNOPSIS

bear [ options] -- [build commands]

DESCRIPTION

Bear is a tool to generate compilation database for clang tooling.
The JSON compilation database (http://clang.llvm.org/docs/JSONCompilationDatabase.html) is used in clang project to provide information how a single compilation unit was processed. When that is available then it is easy to re-run the compilation with different programs.
Bear execs the original build command and intercept the exec calls. To achive that Bear uses the LD_PRELOAD or DYLD_INSERT_LIBRARIES mechanisms provided by the dynamic linker. There is a library which defines the exec methods and used in every child processes of the build command. The executable itself sets the environment up to child processes and writes the output file.

OPTIONS

-c config
Specify config file. Default value provided.
-o output
Specify output file. Default value provided. (This option mainly for development purposes.)
-l library
Specify the preloaded library location. Default value provided. (This option mainly for development purposes.)
-s socket
Specify UNIX socket file. Default value provided. (This option mainly for development purposes.)
-n
Disable filter. The output is also a JSON formated file. But the result is not a compilation database. It contains all available information of the exec calls. (This option mainly for development purposes.)
-x
Verbose filter dump at the end. This option dump a short statistic about the filtering. Might give some insight when the output is not what it expected or when config file were changed.
-v
Print out Bear version and exit.

OUTPUT

There are two version of output formats. One is defined by the clang tooling. This goes like this: 
[
  { "directory": "/home/user/llvm/build",
    "command": "clang++ -Irelative -c -o file.o file.cc",
    "file": "file.cc" },
  ...
]
To achive this bear has to run some filtering and formating. Build tools exec many commands during the build process. Bear has to find was that a compiler call, and what was the source file?
Filtering has three steps. It checks the executable name agains the known compiler names. It checks any of the arguments to match as source file. (Usually done by extension match.) And checks that there is no parameter which might considered as non compilation. (Like dependency file generation, which migth cause duplicates in the output.)
Filters are specified in the config file. The syntax of the file defined by libconfig (http://www.hyperrealm.com/libconfig/). The filter values are extended POSIX regular expressions (http://en.wikipedia.org/wiki/Regular_expression).
Since the post process might be buggy, there is a way to see all exec calls. This gives opportunity to write custom post processing. The format of the non filtered output looks like this: 
[
  { "pid": "1234",
    "ppid": "100",
    "function": "execve",
    "directory": "/home/user/llvm/build",
    "command": "clang++ -Irelative -c -o file.o file.cc" },
  ...
]
Both output is JSON format, which means that command field is escaped if one of the argument had space, slash or quote character. All the other fields are as it was captured.

EXIT STATUS

Bear exit status is the exit status of the build command. Except when bear crashes, then it sets to non zero.

ENVIRONMENT

BEAR_OUTPUT
The place of the socket file where client shall report exec calls. Value set by bear, overrides previous value for child processes.
LD_PRELOAD
Used by the dynamic loader on Linux, FreeBSD and other UNIX OS. Value set by bear, overrides previous value for child processes.
DYLD_INSERT_LIBRARIES
Used by the dynamic loader on OS X. Value set by bear, overrides previous value for child processes.
DYLD_FORCE_FLAT_NAMESPACE
Used by the dynamic loader on OS X. Value set by bear, overrides previous value for child processes.

FILES

/etc/bear.conf
bear configuration file for post processing.
/usr/lib/x86_64-linux-gnu/bear/libear.so
bear library to implement exec calls.

SEE ALSO

ld.so(8), exec(3), ld.so(8)

BUGS

Compiler wrappers like ccache (http://ccache.samba.org/) and distcc (http://code.google.com/p/distcc/) could cause duplicates or missing items in the compilation database. Make sure you have been disabled before you run Bear.
In case of duplicate entries, you might consider to edit the config file to filter out wrapper calls (by path, or by file name) or filter out the compiler calls (and collect the wrapper calls only).

COPYRIGHT

Copyright (C) 2012-2014 by László Nagy <https://github.com/rizsotto/Bear>

AUTHORS

László Nagy.
January 9, 2014 Bear User Manuals