1# Symbol-Type Graph (STG) 2 3The STG (symbol-type graph) is an ABI representation and this 4project contains tools for the creation and comparison of such 5representations. 6 7The ABI extraction tool, `stg`, emits a native ABI format. Parsers exist for 8libabigail's XML format, BTF and ELF / DWARF. 9 10The ABI diff tool, `stgdiff`, supports multiple reporting options. 11 12STG has a versioned native file format. Older formats can be read and 13rewritten as the latest. 14 15NOTE: STG is under active developement. Tool arguments and behaviour are 16subject to change. 17 18## Getting STG 19 20### Distributions 21 22We intend to package STG for major distributions. Currently we have 23packages as follows: 24 25| *Distribution* | *Package* | 26| ---------------- | ----------------------------------------------------- | 27| Arch Linux (AUR) | [stg-git](https://aur.archlinux.org/packages/stg-git) | 28 29### Source Code 30 31This source code is available at 32https://android.googlesource.com/platform/external/stg/. 33 34## Building from Source 35 36Instructions are included for local and Docker builds. 37 38### Dependencies 39 40STG is written in C++20. It is known to compile with GCC 11, Clang 15 or 41later versions. Mininum requirements for a local build are: 42 43| *Dependency* | *Debian* | *RedHat* | *Version* | 44| ------------- | ----------------- | ----------------- | --------- | 45| build | cmake | cmake | 3.14 | 46| ELF, BTF | libelf-dev | elfutils-devel | 0.189 | 47| DWARF | libdw-dev | elfutils-devel | 0.189 | 48| XML | libxml2-dev | libxml2-devel | 2.9 | 49| BTF | linux-libc-dev | kernel-headers | 5.19 | 50| native format | libprotobuf-dev | protobuf-devel | 3.19 | 51| native format | protobuf-compiler | protobuf-compiler | 3.19 | 52| allocator[^1] | libjemalloc-dev | jemalloc-devel | 5 | 53| catch2[^2] | catch2 | catch2-devel | 2 (only) | 54 55[^1]: jemalloc is optional, but will likely improve performance. 56[^2]: catch2 is optional, but required to build the test suite. 57 58### Local Build 59 60Build STG using CMake as follows: 61 62```bash 63$ mkdir build && cd build 64$ cmake .. 65$ cmake --build . --parallel 66``` 67 68Run the STG unit test suite: 69 70```bash 71$ ctest 72``` 73 74### Docker Build 75 76A [Dockerfile](Dockerfile) is provided to build a container with the 77STG tools: 78 79```bash 80$ docker build -t stg . 81``` 82 83And then enter the container: 84 85```bash 86$ docker run -it stg 87``` 88 89Note that the Dockerfile provides only a production image. To use 90Docker as a development environment, you can comment out everything 91after the line `# second stage`. 92 93After that you may bind your development code to the container: 94 95```bash 96$ docker run -it $PWD:/src -it stg 97``` 98 99The source code is added to `/src`, so when your code is bound you can 100edit on your host and re-compile in the container. 101 102## Contributions 103 104See [CONTRIBUTING.md](CONTRIBUTING.md) for details. 105 106## Contact Information 107 108Please send feedback, questions and bug reports to 109[[email protected]](mailto:[email protected]). 110