bear-intercept(1)

1BEAR-INTERCEPT(1)                                            BEAR-INTERCEPT(1)
2
3
4

NAME

6       bear-intercept - intercept command executions in user space.
7

SYNOPSIS

9       bear intercept [options] -- [build command]
10

DESCRIPTION

12       The  command  executes  the given build command and generates an output
13       file which contains all process execution related events  has  happened
14       during the build.
15
16       The process execution events are: start, signal, termination.  The out‐
17       put will contain only the child processes.  Depending on the  intercep‐
18       tion  mode  the output might only contain a subset of the executed com‐
19       mands.  Interception modes are:
20
21       • preload uses the LD_PRELOAD or DYLD_INSERT_LIBRARIES mechanisms  pro‐
22         vided  by  the  dynamic  linker.   The pre-loaded library hijacks the
23         process execution calls, and executes a supervisor process, which re‐
24         ports the execution.  The method fails when the executable statically
25         linked, or security protection disables the dynamic linker.
26
27       • wrapper mode interpose a wrapper program to the build.   The  wrapper
28         sends  execution  report  and calls the original program.  The method
29         fails when the build system is not flexible  enough  for  interposing
30         build tools.
31
32       The  reports  are collected by the intercept over a gRPC interface, and
33       written into an output file.
34

OPTIONS

36       --version
37              Print version number.
38
39       --help Print help message.
40
41       --verbose
42              Enable verbose logging.
43
44       --output file
45              Specify output file.  (Default file name provided.)  The  output
46              is  a  command execution list, with some extra information.  The
47              syntax is detailed in a separate section.
48
49       --force-preload
50              Force to use the preload method to intercept the  children  pro‐
51              cesses.
52
53       --force-wrapper
54              Force  to  use the wrapper method to intercept the children pro‐
55              cesses.
56

EXIT STATUS

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

OUTPUT FILE

62       The  output  file has JSON lines (https://jsonlines.org/) format, where
63       each line terminated with \n line separator and each line is a JSON ob‐
64       ject.
65
66       The  JSON  objects are process execution events: process start, process
67       got signal, process terminated.   (For  the  schema  of  these  events,
68       please consult with the source code of this project.)
69

TROUBLESHOOTING

71       The  potential problems you can face with are: the build with and with‐
72       out the interception behaves differently (eg.: the build crash with the
73       intercept  tool,  but  succeed otherwise).  The output is empty, and it
74       failed to intercept the children process execution by  the  build  com‐
75       mand.
76
77       The  most  common cause for empty outputs is that the build command did
78       not execute any commands.  The reason for that could be, because incre‐
79       mental  builds  not  running the compilers if everything is up-to-date.
80       Remember, this program does not understand the build file  (eg.:  make‐
81       file), but intercepts the executed commands.
82
83       There  could be many reasons for any of these failures.  It’s better to
84       consult with the project wiki page for known problems,  before  open  a
85       bug report.
86

COPYRIGHT

91       Copyright  (C)  2012-2023  by  László  Nagy <https://github.com/rizsot‐
92       to/Bear>
93

AUTHORS

95       László Nagy.
96
97
98
99Bear User Manuals                Sep 04, 2021                BEAR-INTERCEPT(1)