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 achieve 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

       -o output, --cdb output
              Specify output file.  Default value provided.

       -a, --append
              Use  previously  generated  output file and append the new entries to it.  This way
              you can run bear continuously during work, and it keeps the compilation database up
              to  date.  File deletion and addition are both considered. But build process change
              (modifying compiler flags) will cause duplicate entries.

       -v, --verbose
              Make bear more verbose.

       -l library
              Specify the preloaded library location.   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.)

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 achieve 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?  The other output format is generated by the -n flag. (This output is
       not formalized, it's used to debug bear itself.)

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 temporary files 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

       /usr/lib/x86_64-linux-gnu/bear/libear.so
              bear library to implement exec calls.

SEE ALSO

       ld.so(8), exec(3)

BUGS

       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 these variables might not work.
       (I don't know any build tool which does that, but please let me know if you do.)

       Security extension/modes on different operating systems might  disable  library  preloads.
       This case Bear behaves normaly, but the result compilation database will be empty. (Please
       make sure it's not the case when reporting bugs.)  Notable examples for  enabled  security
       modes are: SIP on OS X Captain and SELinux on Fedora, CentOS, RHEL.

COPYRIGHT

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

AUTHORS

       László Nagy.