NAME

       bear-intercept - intercept command executions in user space.

SYNOPSIS

       bear intercept [options] -- [build command]

DESCRIPTION

       The command executes the given build command and generates an output file which contains all process exe‐
       cution related events has happened during the build.

       The  process  execution  events  are: start, signal, termination.  The output will contain only the child
       processes.  Depending on the interception mode the output might only contain a  subset  of  the  executed
       commands.  Interception modes are:

       • preload  uses  the  LD_PRELOAD or DYLD_INSERT_LIBRARIES mechanisms provided by the dynamic linker.  The
         pre-loaded library hijacks the process execution calls, and executes a supervisor  process,  which  re‐
         ports  the  execution.   The method fails when the executable statically linked, or security protection
         disables the dynamic linker.

       • wrapper mode interpose a wrapper program to the build.  The wrapper sends execution  report  and  calls
         the  original  program.   The method fails when the build system is not flexible enough for interposing
         build tools.

       The reports are collected by the intercept over a gRPC interface, and written into an output file.

OPTIONS

       --version
              Print version number.

       --help Print help message.

       --verbose
              Enable verbose logging.

       --output file
              Specify output file.  (Default file name provided.) The output is a command execution  list,  with
              some extra information.  The syntax is detailed in a separate section.

       --force-preload
              Force to use the preload method to intercept the children processes.

       --force-wrapper
              Force to use the wrapper method to intercept the children processes.

EXIT STATUS

       The  exit  status of the program is the exit status of the build command.  Except when the program itself
       crashes, then it sets to non-zero.

OUTPUT FILE

       The output file has JSON lines (https://jsonlines.org/) format, where each line terminated with  \n  line
       separator and each line is a JSON object.

       The  JSON  objects  are  process execution events: process start, process got signal, process terminated.
       (For the schema of these events, please consult with the source code of this project.)

TROUBLESHOOTING

       The potential problems you can face with are: the build with and without the interception behaves differ‐
       ently (eg.: the build crash with the intercept tool, but succeed otherwise).  The output is empty, and it
       failed to intercept the children process execution by the build command.

       The most common cause for empty outputs is that the build command did not execute any commands.  The rea‐
       son for that could be, because incremental builds not running the compilers if everything is  up-to-date.
       Remember,  this  program  does not understand the build file (eg.: makefile), but intercepts the executed
       commands.

       There could be many reasons for any of these failures.  It’s better to consult with the project wiki page
       for known problems, before open a bug report.

SEE ALSO

       bear(1)

COPYRIGHT

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

AUTHORS

       László Nagy.

Bear User Manuals                                 Sep 04, 2021                                 BEAR-INTERCEPT(1)