cjhopman / magic-debugging

Magic

The magic debugging library by Chris Hopman <[e-mail]>

I love debugging via printf, and you should too. This library will help.

It introduces several useful functions that are automatically available in every c++ file in your chromium checkout (some exceptions). These functions make it easy to print messages, to visualize c++ scopes in logs, to print values, etc. Here's a sample of what's available:

All messages include a tag with file:line+function_name

DUMP() << "this is a message"; // Prints the message.
DUMP_INDENT; // Indents all magic logging one level until the end of this scope.

DUMP_SCOPE(); // Prints a "<<<<<" now, and ">>>>>" when this scope exits. Also indents all logs within this scope.
DUMP_SCOPE("enter", "exit"); // Same as above, but prints "enter" and "exit" instead of "<<<<<" and ">>>>>".

DUMP(x, y) << " wow!"; // Same as: DUMP() << "x = " << x << " y = " << y << " wow!";
DUMP(*foo->bar().baz); // Same as: DUMP() << "*foo->bar().baz = " << *foo->bar().baz;

DUMP() << TFORMAT(x, y, z, w); // Same as: DUMP() << "x = " << x << "y = " << y << "z = " << z << "w = " << w;

In addition, the magic library automatically knows how to print many things that have a reasonable way of being printed:

Classes with function OutputToStream -- e.g. base::debug::StackTrace
Classes with function ToString -- e.g. ui::gfx::Size
Classes with free function PrintTo -- e.g. things printable by gtest
Iterable classes -- std::vector, std::map, etc.


Installing:

This library should be in your chromium source tree at "src/magic".

So that this new directory does not show up as "dirty" in git, add it to the repo's .git/info/exclude:
  echo "/magic" >> .git/info/exclude

Option 1:

Clone the git repo into "src/magic".
  git clone https://github.com/cjhopman/magic-debugging.git src/magic

Option 2:

Add the following to the 'solutions' list in your .gclient file (in src/../):

  {
    "name"        : "src/magic",
    "url"         : "https://github.com/cjhopman/magic-debugging.git",
    "managed"     : True,
  },


Enabling:

By default, the magic library is disabled. To enable it, the gyp variable "magic_enabled" must be set to 1. This can be done either by adding it to GYP_DEFINES:

export GYP_DEFINES="magic_enabled=1 $GYP_DEFINES"

This needs to be done before running gyp (i.e. before 'android_gyp', 'gclient sync', 'gclient runhooks', 'python build/gyp_chromium', or however else you run gyp).

Another option is to add the variable to your chrome/supplement.gypi or ~/include.gypi files. These are global/per-repo personal gyp settings. An example of such a file:

{
  'variables': {
    'clang': 1,
    'magic_enabled': 1,
  },
},


Downsides:

Toggling magic_enabled causes a full rebuild.
In non-Android builds, the indent level is not shared across shared_library targets.