INTERCEPT(1)

📦 version 3.0.20, in epel 9, ubuntu jammy

✨ NAME ✨

okay so bestie, welcome to the intercept(1) manual page 💖 this one's all about intercept — the tool that intercepts command executions in user space. yes, it's giving spy movie but for your build system 🕵️♀️✨

🌸 SYNOPSIS 🌸

intercept [options] -- [build command]

🦋 DESCRIPTION 🦋

so the tea is: intercept runs the build command you hand it, and then it spits out an output file that's absolutely packed with every single process-execution-related event that went down while that build was doing its thing. 👑

the process execution events you're gonna see are:

  • start
  • signal
  • termination

and like, heads up — the output contains only the child processes. not the whole family tree, just the kiddos. 🙈

depending on the interception mode, the output might only contain a subset of the commands that actually ran. the interception modes are, in no particular order of slay:

  • preload — this one uses the LD_PRELOAD or DYLD_INSERT_LIBRARIES mechanisms that the dynamic linker provides. the pre-loaded library hijacks the process execution calls and executes a supervisor process, which reports the execution. 💅 however — and this is the important part — the method fails when the executable is statically linked, or when security protection disables the dynamic linker. no cap, that's a hard limitation.
  • wrapper mode — this one interposes a wrapper program into the build. the wrapper sends the execution report and then calls the original program. 🎀 but it fails when the build system is not flexible enough for interposing build tools. tragic, honestly.

and then the reports? they get collected by intercept over a gRPC interface, and written into an output file. the whole pipeline is lowkey iconic. ⭐

💅 OPTIONS 💅

  • --version — prints the version number. simple. clean. ate.
  • --help — prints the help message. your bestie when you're lost fr fr.
  • --verbose — turns on verbose logging. for when you want the full play-by-play commentary. 👀
  • --output file — specify the output file. (there's a default file name provided, don't worry.) the output is a command execution list, with some extra information sprinkled on top. the syntax gets its own dedicated section below — see it, love it. 🫶
  • --force-preload — forces the use of the preload method to intercept the children processes. periodt.
  • --force-wrapper — forces the use of the wrapper method to intercept the children processes. also periodt.

🔥 EXIT STATUS 🔥

the exit status of the program is the exit status of the build command. that's it, that's the whole vibe. ✨

except when the program itself crashes — then it gets set to non-zero. 😭 so if you see a non-zero and your build was fine… yeah, that's what happened.

🌈 OUTPUT FILE 🌈

the output file has JSON lines format — that's https://jsonlines.org/ for anyone who wants the full lore 💖 — where each line is terminated with a \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. iykyk 🧚)

🎀 TROUBLESHOOTING 🎀

okay so the potential problems you might face are:

  • the build behaves differently with and without the interception (eg.: the build crashes with the intercept tool, but succeeds 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. and the reason for that could be… incremental builds not running the compilers if everything is already up-to-date. 🙈

remember: intercept does not understand the build file (eg.: makefile). it only intercepts the executed commands. it's not reading your makefile, bestie, it's watching what actually runs. 👑

there could be many reasons for any of these failures. it's better to consult with the project wiki page for known problems before you open a bug report. do your research first, queen. 🫶

🌟 SEE ALSO 🌟

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

💜 AUTHORS 💜

László Nagy.

and that's the whole page, bestie!! 🎀 this gem came to you courtesy of the Bear User Manuals, dated Sep 04, 2021 — take care of her, she's iconic ✨🦋💖

📦 where this page comes from