<commit_before>Calling Context Tree Debugging
=========

Warning: This is in development and is not ready to use.

CCTDB is a debugging technique where every function call is recorded for two runs of a program and then compared to find where they differ. This approach is useful for large software projects where a failing testcase is available but it's not obvious where to start debugging.

Tutorial
---------
The first step is to find module and function symbols for some high-level entry point in the program (e.g., `main()`).
```
> ./listModules.py '[your program]'
    moduleA
    moduleB
    ...
> ./listFunctions.py '[your program]' -m 'moduleA'
    int main()
    void functionA()
    int functionB(int, char)
    ...
```

Now record every function call made within the module `moduleA` and the function `int main()`. You can also capture every function call by omitting -f and -m, or attach to existing processes with -p, etc.
```
> ./record.py -m 'moduleA' -f 'int main()' [your program] [goodargs] > good.json
```

This will record a Calling Context Tree (CCT) which has a format like the following:
```
[
    {
        "name": "int main()"
        "calls": [
            { "name": "int secondFunction(...)" },
            { "name": "void thirdFunction(...)" },
            { "name": "int secondFunction(...)" }
        ]
    }
]
```

Now record a second CCT but on a run of the program that contains a bug:
```
> ./record.py -m 'moduleA' -f 'int main()' [program] [badargs] > bad.json
```

Lastly, compare the two runs.
```
> ./compare.py good.json bad.json
    good.json diverged from bad.json in 1 places:
        void thirdFunction(...) which was called by int main()
```

The bad input didn't call `thirdFunction(...)` but the good input did. Time to start debugging calls to `thirdFunction(...)`!<commit_msg>Update main README after switch to LLDB<commit_after>Calling Context Tree Debugging
=========

Warning: This is in development and is not ready to use.

CCTDB is a debugging technique where every function call is recorded for two runs of a program and then compared to see where they diverge. This has been implemented as an LLDB script for recording function calls and some simple analysis scripts for comparing recordings.

This technique is useful for large software projects where a failing testcase is available but it's not obvious where to start debugging. Many bugs in Chromium end up being trivial one-line fixes where an engineer spends days finding the bug but only a few minutes fixing it. CCTDB can be used to save time by automatically narrowing in on suspect code.

Tutorial
---------
The first step is to start debugging your program with LLDB by setting a breakpoint at some high-level entry point (e.g., `main()`):
```
> lldb path/to/program
(lldb) breakpoint set --name main
(lldb) run [known-good arguments]
[breakpoint hit]
```

Now record every function call made from the function `int main()` by loading and running the `record` script:
```
(lldb) command script import path/to/command.py
The "record" command has been installed, type "help record" for more information.
(lldb) record --output good.json
```

This will record a Calling Context Tree (CCT) which has a format like the following:
```
[
    {
        "name": "int main()"
        "calls": [
            { "name": "int secondFunction(...)" },
            { "name": "void thirdFunction(...)" },
            { "name": "int secondFunction(...)" }
        ]
    }
]
```

Now record a second CCT but on a run of the program that contains a bug:
```
(lldb) run [known-bad arguments]
[breakpoint hit]
(lldb) record --output bad.json
```

Finally, compare the two runs:
```
> ./compare.py good.json bad.json
    good.json diverged from bad.json in 1 places:
        void thirdFunction(...) which was called by int main()
```

The bad input didn't call `thirdFunction(...)` but the good input did. Time to start debugging calls to `thirdFunction(...)`.
{'fraction_non_alphanumeric': 0.11479140328697851, 'fraction_numerical': 0.0005056890012642225, 'mean_word_length': 3.235546038543897, 'pattern_counts': {'":': 10, '<': 3, '<?xml version=': 0, '>': 12, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1707863', 'n_tokens_mistral': 1126, 'n_tokens_neox': 1070, 'n_words': 535}