- Generated by
1.9.8
|
FLTK 1.4.0
|
This chapter details the procedure to update the libraries which are bundled inside FLTK.
This file is mainly intended for FLTK developers and contains information about the current versions of all bundled libraries and about how to upgrade these bundled libraries.
Starting with FLTK 1.4.0 the bundled libraries jpeg, png, and zlib use "symbol prefixing" with the prefix 'fltk_' for all external symbols to distinguish the bundled libraries from existing system libraries and to avoid runtime errors.
User code compiled correctly with the header files provided by the bundled image libraries need not be changed.
The nanosvg library is not affected.
FLTK does not include the entire library distributions. We only provide the source files necessary to build the FLTK library and some README and/or CHANGELOG files. There are no test programs or other contributed files.
We use our own build files, hence a few files MUST NOT be upgraded when the library source files are upgraded. We strive to keep changes to the library source files as small as possible. Patching library code to work with FLTK should be a rare exception. Symbol prefixing with prefix 'fltk_' is one such exception to the rule.
If patches are necessary all changes in the library files should be marked with "FLTK" in a comment so a developer who upgrades the library later is aware of changes in the source code for FLTK. Look for 'FLTK' and/or 'fltk_' to find the differences.
Additional comments should be added to show the rationale, i.e. why a particular change was necessary. If applicable, add a reference to a Software Trouble Report, GitHub Issue or Pull Request (PR) like "STR 3456", "Issue #123", or "PR #234".
It is generally advisable to use a graphical merge program. I'm using 'meld' under Linux, but YMMV.
Do not add any source files unless they are required to build the library.
Some config header files may be pre-generated in the FLTK sources. These header files should be left untouched, but it may be necessary to update these files if new items were added to the new library version. In this case the new header should be pre-generated on a Linux system with default options unless otherwise mentioned below for a specific library. Currently there are no known exceptions.
Please check if some source and header files contain "FLTK" comments and/or 'fltk_' symbol prefixing to be aware of necessary merges. It is also good to download the distribution tar ball or Git source files of the previous version and to run a (graphical) diff or merge tool on the previous version and the bundled version of FLTK to see the "previous" differences.
Files that were not patched in previous versions should be copied to the new version w/o changes. Files that had FLTK specific patches must be merged manually. FLTK patches should be verified (if still necessary) and should be kept in the new source files.
Source and header files that have been added in the new library version should be added in FLTK as well if they are necessary to build the library. A simple "trial and error" should be sufficient to find files that need to be added. Added files must be added to FLTK's build files as well, usually to both ‘Makefile’ and ‘CMakeLists.txt’ to be used in configure/make and in CMake based builds, respectively.
There is only one dependency between all bundled libraries: libpng depends on zlib. Hence zlib should be upgraded first, then all other libs can be upgraded in arbitrary order.
Tests should be done on as many platforms as possible, both with autotools (configure/make) and CMake. Windows (Visual Studio) and macOS (Xcode) builds need CMake to generate the IDE files.
The following chapters contain informations about specific files and how they are upgraded. Since the changes in all bundled libraries are not known in advance this information may change in the future. Please verify that no other changes are necessary.
Website: https://zlib.net/
Download: See website and follow links.
Repository: git clone https://github.com/madler/zlib.git
zlib should be upgraded first because libpng depends on zlib.
Download the latest zlib sources, ‘cd’ to /path-to/zlib and run
This creates the header file 'zconf.h' with definitions to enable the standard 'z_' symbol prefix.
Unfortunately zlib requires patching some source and header files to convert this 'z_' prefix to 'fltk_z_' to be more specific. As of this writing (Nov. 2021) three files need symbol prefix patches:
You may want to compare these files and/or the previous version to find out which changes are required. The general rule is to change all occurrences of 'z_' to 'fltk_z_' but there are exceptions.
The following files need special handling:
Run ‘make depend’ in the zlib folder on a Linux system after the upgrade to update this file.
Website: http://libpng.org/pub/png/libpng.html
Download: See website and follow links.
Repository: git clone https://git.code.sf.net/p/libpng/code libpng
libpng should be upgraded after zlib because it depends on zlib.
Download the latest libpng sources, ‘cd’ to /path-to/libpng and run
This creates the header files 'pnglibconf.h' and 'pngprefix.h' with the 'fltk_' symbol prefix.
The following files need special handling:
Run ‘make depend’ in the png folder on a Linux system after the upgrade to update this file.
Website: https://ijg.org/
Download: See website and follow links.
Repository: N/A
Download the latest jpeg-xy sources on a Linux (or Unix) system, ‘cd’ to /path-to/jpeg-xy and run
This builds the library and should create the static library file '.libs/libjpeg.a'.
Execute the following command to extract the libjpeg symbol names used to build the 'prefixed' libfltk_jpeg library:
This creates the header file 'fltk_jpeg_prefix.h' with the '# define' statements using the 'fltk_' symbol prefix.
The following files need special handling:
/* FLTK */Note: more to come...
Run ‘make depend’ in the jpeg folder on a Linux system after the upgrade to update this file.
Website: https://github.com/memononen/nanosvg
Download: See website and follow links.
Repository: git clone https://github.com/memononen/nanosvg.git
FLTK Fork: git clone https://github.com/fltk/nanosvg.git
FLTK has its own GitHub fork of the original repository (see above).
The intention is to update this fork from time to time so the FLTK specific patches are up-to-date with the original library. Hopefully the FLTK patches will be accepted upstream at some time in the future so we no longer need our own patches. AlbrechtS, 04 Feb 2018.
Update (Feb 22, 2021): The upstream library is officially no longer maintained (see README.md) although updates appear from time to time.
Use this fork (branch 'fltk') to get the nanosvg library with FLTK specific patches:
This library does not have its own build files since it is a header-only library. The headers are included in FLTK where necessary.
The following files need special handling:
nanosvg.h: Merge or download from FLTK's fork (see above).
nanosvgrast.h: Merge or download from FLTK's fork (see above).
Maintaining branch 'fltk' in FLTK's fork of nanosvg (fltk/nanosvg):
Only maintainers with write access on fltk/nanosvg can do this. Others can fork our fltk/nanosvg fork in their own GitHub account and either open a PR on fltk/nanosvg or tell us about their changes in fltk.development.
Use something similar to the following commands to update FLTK's fork of nanosvg to the latest version. Commands are only examples, you may need to change more or less, depending on the outstanding updates.
Step 1: clone the fltk/nanosvg fork, set the remote 'upstream', and update the 'master' branch:
Note: the 'master' branch must never be changed, i.e. it must always be the same as 'upstream/master'. Never commit your own (FLTK specific) changes to branch 'master'.
Step 2: rebase branch 'fltk' on the new master (upstream/master), fix potential conflicts, and tag the new branch.
It is important to keep the individual FLTK specific patches intact (one commit per patch) because this will preserve the history and the committer and make it easier to skip single patches when they are accepted upstream.
At this point you may need to fix conflicts! Do whatever is necessary to update the branch 'fltk'.
Now ‘git tag’ the 'fltk' branch for later reference.
Hint: use ‘git show <any-older-tag-name>’ to see its contents. I like to write a summary of commits in the tag comment.
Replace 'yyyy-mm-dd' with the current date and add a comment when asked for it (your editor will open an empty file).
Step 3: at this point it is recommended to copy the changed header files to your working copy of the FLTK library and test the changes. If anything is wrong, go back, fix the bugs and change the git tag (delete and create a new one).
Step 4: push the new branch 'fltk' and the tag to the fltk/nanosvg repository:
Step 5: copy the changed files to your working copy of the FLTK repository (if not done already), update this file accordingly, and commit/push the update to the fltk/fltk repository.
Website: https://gitlab.freedesktop.org/libdecor/libdecor
Download: See website and follow links.
Repository: git clone https://gitlab.freedesktop.org/libdecor/libdecor.git
libdecor is used by the Wayland/X11 hybrid platform to draw window titlebars when FLTK apps run as Wayland clients and the running Wayland compositor uses client-side decoration. In the future, when libdecor will have made its way into Linux packages, FLTK will use the system version of libdecor. libdecor will remain as an FLTK bundle to support Linux configurations where the libdecor package is not available or not installed.
FLTK uses libdecor source files without any modification. This part of the libdecor source tree is copied to directory libdecor/ of the FLTK source tree:
LICENSE
README.md
src/ ... and files below except meson.build files
Furthermore, directory libdecor/build/ of the FLTK source tree does not originate from the libdecor source tree but contains 3 FLTK-created files. File build/Makefile may need changes if a libdecor update adds or renames source files.
1.9.8