INSTALL

Copyright (C) 2009-2011 Institute for System Programming, RAS
Copyright (C) 2011-2012 Nokia Corporation and/or its subsidiary(-ies)
Copyright (C) 2012-2018 Andrey Ponomarenko's ABI Laboratory
All rights reserved.


RELEASE INFORMATION

Project:           ABI Compliance Checker (ABICC)
Version:           2.3
Date:              May 15, 2018


This file explains how to install and setup environment
for the tool in your computer.


Content:

   1. Requirements for Linux and FreeBSD
   2. Requirements for Mac OS X
   3. Requirements for MS Windows
   4. Configure and Install
   5. Usage (with ABI Dumper)
   6. Usage (Original)


1. REQUIREMENTS FOR LINUX AND FREEBSD
=====================================

   1. G++ (3.0 or newer)
   2. GNU Binutils (c++filt, readelf, objdump)
   3. Perl 5
   4. Ctags
   5. ABI Dumper (1.1 or newer)



2. REQUIREMENTS FOR MAC OS X
============================

   1. Xcode (g++, c++filt, otool, nm)
   2. Perl 5
   3. Ctags

2.1 Setup environment

   1. If /usr/bin/g++ points to clang, then please
      specify GCC path by the -gcc-path option
   
   2. You can install GCC by the command:
        
        brew install homebrew/versions/gcc49
      
      And then specify its path:
      
        abi-compliance-checker --gcc-path=/usr/local/bin/gcc-4.9 ...



3. REQUIREMENTS FOR MS WINDOWS
==============================

   1. MinGW (3.0 or newer)
   2. MS Visual C++ (dumpbin, undname, cl)
   3. Active Perl 5 (5.8 or newer)
   4. Sigcheck v1.71 or newer
   5. Info-ZIP 3.0 (zip, unzip)
   6. Ctags

3.1 Setup environment

   1. Add tool locations to the PATH environment variable
   2. Run vcvars64.bat script (C:\Microsoft Visual Studio 9.0\VC\bin\)



4. CONFIGURE AND INSTALL
========================

   This command will install the abi-compliance-checker program into the
   PREFIX/bin system directory and private modules into the PREFIX/share:

     sudo make install prefix=PREFIX [/usr, /usr/local, ...]

4.1 Remove

     sudo make uninstall prefix=PREFIX



5. USAGE (WITH ABI DUMPER)
==========================

   Library should be compiled with -g -Og
   options to contain DWARF debug info.

   Create ABI dumps for both library versions
   using the ABI Dumper tool (https://github.com/lvc/abi-dumper):

     abi-dumper OLD.so -o ABI-0.dump -lver 0
     abi-dumper NEW.so -o ABI-1.dump -lver 1

   You can filter public ABI symbols with the help of
   additional -public-headers option of the ABI Dumper tool.
      
   Compare ABI dumps to create report:

     abi-compliance-checker -l NAME -old ABI-0.dump -new ABI-1.dump



6. USAGE (ORIGINAL)
===================

   Create XML-descriptors for two versions
   of a library (OLD.xml and NEW.xml):

        <version>
            1.0
        </version>

        <headers>
            /path1/to/header(s)/
            /path2/to/header(s)/
                ...
        </headers>

        <libs>
            /path1/to/library(ies)/
            /path2/to/library(ies)/
                ...
        </libs>

   Check compatibility:
   
     abi-compliance-checker -lib NAME -old OLD.xml -new NEW.xml
   
   For advanced usage, see doc/index.html or -help option.


Enjoy!