1                      wxWidgets naming conventions
2                      ============================
3
4Being a cross platform development library, it is naturally desirable
5(at least to me ;) for wxWidgets to be exploited in a fully cross
6platform development environment -- a single invocation of make should
7be sufficient to build target executables for a variety of host platforms
8when desired.
9
10Since this is now in fact possible for at least the most commonly used
11platforms, wxWidgets has been structured to allow multiple, simultaneous
12installations of the library.  Common files are shared, platform and port
13specific files and libraries are arranged so as to be unambiguous when
14installed together.
15
16To manage this sanely we need a sufficiently descriptive and logical
17labelling convention for file and install path names -- this document (at
18least at its time of writing) describes the system we have adopted.
19
20It is not fine grained enough to include every possible build configuration
21for wxWidgets, but is encompassing enough to maintain a relatively complete
22set of cross platform build tools on a single machine and to provide an
23obvious slot for new ports to slip into.
24
25
26For UNIX libraries, the canonical library name shall be of the form:
27
28libwx_$(toolkit)$(widgetset)$(debug)-$(version)-$(host).$(lib_extension)
29
30For MSW (native hosted only) libraries the library name should be of
31the form:
32
33wx$(toolkit)$(widgetset)$(version)$(unicode)$(debug).$(lib_extension)
34
35
36Where:
37
38--------------------------------------------------------------------
39
40$toolkit must currently be one of the following:
41
42	msw
43	gtk
44	base
45	mac
46	os2
47	pm
48	mgl
49	motif
50
51--------------------------------------------------------------------
52
53$widgetset may be one of:
54
55	univ
56
57or empty if the widget set is the same as the toolkit.
58
59--------------------------------------------------------------------
60
61$version is a string encoding the full version (major, minor, release)
62for MSW, or just the major and minor number for UNIX.
63
64eg. for wxWidgets 2.3.2, $version = 232 for MSW or 2.3 for UNIX.
65
66The rationale for this is that under UNIX-like systems it is desirable
67that differently 'minor numbered' releases can be installed together,
68meaning your old 2.2 apps can continue to work even if you migrate
69development to the next stable or unstable release (eg.  2.3, 2.4),
70but binary compatibility is maintained between point releases (those
71with the same major.minor number)
72
73A known break in binary compatibility should be addressed by updating
74the library soname (see the notes in configure.in for details on this)
75
76I do not know why MSW should not also omit the release number from
77$version. (maybe that will change by the time this document is ratified)
78
79--------------------------------------------------------------------
80
81$unicode and $debug are either empty or set to 'u' and 'd'
82respectively when enabled.
83
84--------------------------------------------------------------------
85
86$host is empty for a 'native' library, (that is one where the host
87system is the same as the build system) or set to the value returned
88by the autoconf ${host_alias} variable in configure for libraries
89that are cross compiled.
90
91--------------------------------------------------------------------
92
93$lib_extension is system specific and most usually set to .a for
94a static library, .dll for a MSW shared library, or .so.$so_version
95for a shared UNIX library.
96
97====================================================================
98
99
100The installed location of the library specific setup.h is also
101determined by the values of these items.  On UNIX systems they
102will be found in:
103
104$(prefix)/lib/wx/include/$(toolkit)$(widgetset)$(debug)-$(version)-$(host)/wx/
105
106which will be in the include search path returned by the relevant
107wx-config for that library.  (or presumably set in the relevant
108make/project files for platforms that do not use wx-config)
109
110====================================================================
111
112
113The port specific wx-config file for each library shall be named:
114
115wx-$(toolkit)$(widgetset)$(debug)-$(version)-$(host)-config
116
117${prefix}/bin/wx-config shall exist as a link to (or copy of) one of
118these port specific files (on platforms which support it) and as such
119it defines the default build configuration for wxApps on the system.
120It may be modified by the system user at any time.
121
122
123
124                         ---==O==---
125
126