1         How to add new files and libraries to wxWidgets build system
2         ============================================================
3
4
51. Regenerating makefiles
6-------------------------
7
8wxWidgets now uses Bakefile (http://bakefile.sourceforge.net) to generate
9native makefiles. You must have bakefile installed if you want to regenerate
10the makefiles. Bakefile currently runs on Unix and Windows systems. You will
11need Python >= 2.2 installed on Unix and either use Bakefile installer or have
12Python on Windows.
13
14Once you have installed Bakefile, you can easily regenerate the makefiles using
15the bakefile_gen tool. Run it from $(wx)/build/bakefiles directory and it will
16regenerate all outdated makefiles. See $(wx)/build/bakefiles/README for more
17details.
18
19Note that it generates makefiles for samples and contrib libraries, too.
20
21IMPORTANT NOTE: Don't forget to run autoconf in wxWidgets root directory
22                (after running Bakefile) if you changed any conditional
23                variable or target condition in .bkl files! You will know that
24                this happened if $(wx)/autoconf_inc.m4 content changed.
25
26You can use Bakefile to generate makefiles or projects customized to your
27needs, too. See Bakefiles.bkgen for details on bakefile commands used to
28generate makefiles. For example, you can use this command to generate
29VC++ project files without wxUniversal configurations:
30    bakefile -v -fmsvc6prj -o../wxmy.dsw -DRUNTIME_LIBS=dynamic
31             -DDEBUG_INFO=default -DDEBUG_FLAG=default
32             -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1 -DUSE_ODBC=1
33             -DMONOLITHIC=0 -DUSE_GUI=1 -DWXUNIV=0 wx.bkl
34Or monolithic instead of multilib (the default):
35    bakefile -v -fmsvc6prj -o../wxmono.dsw -DRUNTIME_LIBS=dynamic
36             -DDEBUG_INFO=default -DDEBUG_FLAG=default
37             -DOFFICIAL_BUILD=0 -DUSE_HTML=1 -DUSE_OPENGL=1 -DUSE_ODBC=1
38             -DMONOLITHIC=1 -DUSE_GUI=1 wx.bkl
39Or monolithic wxBase:
40    bakefile -v -fmsvc6prj -o../wxBase.dsw -DRUNTIME_LIBS=dynamic
41             -DDEBUG_INFO=default -DDEBUG_FLAG=default
42             -DOFFICIAL_BUILD=0 -DUSE_HTML=0 -DUSE_OPENGL=0 -DUSE_ODBC=0
43             -DMONOLITHIC=1 -DUSE_GUI=0 wx.bkl
44It is, however, recommended to modify Bakefiles.bkgen (or
45Bakefiles.local.bkgen) by means of <add-flags> and <del-flags> directives
46and use bakefile_gen instead of running bakefile directly.
47
48
492. Bakefile files organization
50------------------------------
51
52Makefile are generated from .bkl files ("bakefiles") from three places:
53  - $(wx)/build/bakefiles directory
54  - $(wx)/contrib/build/* directories
55  - samples directories
56$(wx)/build/bakefiles contains bakefiles for main library and support files
57that simplify writing bakefiles for contrib and samples.
58
59Support files are:
60  wxwin.py                - helper functions
61  common.bkl
62  common_samples.bkl
63  common_contrib.bkl      - shared definitions and templates
64  config.bkl              - user-configurable build options
65  make_dist.mk            - implementation of "make dist" on Unix
66
67Files used to build the library are:
68  wx.bkl                  - main file
69  files.bkl               - lists of source files
70  monolithic.bkl          - targets for wxWin built as single big library
71  multilib.bkl            - targets for multilib build
72  opengl.bkl              - GL library with wxGLCanvas (this one is not
73                            included in monolithic library for historical
74                            reasons, so "monolithic" really means "two libs")
75  {expat,jpeg,png,tiff,
76   regex,zlib,odbc}.bkl   - 3rd party libraries makefiles
77
78
793. Adding files to existing library
80-----------------------------------
81
82All files used by main libraries are listed in files.bkl. The file is
83organized into variables for toolkits, platforms and libraries. The variables
84come in pairs: there's always FOO_SRC for source files and FOO_HDR for header
85files. Platform or toolkit specific files are grouped together in variable
86with platform or toolkit name in them, e.g. BASE_WIN32_SRC, BASE_UNIX_SRC,
87GTK_SRC, MOTIF_SRC.
88
89Note: A side effect of this toolkit-centric organization is that one file may
90      be present several times in files.bkl in different contexts.
91
92When you are adding a file, you must put it into appropriate variable. This is
93easy if you are adding the file to library that is always built from same
94sources on all platforms (e.g. wxXml or wxXML) -- simply add the file to e.g.
95HTML_SRC or HTML_HDR.
96
97If the file is used only on one platform and is part of wxBase, add it to
98BASE_{platform}_SRC/HDR. If it is used on all platforms, add it to BASE_CMN.
99If it is built on more than one platform but not on all of them, add the file
100to *all platforms that use it*!
101
102If a file is not wxBase file, but GUI file, then the variables are named after
103toolkits/ports, not platforms. Same rules as for wxBase files apply
104(substitute "platform" with "toolkit"). Make sure you correctly choose between
105{port}_LOWLEVEL_SRC and {port}_SRC -- the former is for files used by
106wxUniversal, e.g. GDI classes. Files shared by all X Window System ports
107should be put into XWIN_LOWLEVEL_SRC.
108
109
1104. Adding sample
111----------------
112
113Copy the bakefile from another sample, change the ID and files accordingly.
114If the sample uses some data files, make sure to have <wx-data> node
115in the sample's bakefile (see e.g. samples/image/image.bkl for an example).
116Make sure to add <wx-lib> statements for all libraries from multilib build
117that are required by the sample.
118
119The Windows resource specification should use the central .rc file:
120
121        <win32-res>../sample.rc</win32-res>
122        
123Run bakefile_gen in $(wx)/build/bakefiles to regenerate the bakefiles.
124
125Finally commit $(wx)/build/bakefiles/make_dist.mk and all the other modified files.
126
127Currently we commit the generated makefiles except .dms, .vcp.
128
129
1305. Adding contrib library
131-------------------------
132
133Contrib library bakefiles are located in $(wx)/contrib/build/name-of-contrib
134directory, together with generated makefiles. Copy the bakefile from another
135contrib library, change the IDs and files accordingly. Note that there must be
136two targets for contrib wxFoo: foodll and foolib.
137
138foodll definition must contain <wx-lib> statements for all libraries it
139depends on. WXUSINGDLL and WXMAKINGDLL_FOO must be defined and symbols from
140the library should use WXDLLIMPEXP_FOO defined in wxFoo's headers analogically
141to WXDLLIMPEXP_{BASE,CORE,HTML,...} in the main library (see 5g below for
142additional details).
143
144Run bakefile_gen in $(wx)/build/bakefiles to regenerate makefiles
145then commit $(wx)/build/bakefiles/Makefile.
146
147
1486. Adding new core library
149--------------------------
150
151When adding new library to the core set of libraries, the files must be
152added to both a newly added library in multilib build and into the single
153library built in monolithic mode. We will assume that the new library is
154called wxFoo.
155
156a) Add files to files.bkl:
157   * If wxFoo builds from same files on all platforms (e.g. wxNet),
158     add FOO_SRC and FOO_HDR variables with lists of sources and headers.
159   * If wxFoo have no files in common (e.g. wxGL), add FOO_SRC and FOO_HDR
160     with toolkit or platform conditions. Have a look at OPENGL_SRC for an
161     example.
162   * Otherwise add FOO_CMN_SRC and FOO_CMN_HDR for common files and
163     FOO_{platform}_{SRC,HDR} or FOO_{toolkit}_{SRC,HDR} as appropriate. Add
164     FOO_PLATFORM_{SRC,HDR} into "Define sources for specific libraries"
165     section that is conditionally set to one of FOO_xxx_{SRC,HDR} based on
166     target platform/toolkit (see NET_PLATFORM_SRC definition for an example).
167     Finally, define FOO_SRC and FOO_HDR to contain both
168     FOO_PLATFORM_{SRC,HDR} and FOO_{SRC,HDR} (see NET_SRC definition for an
169     example).
170   * Add FOO_HDR to ALL_GUI_HEADERS or ALL_BASE_HEADERS. 
171   * If wxFoo is wxBase library (doesn't use GUI), add FOO_SRC to
172     ALL_BASE_SOURCES.
173
174   (You can apply different approaches to HDR and SRC variables, if e.g.
175   headers are all common but sources are not.)
176
177   Note that the conditions can only test for equality, due to limitations of
178   native make tools.
179
180b) Modify bakefile system in build/bakefiles/ to recognize wxFoo:
181   * Add 'foo' to MAIN_LIBS and LIBS_NOGUI or LIBS_GUI (depending on whether
182     the library depends on wxCore or not) to wxwin.py file.
183   * Add extra libraries needed by wxFoo (if any) to EXTRALIBS in wxwin.py
184   * Add WXLIB_FOO definition to common.bkl (into the "Names of component
185     libraries" section). It looks like this:
186       <set var="WXLIB_FOO">
187          <if cond="MONOLITHIC=='0'">$(mk.evalExpr(wxwin.mkLibName('foo')))</if>
188       </set>
189
190c) Modify monolithic.bkl to add files to monolithic build: it's enough to add
191   FOO_SRC to MONOLIB_GUI_SRC or MONOLIB_SRC, depending on whether wxFoo uses
192   GUI or not.
193
194d) Modify multilib.bkl to add files to multilib build: add foolib and foodll
195   targets. Don't use wxBase targets as the template, use e.g. wxXML or wxHTML.
196   Make sure WXMAKINGDLL_FOO is defined in foodll.
197
198e) Regenerate all makefiles (don't forget to run autoconf)
199
200f) Update configure.in and wx-config.in to contain information about
201   the library and needed linker flags:
202   * Add "foo" to either CORE_BASE_LIBS or CORE_GUI_LIBS in configure.in so
203     that wxFoo is not treated as contrib library in monolithic build.
204   * If wxFoo links against additional libraries, add necessary linker
205     flags and libraries to ldflags_foo and ldlibs_foo variables in
206     wx-config.in (both are optional).
207
208g) Update dlimpexp.h to define WXMAKINGDLL_FOO if WXMAKINGDLL is defined (add
209   #define WXMAKINGDLL_FOO inside first "#ifdef WXMAKINGDLL" block in
210   dlimpexp.h) and to define WXDLLIMPEXP_FOO and WXDLLIMPEXP_DATA_FOO. You
211   can copy e.g. WXDLLIMPEXP_NET definition, it is something like this:
212        #ifdef WXMAKINGDLL_NET
213            #define WXDLLIMPEXP_NET WXEXPORT
214            #define WXDLLIMPEXP_DATA_NET(type) WXEXPORT type
215        #elif defined(WXUSINGDLL)
216            #define WXDLLIMPEXP_NET WXIMPORT
217            #define WXDLLIMPEXP_DATA_NET(type) WXIMPORT type
218        #else // not making nor using DLL
219            #define WXDLLIMPEXP_NET
220            #define WXDLLIMPEXP_DATA_NET(type) type
221        #endif
222   Use WXDLLIMPEXP_FOO when declaring wxFoo classes and functions.
223
224h) Add this code to one of wxFoo's files (the more often used, the better):
225      // DLL options compatibility check:
226      #include "wx/app.h"
227      WX_CHECK_BUILD_OPTIONS("wxFoo")
228
229i) Add information about wxFoo to the manual ("Libraries list" section
230   in libs.tex) and update docs/latex/wx/libs.dia (you need Dia for this)
231   to show the dependencies of the new library.
232
233j) Also please add 4 #pragma comment(lib, "foo") (for Unicode/ANSI
234   Release/Debug combinations) to the file include/msvc/wx/setup.h and
235   add a check for WXMAKINGDLL_FOO to the test whether we're building a DLL at
236   the end of include/wx/msw/chkconf.h.
237
238=== EOF ===
239
240Version: $Id: tn0016.txt 38334 2006-03-24 08:28:38Z JS $
241