What is broccoli-debug?
The broccoli-debug npm package is a tool for debugging Broccoli.js build pipelines. It allows developers to inspect and visualize the intermediate states of their build trees, making it easier to understand and troubleshoot the build process.
What are broccoli-debug's main functionalities?
Debugging Build Trees
This feature allows you to insert debug checkpoints in your Broccoli build pipeline. By labeling different stages of the build process, you can inspect the state of the build tree at various points.
const debugTree = require('broccoli-debug');
let tree = someBroccoliTree;
tree = debugTree(tree, 'initial');
// Perform some transformations
// Debug the transformed tree
tree = debugTree(tree, 'transformed');
Visualizing Build Trees
This feature allows you to visualize the build tree at different stages. By using the debugTree function with appropriate labels, you can generate visual representations of the build tree, which can be helpful for understanding the build process and identifying issues.
const debugTree = require('broccoli-debug');
const broccoli = require('broccoli');
let tree = someBroccoliTree;
tree = debugTree(tree, 'visualize');
const builder = new broccoli.Builder(tree);
builder.build().then(() => {
console.log('Build complete. Check the debug output for visualization.');
});
Other packages similar to broccoli-debug
broccoli-inspector
broccoli-inspector is another tool for inspecting Broccoli.js build pipelines. It provides similar functionality to broccoli-debug, allowing developers to visualize and debug their build trees. However, broccoli-inspector focuses more on providing a graphical interface for inspecting the build process, whereas broccoli-debug is more code-centric.
broccoli-viz
broccoli-viz is a visualization tool for Broccoli.js build pipelines. It generates visual representations of the build tree, similar to broccoli-debug's visualization feature. The main difference is that broccoli-viz is specifically designed for creating visual outputs, while broccoli-debug also includes debugging capabilities.
broccoli-debug
Utility for build pipeline authors to allow trivial debugging of the Broccoli
pipelines they author.
Heavily inspired by @stefanpenner's
broccoli-stew's debug
's helper,
but improved in a few ways:
- Supports leaving debug trees in the build with minimal cost when not being used.
- Supports binary files (e.g. does not write
.png
's as utf8
text). - Adds debug style debug matching.
Usage
Pipeline Authors
To allow consumers to debug the internals of various stages in your build pipeline,
you create a new instance of BroccoliDebug
and return it instead.
Something like this:
var BroccoliDebug = require('broccoli-debug');
let tree = new BroccoliDebug(input, `ember-engines:${this.name}:addon-input`);
Obviously, this would get quite verbose to do many times, so we have created a shortcut
to easily create a number of debug trees with a shared prefix:
let debugTree = BroccoliDebug.buildDebugCallback(`ember-engines:${this.name}`);
let tree1 = debugTree(input1, 'addon-input');
let tree2 = debugTree(input2, 'addon-output');
Consumers
Folks wanting to inspect the state of the build pipeline at that stage, would do the following:
BROCCOLI_DEBUG=ember-engines:* ember b
Now you can take a look at the state of that input tree by:
ls DEBUG/ember-engines
API
interface BroccoliDebugOptions {
label: string
baseDir: string
force?: boolean
}
class BroccoliDebug {
static buildDebugCallback(prefix: string): (node: any, labelOrOptions: string | BroccoliDebugOptions) => BroccoliNode
constructor(node: BroccoliNode, labelOrOptions: string | BroccoliDebugOptions);
debugLabel: string;
}
Development
Installation
git clone git@github.com:broccolijs/broccoli-debug.git
cd broccoli-debug
yarn
Testing