mirror of
https://github.com/fltk/fltk.git
synced 2026-02-05 15:59:50 +08:00
Add more documentation about ABI checking and a script to do it
misc/abi-check: This new script can be used (on Linux) to check ABI compatibility between patch releases. It does everything required in one execution (after installing the prerequisites once). Documentation is included in the script. It may be modified for other platforms, or ABI checking can be done manually. README.abi-version.txt: add a chapter regarding ABI checks misc/abi-compliance-checker.txt: update documentation on how to run misc/abi-check. In previous versions (1.4) building was done using configure/make. Thus this file was almost completely rewritten. documentation/src/migration_1_4.dox: an unrelated but tiny correction.
This commit is contained in:
Albrecht Schlosser
@@ -51,37 +51,48 @@ designated for the *next* FLTK release when using FLTK from Git with new
|
||||
ABI features included for the next release.
|
||||
|
||||
|
||||
How to select the ABI version with CMake
|
||||
How to Select the ABI Version with CMake
|
||||
----------------------------------------
|
||||
|
||||
Use CMake to build the Makefile's and run 'make' or use any other CMake
|
||||
generator of your choice. To select the ABI version use one of the CMake
|
||||
configuration tools (cmake-gui or ccmake), or run CMake with these or
|
||||
similar commands:
|
||||
Use CMake to build the Makefile's and run 'make' or use any other CMake
|
||||
generator of your choice. To select the ABI version use one of the CMake
|
||||
configuration tools (cmake-gui or ccmake), or run CMake with these or
|
||||
similar commands:
|
||||
|
||||
cd /path/to/fltk
|
||||
cmake . -B build [-G <GENERATOR>] -D FLTK_ABI_VERSION:STRING=10401
|
||||
cd /path/to/fltk
|
||||
cmake . -B build [-G <GENERATOR>] -D FLTK_ABI_VERSION:STRING=10401
|
||||
|
||||
The optional part '[-G <GENERATOR>]' can be used to select a particular
|
||||
build tool that is not the default for the build platform, for instance
|
||||
'-G Ninja'. Further CMake options can be appended.
|
||||
The optional part '[-G <GENERATOR>]' can be used to select a particular
|
||||
build tool that is not the default for the build platform, for instance
|
||||
'-G Ninja'. Further CMake options can be appended.
|
||||
|
||||
Then execute
|
||||
Then execute
|
||||
|
||||
cmake --build build
|
||||
cmake --build build
|
||||
|
||||
or the selected build tool (-G <GENERATOR>), e.g. `make`.
|
||||
or the selected build tool (-G <GENERATOR>), e.g. `make`.
|
||||
|
||||
For more information on how to use CMake with FLTK see README.CMake.txt.
|
||||
For more information on how to use CMake with FLTK see README.CMake.txt.
|
||||
|
||||
|
||||
General Note on CMake
|
||||
---------------------
|
||||
|
||||
CMake generates FL/fl_config.h in the build tree. You may run
|
||||
'make install' to install the FLTK library including all headers in
|
||||
the chosen installation directory (set CMAKE_INSTALL_PREFIX to do this),
|
||||
although this is not necessary.
|
||||
CMake generates FL/fl_config.h in the build tree. You may run
|
||||
'make install' to install the FLTK library including all headers in
|
||||
the chosen installation directory (set CMAKE_INSTALL_PREFIX to do this),
|
||||
although this is not necessary.
|
||||
|
||||
The FLTK team recommends to use the FLTK library directly from the
|
||||
build folder. See README.CMake.txt for more information.
|
||||
The FLTK team recommends to use the FLTK library directly from the
|
||||
build folder. See README.CMake.txt for more information.
|
||||
|
||||
|
||||
Checking FLTK Branches for ABI Breaking Issues
|
||||
----------------------------------------------
|
||||
|
||||
Please see 'misc/abi-compliance-checker.txt' for further information on
|
||||
how to check a branch, for instance 1.4.x, for ABI breaking changes.
|
||||
|
||||
Since FLTK 1.5 there is a convenient script for doing this with a single
|
||||
command in 'misc/abi-check'. This can be done easily during development
|
||||
to find and fix potential ABI breaking changes early.
|
||||
|
||||
@@ -339,10 +339,10 @@ some of the "old" names have been introduced in early 1.4.0 development.
|
||||
|
||||
Old Option Name (FLTK 1.3.x) | New Option Name (FLTK 1.4.x)
|
||||
-------------------------------------|------------------------------------
|
||||
none (built always) | FLTK_BUILD_FORMS
|
||||
FLTK_BUILD_EXAMPLES | FLTK_BUILD_EXAMPLES
|
||||
FLTK_BUILD_FLTK_OPTIONS | FLTK_BUILD_FLTK_OPTIONS
|
||||
FLTK_BUILD_FLUID | FLTK_BUILD_FLUID
|
||||
FLTK_BUILD_FORMS | FLTK_BUILD_FORMS
|
||||
FLTK_BUILD_TEST | FLTK_BUILD_TEST
|
||||
FLTK_MSVC_RUNTIME_DLL | FLTK_MSVC_RUNTIME_DLL
|
||||
OPTION_ABI_VERSION | FLTK_ABI_VERSION
|
||||
|
||||
258
misc/abi-check
Executable file
258
misc/abi-check
Executable file
@@ -0,0 +1,258 @@
|
||||
#!/bin/bash
|
||||
#
|
||||
# This script checks ABI compatibility of the current branch against
|
||||
# a prior release (git tag) of the same branch.
|
||||
#
|
||||
# We recommend to execute this script in an empty, temporary directory.
|
||||
# See below for details why this is useful.
|
||||
#
|
||||
# Requirements:
|
||||
#
|
||||
# CMake, a POSIX shell (bash), abi-checker, and perl (for abi checker).
|
||||
# This script has been tested only on Linux. After the check it *tries*
|
||||
# to open the compatibility report with the standard browser (xdg-open).
|
||||
#
|
||||
# Usage:
|
||||
#
|
||||
# $ /path-to/abi-check FLTK_DIR MINOR_VERSION P1 P2
|
||||
#
|
||||
# Parameters:
|
||||
#
|
||||
# FLTK_DIR Where the FLTK source files are (must be a git checkout).
|
||||
# This must be a "clean" working copy: this script checks
|
||||
# out the prior version (release tag) and the tip of the
|
||||
# branch (in this order). The last checkout is left in place.
|
||||
#
|
||||
# MINOR_VERSION FLTK major.minor version, e.g. 1.3, 1.4, or 1.5.
|
||||
#
|
||||
# P1 First FLTK patch version to compare (prior release)
|
||||
#
|
||||
# P2 Current version (tip) of the development branch. This
|
||||
# version must be given as well. If the version in git has
|
||||
# not yet been updated you can enter the "next" version.
|
||||
# This is typically the case if you check the current branch
|
||||
# for ABI issues *before* preparation of the next release.
|
||||
#
|
||||
# Examples:
|
||||
#
|
||||
# /path-to/abi-check /path-to/fltk-1.3 1.3 10 11
|
||||
# /path-to/abi-check /path-to/fltk-1.4 1.4 3 4
|
||||
#
|
||||
# The latter checks ABI compatibility of git tag "release-1.4.3" and the
|
||||
# HEAD of the selected development branch (see below) as version 1.4.4. This
|
||||
# can be done even if the version number in 'branch-1.4' is still 1.4.3.
|
||||
#
|
||||
# This is typically used to check ABI compatibility of a development branch
|
||||
# against the latest release of the same branch, but can also be used to test
|
||||
# any prior version of the branch against the current tip of the branch.
|
||||
#
|
||||
# The script uses `cmake --build` and `cmake --install` for simplicity, but
|
||||
# you can select any CMake generator you like, as long as the script can
|
||||
# be executed by a POSIX shell and `cmake --install` works for the given
|
||||
# generator (not tested for Xcode and Visual Studio).
|
||||
# "Installing" the build ensures that all header files including generated
|
||||
# ones are present where `abi-compliance-checker.pl` expects them to be.
|
||||
#
|
||||
# This script is known to work with FLTK versions since 1.3.6. Older versions
|
||||
# may not compile, build, or install correctly with current compilers.
|
||||
#
|
||||
# Warning: this script does NOT check runtime errors, e.g. when checking out
|
||||
# git versions, or when building and installing FLTK libs. Please check the
|
||||
# logs that are displayed and/or stored in `logs` for errors.
|
||||
#
|
||||
# Error checks may be added in a later version of this script.
|
||||
#
|
||||
# ------------------------------------------------------------------------------
|
||||
#
|
||||
# Some variables are "constants" in this script and need to be edited for
|
||||
# use in other build environments. The variables that need to be edited for
|
||||
# your build environment are documented below:
|
||||
#
|
||||
# ABI_PATH Directory of ABI checker ("abi-compliance-checker.pl"); can
|
||||
# be empty (default) if the ABI checker is in the user's PATH.
|
||||
# If the path is given it must have a trailing slash ('/').
|
||||
#
|
||||
# ABI_CHECKER Name of the ABI checker executable (script). The default
|
||||
# ("abi-compliance-checker.pl") should be correct.
|
||||
#
|
||||
# GENERATOR CMake generator, e.g. "Ninja", "Unix Makefiles" (see CMake docs).
|
||||
#
|
||||
# PARALLEL Number of parallel build jobs, recommended for "Unix Makefiles".
|
||||
# Use CMake syntax "--parallel=N" if needed.
|
||||
# Ninja uses the number of available cores if not specified.
|
||||
#
|
||||
# CMAKE_WARNINGS Should be empty; "-Wno-dev" suppresses "developer warnings".
|
||||
#
|
||||
# CXX_FLAGS Can be used to suppress compiler warnings (not recommended).
|
||||
#
|
||||
# CXX_STANDARD Default: "11" (C++11); can be set to "98" (C++98) for 1.3.
|
||||
#
|
||||
# This script creates several subdirectories in the current working directory
|
||||
# (referred as $PWD below). The files created by the script can be deleted
|
||||
# after the check.
|
||||
#
|
||||
# Both FLTK versions ($VER) will be built in $PWD/build/$VER and installed in
|
||||
# $PWD/bin/$VER, resp.. These folders are cleared before build/installation
|
||||
# but left as-is after the abi-check. They must be deleted manually.
|
||||
#
|
||||
# Example: Folders created for ABI check of FLTK 1.4.2 vs 1.4.3:
|
||||
#
|
||||
# . (current dir: $PWD)
|
||||
# ├── bin
|
||||
# │ ├── 1.4.2
|
||||
# │ └── 1.4.3
|
||||
# ├── build
|
||||
# │ ├── 1.4.2
|
||||
# │ └── 1.4.3
|
||||
# ├── compat_reports
|
||||
# │ └── fltk
|
||||
# ├── logs
|
||||
# │ └── fltk
|
||||
# └── xml
|
||||
# ├── fltk-1.4.2.xml
|
||||
# └── fltk-1.4.3.xml
|
||||
#
|
||||
# -----------------------------------------------------
|
||||
# Edit the following "constants" for your environment,
|
||||
# see above for documentation:
|
||||
# -----------------------------------------------------
|
||||
#
|
||||
ABI_PATH=""
|
||||
ABI_CHECKER="abi-compliance-checker.pl"
|
||||
GENERATOR="Ninja"
|
||||
PARALLEL=""
|
||||
CMAKE_WARNINGS=""
|
||||
CXX_FLAGS=""
|
||||
CXX_STANDARD="11"
|
||||
|
||||
# -----------------------------------------------------
|
||||
# End of constants, no need to edit anything below.
|
||||
# -----------------------------------------------------
|
||||
|
||||
# Define derived variables
|
||||
|
||||
ABI_CHECKER="$ABI_PATH$ABI_CHECKER"
|
||||
SOURCE_DIR="$1"
|
||||
BASE_DIR="$PWD"
|
||||
BASE_VERSION="$2"
|
||||
BUILD_DIR="$BASE_DIR/build"
|
||||
PREFIX="$BASE_DIR/bin"
|
||||
|
||||
# CMake options -- in parts depending on the development branch.
|
||||
#
|
||||
# This could be simplified if the script was written only for the current
|
||||
# FLTK version but for now (work in progress) it is written to be used for
|
||||
# other FLTK versions (branches) as well, just in case older branches need
|
||||
# a new release. It is intended that developers can use the latest script
|
||||
# from the 'master' branch in older branches (1.3.6 and higher) as well.
|
||||
#
|
||||
# Default values are set first for FLTK 1.5 (master).
|
||||
|
||||
BUILD_SHARED="-D FLTK_BUILD_SHARED_LIBS=ON"
|
||||
BUILD_CAIRO="-D FLTK_OPTION_CAIRO_WINDOW=ON"
|
||||
BUILD_FORMS="-D FLTK_BUILD_FORMS=ON"
|
||||
BUILD_FLUID="-D FLTK_BUILD_FLUID=OFF"
|
||||
BUILD_OPTIONS="-D FLTK_BUILD_FLTK_OPTIONS=OFF"
|
||||
|
||||
# Version dependent options are set or overriden here:
|
||||
|
||||
if test v$BASE_VERSION = v1.5; then
|
||||
BASE_BRANCH="master"
|
||||
elif test v$BASE_VERSION = v1.4; then
|
||||
BASE_BRANCH="branch-1.4"
|
||||
else # 1.3: some old option names, some options are not present
|
||||
BASE_BRANCH="branch-1.3"
|
||||
BUILD_SHARED="-D OPTION_BUILD_SHARED_LIBS=ON"
|
||||
BUILD_CAIRO="-D OPTION_CAIRO=ON"
|
||||
BUILD_FORMS=""
|
||||
BUILD_FLUID=""
|
||||
BUILD_OPTIONS=""
|
||||
fi
|
||||
|
||||
V1=$BASE_VERSION.$3
|
||||
V2=$BASE_VERSION.$4
|
||||
|
||||
# define a common function for both builds
|
||||
|
||||
build_and_install() {
|
||||
|
||||
REL="$1"
|
||||
VER="$2"
|
||||
XML="xml/fltk-$VER.xml"
|
||||
|
||||
# generate XML file for ABI checker
|
||||
|
||||
echo
|
||||
echo "-------- Creating XML file $XML for abi-checker --------"
|
||||
echo
|
||||
|
||||
cat > $XML << EOF
|
||||
<version>
|
||||
$VER
|
||||
</version>
|
||||
<headers>
|
||||
$PREFIX/$VER/include/FL/
|
||||
</headers>
|
||||
<skip_headers>
|
||||
win32.H
|
||||
mac.H
|
||||
</skip_headers>
|
||||
<libs>
|
||||
$PREFIX/$VER/lib/
|
||||
</libs>
|
||||
EOF
|
||||
|
||||
pushd $SOURCE_DIR
|
||||
|
||||
echo
|
||||
echo "-------- Checking out Git tag/branch $REL for $VER in $PWD --------"
|
||||
echo
|
||||
|
||||
git checkout $REL
|
||||
|
||||
echo
|
||||
echo "-------- Configuring FLTK $VER in $BUILD_DIR/$VER --------"
|
||||
echo
|
||||
|
||||
cmake $CMAKE_WARNINGS \
|
||||
-S . -B $BUILD_DIR/$VER \
|
||||
-G "$GENERATOR" \
|
||||
-D CMAKE_BUILD_TYPE=Debug \
|
||||
-D CMAKE_CXX_FLAGS_INIT="$CXX_FLAGS" \
|
||||
-D CMAKE_INSTALL_PREFIX=$PREFIX/$VER \
|
||||
-D FLTK_BUILD_EXAMPLES=OFF \
|
||||
-D FLTK_BUILD_TEST=OFF \
|
||||
-D CMAKE_CXX_STANDARD=$CXX_STANDARD \
|
||||
$BUILD_SHARED $BUILD_FLUID $BUILD_OPTIONS $BUILD_FORMS $BUILD_CAIRO
|
||||
|
||||
echo
|
||||
echo "-------- Building FLTK $VER in $BUILD_DIR/$VER --------"
|
||||
echo
|
||||
|
||||
cmake --build $BUILD_DIR/$VER $PARALLEL
|
||||
|
||||
echo
|
||||
echo "-------- Installing FLTK $VER in $PREFIX/$VER --------"
|
||||
echo
|
||||
|
||||
rm -rf $PREFIX/$VER
|
||||
cmake --install $BUILD_DIR/$VER
|
||||
|
||||
popd
|
||||
}
|
||||
|
||||
# create subdirectory 'xml' if it doesn't exist
|
||||
|
||||
[[ ! -d xml ]] && mkdir xml
|
||||
[[ ! -d compat_reports ]] && mkdir compat_reports
|
||||
|
||||
build_and_install release-$V1 $V1
|
||||
|
||||
build_and_install $BASE_BRANCH $V2
|
||||
|
||||
$ABI_CHECKER \
|
||||
-lib fltk \
|
||||
-old xml/fltk-${V1}.xml \
|
||||
-new xml/fltk-${V2}.xml
|
||||
|
||||
xdg-open compat_reports/fltk/${V1}_to_${V2}/compat_report.html
|
||||
@@ -1,120 +1,79 @@
|
||||
============================================================================
|
||||
How to use `abi-compliance-checker' to test FLTK ABI compatibility (Linux)
|
||||
How to use `abi-compliance-checker' to test FLTK ABI compatibility on Linux
|
||||
============================================================================
|
||||
|
||||
This howto uses directories in /git/ as example directories. Please
|
||||
adjust versions and directory names as appropriate on your system.
|
||||
This howto explains how to execute the script 'misc/abi-check' to check
|
||||
two FLTK releases of the same branch for ABI incompatibilities on Linux.
|
||||
Other platforms may work as well, but then you will likely need to change
|
||||
the script documented below or do the required steps manually.
|
||||
|
||||
In this howto we compare FLTK 1.3.4-1 (last 1.3.x release as of Jan 02, 2019)
|
||||
with the current version (1.3.5) before it will be released.
|
||||
The important point is that you build two different FLTK versions with
|
||||
identical build options and *with* shared libraries.
|
||||
|
||||
For documentation on its usage please refer to:
|
||||
For documentation on abi-compliance-checker please refer to:
|
||||
|
||||
https://lvc.github.io/abi-compliance-checker/
|
||||
|
||||
You need `perl` and everything required to build FLTK installed on your
|
||||
system before you continue.
|
||||
|
||||
|
||||
(1) Download 'abi-compliance-checker' from GitHub:
|
||||
|
||||
$ cd /git
|
||||
$ cd /path/to/dev
|
||||
$ git clone https://github.com/lvc/abi-compliance-checker.git
|
||||
|
||||
Download directory: /git/abi-compliance-checker/
|
||||
Record the path '/path/to/dev/abi-compliance-checker' for later. You
|
||||
may add it to your PATH, or you may "install" abi-compliance-checker
|
||||
on your system. The latter is untested and not covered by this document.
|
||||
|
||||
|
||||
(2) Use two different Git checkout (working) directories to build libs,
|
||||
for instance (as used in this example):
|
||||
(2) There are chances that you can use the script 'misc/abi-check' directly
|
||||
from the FLTK checkout (branch `master`). There are some variables in
|
||||
the script that may need to be edited though. Please check the docs in
|
||||
the script for these variables, particularly some paths and the CMake
|
||||
generator you use to build (default and recommended is "Ninja").
|
||||
|
||||
(new) /git/fltk-1.3 current version = 1.3.5
|
||||
(old) /git/fltk-1.3.4-1 previous version = 1.3.4-1 [1]
|
||||
If this doesn't work for you, please copy the script 'misc/abi-check'
|
||||
(new since FLTK 1.5) to a place of your choice (maybe in your PATH),
|
||||
and edit the variables for your build environment, as documented in
|
||||
the script. It is not recommended to edit it in place to avoid checking
|
||||
it into the repository or causing conflicts when pulling changes.
|
||||
|
||||
[1] The second working directory can be created from the first
|
||||
git working tree ( /git/fltk-1.3 ) with these commands:
|
||||
|
||||
$ cd /git/fltk-1.3
|
||||
$ git worktree add /git/fltk-1.3.4-1 release-1.3.4-1
|
||||
|
||||
This creates the worktree in /git/fltk-1.3.4-1 and checks the
|
||||
tag 'release-1.3.4-1' out.
|
||||
You need to do this only once and can keep the edited version, but
|
||||
please check for updates in git (branch 'master') and update your file
|
||||
if there are relevant changes.
|
||||
|
||||
|
||||
(3) Create two xml descriptions to test library compatibility in
|
||||
an arbitrary working directory (here: /git/workdir):
|
||||
(3) Change your directory (cd) to an empty working directory (recommended)
|
||||
and execute the (maybe copied and edited) script 'abi-check' as
|
||||
documented at the top of that script.
|
||||
|
||||
--- fltk-1.3.4-1.xml ---
|
||||
<version>
|
||||
1.3.4-1
|
||||
</version>
|
||||
Example:
|
||||
|
||||
<headers>
|
||||
/git/fltk-1.3.4-1/FL/
|
||||
</headers>
|
||||
$ /path/to/abi-check /path/to/fltk-1.4 1.4 2 3
|
||||
|
||||
<skip_headers>
|
||||
win32.H
|
||||
mac.H
|
||||
</skip_headers>
|
||||
This would compare the binary versions of git tag 'release-1.4.2'
|
||||
with the tip of 'branch-1.4', assuming version number 1.4.3.
|
||||
|
||||
<libs>
|
||||
/git/fltk-1.3.4-1/src/
|
||||
/git/fltk-1.3.4-1/cairo/
|
||||
</libs>
|
||||
--- end of file ---
|
||||
The latter is required and is used to distinguish the different
|
||||
build folders and for the ABI compatibility report.
|
||||
|
||||
--- fltk-1.3.5.xml ---
|
||||
<version>
|
||||
1.3.5
|
||||
</version>
|
||||
Note: the working copy checked out at '/path/to/fltk-1.4' must be
|
||||
"clean", i.e. there must not be changed files. The script checks
|
||||
out the two requested versions and builds and installs them under
|
||||
the current working directory. The FLTK working copy is left with
|
||||
the tip of the branch (in this example `branch-1.4`) checked out.
|
||||
For FLTK 1.5 this would be `master`.
|
||||
|
||||
<headers>
|
||||
/git/fltk-1.3/FL/
|
||||
</headers>
|
||||
If all goes well you'll see CMake configuration and build and install
|
||||
logs and the log of the ABI checker tool, ending with something like:
|
||||
|
||||
<skip_headers>
|
||||
win32.H
|
||||
mac.H
|
||||
</skip_headers>
|
||||
|
||||
<libs>
|
||||
/git/fltk-1.3/src/
|
||||
/git/fltk-1.3/cairo/
|
||||
</libs>
|
||||
--- end of file ---
|
||||
|
||||
|
||||
(4) Configure and build both libraries with the same options.
|
||||
You *must* include '--enable-cairo' to build and compare the
|
||||
Cairo libs and '--enable-shared' to build the shared libs:
|
||||
|
||||
$ make clean
|
||||
$ ./configure --enable-cairo --enable-shared --enable-debug
|
||||
$ make
|
||||
|
||||
Note: you must *not* use '--with-abiversion' because we need to
|
||||
build the default ABI version.
|
||||
|
||||
|
||||
(5) Run `abi-compliance-checker.pl':
|
||||
|
||||
$ cd /git/workdir
|
||||
$ /git/abi-compliance-checker/abi-compliance-checker.pl \
|
||||
-lib fltk -old fltk-1.3.4-1.xml -new fltk-1.3.5.xml
|
||||
Preparing, please wait ...
|
||||
Using GCC 7 (x86_64-linux-gnu, target: x86_64)
|
||||
WARNING: May not work properly with GCC 4.8.[0-2], 6.* and higher
|
||||
due to bug #78040 in GCC. Please try other GCC versions with the
|
||||
help of --gcc-path=PATH option or create ABI dumps by ABI Dumper
|
||||
tool instead to avoid using GCC. Test selected GCC version first
|
||||
by -test option.
|
||||
------------------------------------------------------------------
|
||||
--> ignore warning (but run `abi-compliance-checker.pl -test')
|
||||
------------------------------------------------------------------
|
||||
Checking header(s) 1.3.4-1 ...
|
||||
...
|
||||
Checking header(s) 1.4.2 ...
|
||||
WARNING: can't find 'ctags' program
|
||||
Checking header(s) 1.3.5 ...
|
||||
Checking header(s) 1.4.3 ...
|
||||
WARNING: can't find 'ctags' program
|
||||
------------------------------------------------------------------
|
||||
--> ignore warning (or install 'ctags' and repeat)
|
||||
------------------------------------------------------------------
|
||||
Comparing ABIs ...
|
||||
Comparing APIs ...
|
||||
Creating compatibility report ...
|
||||
@@ -122,26 +81,39 @@ For documentation on its usage please refer to:
|
||||
Source compatibility: 100%
|
||||
Total binary compatibility problems: 0, warnings: 0
|
||||
Total source compatibility problems: 0, warnings: 1
|
||||
Report: compat_reports/fltk/1.3.4-1_to_1.3.5/compat_report.html
|
||||
Report: compat_reports/fltk/1.4.2_to_1.4.3/compat_report.html
|
||||
|
||||
You can safely ignore the "ctags" warnings if you don't have `ctags`
|
||||
installed.
|
||||
|
||||
The script will try to open the above mentioned report automatically
|
||||
with the default browser (by using `xdg-open`) which may or may not
|
||||
work on your system. If it doesn't, please open the report manually
|
||||
with your browser.
|
||||
|
||||
In the example above the only warning ("warnings: 1") is obviously
|
||||
caused by the changed FLTK patch version (1.4.2 -> 1.4.3) and can
|
||||
be ignored.
|
||||
|
||||
If there are errors and other warnings, then the report should be
|
||||
checked thoroughly. Maybe there are ABI breaking changes that
|
||||
must be fixed by putting the according code under ABI guards as
|
||||
documented in 'README.abi-version.txt', or there may be one or more
|
||||
commits that must be reverted to prevent ABI breaking changes.
|
||||
|
||||
|
||||
(6) Check the generated report (last line above) with a browser:
|
||||
|
||||
$ firefox compat_reports/fltk/1.3.4-1_to_1.3.5/compat_report.html
|
||||
(4) You may want to remove the entire working directory for this ABI check
|
||||
when you're done with the checks.
|
||||
|
||||
|
||||
(7) You may want to remove the additional worktree created above with:
|
||||
Using this script from time to time is very convenient and can help to
|
||||
find ABI issues early, i.e. before the branch is ready to be prepared
|
||||
for the next release.
|
||||
|
||||
$ cd /git/fltk-1.3
|
||||
$ git worktree remove --force /git/fltk-1.3.4-1
|
||||
All FLTK devs and users are encouraged to do this and to report issues
|
||||
as soon as possible.
|
||||
|
||||
|
||||
(8) Done.
|
||||
|
||||
|
||||
Note 1: The report as given above issued 100% ABI compatibility. The only
|
||||
warning was the different patch version number.
|
||||
|
||||
Note 2: There are other recommended methods to use abi-compliance-checker
|
||||
together with abi-dumper, but this is not (yet) covered here (see
|
||||
abi-compliance-checker documentation).
|
||||
Note: There are other recommended methods to use abi-compliance-checker
|
||||
together with `abi-dumper` but this is not covered by this document
|
||||
(see abi-compliance-checker documentation: link above).
|
||||
|
||||
Reference in New Issue
Block a user