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 were 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

If any of the names are not found in the compilation, the tool will return failure. In conjunction with the 'find' tool, this makes it possible to quickly find which compilation in a large build is responsible for defining a particular name:

find . -name \*.o -exec repo-fragments {} f \; -print

This will search the directory tree starting at the current working directory for files named *.o. For each one found, it will run repo-fragments. If this returns success — which it will do if the compilation contains a definition named ‘f’ — the name of the file is printed. A useful tool when understanding the reasons for a link failure.

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