Exploring a Program Repository

Once one or more source files have been compiled to a Program Repository, you might want to explore the resulting data. We have some tools to make this quite straightforward. There are three main utilities: repo-ticket-dump, repo-fragments, and pstore-dump.

Note that the first two tools default to use a pstore file named “clang.db” in the current directory. You can override this using the --repo switch or the REPOFILE environment variable.

repo-ticket-dump

This is a simple tool to extract the compilation digest from a ticket file.

$ repo-ticket-dump ticket.o
910b1351c4706db2f8f2eb0c90cf4a99
$ 

We can then use this in combination with pstore-dump to examine the contents of that compilation record.

For example, if a source file foo.c where to resemble the following:

int foo (void) { return 1; }

This might be compiled with a command such as:

clang -c --target=x86_64-pc-linux-gnu-repo foo.c -o foo.o

This will write results to a program repository named clang.db and produce a ticket file named foo.o. If we then use pstore-dump to examine the contents of the resulting compilation:

pstore-dump --compilation=$(repo-ticket-dump foo.o) clang.db

This should produce YAML output resembling the following:

---
- file         : 
      path : clang.db
      size : 2584
  compilations : 
      - digest      : 910b1351c4706db2f8f2eb0c90cf4a99
        compilation : 
            members : 
                - digest     : 73a7c7679567bfb0041f384debf2ac12
                  fext       : { addr: 1680, size: 448 }
                  name       : foo
                  linkage    : external
                  visibility : default
            path    : /Home/example
            triple  : x86_64-pc-linux-gnu-repo
...

repo-fragments

A utility for dumping the names and digests from a compilation using its ticket file.

For example:

$ repo-fragments ticket.o
f:9f79e432840075c073e1b70610aabdd0
str:e88ce1bd9c14b6c379492240050ae7a8
$

Here ticket.o is a ticket file which references a compilation containing the names 'f' and 'str' with the fragment digests noted. By default, the tool will dump all of the names from the compilation, but you can request one or more by name:

$ repo-fragments ticket.o f
f:9f79e432840075c073e1b70610aabdd0

The --digest-only (-d) switch suppresses the symbol name, so:

$ repo-fragments --digest-only ticket.o f
9f79e432840075c073e1b70610aabdd0

This can be particularly useful to construct a command-line for the pstore-dump --fragment switch. For example, if you’d like to see the internals of the fragment used to define a function or variable named ‘f’:

pstore-dump --fragment=$(repo-fragments --digest-only ticket.o f) clang.db

The command-line above will dump the contents of the fragment which corresponds to the name 'f' in ticket.o.

We can go further and dump multiple fragments by adding the --comma (-c) switch:

pstore-dump --fragment=$(repo-fragments -d -c ticket.o) clang.db

This will dump all of the fragments referenced by all of the definitions in ticket.o.