tree: ba0f6ca474fa91c94ff6cc795904a62c59a28f3d [path history] [tgz]
  1. CMakeLists.txt
  2. README.md
  3. TraceAnnotator.cpp
  4. tests/
tools/clang/trace_annotator/README.md

Trace Annotator Tool

Introduction

A tool to annotate functions with c++ TRACE_EVENT. This tool serves two workflows:

  • Debugging: bulk add traces to all functions in a directory and after finding the bug remove the traces.
  • Adding traces to code: bulk add traces to all functions in a directory, review the changes carefully and create a patch.

The goal of this tool is to transfer a function:

int foo(int bar, int baz) {
  return 42;
}

into:

int foo(int bar, int baz) {
  TRACE_EVENT0("test", "foo");
  return 42;
}

In future also argument tracing is to be supported.

This document is based on //docs/clang_tool_refactoring.md

Building

The following might take approx. 2 hours depending on your computer.

  • Make a new checkout of chromium (suggested, but optional).
  • From chromium/src:
  • shell cr build all To make sure all files have been generated.
  • shell cp -R third_party/llvm-build ~
  • --without-fuchsia --extra-tools trace_annotator```
    *  TODO how to build with plugin 'find-bad-constructs'?
    
  • shell cp -R ~/llvm-build third_party This should enable goma support again.

Rebuild just the tool:

  • shell cd third_party/llvm-build/Release+Asserts
  • shell ninja trace_annotator

Beware that running shell gclient sync might overwrite the build and another full build might be necessary. A backup of the binary from //third_party/llvm-build/Release+Asserts/bin/trace_annotator might be useful.

Testing

  • shell tools/clang/scripts/test_tool.py --apply-edits trace_annotator

Running

  • Chrome plugins are not supported yet, run: shell gn args out/Debug/ and add: clang_use_chrome_plugins = false option.

  • Make sure you have up to date compilation database:

    • To generate it run: shell tools/clang/scripts/generate_compdb.py -p out/Debug/ > out/Debug/compile_commands.json
    • These are the compiler options for individual files (needed to use the right version of C++, right library paths...).
  •    git checkout $DIR && tools/clang/scripts/run_tool.py --tool trace_annotator -p out/Debug/ $DIR \
       | tools/clang/scripts/extract_edits.py \
       | tools/clang/scripts/apply_edits.py -p out/Debug $DIR \
       && git cl format $DIR```
    
    
  • Consult documentation of //tools/clang/scripts/run_tool.py for more options.

Suggestion:

Do not run the tool on //base or anything that has to do with tracing or synchronization. Or at least do not submit the resulting patch.

Debugging workflow suggestion:

  • Do some changes.
  • shell git add . ; git commit
  • Run the tool.
  • shell git add . ; git commit
  • Do some more changes (including fixing a bug).
  • shell git add . ; git commit
  • shell git rebase -i and follow the help.

Creating tracing patch suggestion:

  • Run the tool.
  • Double check all generated code.
  • Add method annotations for methods that are hidden by compiler options (e.g., if you are on unix then the code in c++ #ifdef OS_WIN will not be annotated.

TODO

  • Add options:
    • Whether to add “do not submit” comment (in upper case).
    • Function name formatting (without namespace(s) / getQualifiedNameAsString / with namespaces but without template tags).
    • Category name.
    • Make tracing of function arguments.
  • Standalone build of the tool (outside of //third_party to avoid overwriting by shell gclient sync).