BEAR-INTERCEPT(1)

🌸 bear-intercept(1) 🌸

okay bestie, pull up a chair — you're reading the manual page for bear-intercept, straight outta the Bear User Manuals. It's giving "let me spy on your build" energy and honestly? iconic. 💅

---

✨ NAME ✨

bear-intercept — intercept command executions in user space. no cap, that's literally the whole job. 🦋

---

✨ SYNOPSIS ✨

bear intercept [options] -- [build command]

---

✨ DESCRIPTION ✨

So here's the vibe: this thing runs the build command you gave it, and while that's happening it generates an output file stuffed with every single process-execution-related event that went down during the build. 👑

The process execution events are: start, signal, termination. And the output will contain only the child processes. Depending on the interception mode, the output might only contain a subset of the executed commands. Not me gatekeeping, it's just how it works. 🙈

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 reports 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. (slay, now you know what you're running)
• --help — Print help message. (your bestie when you're lost fr fr)
• --verbose — Enable verbose logging. (it will NOT stop talking and we love that)
• --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. 💀 (bestie if it crashes, that's a non-zero, no negotiating)

---

✨ 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 differently (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 reason 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. 🐛

lowkey the empty-output thing is the #1 "why is nothing happening" moment. if everything's up to date, nothing gets compiled, nothing gets intercepted. iykyk 💅

---

✨ SEE ALSO ✨

bear(1)

---

✨ COPYRIGHT ✨

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

---

✨ AUTHORS ✨

László Nagy. 👑

---

and that's the whole page, bestie — Bear User Manuals, dated Sep 04, 2021, BEAR-INTERCEPT(1), periodt. 🎀✨🦋🌸💜