lvc / abi-tracker

A tool to visualize ABI changes timeline of a C/C++ software library

ABI Tracker 1.11

ABI Tracker — visualize ABI changes timeline of a C/C++ software library.

Contents

1. About
2. Install
3. Usage
4. Profile

About

The tool requires input profile of the library in JSON format. It can be created manually or automatically generated by the ABI Monitor: https://github.com/lvc/abi-monitor

Sample report: https://abi-laboratory.pro/tracker/timeline/glib/

The tool is developed by Andrey Ponomarenko. Please consider to add ABI Viewer reports for visualization of the ABI structure and high detailed binary compatibility analysis: https://abi-laboratory.pro/index.php?view=abi-view

Install

sudo make install prefix=/usr

Requires

• Perl 5 (5.8 or newer)
• Elfutils
• ABI Dumper (1.1 or newer)
• Vtable-Dumper (1.1 or newer)
• ABI Compliance Checker (2.2 or newer)
• ABI Monitor (1.12 or newer)
• PkgDiff (1.6.4 or newer)
• RfcDiff (1.41 or newer)

You can use the installer (https://github.com/lvc/installer) to automatically download and install most of the required tools.

Usage

abi-tracker [options] [profile]

The input profile can be generated by the ABI Monitor tool. All manual edits in the profile will be preserved after re-generating it by the ABI Monitor.

The home page of the output report is: timeline/LIB_NAME/index.html

Examples

abi-tracker -build libssh.json
abi-tracker -rebuild -target abireport -v 0.7.0 libssh.json

Graph

abi-tracker -build -t graph libssh.json

RSS

abi-tracker -build -rss libssh.json

Cron job

abi-monitor -get -build-new [profile]
abi-tracker -build [profile]

Adv. usage

For advanced usage, see output of -help option.

Profile

{
    "Name":        "SHORT LIBRARY NAME",
    "Maintainer":  "MAINTAINER NAME",
    "SourceUrl":   "URL TO DOWNLOAD PACKAGES",
    "Git":         "GIT ADDRESS TO CLONE",
    
    "Versions": [
    {
        "Number":      "VERSION NUMBER",
        "Installed":   "INSTALL TREE PATH",
        "Source":      "SOURCE PACKAGE PATH",
        "Changelog":   "CHANGELOG: On/Off",
        "HeadersDiff": "HEADERS DIFF: On/Off",
        "PkgDiff":     "PACKAGE DIFF: On/Off",
        "ABIView":     "ABI VIEW: On/Off",
        "ABIDiff":     "ABI DIFF: On/Off"
    },
    
    ...
    
    {
        ...
    }]
}

Profile example

{
    "Name":        "libssh",
    "Maintainer":  "Andrey P.",
    "SourceUrl":   "https://red.libssh.org/projects/libssh/files",
    "Git":         "https://git.libssh.org/projects/libssh.git",
    
    "Versions": [
    {
        "Number":      "0.7.0",
        "Installed":   "installed/libssh/0.7.0",
        "Source":      "src/libssh/0.7.0/libssh-0.7.0.tar.xz",
        "Changelog":   "On",
        "HeadersDiff": "On",
        "PkgDiff":     "On",
        "ABIView":     "Off",
        "ABIDiff":     "Off"
    },
    
    {
        "Number":      "0.6.5",
        "Installed":   "installed/libssh/0.6.5",
        "Source":      "src/libssh/0.6.5/libssh-0.6.5.tar.xz",
        "Changelog":   "On",
        "HeadersDiff": "On",
        "PkgDiff":     "On",
        "ABIView":     "Off",
        "ABIDiff":     "Off"
    },
    
    ...
    
    {
        "Number":      "0.5.2",
        "Installed":   "installed/libssh/0.5.2",
        "Source":      "src/libssh/0.5.2/libssh-0.5.2.tar.xz",
        "Changelog":   "On",
        "HeadersDiff": "On",
        "PkgDiff":     "On",
        "ABIView":     "Off",
        "ABIDiff":     "Off"
    }]
}

See more profile examples in this repository: https://github.com/lvc/upstream-tracker/tree/master/profile

Adv. options

If you want to allow users to connect the maintainer of the tracker then you can set "MaintainerUrl" option.

To skip checking of some objects in the install tree of a library please define "SkipObjects": ["O1", ..., "On"] option.

The name of the analysed library in the title can be changed by "Title" option.

Adv. options (in "Versions")

To hide some version in the report you can define "Deleted" option.

Enjoy!