Abi checker


 * 1) Checking for API/ABI breakage

1. Install last version of API/ABI checker (beware of old versions shipped in old ubuntu distros):

sudo apt-get install exuberant-ctags

git clone git://github.com/lvc/abi-compliance-checker.git

2. Download, compile and install into /tmp the latest released version of your package:

export SOFTWARE=gazebo-2.0.0

wget http://gazebosim.org/assets/distributions/$SOFTWARE.tar.bz2

mkdir -p /tmp/$SOFTWARE/source && tar xvf $SOFTWARE.tar.bz2 -C /tmp/$SOFTWARE/source --strip-components=1

cd /tmp/$SOFTWARE/source && mkdir build && cd build && \ cmake -DCMAKE_INSTALL_PREFIX=/tmp/$SOFTWARE/install -DENABLE_TESTS_COMPILATION:BOOL=False .. && \     make -j8 install

3. Download compile and install into /tmp the current version of code:

export SOFTWARE=gazebo

mkdir -p /tmp/$SOFTWARE && hg clone https://bitbucket.org/osrf/$SOFTWARE /tmp/$SOFTWARE/source

cd /tmp/$SOFTWARE/source && mkdir build && cd build && \ cmake -DCMAKE_INSTALL_PREFIX=/tmp/$SOFTWARE/install -DENABLE_TESTS_COMPILATION:BOOL=False .. && \     make -j8 install

4. Prepare the config files to run the checker:

TODO: we need to migrate this config probably to source code repo and make a script to automatically generates it for you.

Create a current.xml and a released.xml. Below are examples:

current.xml current /tmp/gazebo/install/include/gazebo-2.0/gazebo  /tmp/gazebo/install/include/gazebo-2.0/gazebo/GIMPACT /tmp/gazebo/install/include/gazebo-2.0/gazebo/opcode /tmp/gazebo/install/include/gazebo-2.0/gazebo/test  /tmp/gazebo/install/lib/

released.xml released /tmp/gazebo-2.0.0/install/include/gazebo-2.0/gazebo  /tmp/gazebo-2.0.0/install/include/gazebo-2.0/gazebo/GIMPACT /tmp/gazebo-2.0.0/install/include/gazebo-2.0/gazebo/opcode /tmp/gazebo-2.0.0/install/include/gazebo-2.0/gazebo/test  /tmp/gazebo-2.0.0/install/lib/

5. Run the checker:

Before run the checker, please be aware that it will be slow on big projects, like gazebo.

abi-compliance-checker -l lib$SOFTWARE -old released.xml -new current.xml

6. Upload for pull-request reviews

Upload the report result to gazebosim.org, and link to the html page in your pull-request. Put all reports at this location so that they are centralized in one spot. Below is an example:

scp compat_reports/gazebo/default_to_new/compat_report.html ubuntu@gazebosim.org:/var/www/compat_reports/pr_734.html

7. Troubleshooting

7.1 Errors displayed on gazebo headers

While running the checker for gazebo it will complain about some problems found with headers. It's something related to boost libraries and does not seem to affect to the rest of the check. Do not stop the check.

7.2 --old or --new parameter in the checker are not valid

You are probably using an old version of the checker, probably shipped with your ubuntu distribution. Use the latest one from repo.