1----------------------------------------------------------------------- 2Creating a Cross-Platform Build System Using Bakefile 3The 10-minute, do-it-yourself wx project baking guide (with free sample recipes!) 4 5Status: DRAFT 6Author: Kevin Ollivier 7Date: 2/13/04 8License: wxWidgets License 9----------------------------------------------------------------------- 10 11Supporting many different platforms can be a difficult challenge. The 12challenge for wxWidgets is especially great, because it supports a variety of 13different compilers and development environments, including MSVC, Borland C++, 14MinGW, DevCPP, GNU make/automake, among others. Maintaining such a large 15number of different project files and formats can quickly become overwhelming. 16To simplify the maintenance of these formats, one of the wxWidgets developers, 17Vaclav Slavik, created Bakefile, a XML-based makefile wrapper that generates 18all the native project files for wxWidgets. So now, even though wxWidgets 19supports all these formats, wxWidgets developers need only update one file - 20the Bakefile, and it handles the rest. But Bakefile isn't specific to 21wxWidgets in any way - you can use Bakefile for your own projects, too. This 22brief tutorial will take a look at how to do that. 23 24Note that this tutorial assumes that you are familiar with how to build 25software using one of the supported Bakefile makefile systems, that you have 26some basic familiarity with how makefiles work, and that you are capable of 27setting environment variables on your platform. Also note that the terms Unix 28and Unix-based refers to all operating systems that share a Unix heritage, 29including FreeBSD, Linux, Mac OS X, and various other operating systems. 30 31-- Getting Started -- 32 33First, you'll need to install Bakefile. You can always find the latest version 34for download online at http://bakefile.sf.net. A binary installer is provided 35for Windows users, while users of Unix-based operating systems (OS) will need 36to unpack the tarball and run configure && make && make install. (Packages for 37some distros are also available, check http://bakefile.sf.net for details.) 38 39-- Setting Up Your wx Build Environment -- 40 41Before you can build wxWidgets software using Bakefile or any other build 42system, you need to make sure that wxWidgets is built and that wxWidgets 43projects can find the wxWidgets includes and library files. wxWidgets build 44instructions can be found by going to the docs subfolder, then looking for the 45subfolder that corresponds to your platform (i.e. msw, gtk, mac) and reading 46"install.txt" there. Once you've done that, here are some extra steps you 47should take to make sure your Bakefile projects work with wxWidgets: 48 49On Windows 50---------- 51Once you've built wxWidgets, you should create an environment variable named 52WXWIN and set it to the home folder of your wxWidgets source tree. (If you use 53the command line to build, you can also set or override WXWIN at build time by 54passing it in as an option to your makefile.) 55 56On Unix 57------- 58In a standard install, you need not do anything so long as wx-config is on 59your PATH. wx-config is all you need. (See the section of the book on using 60wx-config for more information.) 61 62-- A Sample wx Project Bakefile -- 63 64Now that everything is setup, it's time to take Bakefile for a test run. I 65recommend that you use the wx sample Bakefile to get you started. It can be 66found in the 'build/bakefiles/wxpresets/sample' directory in the wxWidgets 67source tree. Here is the minimal.bkl Bakefile used in the sample: 68 69minimal.bkl 70------------------------------------------------------------- 71<?xml version="1.0" ?> 72<!-- $Id: bakefile_quickstart.txt 37501 2006-02-11 18:41:11Z KO $ --> 73 74<makefile> 75 76 <include file="presets/wx.bkl"/> 77 78 <exe id="minimal" template="wx"> 79 <app-type>gui</app-type> 80 <debug-info>on</debug-info> 81 <runtime-libs>dynamic</runtime-libs> 82 83 <sources>minimal.cpp</sources> 84 85 <wx-lib>core</wx-lib> 86 <wx-lib>base</wx-lib> 87 </exe> 88 89</makefile> 90--------------------------------------------------------------- 91 92It's a complete sample ready to be baked, so go into the directory mentioned 93above and run the following command: 94 95On Windows: 96bakefile -f msvc -I.. minimal.bkl 97 98On Unix: 99bakefile -f gnu -I.. minimal.bkl 100 101It should generate a makefile (makefile.vc or GNUmakefile, respectively) which 102you can use to build the software. Just build the software using the command 103"nmake -f makefile.vc" or "make -f GNUmakefile" respectively. Now let's take a 104look at some of the basic Bakefile concepts that you'll need to know to move 105on from here. 106 107-- Project Types -- 108 109As mentioned earlier, Bakefile builds makefiles for many different 110development environments. The -f option accepts a list of formats that you 111would like to build, separated by commas. Valid values are: 112 113 autoconf GNU autoconf Makefile.in files 114 borland Borland C/C++ makefiles 115 cbuilderx C++ Builder X project files 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 124 125TIP: autoconf Project Type 126--------------------------- 127You may notice that in the sample folder, there is also a file called 128configure.in. That file is the input for autoconf, which creates the configure 129scripts that you often see when you build software from source on Unix-based 130platforms. People use configure scripts because they make your Unix makefiles 131more portable by automatically detecting the right libraries and commands to 132use on the user's machine and OS. This is necessary because there are many 133Unix-based operating systems and they all are slightly different in various 134small ways. 135 136Bakefile does not generate a configure or configure.in script, so if you want 137to use configure scripts with your Unix-based software, you will need to learn 138how to use autoconf. Unfortunately, this topic deserves a book all its own and 139is beyond the scope of this tutorial, but a book on the subject can be found 140online at: http://sources.redhat.com/autobook/. Note that you do not need to 141use automake when you are using Bakefile, just autoconf, as Bakefile 142essentially does the same thing as automake. 143---------------------------- 144 145-- Targets -- 146 147Every project needs to have a target or targets, specifying what is to be 148built. In Bakefile, you specify the target by creating a tag named with the 149target type. The possible names for targets are: 150 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) 155 156Note the sample above is an "exe" target. Once you create the target, all the 157build settings, including flags and linker options, should be placed inside 158the target tag, as they are in the sample above. 159 160-- Adding Sources and Includes -- 161 162Obviously, you need to be able to add source and include files to your 163project. You add sources using the "<sources>" tag (as shown above), and add 164include directories using the "<include>" tag. You can add multiple <sources> 165and <include> tags to add multiple source files, or you can also add multiple 166sources and includes into one tag by separating them with a space, like so: 167 168<sources>minimal.cpp minimal2.cpp minimal3.cpp</sources> 169 170If your sources are in a subfolder of your Bakefile, you use the slash "/" 171character to denote directories, even on Windows. (i.e. src/minimal.cpp) For 172more options and flags, please consult the Bakefile documentation in the 'doc' 173subfolder of Bakefile, or you can also find it on the Bakefile web site. 174 175-- Build Options -- 176 177What if you want to offer a DEBUG and a RELEASE build? Or a UNICODE/ANSI 178build? You can do this in Bakefile by creating options. To create an option, 179use the "<option>" tag. A typical option has three important parts: a name, a 180default value, and a comma-separated list of values. For example, here is how 181to create a DEBUG option which builds debug by default: 182 183<option name="DEBUG"> 184 <default-value>1</default-value> 185 <values>0 1</values> 186</option> 187 188You can then test the value of this option and conditionally set build 189settings, flags, etc. For more information on both options and conditional 190statements, please refer to the Bakefile documentation. 191 192-- Bakefile Presets/Templates and Includes -- 193 194It is common that most projects will reuse certain settings, or options, in 195their makefiles. (i.e. DEBUG or static/dynamic library options) Also, it is 196common to have to use settings from another project; for example, any project 197that uses wxWidgets will need to build using the same flags and options that 198wxWidgets was built with. Bakefile makes these things easier by allowing users 199to create Bakefile templates, where you can store common settings. 200 201Bakefile ships with a couple of templates, found in the 'presets' subfolder of 202your Bakefile installation. The "simple.bkl" template adds a DEBUG option to 203makefiles so you can build in release or debug mode. To add this template to 204your project, simply add the tag "<include file="presets/simple.bkl"/>" to the 205top of your Bakefile. Then, when creating your target, add the 206"template="simple"" attribute to it. Now, once you build the makefile, your 207users can write commands like: 208 209nmake -f makefile.vc DEBUG=1 210 211or 212 213make -f GNUmakefile DEBUG=1 214 215In order to build the software in debug mode. 216 217To simplify the building of wxWidgets-based projects, wxWidgets contains a a 218set of Bakefiles that automatically configure your build system to be 219compatible with wxWidgets. As you'll notice in the sample above, the sample 220project uses the wx template. Once you've included the template, your software 221will now build with wxWidgets support. 222 223But since the wx presets don't exist in the Bakefile presets subfolder, 224Bakefile needs to know where to find these presets. The "-I" command adds the 225wxpresets folder to Bakefile's search path. 226 227If you regularly include Bakefile presets in places other than the Bakefile 228presets folder, then you can set the BAKEFILE_PATHS environment variable so 229that Bakefile can find these Bakefiles and include them in your project. This 230way you no longer need to specify the -I flag each time you build. 231 232Lastly, it's important to note that the Win 32 wx project Bakefiles come with 233some common build options that users can use when building the software. These 234options are: 235 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(defualt),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 244 245*Note: Any version of wx past 2.5 will be allowed here, so 25/26 is not a 246complete list of values. 247 248These options are not needed under Unix as wx-config can be used to specify 249these options. 250 251-- bakefile_gen - Automated Bakefile Scripts -- 252 253If you have a large project, you can imagine that the calls to Bakefile would 254get more and more complex and unwieldly to manage. For this reason, a script 255called bakefile_gen was created, which reads in a .bkgen file that provides 256all the commands needed to build all the makefiles your project supports. A 257discussion of how to use bakefile_gen is beyond the scope of this tutorial, 258but it deserves mention because it can be invaluable to large projects. 259Documentation on bakefile_gen can be found in the Bakefile documentation. 260 261-- Conclusion -- 262 263This concludes our basic tutorial of the cross-platform Bakefile build system 264management tool. From here, please be sure to take a good look at the Bakefile 265documentation to see what else it is capable of. Please post questions to the 266bakefile-devel@lists.sourceforge.net list, or if you have questions specific 267to the wx template Bakefile, send an email to wx-users@lists.wxwidgets.org. 268 269Enjoy using Bakefile! 270