Package: blight
blightblightis a framework for wrapping and instrumenting build tools and build
systems. It contains:A collection of high-fidelity models for various common build tools (e.g.
the C and C++ compilers, the standard linker, the preprocessor, etc.);A variety of "actions" that can be run on each build tool or specific
classes of tools (e.g. "whenever the build system invokes$CC, add this
flag");Command-line wrappers (blight-envandblight-exec) for instrumenting
builds.InstallationUsageQuickstartCookbookGoalsAnti-goalsContributingInstallationblightis available on PyPI and is installable viapip:python-mpipinstallblightPython 3.7 or newer is required.Usageblightcomes with two main entrypoints:blight-exec: directly execute a command within ablight-instrumented
environmentblight-env: write ash-compatible environment definition tostdout,
which the shell or other tools can consume to enter ablight-instrumented
environmentIn most cases, you'll probably wantblight-exec.blight-envcan be thought
of as the "advanced" or "plumbing" interface.Usage: blight-exec [OPTIONS] TARGET [ARGS]...

Options:
  --guess-wrapped      Attempt to guess the appropriate programs to wrap
  --swizzle-path       Wrap via PATH swizzling
  --stub STUB          Stub a command out while swizzling
  --shim SHIM          Add a custom shim while swizzling
  --action ACTION      Enable an action
  --journal-path PATH  The path to use for action journaling
  --help               Show this message and exit.Usage: blight-env [OPTIONS]

Options:
  --guess-wrapped  Attempt to guess the appropriate programs to wrap
  --swizzle-path   Wrap via PATH swizzling
  --stub TEXT      Stub a command out while swizzling
  --shim TEXT      Add a custom shim while swizzling
  --unset          Unset the tool variables instead of setting them
  --help           Show this message and exit.QuickstartThe easiest way to get started withblightis to useblight-execwith--guess-wrappedand--swizzle-path. These flags tellblightto configure
the environment with some common-sense defaults:--guess-wrapped: guess the appropriate underlying tools to invoke from
the currentPATHand other runtime environment;--swizzle-path: rewrite thePATHto put some common build tool shims
first, e.g. redirectingcctoblight-cc.For example, the following will runcc -vunderblight's instrumentation,
with theDemoaction:blight-exec--actionDemo--swizzle-path--guess-wrapped--cc-vwhich should produce something like:[demo] before-run: /usr/bin/ccApple clang version 14.0.0 (clang-1400.0.29.202)Target: x86_64-apple-darwin22.2.0Thread model: posixInstalledDir: /Library/Developer/CommandLineTools/usr/bin[demo] after-run: /usr/bin/ccWe can also see the effect of--swizzle-pathby runningwhich ccunderblight, and observing that it points to a temporary shim rather than the
normalcclocation:$blight-exec--swizzle-path--guess-wrapped--whichcc
/var/folders/zj/hy934vnj5xs68zv6w4b_f6s40000gn/T/tmp5uahp6tg@blight-swizzle@/cc

$whichcc
/usr/bin/ccAll theDemoaction does is print a message before and after each tool run,
allowing you to diagnose when a tool is or isn't correctly instrumented.
See theactions documentation belowfor information on
using and configuring more interesting actions.CookbookRunningblightagainst amake-based buildMostmake-based builds use$(CC),$(CXX), etc., which means that they
should work out of the box withblight-exec:blight-exec--guess-wrapped--makeIn some cases, poorly written builds may hard-codecc,clang,gcc, etc.
rather than using their symbolic counterparts. For these, you can use--swizzle-pathto interpose shims that redirect those hardcoded tool
invocations back toblight's wrappers:blight-exec--guess-wrapped--swizzle-path--makeSeeTaming an uncooperative build with shims and stubsfor more advanced techniques for dealing with poorly written build systems.Enabling actionsActions are whereblightreally shines: they allow you to run arbitrary Python
code before and after each build tool invocation.blightcomes with built-in actions, which aredocumented here.
See each action's Python module for its documentation.Actions can be enabled in two different ways:With the--actionflag, which can be passed multiple times. For example,--action SkipStrip --action Recordenables both theSkipStripandRecordactions.With theBLIGHT_ACTIONSenvironment variable, which can take multiple
actions delimited by:. For example,BLIGHT_ACTIONS=SkipStrip:Recordis equivalent to--action SkipStrip --action Record.Actions are run in the order of specification with duplicates removed, meaning
thatBLIGHT_ACTIONS=Foo:Bar:Foois equivalent toBLIGHT_ACTIONS=Foo:BarbutnotBLIGHT_ACTIONS=Bar:Foo. This is important if actions have side
effects, which they may (such as modifying the tool's flags).Action configurationSome actions accept or require additional configuration, which is passed
through theBLIGHT_ACTION_{ACTION}environment variable inkey=valueformat, where{ACTION}is the uppercased name of the action.For example, to configureRecord's output file:BLIGHT_ACTION_RECORD="output=/tmp/output.jsonl"Action outputsThere are two ways to get output from actions underblight:Many actions support anoutputconfiguration value, which should be a
filename to write to. This allows each action to write its own output
file.blightsupports a "journaling" mode, in which all action outputs
are written to a single file, keyed by action name.The "journaling" mode is generally encouraged over individual outputs,
and can be enabled with eitherBLIGHT_JOURNAL_PATH=/path/to/output.jsonlin the environment orblight-exec --journal-path /path/to/output.jsonl.Configuring an environment withblight-envblight-envbehaves exactly the same asblight-exec, except that it
stops before actually executing anything. You can use it to set up an
environment for use across multiple build system runs.By default,blight-envwill just export the appropriate environment
for replacingCC, etc., with theirblightwrappers:$blight-envexportCC=blight-ccexportCXX=blight-c++exportCPP=blight-cppexportLD=blight-ldexportAS=blight-asexportAR=blight-arexportSTRIP=blight-stripexportINSTALL=blight-install--guess-wrappedaugments this by adding a best-guess underlying tool for
each wrapper:$blight-env--guess-wrappedexportBLIGHT_WRAPPED_CC=/usr/bin/ccexportBLIGHT_WRAPPED_CXX=/usr/bin/c++exportBLIGHT_WRAPPED_CPP=/usr/bin/cppexportBLIGHT_WRAPPED_LD=/usr/bin/ldexportBLIGHT_WRAPPED_AS=/usr/bin/asexportBLIGHT_WRAPPED_AR=/usr/bin/arexportBLIGHT_WRAPPED_STRIP=/usr/bin/stripexportBLIGHT_WRAPPED_INSTALL=/usr/bin/installexportCC=blight-ccexportCXX=blight-c++exportCPP=blight-cppexportLD=blight-ldexportAS=blight-asexportAR=blight-arexportSTRIP=blight-stripexportINSTALL=blight-install--guess-wrappedalso respectsCC, etc. in the environment:$CC=/some/custom/ccblight-env--guess-wrappedexportBLIGHT_WRAPPED_CC=/some/custom/ccexportBLIGHT_WRAPPED_CXX=/usr/bin/c++exportBLIGHT_WRAPPED_CPP=/usr/bin/cppexportBLIGHT_WRAPPED_LD=/usr/bin/ldexportBLIGHT_WRAPPED_AS=/usr/bin/asexportBLIGHT_WRAPPED_AR=/usr/bin/arexportBLIGHT_WRAPPED_STRIP=/usr/bin/stripexportBLIGHT_WRAPPED_INSTALL=/usr/bin/installexportCC=blight-ccexportCXX=blight-c++exportCPP=blight-cppexportLD=blight-ldexportAS=blight-asexportAR=blight-arexportSTRIP=blight-stripexportINSTALL=blight-install--swizzle-pathfurther modifies the environment by rewritingPATH:$blight-env--guess-wrapped-swizzle-pathexportBLIGHT_WRAPPED_CC=/usr/bin/ccexportBLIGHT_WRAPPED_CXX=/usr/bin/c++exportBLIGHT_WRAPPED_CPP=/usr/bin/cppexportBLIGHT_WRAPPED_LD=/usr/bin/ldexportBLIGHT_WRAPPED_AS=/usr/bin/asexportBLIGHT_WRAPPED_AR=/usr/bin/arexportBLIGHT_WRAPPED_STRIP=/usr/bin/stripexportBLIGHT_WRAPPED_INSTALL=/usr/bin/installexportPATH='/var/folders/zj/hy934vnj5xs68zv6w4b_f6s40000gn/T/tmpxh5ryu22@blight-swizzle@:/bin:/usr/bin:/usr/local/bin'exportCC=blight-ccexportCXX=blight-c++exportCPP=blight-cppexportLD=blight-ldexportAS=blight-asexportAR=blight-arexportSTRIP=blight-stripexportINSTALL=blight-installThe swizzled addition can be identified by its@blight-swizzle@directory name.Taming an uncooperative build with shims and stubsSometimes build systems need more coaxing than just--guess-wrappedand--swizzle-path. Common examples include:Hard-coding a particular tool or tool version rather than using the symbolic
name (e.g.clang-7 example.cinstead of$(CC) example.c);Running lots of "junk" commands that can be suppressed (e.g. lots ofechoinvocations)You can useshimsandstubsto smooth out these cases:shimsreplace a command with a build tool thatblightknows about, e.g.clang-3.8withcc.stubsreplace a command with an invocation oftrue, meaning that it
does nothing and never fails.Shims are specified with--shim cmd:tool, while stubs are specified with--stub cmd. Both require--swizzle-path, since thePATHmust be rewritten
to inject additional commands.For example, to instrument a build system that hardcodestcceverywhere
and that spews way too much output withecho:blight-exec--guess-wrapped--swizzle-path--shimtcc:cc--stubecho--makeGoalsWrappingCC,CXX,CPP,LD,AS,AR,STRIP, andINSTALL.Providing a visitor-style API for each of the above, pre- and post-execution.Providing a nice set of default actions.Being as non-invasive as possible.Anti-goalsUsingLD_PRELOADto capture everyexecin a build system,
a laBear.Supportingcl.exe.Detailed support for non C/C++ languages.ContributingCheck out ourCONTRIBUTING.md!