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.