debugging-the-debugger.md

Debugging the Debugger

Debugging the Debugger is one of the highest levels of inception. Before you begin, prepare yourself for a mind-bending trip of self discovery.

Playing with the debugger

Setup the Debugger so that your environment looks like this gif.

If you have any questions, go back to the getting setup instructions.

Design a new theme ❄️

Lets design a new theme for the debugger, it's not too hard! Our goal here is to style the source tree, editor, and other UI components.

Share your a screenshot of your theme here ! Here's an example camo theme that I designed the other day.

Make breakpoints dance 👯

Adding a breakpoint is a critical piece in the inception game... Lets make the debugger do something special when a breakpoint is added.

You can find the file that handles breakpoints here: /debugger.html/src/components/Editor/Breakpoint.js Then go ahead and find (Cntrl-F) "addBreakpoint". This should pull up the addBreakpoint function, which (surprise!) adds a breakpoint! Then we are going to add an alert so can see something for our actions:

addBreakpoint() {
    const { breakpoint, editor, selectedSource } = this.props;

    // Hidden Breakpoints are never rendered on the client
    if (breakpoint.hidden) {
      return;
    }

	//Add the code below
	alert("Your first breakpoint! Congratulations!");


    // NOTE: we need to wait for the breakpoint to be loaded
    // to get the generated location
    if (!selectedSource || breakpoint.loading) {
      return;
    }

This will show a popup when we create a breakpoint.

Pausing FTW 🔴

When the debugger pauses, the fun begins. Here's a gif of what the debugger does normally when it pauses. Your mission if you choose to accept it, is to make it do something truly weird.

Here's some example code that you can help you to get you started; debugger.html/src/components/SecondaryPanes/Frames/WhyPaused.js renders the pause reason into the sidebar, and /debugger.html/src/utils/pause/why.js is used in several places to expose the current paused state.

WhyPaused.js (Starts at line 42):

export default function renderWhyPaused({ pause }: { pause: Pause }) {
  const reason = getPauseReason(pause);

  if (!reason) {
    return null;
  }
  //Add the code below:
  console.log("Hello from src/components/SecondaryPanes/Frames/WhyPaused.js!");

  return (
    <div className={"pane why-paused"}>
      <div>{L10N.getStr(reason)}</div>
      {renderMessage(pause)}
    </div>
  );
}
renderWhyPaused.displayName = "whyPaused";

Then in why.js (Starts at line 31) :

export function getPauseReason(why?: Why): string | null {
  if (!why) {
    return null;
  }
  //Add the code below:
  console.log("hello from src/utils/pause/why.js!");

  const reasonType = get(pauseInfo, "why.type", null);
  if (!reasons[reasonType]) {
    console.log("Please file an issue: reasonType=", reasonType);
  }
  return reasons[reasonType];
}

Debugger Philosophy

Here's the debugger philosophy in a nutshell.

1. When you inspect the running debugger app, you're debugging a web app
2. The Debugger like other applications has an API to communicate with the browser
3. There's no magic here. If you can build a web app, you can hack on the debugger!
4. You are the debugger's principal customer. Remember, the customer is always right!

Please let us know if we're missing something zen here.

Next Steps

Now that you've internalized the debugger philosophy, it's time to start putting this wisdom to use.

Share what you know Give a talk in school, work, or a local meetup. I'm willing to bet your audience will not know the debugger is a web app! Write a blog post. We'd be happy to link to it here and it could go a really long way towards helping a newcomer grok the philosophy.

• here are @amitzur's slides from his talk

Contribute back take a look at how you can start contributing. We would love the help!