diff options
| -rw-r--r-- | README.abi-version.txt | 51 | ||||
| -rw-r--r-- | documentation/src/migration_1_4.dox | 2 | ||||
| -rwxr-xr-x | misc/abi-check | 258 | ||||
| -rw-r--r-- | misc/abi-compliance-checker.txt | 174 |
4 files changed, 363 insertions, 122 deletions
diff --git a/README.abi-version.txt b/README.abi-version.txt index 10729a959..2128da7c9 100644 --- a/README.abi-version.txt +++ b/README.abi-version.txt @@ -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. diff --git a/documentation/src/migration_1_4.dox b/documentation/src/migration_1_4.dox index 0a92072c0..f59827f17 100644 --- a/documentation/src/migration_1_4.dox +++ b/documentation/src/migration_1_4.dox @@ -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 diff --git a/misc/abi-check b/misc/abi-check new file mode 100755 index 000000000..99f096d31 --- /dev/null +++ b/misc/abi-check @@ -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 diff --git a/misc/abi-compliance-checker.txt b/misc/abi-compliance-checker.txt index 9f6889e6d..74c42fed5 100644 --- a/misc/abi-compliance-checker.txt +++ b/misc/abi-compliance-checker.txt @@ -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/ - - -(2) Use two different Git checkout (working) directories to build libs, - for instance (as used in this example): - - (new) /git/fltk-1.3 current version = 1.3.5 - (old) /git/fltk-1.3.4-1 previous version = 1.3.4-1 [1] - - [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. - - -(3) Create two xml descriptions to test library compatibility in - an arbitrary working directory (here: /git/workdir): - ---- fltk-1.3.4-1.xml --- -<version> - 1.3.4-1 -</version> - -<headers> - /git/fltk-1.3.4-1/FL/ -</headers> + 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. -<skip_headers> - win32.H - mac.H -</skip_headers> -<libs> - /git/fltk-1.3.4-1/src/ - /git/fltk-1.3.4-1/cairo/ -</libs> ---- end of file --- +(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"). ---- fltk-1.3.5.xml --- -<version> - 1.3.5 -</version> + 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. -<headers> - /git/fltk-1.3/FL/ -</headers> + 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. -<skip_headers> - win32.H - mac.H -</skip_headers> -<libs> - /git/fltk-1.3/src/ - /git/fltk-1.3/cairo/ -</libs> ---- end of file --- +(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. + Example: -(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: + $ /path/to/abi-check /path/to/fltk-1.4 1.4 2 3 - $ make clean - $ ./configure --enable-cairo --enable-shared --enable-debug - $ make + 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. - Note: you must *not* use '--with-abiversion' because we need to - build the default ABI version. + The latter is required and is used to distinguish the different + build folders and for the ABI compatibility report. + 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`. -(5) Run `abi-compliance-checker.pl': + 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: - $ 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. -(6) Check the generated report (last line above) with a browser: + 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. - $ firefox compat_reports/fltk/1.3.4-1_to_1.3.5/compat_report.html + 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. -(7) You may want to remove the additional worktree created above with: - $ cd /git/fltk-1.3 - $ git worktree remove --force /git/fltk-1.3.4-1 +(4) You may want to remove the entire working directory for this ABI check + when you're done with the checks. -(8) Done. +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. +All FLTK devs and users are encouraged to do this and to report issues +as soon as possible. -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). |