Mirrors_UI_SDK/fltk
1
0
Fork 0
mirror of https://github.com/fltk/fltk.git synced 2026-06-01 06:14:28 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Create new documentation chapter for FLTK developers

Browse Source 
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
This commit is contained in:
ManoloFLTK
2023-01-19 12:27:20 +01:00
parent 7b245ef0ab
commit f314ca75fe
4 changed files with 901 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/Doxyfile.in
+2
View File
@@ -580,6 +580,8 @@ INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/development.dox
INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/license.dox INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/license.dox
INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/examples.dox INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/examples.dox
INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/faq.dox INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/faq.dox
INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/wayland.dox
INPUT += @CMAKE_CURRENT_SOURCE_DIR@/src/bundled-libs.dox
# This tag can be used to specify the character encoding of the source files # This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
README.bundled-libs.txt → documentation/src/bundled-libs.dox
+76 -76
View File
@@ -1,5 +1,11 @@
README.bundled-libs.txt - Developer information for bundled libraries /**
---------------------------------------------------------------------
\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 This file is mainly intended for FLTK developers and contains information
about the current versions of all bundled libraries and about how to about the current versions of all bundled libraries and about how to
@@ -15,8 +21,9 @@ bundled image libraries need not be changed.
The nanosvg library is not affected. The nanosvg library is not affected.
\section bundled-status Current status
\code
Current versions of bundled libraries (as of Jan 16, 2023): Current versions of bundled libraries (as of Jan 16, 2023):
Library Version/git commit Release date FLTK Version Library Version/git commit Release date FLTK Version
-------------------------------------------------------------------------- --------------------------------------------------------------------------
jpeg jpeg-9e 2022-01-16 1.4.0 jpeg jpeg-9e 2022-01-16 1.4.0
@@ -40,8 +47,9 @@ Previous versions of bundled libraries (FLTK 1.3.x):
See also git tag 'fltk_yyyy-mm-dd' where yyyy-mm-dd == "Release date" See also git tag 'fltk_yyyy-mm-dd' where yyyy-mm-dd == "Release date"
and file nanosvg/README.txt. and file nanosvg/README.txt.
[2] Git commit in https://gitlab.freedesktop.org/libdecor/libdecor [2] Git commit in https://gitlab.freedesktop.org/libdecor/libdecor
\endcode
General information: <h2>General information:</h2>
FLTK does not include the entire library distributions. We only provide the 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 source files necessary to build the FLTK library and some README and/or
@@ -64,7 +72,7 @@ General information:
"STR 3456", "Issue #123", or "PR #234". "STR 3456", "Issue #123", or "PR #234".
How to update the bundled libraries: \section bundled-how-to How to update the bundled libraries
It is generally advisable to use a graphical merge program. I'm using It is generally advisable to use a graphical merge program. I'm using
'meld' under Linux, but YMMV. 'meld' under Linux, but YMMV.
@@ -79,7 +87,7 @@ How to update the bundled libraries:
Currently there are no known exceptions. Currently there are no known exceptions.
Merging source files: <h2>Merging source files:</h2>
Please check if some source and header files contain "FLTK" comments Please check if some source and header files contain "FLTK" comments
and/or 'fltk_' symbol prefixing to be aware of necessary merges. and/or 'fltk_' symbol prefixing to be aware of necessary merges.
@@ -101,21 +109,21 @@ Merging source files:
configure/make and in CMake based builds, respectively. configure/make and in CMake based builds, respectively.
Upgrade order: <h2>Upgrade order:</h2>
There is only one dependency between all bundled libraries: libpng There is only one dependency between all bundled libraries: libpng
depends on zlib. Hence zlib should be upgraded first, then all other depends on zlib. Hence zlib should be upgraded first, then all other
libs can be upgraded in arbitrary order. libs can be upgraded in arbitrary order.
Tests after merge: <h2>Tests after merge:</h2>
Tests should be done on as many platforms as possible, both with Tests should be done on as many platforms as possible, both with
autotools (configure/make) and CMake. Windows (Visual Studio) and autotools (configure/make) and CMake. Windows (Visual Studio) and
macOS (Xcode) builds need CMake to generate the IDE files. macOS (Xcode) builds need CMake to generate the IDE files.
Upgrade notes for specific libraries: <h2>Upgrade notes for specific libraries:</h2>
The following chapters contain informations about specific files and The following chapters contain informations about specific files and
how they are upgraded. Since the changes in all bundled libraries are how they are upgraded. Since the changes in all bundled libraries are
@@ -123,18 +131,18 @@ Upgrade notes for specific libraries:
verify that no other changes are necessary. verify that no other changes are necessary.
zlib: \section bundled-zlib zlib:
Website: https://zlib.net/ Website: https://zlib.net/
Download: See website and follow links. \n Download: See website and follow links.
Repository: git clone https://github.com/madler/zlib.git \n Repository: git clone https://github.com/madler/zlib.git
zlib should be upgraded first because libpng depends on zlib. zlib should be upgraded first because libpng depends on zlib.
Download the latest zlib sources, `cd' to /path-to/zlib and run Download the latest zlib sources, `cd' to /path-to/zlib and run
\code
$ ./configure --zprefix $ ./configure --zprefix
\endcode
This creates the header file 'zconf.h' with definitions to enable This creates the header file 'zconf.h' with definitions to enable
the standard 'z_' symbol prefix. the standard 'z_' symbol prefix.
@@ -153,100 +161,89 @@ zlib:
The following files need special handling: The following files need special handling:
CMakeLists.txt: Keep FLTK version, update manually if necessary. - 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.
Makefile: Same as CMakeLists.txt. Run `make depend' in the zlib folder on a Linux system after
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. the upgrade to update this file.
png: \section bundled-ong png:
Website: http://libpng.org/pub/png/libpng.html Website: http://libpng.org/pub/png/libpng.html
Download: See website and follow links. \n Download: See website and follow links.
Repository: git clone https://git.code.sf.net/p/libpng/code libpng \n Repository: git clone https://git.code.sf.net/p/libpng/code libpng
libpng should be upgraded after zlib because it depends on zlib. libpng should be upgraded after zlib because it depends on zlib.
Download the latest libpng sources, `cd' to /path-to/libpng and run Download the latest libpng sources, `cd' to /path-to/libpng and run
\code
$ ./configure --with-libpng-prefix=fltk_ $ ./configure --with-libpng-prefix=fltk_
$ make $ make
\endcode
This creates the header files 'pnglibconf.h' and 'pngprefix.h' This creates the header files 'pnglibconf.h' and 'pngprefix.h'
with the 'fltk_' symbol prefix. with the 'fltk_' symbol prefix.
The following files need special handling: The following files need special handling:
CMakeLists.txt: Keep FLTK version, update manually if necessary. - 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.
Makefile: Same as CMakeLists.txt. Run `make depend' in the png folder on a Linux system after
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. the upgrade to update this file.
jpeg: \section bundled-jpeg jpeg:
Website: https://ijg.org/ Website: https://ijg.org/
Download: See website and follow links. \n Download: See website and follow links.
Repository: <unknown> \n Repository: N/A
Download the latest jpeg-xy sources on a Linux (or Unix) system, Download the latest jpeg-xy sources on a Linux (or Unix) system,
`cd' to /path-to/jpeg-xy and run `cd' to /path-to/jpeg-xy and run
\code
$ ./configure $ ./configure
$ make [-jN] $ make [-jN]
\endcode
This builds the library and should create the static library file This builds the library and should create the static library file
'.libs/libjpeg.a'. '.libs/libjpeg.a'.
Execute the following command to extract the libjpeg symbol names Execute the following command to extract the libjpeg symbol names
used to build the 'prefixed' libfltk_jpeg library: used to build the 'prefixed' libfltk_jpeg library:
\code
$ nm --extern-only --defined-only .libs/libjpeg.a | awk '{print $3}' \ $ nm --extern-only --defined-only .libs/libjpeg.a | awk '{print $3}' \
| sed '/^$/d' | sort -u | awk '{print "#define "$1" fltk_"$1}' \ | sed '/^$/d' | sort -u | awk '{print "#define "$1" fltk_"$1}' \
> fltk_jpeg_prefix.h > fltk_jpeg_prefix.h
\endcode
This creates the header file 'fltk_jpeg_prefix.h' with the This creates the header file 'fltk_jpeg_prefix.h' with the
'#define' statements using the 'fltk_' symbol prefix. '# define' statements using the 'fltk_' symbol prefix.
The following files need special handling: The following files need special handling:
CMakeLists.txt: Keep FLTK version, update manually if necessary. - CMakeLists.txt: Keep FLTK version, update manually if necessary.
- Makefile: Same as CMakeLists.txt.
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
fltk_jpeg_prefix.h: Generate on a Linux system and merge (see above).
jconfig.h: keep changes flagged with /* FLTK */
Note: more to come... Note: more to come...
- makedepend: Keep this file.
makedepend: Keep this file. Run `make depend' in the jpeg folder on a Linux system after
Run `make depend' in the jpeg folder on a Linux system after
the upgrade to update this file. the upgrade to update this file.
nanosvg: \section bundled-nanosvg nanosvg:
Website: https://github.com/memononen/nanosvg Website: https://github.com/memononen/nanosvg
Download: See website and follow links. \n Download: See website and follow links.
Repository: git clone https://github.com/memononen/nanosvg.git \n Repository: git clone https://github.com/memononen/nanosvg.git
FLTK Fork: git clone https://github.com/fltk/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). FLTK has its own GitHub fork of the original repository (see above).
@@ -261,20 +258,20 @@ nanosvg:
Use this fork (branch 'fltk') to get the nanosvg library with FLTK Use this fork (branch 'fltk') to get the nanosvg library with FLTK
specific patches: specific patches:
\code
$ git clone https://github.com/fltk/nanosvg.git nanosvg-fltk $ git clone https://github.com/fltk/nanosvg.git nanosvg-fltk
$ cd nanosvg-fltk $ cd nanosvg-fltk
$ git checkout fltk $ git checkout fltk
$ cd src $ cd src
$ cp nanosvg.h nanosvgrast.h /path/to/fltk-1.4/nanosvg/ $ 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 This library does not have its own build files since it is a header-only
library. The headers are included in FLTK where necessary. library. The headers are included in FLTK where necessary.
The following files need special handling: The following files need special handling:
nanosvg.h: Merge or download from FLTK's fork (see above). nanosvg.h: Merge or download from FLTK's fork (see above).
nanosvgrast.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): Maintaining branch 'fltk' in FLTK's fork of nanosvg (fltk/nanosvg):
@@ -290,14 +287,14 @@ nanosvg:
Step 1: clone the fltk/nanosvg fork, set the remote 'upstream', Step 1: clone the fltk/nanosvg fork, set the remote 'upstream',
and update the 'master' branch: and update the 'master' branch:
\code
$ cd /to/your/dev/dir $ cd /to/your/dev/dir
$ git clone https://github.com/fltk/nanosvg.git nanosvg-fltk $ git clone https://github.com/fltk/nanosvg.git nanosvg-fltk
$ cd nanosvg-fltk $ cd nanosvg-fltk
$ git remote add upstream https://github.com/memononen/nanosvg $ git remote add upstream https://github.com/memononen/nanosvg
$ git checkout master $ git checkout master
$ git pull upstream master $ git pull upstream master
\endcode
Note: the 'master' branch must never be changed, i.e. it must Note: the 'master' branch must never be changed, i.e. it must
always be the same as 'upstream/master'. Never commit your own always be the same as 'upstream/master'. Never commit your own
(FLTK specific) changes to branch 'master'. (FLTK specific) changes to branch 'master'.
@@ -309,10 +306,10 @@ nanosvg:
(one commit per patch) because this will preserve the history and (one commit per patch) because this will preserve the history and
the committer and make it easier to skip single patches when they the committer and make it easier to skip single patches when they
are accepted upstream. are accepted upstream.
\code
$ git checkout fltk $ git checkout fltk
$ git rebase upstream/master $ git rebase upstream/master
\endcode
At this point you may need to fix conflicts! Do whatever is At this point you may need to fix conflicts! Do whatever is
necessary to update the branch 'fltk'. necessary to update the branch 'fltk'.
@@ -320,9 +317,9 @@ nanosvg:
Hint: use `git show <any-older-tag-name>' to see its contents. Hint: use `git show <any-older-tag-name>' to see its contents.
I like to write a summary of commits in the tag comment. I like to write a summary of commits in the tag comment.
\code
$ git tag -a fltk_yyyy-mm-dd fltk $ git tag -a fltk_yyyy-mm-dd fltk
\endcode
Replace 'yyyy-mm-dd' with the current date and add a comment Replace 'yyyy-mm-dd' with the current date and add a comment
when asked for it (your editor will open an empty file). when asked for it (your editor will open an empty file).
@@ -333,20 +330,20 @@ nanosvg:
Step 4: push the new branch 'fltk' and the tag to the fltk/nanosvg Step 4: push the new branch 'fltk' and the tag to the fltk/nanosvg
repository: repository:
\code
$ git push -f origin fltk $ git push -f origin fltk
$ git push origin fltk_yyyy-mm-dd $ git push origin fltk_yyyy-mm-dd
\endcode
Step 5: copy the changed files to your working copy of the FLTK Step 5: copy the changed files to your working copy of the FLTK
repository (if not done already), update this file accordingly, repository (if not done already), update this file accordingly,
and commit/push the update to the fltk/fltk repository. and commit/push the update to the fltk/fltk repository.
libdecor: \section bundled-libdecor libdecor:
Website: https://gitlab.freedesktop.org/libdecor/libdecor Website: https://gitlab.freedesktop.org/libdecor/libdecor
Download: See website and follow links. \n Download: See website and follow links.
Repository: git clone https://gitlab.freedesktop.org/libdecor/libdecor.git \n Repository: git clone https://gitlab.freedesktop.org/libdecor/libdecor.git
libdecor is used by the Wayland/X11 hybrid platform to draw window libdecor is used by the Wayland/X11 hybrid platform to draw window
titlebars when FLTK apps run as Wayland clients and the running titlebars when FLTK apps run as Wayland clients and the running
@@ -359,12 +356,15 @@ libdecor:
FLTK uses libdecor source files without any modification. FLTK uses libdecor source files without any modification.
This part of the libdecor source tree is copied to directory libdecor/ of This part of the libdecor source tree is copied to directory libdecor/ of
the FLTK source tree: the FLTK source tree:
<pre>
demo/ demo/
demo.c demo.c
egl.c egl.c
LICENSE LICENSE
README.md README.md
src/ ... and files below except meson.build files src/ ... and files below except meson.build files
</pre>
Furthermore, directory libdecor/build/ of the FLTK source tree does not Furthermore, directory libdecor/build/ of the FLTK source tree does not
originate from the libdecor source tree but contains 3 FLTK-created files. originate from the libdecor source tree but contains 3 FLTK-created files.
*/
documentation/src/index.dox
-2
View File
@@ -93,8 +93,6 @@
- \subpage migration_1_4 - \subpage migration_1_4
- \subpage development
- \subpage license - \subpage license
- \subpage examples - \subpage examples
documentation/src/wayland.dox
+823
View File
File diff suppressed because it is too large Load Diff