Copyright (C) 2009-2010 The Linux Foundation
Copyright (C) 2009-2011 Institute for System Programming, RAS
Copyright (C) 2011-2012 Nokia Corporation and/or its subsidiary(-ies)
Copyright (C) 2011-2014 ROSA Laboratory
All rights reserved.


RELEASE INFORMATION

Project:           ABI Compliance Checker (ACC)
Version:           1.99.9
Date:              2014-03-06


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. Configuring and Installing
   5. Running the Tool
   6. Usage with ABI Dumper


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

   1. G++ (3.0-4.7, 4.8.3, recommended 4.5 or newer)
   2. GNU Binutils (c++filt, readelf, objdump)
   3. Perl 5 (5.8 or newer)
   4. Ctags (5.8 or newer)



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

   1. Xcode (g++, c++filt, otool, nm)
   2. Ctags (5.8 or newer)



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

   1. MinGW (3.0-4.7, recommended 4.5 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 (5.8 or newer)

3.1 Setup environment

   1. Add tool locations to the PATH environment variable
   2. Run vsvars32.bat script (C:\Microsoft Visual Studio 9.0\Common7\Tools\)



4. CONFIGURING AND INSTALLING
=============================

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

     sudo perl Makefile.pl -install --prefix=PREFIX [/usr, /usr/local, ...]

4.1 Update

     sudo perl Makefile.pl -update --prefix=PREFIX

4.2 Remove

     sudo perl Makefile.pl -remove --prefix=PREFIX



5. RUNNING THE TOOL
===================

   1. 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>

   2. abi-compliance-checker -lib NAME -old OLD.xml -new NEW.xml
   3. For advanced usage, see doc/Readme.html or --help option



6. USAGE WITH ABI DUMPER
========================

   1. Library should be compiled with -g
      option to contain DWARF debug info
      
   2. 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
        
   3. Compare ABI dumps:
   
        abi-compliance-checker -l NAME -old ABI-0.dump -new ABI-1.dump


Enjoy!