Source Code Annotation Using run-clang-prob-annotate

run-clang-prob-annotate.py encapsulates the clang-prob-annotate annotation tool, making it easier to use in large-scale projects. The script still depends on the clang-prob-annotate annotation tool. Therefore, you need to configure a proper environment variable PATH.

You can use -h or --help to view the options supported by the script.

The script tool supports four annotation modes:

1. Annotate a single source code file.
2. Annotate all source code files.
3. Annotate source code files in the specified directory (including subdirectories).
4. Annotate source code files in batches in the specified source code path list.

Usage:

1. Prepare for the work.

Before annotation, ensure that the correct profile data file and compile_commands.json have been obtained based on the preceding process.

This script tool can parse compile_commands.json to obtain the build information of each source file. The -p /path/to/compile_commands.json parameter is required to specify the file path. The profile data file can be specified using the -r /path/to/***.profdata parameter. This parameter is optional, but if the compile_commands.json file is generated from a properly compiled project and does not include the -fproile-instr-use=/path/to/***.profdata parameter, you must specify the profile data file path to provide data input.

2. Annotate a single source code file.

Reference commands:

• compile_commands.json without -fprofile-instr-use

1

python3 run-clang-prob-annotate.py -p /path/to/compile_commands.json -s /path/to/annotate-source-file -r /path/to/***.profdata

• compile_commands.json with -fprofile-instr-use

1

python3 run-clang-prob-annotate.py -p /path/to/compile_commands.json -s /path/to/annotate-source-file

3. Annotate all source code files.

Reference commands:

• compile_commands.json without -fprofile-instr-use

1

python3 run-clang-prob-annotate.py -p /path/to/compile_commands.json -a -r /path/to/***.profdata

• compile_commands.json with -fprofile-instr-use

1

python3 run-clang-prob-annotate.py -p /path/to/compile_commands.json -a

4. Annotate source code files in the specified directory (including subdirectories).

Reference commands:

• compile_commands.json without -fprofile-instr-use

1

python3 run-clang-prob-annotate.py -p /path/to/compile_commands.json -d /path/to/annotate-source-directory -r /path/to/***.profdata

• compile_commands.json with -fprofile-instr-use

1

python3 run-clang-prob-annotate.py -p /path/to/compile_commands.json -d /path/to/annotate-source-directory

5. Annotate source code files in batches in the specified source code path list.

Reference commands:

• compile_commands.json without -fprofile-instr-use

1

python3 run-clang-prob-annotate.py -p /path/to/compile_commands.json -b /path/to/***.json -r /path/to/***.profdata

• compile_commands.json with -fprofile-instr-use

1

python3 run-clang-prob-annotate.py -p /path/to/compile_commands.json -b /path/to/***.json

• Specify the source code path list in JSON format.

The reference format is as follows:

1
2
3
4

{
"path": "/path/to/prob-annotate",
"files": ["func.cpp", "test/test.cpp"]
}

You must specify the path list in strict accordance with the preceding format to ensure that path/files is a complete file path. In addition, multiple {} objects cannot be used as the input.