Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update library naming convention documentation

Browse Source
This commit is contained in:
Maarten Bent
2021-05-02 21:29:00 +02:00
parent 0f0f9eb790
commit 01edac992d
1 changed files with 85 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
docs/contributing/about-platform-toolkit-and-library-names.md
View File

@@ -1,5 +1,4 @@
wxWidgets naming conventions ## wxWidgets naming conventions
============================
Being a cross platform development library, it is naturally desirable Being a cross platform development library, it is naturally desirable
(at least to me ;) for wxWidgets to be exploited in a fully cross (at least to me ;) for wxWidgets to be exploited in a fully cross
@@ -9,7 +8,7 @@ when desired.
Since this is now in fact possible for at least the most commonly used Since this is now in fact possible for at least the most commonly used
platforms, wxWidgets has been structured to allow multiple, simultaneous platforms, wxWidgets has been structured to allow multiple, simultaneous
installations of the library. Common files are shared, platform and port installations of the library. Common files are shared, platform and port
specific files and libraries are arranged so as to be unambiguous when specific files and libraries are arranged so as to be unambiguous when
installed together. installed together.
@@ -22,61 +21,99 @@ for wxWidgets, but is encompassing enough to maintain a relatively complete
set of cross platform build tools on a single machine and to provide an set of cross platform build tools on a single machine and to provide an
obvious slot for new ports to slip into. obvious slot for new ports to slip into.
The libraries use the following naming convention.
When an item of the name is empty, `'_'` or `'-'` are omitted.
For UNIX libraries, the canonical library name shall be of the form: *UNIX libraries* (using configure):
libwx_$(toolkit)$(widgetset)$(debug)-$(version)-$(host).$(lib_extension) libwx_$(toolkit)$(widgetset)$(unicode)_$(flavour)_$(name)-$(version)-$(host).$(lib_extension)
For MSW (native hosted only) libraries the library name should be of *Windows libraries* (using VS solution or makefile.gcc/vc):
the form:
wx$(toolkit)$(widgetset)$(version)$(unicode)$(debug).$(lib_extension) wx$(toolkit)$(widgetset)$(version)$(unicode)$(debug)_$(flavour)_$(name)_$(compiler)_$(arch)_$(vendor).$(lib_extension)
Where: Where:
-------------------------------------------------------------------- --------------------------------------------------------------------
`$toolkit` must currently be one of the following: `$toolkit` can currently be one of the following:
msw - `base`
gtk - `msw`
base - `gtk`, `gtk2`, `gtk3`, `gtk4`
mac - `osx_cocoa`, `osx_iphone`
motif - `motif`
- `x11`
- `dfb`
- `qt`
-------------------------------------------------------------------- --------------------------------------------------------------------
`$widgetset` may be one of: `$widgetset` may be one of:
univ - `univ`
or empty if the widget set is the same as the toolkit. or empty if the widget set is the same as the toolkit.
-------------------------------------------------------------------- --------------------------------------------------------------------
`$version` is a string encoding the full version (major, minor, release) `$version` is a string encoding the major and minor version number,
for MSW, or just the major and minor number for UNIX. separated by a dot on UNIX and without separator on Windows.
Windows shared libraries of development versions (odd minor releases)
contain the full version (major, minor, release).
On UNIX, the `$so_version` contains the release number.
eg. for wxWidgets 2.3.2, `$version` = 232 for MSW or 2.3 for UNIX. Eg. for wxWidgets 3.1.5, `$version` is `315` for Windows shared libraries,
`31` for Windows static libraries, and `3.1` for UNIX libraries. And the
`$so_version` for UNIX libraries is `.5` and `.5.0.0`.
The rationale for this is that under UNIX-like systems it is desirable The rationale for this is that under UNIX-like systems it is desirable
that differently 'minor numbered' releases can be installed together, that differently 'minor numbered' releases can be installed together,
meaning your old 2.2 apps can continue to work even if you migrate meaning your old 2.2 apps can continue to work even if you migrate
development to the next stable or unstable release (eg. 2.3, 2.4), development to the next stable or unstable release (eg. 2.3, 2.4),
but binary compatibility is maintained between point releases (those but binary compatibility is maintained between point releases (those
with the same major.minor number) with the same major.minor number).
A known break in binary compatibility should be addressed by updating A known break in binary compatibility should be addressed by updating
the library soname (see the notes in configure.in for details on this) the library soname (see the notes in configure.in for details on this).
I do not know why MSW should not also omit the release number from
`$version`. (maybe that will change by the time this document is ratified)
-------------------------------------------------------------------- --------------------------------------------------------------------
`$unicode` and `$debug` are either empty or set to `'u'` and `'d'` `$unicode` is set to `'u'` when Unicode is enabled (default on), and is empty
respectively when enabled. when disabled. In the `setup.h` and `wx-config` names, the full `'unicode'`
name is used.
--------------------------------------------------------------------
`$debug` is set to `'d'` for the libraries using debug version of CRT and is empty
for release libraries. It is only really useful for the libraries created with MSVC
projects and makefiles, as MSVC debug and release CRT are not ABI-compatible,
but is also used by `makefile.gcc` under MSW for consistency with `makefile.vc`.
When using configure under MSW or UNIX, it is always empty.
--------------------------------------------------------------------
`$flavour` is an optional name to identify the build. It is empty by default.
--------------------------------------------------------------------
`$name` is the name of the library. It is empty for the `'base'` library.
--------------------------------------------------------------------
`$compiler` is the used compiler, for example `'vc'` or `'gcc'`.
It is only added to shared libraries on Windows.
--------------------------------------------------------------------
`$arch` is used by MSVC solutions. It is empty for 32-bit builds and
`'x64'` for 64-bit builds. It is only added to shared libraries.
--------------------------------------------------------------------
`$vendor` is an optional name appended to the library name. It is only
added to shared libraries on Windows. It defaults to `'custom'`.
-------------------------------------------------------------------- --------------------------------------------------------------------
@@ -87,29 +124,40 @@ that are cross compiled.
-------------------------------------------------------------------- --------------------------------------------------------------------
`$lib_extension` is system specific and most usually set to `.a` for `$lib_extension` is system specific and most usually set to `'.a'` for
a static library, `.dll` for a MSW shared library, or `.so.$so_version` a static UNIX library, `'.so.$so_version'` for a shared UNIX library,
for a shared UNIX library. `'.lib'` for a static MSVC library or `'.dll'` for a shared MSVC library.
==================================================================== --------------------------------------------------------------------
`type` is used to indicate a shared or static build. For MSVC, type is
`'lib'` for shared libraries and `'dll'` for static libraries.
On UNIX, type is empty for shared libraries and `'static'` for static libraries.
--------------------------------------------------------------------
## setup.h
The installed location of the library specific setup.h is also The installed location of the library specific setup.h is also
determined by the values of these items. On UNIX systems they determined by the values of these items. On UNIX they will be found in:
will be found in:
$(prefix)/lib/wx/include/$(toolkit)$(widgetset)$(debug)-$(version)-$(host)/wx/ $(prefix)/lib/wx/include/$(host)-$(toolkit)$(widgetset)-$(unicode)-$(type)-$(version)-$(flavour)/wx/setup.h
which will be in the include search path returned by the relevant which will be in the include search path returned by the relevant
wx-config for that library. (or presumably set in the relevant wx-config for that library (or presumably set in the relevant
make/project files for platforms that do not use wx-config) make/project files for platforms that do not use wx-config).
==================================================================== For MSVC and gcc/vc makefile, the file is found in:
$(prefix)/lib/$(compiler)_$(arch)_$(type)/$(toolkit)$(widgetset)$(unicode)$(debug)/wx/setup.h
--------------------------------------------------------------------
## wx-config
The port specific wx-config file for each library shall be named: The port specific wx-config file for each library shall be named:
wx-$(toolkit)$(widgetset)$(debug)-$(version)-$(host)-config $(prefix)/lib/wx/config/$(host)-$(toolkit)$(widgetset)-$(unicode)-$(type)-$(version)-$(flavour)
${prefix}/bin/wx-config shall exist as a link to (or copy of) one of ${prefix}/bin/wx-config shall exist as a link to (or copy of) one of
these port specific files (on platforms which support it) and as such these port specific files (on platforms which support it) and as such