1 -----------------------------------------------------------------------
2 Creating a Cross-Platform Build System Using Bakefile
3 The 10-minute, do-it-yourself wx project baking guide (with free sample recipes!)
8 License: wxWidgets License
9 -----------------------------------------------------------------------
11 Supporting many different platforms can be a difficult challenge. The
12 challenge for wxWidgets is especially great, because it supports a variety of
13 different compilers and development environments, including MSVC, Borland C++,
14 MinGW, DevCPP, GNU make/automake, among others. Maintaining such a large
15 number of different project files and formats can quickly become overwhelming.
16 To simplify the maintenance of these formats, one of the wxWidgets developers,
17 Vaclav Slavik, created Bakefile, a XML-based makefile wrapper that generates
18 all the native project files for wxWidgets. So now, even though wxWidgets
19 supports all these formats, wxWidgets developers need only update one file -
20 the Bakefile, and it handles the rest. But Bakefile isn't specific to
21 wxWidgets in any way - you can use Bakefile for your own projects, too. This
22 brief tutorial will take a look at how to do that.
24 Note that this tutorial assumes that you are familiar with how to build
25 software using one of the supported Bakefile makefile systems, that you have
26 some basic familiarity with how makefiles work, and that you are capable of
27 setting environment variables on your platform. Also note that the terms Unix
28 and Unix-based refers to all operating systems that share a Unix heritage,
29 including FreeBSD, Linux, Mac OS X, and various other operating systems.
33 First, you'll need to install Bakefile. You can always find the latest version
34 for download online at http://www.bakefile.org. A binary installer is provided
35 for Windows users, while users of Unix-based operating systems (OS) will need
36 to unpack the tarball and run configure && make && make install. (binary
37 packages for some Linux distributions are also available, check
38 http://www.bakefile.org/download.html for details).
40 -- Setting Up Your wx Build Environment --
42 Before you can build wxWidgets software using Bakefile or any other build
43 system, you need to make sure that wxWidgets is built and that wxWidgets
44 projects can find the wxWidgets includes and library files. wxWidgets build
45 instructions can be found by going to the docs subfolder, then looking for the
46 subfolder that corresponds to your platform (i.e. msw, gtk, mac) and reading
47 "install.txt" there. Once you've done that, here are some extra steps you
48 should take to make sure your Bakefile projects work with wxWidgets:
52 Once you've built wxWidgets, you should create an environment variable named
53 WXWIN and set it to the home folder of your wxWidgets source tree. (If you use
54 the command line to build, you can also set or override WXWIN at build time by
55 passing it in as an option to your makefile.)
59 In a standard install, you need not do anything so long as wx-config is on
60 your PATH. wx-config is all you need. (See the section of the book on using
61 wx-config for more information.)
63 -- A Sample wx Project Bakefile --
65 Now that everything is setup, it's time to take Bakefile for a test run. I
66 recommend that you use the wx sample Bakefile to get you started. It can be
67 found in the 'build/bakefiles/wxpresets/sample' directory in the wxWidgets
68 source tree. Here is the minimal.bkl Bakefile used in the sample:
71 -------------------------------------------------------------
72 <?xml version="1.0" ?>
77 <include file="presets/wx.bkl"/>
79 <exe id="minimal" template="wx">
80 <app-type>gui</app-type>
81 <debug-info>on</debug-info>
82 <runtime-libs>dynamic</runtime-libs>
84 <sources>minimal.cpp</sources>
91 ---------------------------------------------------------------
93 It's a complete sample ready to be baked, so go into the directory mentioned
94 above and run the following command:
97 bakefile -f msvc -I.. minimal.bkl
100 bakefile -f gnu -I.. minimal.bkl
102 It should generate a makefile (makefile.vc or GNUmakefile, respectively) which
103 you can use to build the software. Just build the software using the command
104 "nmake -f makefile.vc" or "make -f GNUmakefile" respectively. Now let's take a
105 look at some of the basic Bakefile concepts that you'll need to know to move
110 As mentioned earlier, Bakefile builds makefiles for many different
111 development environments. The -f option accepts a list of formats that you
112 would like to build, separated by commas. Valid values are:
114 autoconf GNU autoconf Makefile.in files
115 borland Borland C/C++ makefiles
116 dmars Digital Mars makefiles
117 dmars_smake Digital Mars makefiles for SMAKE
118 gnu GNU toolchain makefiles (Unix)
119 mingw MinGW makefiles (mingw32-make)
120 msevc4prj MS eMbedded Visual C++ 4 project files
121 msvc MS Visual C++ nmake makefiles
122 msvc6prj MS Visual C++ 6.0 project files
123 watcom OpenWatcom makefiles
125 TIP: autoconf Project Type
126 ---------------------------
127 You may notice that in the sample folder, there is also a file called
128 configure.in. That file is the input for autoconf, which creates the configure
129 scripts that you often see when you build software from source on Unix-based
130 platforms. People use configure scripts because they make your Unix makefiles
131 more portable by automatically detecting the right libraries and commands to
132 use on the user's machine and OS. This is necessary because there are many
133 Unix-based operating systems and they all are slightly different in various
136 Bakefile does not generate a configure or configure.in script, so if you want
137 to use configure scripts with your Unix-based software, you will need to learn
138 how to use autoconf. Unfortunately, this topic deserves a book all its own and
139 is beyond the scope of this tutorial, but a book on the subject can be found
140 online at: http://sources.redhat.com/autobook/. Note that you do not need to
141 use automake when you are using Bakefile, just autoconf, as Bakefile
142 essentially does the same thing as automake.
143 ----------------------------
147 Every project needs to have a target or targets, specifying what is to be
148 built. In Bakefile, you specify the target by creating a tag named with the
149 target type. The possible names for targets are:
151 exe create an executable file
152 dll create a shared library
153 lib create a static library
154 module create a library that is loaded at runtime (i.e. a plugin)
156 Note the sample above is an "exe" target. Once you create the target, all the
157 build settings, including flags and linker options, should be placed inside
158 the target tag, as they are in the sample above.
160 -- Adding Sources and Includes --
162 Obviously, you need to be able to add source and include files to your
163 project. You add sources using the "<sources>" tag (as shown above), and add
164 include directories using the "<include>" tag. You can add multiple <sources>
165 and <include> tags to add multiple source files, or you can also add multiple
166 sources and includes into one tag by separating them with a space, like so:
168 <sources>minimal.cpp minimal2.cpp minimal3.cpp</sources>
170 If your sources are in a subfolder of your Bakefile, you use the slash "/"
171 character to denote directories, even on Windows. (i.e. src/minimal.cpp) For
172 more options and flags, please consult the Bakefile documentation in the 'doc'
173 subfolder of Bakefile, or you can also find it on the Bakefile web site.
177 What if you want to offer a DEBUG and a RELEASE build? Or a UNICODE/ANSI
178 build? You can do this in Bakefile by creating options. To create an option,
179 use the "<option>" tag. A typical option has three important parts: a name, a
180 default value, and a comma-separated list of values. For example, here is how
181 to create a DEBUG option which builds debug by default:
183 <option name="DEBUG">
184 <default-value>1</default-value>
188 You can then test the value of this option and conditionally set build
189 settings, flags, etc. For more information on both options and conditional
190 statements, please refer to the Bakefile documentation.
192 -- Bakefile Presets/Templates and Includes --
194 It is common that most projects will reuse certain settings, or options, in
195 their makefiles. (i.e. DEBUG or static/dynamic library options) Also, it is
196 common to have to use settings from another project; for example, any project
197 that uses wxWidgets will need to build using the same flags and options that
198 wxWidgets was built with. Bakefile makes these things easier by allowing users
199 to create Bakefile templates, where you can store common settings.
201 Bakefile ships with a couple of templates, found in the 'presets' subfolder of
202 your Bakefile installation. The "simple.bkl" template adds a DEBUG option to
203 makefiles so you can build in release or debug mode. To add this template to
204 your project, simply add the tag "<include file="presets/simple.bkl"/>" to the
205 top of your Bakefile. Then, when creating your target, add the
206 "template="simple"" attribute to it. Now, once you build the makefile, your
207 users can write commands like:
209 nmake -f makefile.vc DEBUG=1
213 make -f GNUmakefile DEBUG=1
215 In order to build the software in debug mode.
217 To simplify the building of wxWidgets-based projects, wxWidgets contains a
218 set of Bakefiles that automatically configure your build system to be
219 compatible with wxWidgets. As you'll notice in the sample above, the sample
220 project uses the wx template. Once you've included the template, your software
221 will now build with wxWidgets support.
223 But since the wx presets don't exist in the Bakefile presets subfolder,
224 Bakefile needs to know where to find these presets. The "-I" command adds the
225 wxpresets folder to Bakefile's search path.
227 If you regularly include Bakefile presets in places other than the Bakefile
228 presets folder, then you can set the BAKEFILE_PATHS environment variable so
229 that Bakefile can find these Bakefiles and include them in your project. This
230 way you no longer need to specify the -I flag each time you build.
232 Lastly, it's important to note that the Win 32 wx project Bakefiles come with
233 some common build options that users can use when building the software. These
236 Option Values Description
237 ------ ------ -------------
238 WX_MONOLITHIC 0(default),1 Set this to 1 if you built wx
239 as a monolithic library
240 WX_SHARED 0(default),1 Specify static or dynamic wx libs
241 WX_UNICODE 0(default),1 Use ANSI or UNICODE wx libs
242 WX_DEBUG 0,1(default) Use release or debug wx libs
243 *WX_VERSION 25,26(default) Specify version of wx libs
245 *Note: Any version of wx past 2.5 will be allowed here, so 25/26 is not a
246 complete list of values.
248 These options are not needed under Unix as wx-config can be used to specify
251 -- bakefile_gen - Automated Bakefile Scripts --
253 If you have a large project, you can imagine that the calls to Bakefile would
254 get more and more complex and unwieldy to manage. For this reason, a script
255 called bakefile_gen was created, which reads in a .bkgen file that provides
256 all the commands needed to build all the makefiles your project supports. A
257 discussion of how to use bakefile_gen is beyond the scope of this tutorial,
258 but it deserves mention because it can be invaluable to large projects.
259 Documentation on bakefile_gen can be found in the Bakefile documentation.
263 This concludes our basic tutorial of the cross-platform Bakefile build system
264 management tool. From here, please be sure to take a good look at the Bakefile
265 documentation to see what else it is capable of. Please post questions to the
266 bakefile-devel@lists.sourceforge.net list, or if you have questions specific
267 to the wx template Bakefile, send an email to wx-users@lists.wxwidgets.org.
269 Enjoy using Bakefile!