Cross-Platform Builds Using Bakefile

team bbl


Maintaining a large number of different project files and formats can quickly become overwhelming. To simplify the maintenance of these formats, Vaclav Slavik created Bakefile, an XML-based makefile wrapper that generates all the native project files for wxWidgets. So now, even though wxWidgets supports all these formats, wxWidgets developers need only update one filethe bakefileand Bakefile handles the rest. Fortunately, Bakefile isn't specific to wxWidgets in any wayyou can use Bakefile for your own projects.

Note that this tutorial assumes that you are familiar with how to build software using one of the supported makefile systems, that you have some basic familiarity with how makefiles work, and that you are capable of setting environment variables on your platform. Also note that the terms "Unix" and "Unix-based" refer to all operating systems that share a Unix heritage, including FreeBSD, Linux, Mac OS X, and various other operating systems.

Getting Started

First, you'll need to install Bakefile. You can always find the latest version for download at Bakefile's web site: http://bakefile.sf.net.

It is also available on the CD-ROM included with this book. A binary installer is provided for Windows users, whereas users of Unix-based operating systems will need to unpack the tarball and run Packages for some distributions are also available; check the web site for details.

 configure && make && make install 

Setting Up Your wxWidgets Build Environment

Before you can build wxWidgets software using Bakefile or any other build system, you need to make sure that wxWidgets is built and that wxWidgets projects can find the wxWidgets includes and library files. wxWidgets build instructions can be found by going to the docs subfolder, then looking for the subfolder that corresponds to your platform (such as msw, gtk, mac) and reading install.txt there. After you've done that, the following sections provide some extra steps you should take to make sure your Bakefile projects work with wxWidgets.

On Windows

After you've built wxWidgets, you should create an environment variable named WXWIN and set it to the home folder of your wxWidgets source tree. (If you use the command line to build, you can also set or override WXWIN at build time by passing it in as an option to your makefile.)

On Unix and Mac OS X

In a standard install, you need not do anything as long as wx-config is on your PATH. wx-config is all you need; see "Using wx-config" later in this appendix.

A Sample wxWidgets Project Bakefile

Now that everything is set up, it's time to take Bakefile for a test run. It is recommended that you use the wxWidgets sample bakefile to get started. It can be found in the build/bakefiles/wxpresets/sample directory in the wxWidgets source tree. Here is the minimal.bkl bakefile used in the sample:

 <?xml version="1.0" ?> <! $Id: minimal.bkl,v 1.1 2005/01/27 22:47:37 VS Exp $ > <makefile>     <include file="presets/wx.bkl"/>     <exe  template="wx">         <app-type>gui</app-type>         <debug-info>on</debug-info>         <runtime-libs>dynamic</runtime-libs>         <sources>minimal.cpp</sources>         <wx-lib>core</wx-lib>         <wx-lib>base</wx-lib>     </exe> </makefile> 

It's a complete sample ready to be baked, so go into the directory mentioned previously and run the following command.

On Windows:

 bakefile -f msvc -I.. minimal.bkl 

On UNIX:

 bakefile -f gnu -I.. minimal.bkl 

It should generate a makefile (makefile.vc or GNUmakefile, respectively), which you can use to build the software. You can then build the software using the command nmake -f makefile.vc or make -f GNUmakefile respectively. Now let's take a look at some of the basic Bakefile concepts that you'll need to know to move on from here.

Project Types

As mentioned earlier, Bakefile builds makefiles for many different development environments. The -f option accepts a list of formats that you would like to build, separated by commas. Valid values are shown in Table B-1.

Table B-1. Bakefile Project Types

autoconf

GNU autoconf Makefile.in files

borland

Borland C/C++ makefiles

cbuilderx

C++ Builder X project files

dmars

Digital Mars makefiles

dmars_smake

Digital Mars makefiles for SMAKE

gnu

GNU toolchain makefiles (Unix)

mingw

MinGW makefiles (mingw32-make)

msevc4prj

MS Embedded Visual C++ 4 project files

msvc

MS Visual C++ nmake makefiles

msvc6prj

MS Visual C++ 6.0 project files

watcom

OpenWatcom makefiles


autoconf Project Type

You may notice that in the sample folder, there is also a file called configure.in. That file is the input for autoconf, which creates the configure scripts that you often see when you build software from source on Unix-based platforms. People use configure scripts because they make your Unix makefiles more portable by automatically detecting the right libraries and commands to use on the user's operating system. This is necessary because there are many Unix-based operating systems and they are all slightly different.

Bakefile does not generate a configure or configure.in script, so if you want to use these scripts with your Unix-based software, you will need to learn how to use autoconf. Unfortunately, this topic deserves its own a book and is beyond the scope of this tutorial, but a free book on the subject can be found online at: http://sources.redhat.com/autobook/.

Note that you do not need to use automake when you are using Bakefile, just autoconf, as Bakefile essentially does the same thing as automake.

Targets

Every project needs to have a target or targets, specifying what is to be built. With Bakefile, you specify the target by creating a tag named with the target type. The possible names for targets are shown in Table B-2.

Table B-2. Bakefile Targets

exe

Create an executable file.

dll

Create a shared library.

lib

Create a static library.

module

Create a library that is loaded at runtime (a plugin).


Note that the previous sample is an "exe" target. After you create the target, all the build settings, including flags and linker options, should be placed inside the target tag as they are in the minimal.bkl sample.

Adding Sources and Includes

Obviously, you need to be able to add source and include files to your project. You add sources using the <sources> tag (as shown previously), and you add include directories using the <include> tag. You can add multiple <sources> and <include> tags to add multiple source files, or you can add multiple sources and includes into one tag by separating them with a space, like this:

 <sources>minimal.cpp minimal2.cpp minimal3.cpp</sources> 

If your sources are in a subfolder of your Bakefile, you use the slash character to denote directories, even on Windows. (For example, src/minimal.cpp.) For more options and flags, please consult the Bakefile documentation in the doc subfolder of Bakefile or on the Bakefile web site.

Build Options

What if you want to offer a debug and a release build? Or separate Unicode and ANSI builds? You can do this in Bakefile by creating options. To create an option, use the <option> tag. A typical option has three important parts: a name, a default value, and a comma-separated list of values. For example, here is how to create a DEBUG option that builds debug by default:

 <option name="DEBUG">       <default-value>1</default-value>       <values>0 1</values> </option> 

You can then test the value of this option and conditionally set build settings, flags, and so on. For more information on both options and conditional statements, please refer to the Bakefile documentation.

Bakefile Presets/Templates and Includes

Most projects will reuse certain settings, or options, in their makefiles, such as DEBUG or static/dynamic library options. Also it is common to have to use settings from another project; for example, any project that uses wxWidgets will need to build using the same flags and options used to build wxWidgets. Bakefile makes these things easier by letting users create Bakefile templates, where you can store common settings.

Bakefile ships with a couple of templates, found in the presets subfolder of your Bakefile installation. The simple.bkl template adds a DEBUG option to makefiles so that you can build in release or debug mode. To add this template to your project, simply add the tag <include file="presets/simple.bkl"/> to the top of your bakefile. Then, when creating your target, add the template="simple" attribute to it. Now, when you have built the makefile, your users can write commands like

 nmake -f makefile.vc DEBUG=1 

or

 make -f GNUmakefile DEBUG=1 

in order to build the software in debug mode.

To simplify the building of wxWidgets-based projects, wxWidgets contains a set of bakefiles that automatically configure your build system to be compatible with wxWidgets. As you'll notice in the previous sample, the sample project uses the wx template. After you've included the template, your software will now build with wxWidgets support.

Because the wxWidgets presets don't exist in the Bakefile presets subfolder, Bakefile needs to know where to find these presets. The -I command adds the wxpresets folder to Bakefile's search path.

If you regularly include Bakefile presets in places other than the Bakefile presets folder, then you can set the BAKEFILE_PATHS environment variable so that Bakefile can find these Bakefiles and include them in your project. This way you no longer need to specify the -I flag each time you build.

Lastly, it's important to note that the Win32 wx project bakefiles come with some common build options that users can use when building the software. These options are shown in Table B-3.

Table B-3. Bakefile Build Options

Option

Values

Description

WX_SHARED

0 (default), 1

Specify static or dynamic wxWidgets libs.

WX_UNICODE

0 (default), 1

Use ANSI or Unicode wxWidgets libs.

WX_DEBUG

0, 1 (default)

Use release or debug wxWidgets libs.

WX_VERSION

25 and higher (default is 26)

Specify version of wxWidgets libs.


Note that these options are not needed under Unix because wx-config can be used to specify these options.

bakefile_genAutomated Bakefile Scripts

If you have a large project, you can imagine that the calls to Bakefile would get more and more complex and unwieldy. For this reason, a script called bakefile_gen was created, which reads in a .bkgen file that provides all the commands needed to build all the makefiles your project supports. A discussion of how to use bakefile_gen is beyond the scope of this tutorial, but it deserves a mention because it can be invaluable to large projects. Documentation on bakefile_gen can be found in the Bakefile distribution.

Conclusion

This concludes our basic tutorial of the cross-platform Bakefile build system management tool. From here, please be sure to take a good look at the Bakefile documentation to see what else it is capable of. Please post questions to the Bakefile mailing list, or if you have questions specific to the wxWidgets template Bakefile, send an email to the wxWidgets mailing list. See the Bakefile and wxWidgets web sites for information on how to subscribe to these lists.

Enjoy using Bakefile!

    team bbl



    Cross-Platform GUI Programming with wxWidgets
    Cross-Platform GUI Programming with wxWidgets
    ISBN: 0131473816
    EAN: 2147483647
    Year: 2005
    Pages: 262

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net