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, 0 insertions, 370 deletions

diff --git a/README.bundled-libs.txt b/README.bundled-libs.txt
deleted file mode 100644
index 8f84d0f39..000000000
--- a/README.bundled-libs.txt
+++ /dev/null
@@ -1,370 +0,0 @@
-README.bundled-libs.txt - Developer information for bundled libraries
----------------------------------------------------------------------
-
-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.
-
-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
-
-General information:
-
-  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".
-
-
-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.
-
-
-Merging source files:
-
-  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.
-
-
-Upgrade order:
-
-  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 after merge:
-
-  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.
-
-
-Upgrade notes for specific libraries:
-
-  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.
-
-
-zlib:
-
-  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
-
-    $ ./configure --zprefix
-
-  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.
-
-
-png:
-
-  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
-
-    $ ./configure --with-libpng-prefix=fltk_
-    $ make
-
-  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.
-
-
-jpeg:
-
-  Website:    https://ijg.org/
-  Download:   See website and follow links.
-  Repository: <unknown>
-
-  Download the latest jpeg-xy sources on a Linux (or Unix) system,
-  `cd' to /path-to/jpeg-xy and run
-
-    $ ./configure
-    $ make [-jN]
-
-  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:
-
-  $ 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
-
-  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 /* FLTK */
-
-    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.
-
-
-nanosvg:
-
-  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:
-
-    $ 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/
-
-  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:
-
-    $ 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
-
-    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.
-
-    $ git checkout fltk
-    $ git rebase upstream/master
-
-    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.
-
-    $ git tag -a fltk_yyyy-mm-dd fltk
-
-    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:
-
-    $ git push -f origin fltk
-    $ git push origin fltk_yyyy-mm-dd
-
-    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.
-
-
-libdecor:
-
-  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:
-    demo/
-      demo.c
-      egl.c
-    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.