Create new documentation chapter for FLTK developers

Add Doxygen-formatted description of the Wayland backend
Add bundled-libs.dox
Delete README.bundled-libs.txt
Move "Development" page to "Development of FLTK" chapter

1 files changed, 370 insertions, 0 deletions

diff --git a/documentation/src/bundled-libs.dox b/documentation/src/bundled-libs.dox
new file mode 100644
index 000000000..82139ab16
--- /dev/null
+++ b/documentation/src/bundled-libs.dox
@@ -0,0 +1,370 @@
+/**
+
+\page bundled-libs Developer info for bundled libs
+
+This chapter details the procedure to update the libraries which are bundled inside FLTK.
+
+
+\section bundled-intro Introduction
+
+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.
+
+\section bundled-status Current status
+\code
+Current versions of bundled libraries (as of Jan 16, 2023):
+  Library       Version/git commit Release date         FLTK Version
+  --------------------------------------------------------------------------
+  jpeg          jpeg-9e            2022-01-16           1.4.0
+  nanosvg       abcd277ea4 [1]     2022-12-22           1.4.0
+  png           libpng-1.6.39      2022-11-20           1.4.0
+  zlib          zlib-1.2.13        2022-10-13           1.4.0
+  libdecor      3f3e5e1d   [2]     2022-12-29           1.4.0
+  --------------------------------------------------------------------------
+
+Previous versions of bundled libraries (FLTK 1.3.x):
+
+  Library       Version            Release date         FLTK Version
+  ------------------------------------------------------------------
+  jpeg          jpeg-9d            2020-01-12           1.3.6 - 1.3.8
+  png           libpng-1.6.37      2019-04-14           1.3.6 - 1.3.8
+  zlib          zlib-1.2.11        2017-01-15           1.3.6 - 1.3.8
+  --------------------------------------------------------------------------
+
+
+[1] Git commit in branch 'fltk' of https://github.com/fltk/nanosvg
+    See also git tag 'fltk_yyyy-mm-dd' where yyyy-mm-dd == "Release date"
+    and file nanosvg/README.txt.
+[2] Git commit in https://gitlab.freedesktop.org/libdecor/libdecor
+\endcode
+
+<h2>General information:</h2>
+
+  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".
+
+
+\section bundled-how-to How to update the bundled libraries
+
+  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.
+
+
+<h2>Merging source files:</h2>
+
+  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.
+
+
+<h2>Upgrade order:</h2>
+
+  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.
+
+
+<h2>Tests after merge:</h2>
+
+  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.
+
+
+<h2>Upgrade notes for specific libraries:</h2>
+
+  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.
+
+
+\section bundled-zlib zlib:
+
+  Website:    https://zlib.net/
+ \n Download:   See website and follow links.
+ \n 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
+\code
+    $ ./configure --zprefix
+\endcode
+  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:
+
+    - gzread.c
+    - zconf.h
+    - zlib.h
+
+  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:
+
+    - CMakeLists.txt: Keep FLTK version, update manually if necessary.
+    - Makefile: Same as CMakeLists.txt.
+    - gzread.c: Merge changes (see above, manual merge recommended).
+    - zconf.h:  Merge changes (see above, manual merge recommended).
+    - zlib.h:   Merge changes (see above, manual merge recommended).
+    - makedepend: Keep this file.
+
+Run `make depend' in the zlib folder on a Linux system after
+      the upgrade to update this file.
+
+
+\section bundled-ong png:
+
+  Website:    http://libpng.org/pub/png/libpng.html
+\n  Download:   See website and follow links.
+\n 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
+\code
+    $ ./configure --with-libpng-prefix=fltk_
+    $ make
+\endcode
+  This creates the header files 'pnglibconf.h' and 'pngprefix.h'
+  with the 'fltk_' symbol prefix.
+
+  The following files need special handling:
+
+    - CMakeLists.txt: Keep FLTK version, update manually if necessary.
+    - Makefile: Same as CMakeLists.txt.
+    - pnglibconf.h: Generate on a Linux system and merge (see above).
+    - pngprefix.h:  Generate on a Linux system and merge (see above).
+    - makedepend: Keep this file.
+
+Run `make depend' in the png folder on a Linux system after
+      the upgrade to update this file.
+
+
+\section bundled-jpeg jpeg:
+
+  Website:    https://ijg.org/
+\n  Download:   See website and follow links.
+\n  Repository: N/A
+
+  Download the latest jpeg-xy sources on a Linux (or Unix) system,
+  `cd' to /path-to/jpeg-xy and run
+\code
+    $ ./configure
+    $ make [-jN]
+\endcode
+  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:
+\code
+  $ nm --extern-only --defined-only .libs/libjpeg.a | awk '{print $3}' \
+    | sed '/^$/d' | sort -u | awk '{print "#define "$1" fltk_"$1}' \
+    > fltk_jpeg_prefix.h
+\endcode
+  This creates the header file 'fltk_jpeg_prefix.h' with the
+  '# define' statements using the 'fltk_' symbol prefix.
+
+  The following files need special handling:
+
+    - CMakeLists.txt: Keep FLTK version, update manually if necessary.
+    - Makefile: Same as CMakeLists.txt.
+    - fltk_jpeg_prefix.h:  Generate on a Linux system and merge (see above).
+    - jconfig.h: keep changes flagged with \verbatim /* FLTK */ \endverbatim
+    Note: more to come...
+    - makedepend: Keep this file.
+
+Run `make depend' in the jpeg folder on a Linux system after
+      the upgrade to update this file.
+
+
+\section bundled-nanosvg nanosvg:
+
+  Website:    https://github.com/memononen/nanosvg
+\n  Download:   See website and follow links.
+\n  Repository: git clone https://github.com/memononen/nanosvg.git
+\n  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:
+\code
+    $ git clone https://github.com/fltk/nanosvg.git nanosvg-fltk
+    $ cd nanosvg-fltk
+    $ git checkout fltk
+    $ cd src
+    $ cp nanosvg.h nanosvgrast.h /path/to/fltk-1.4/nanosvg/
+\endcode
+  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).
+\n    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:
+\code
+    $ cd /to/your/dev/dir
+    $ git clone https://github.com/fltk/nanosvg.git nanosvg-fltk
+    $ cd nanosvg-fltk
+    $ git remote add upstream https://github.com/memononen/nanosvg
+    $ git checkout master
+    $ git pull upstream master
+\endcode
+    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.
+\code
+    $ git checkout fltk
+    $ git rebase upstream/master
+\endcode
+    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.
+\code
+    $ git tag -a fltk_yyyy-mm-dd fltk
+\endcode
+    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:
+\code
+    $ git push -f origin fltk
+    $ git push origin fltk_yyyy-mm-dd
+\endcode
+    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.
+
+
+\section bundled-libdecor libdecor:
+
+  Website:    https://gitlab.freedesktop.org/libdecor/libdecor
+\n  Download:   See website and follow links.
+\n  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:
+  <pre>
+    demo/
+      demo.c
+      egl.c
+    LICENSE
+    README.md
+    src/    ... and files below except meson.build files
+</pre>
+  Furthermore, directory libdecor/build/ of the FLTK source tree does not
+  originate from the libdecor source tree but contains 3 FLTK-created files.
+  
+*/