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)

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.

COPYRIGHT

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

AUTHORS

       László Nagy.