Smeagle

This is a C++ project that will attempt to extract features from libraries and binaries that can be used to assess ABI Compatibility. I am calling it Smeagle because these features are considered "the precious" - the subcorpora of a binary that is enough to determine ABI compatibility. The name is subject to change. :)

To cleanly separate the library and subproject code, the outer CMakeList.txt only defines the library itself while the tests and other subprojects are self-contained in their own directories. During development it is usually convenient to build all subprojects at once.

Versions

Currently, the VERSION file is only parsed into the automated container build, and this container is used for the build-abi-containers repository. It is not parsed into Smeagle proper. The Smeagle version (produced by the client) is defined in the CMakeLists.txt. So yes, you currently need to update it in both places. We will fix this in the future so it's better.

Develop using a container

The Dockerfile will easily create an environment with all the dependencies that you need. If you need to have a base of Dyninst from master, then build that first:

$ docker build -f docker/Dockerfile.dyninst -t ghcr.io/autamus/dyninst:master .

And ensure that this is the base container of Dockerfile. Otherwise you can uncomment the line to use dyninst from autamus. When you are ready, here is how to build the container:

docker build -t smeagle .

And to enter, change the entrypoint to bash (by default it will just be the Smeagle executable):

$ docker run --rm -it --entrypoint bash -v $PWD:/code smeagle

You should then be in the mounted /code directory, and you can compile as follows:

$ make

or just for the standalone client and not tests (there is a current bug with compiling tests):

$ make standalone

And then you can ask for help, and run against a binary. For example, I built tcl with spack and copied a library into the root folder.

$ ./build/standalone/Smeagle -h
Extract library metadata, the precious.
Usage:
  ./build/standalone/Smeagle [OPTION...]

  -h, --help         Show help
  -v, --version      Print the current version number
  -l, --library arg  Library to inspect
  -f, --fmt arg      Format to output in (default: terminal)

root@98ad59b3999d:/code# ./build/standalone/Smeagle -l libtcl8.6.so 
interface(TclFindElement)
abi_typelocation(function,libtcl8.6.so,TclFindElement,interp,Tcl_Interp *,unknown)
abi_typelocation(function,libtcl8.6.so,TclFindElement,list,const char *,unknown)
abi_typelocation(function,libtcl8.6.so,TclFindElement,listLength,int,%rdx)
...

The part that I'm focusing on now is parsing the types into actual locations (the unknown strings above I haven't done yet). You can also make the standalone client, the docs, format the code, or run tests.

$ make standalone
$ make docs
$ make fmt
$ make test

important be careful about formatting code from the container - it changes all permissions. If you do this and need to fix (from outside the container):

$ sudo chown -R $USER .

See Format.cmake for details on the formatting.

Additional tools

The test and standalone subprojects include the tools.cmake file which is used to import additional tools on-demand through CMake configuration arguments. The following are currently supported.

Sanitizers

Sanitizers can be enabled by configuring CMake with -DUSE_SANITIZER=<Address | Memory | MemoryWithOrigins | Undefined | Thread | Leak | 'Address;Undefined'>.

Static Analyzers

Static Analyzers can be enabled by setting -DUSE_STATIC_ANALYZER=<clang-tidy | iwyu | cppcheck>, or a combination of those in quotation marks, separated by semicolons. By default, analyzers will automatically find configuration files such as .clang-format. Additional arguments can be passed to the analyzers by setting the CLANG_TIDY_ARGS, IWYU_ARGS or CPPCHECK_ARGS variables.

Ccache

Ccache can be enabled by configuring with -DUSE_CCACHE=<ON | OFF>.

License

This project is part of Spack. Spack is distributed under the terms of both the MIT license and the Apache License (Version 2.0). Users may choose either license, at their option.

All new contributions must be made under both the MIT and Apache-2.0 licenses.

See LICENSE-MIT, LICENSE-APACHE, COPYRIGHT, and NOTICE for details.

SPDX-License-Identifier: (Apache-2.0 OR MIT)

LLNL-CODE-811652