7 November 2000

Building ZooLib Demo Applications

Background

There are a couple of constraints that dictate how the source for ZooLib-based applications are laid out and how we manage the build process. First, ZooLib is under daily development, so it's still geared towards being built from source and statically linked, rather than being built as a shared library to be linked with at runtime (although this does work on POSIX/BeOS). Second, many of the current ZooLib developers are responsible for either multiple ZooLib-based applications, or a single application on multiple platforms, or both.

So, we've evolved a general layout where there are three directories of interest for a project.

The ZooLib source directory itself.
The source directory for the particular application.
Each application also has one build directory per platform or compiler.

The idea is to be able to keep a single copy of the ZooLib and application sources on a machine accesible via file sharing to all of the build machines. Each build machine keeps the appropriate platform/compiler specific build directory on a local drive. This allows edits to the source to be immediately checked out on all platforms, without having to schlepp files around by FTP or having to check into and back out of CVS. It also keeps the source directories from getting "polluted" with object files -- so backups can be made easily, and multiple build machines or compile-time settings don't conflict with one another.

General build instructions

First grab the zoolib and zoolib-demos archives in whatever format is most convenient for you (they all have the same content). Create a directory (say "testzoolib") and expand both archives into it. You'll have a directory layout like this:

testzoolib
    zoolib
        {a whole bunch of directories}
    zoolib-demos
        ButtonMessage
        ButtonMessage-build-be
        ButtonMessage-build-cw
        ButtonMessage-build-posix
        ZHelloWorld
        ZHelloWorld-build-be
        ZHelloWorld-build-cw
        ZHelloWorld-build-posix

zoolib contains all the ZooLib source files. zoolib-demos contains the ButtonMessage and ZHelloWorld source directories (no suffix) and build directories (-build-xxxx).

Building for POSIX/BeOS

To build ButtonMessage for posix, cd to

  testzoolib/zoolib-demos/ButtonMessage-build-posix

and type "make". For BeOS, cd to

  testzoolib/zoolib-demos/ButtonMessage-build-be

and type "make". Generally, that's all you'll need to do. For both posix and beOS you'll notice that the makefile itself is very short. It simply sets up a handful of macros to identify where the source files live, then includes the "realmake" file containing the actual rules for the application and finally includes the appropriate platform-specific makefile-engine, which contains the generic rules for building an application. If you decide to keep the ZooLib source directory elsewhere in the file system, simply edit the definition of ZOOLIB_ROOT in makefile to reference that location (you can use either relative or absolute paths, as desired).

If you have immediate problems the most likely cause is that makefile, realmake or the source files have line endings that make or the compiler don't recognize. It's reached the point now that most development tools can deal with any of the line ending conventions, except on UNIX systems, which steadfastly insist on LF (0x0A). So that's what ZooLib uses (and we recommend you do too).

When build for POSIX systems you might also need to either create a link from /usr/X11/lib/ to (for example) /usr/X11R6/lib/. Or edit the LIBPATHS_POSIX line in ButtonMessage/realmake or ZHelloWorld/realmake to reference the location of your X11 libraries.

Building for CodeWarrrior

BEFORE YOU START -- Read the sections "Background" and "General build instructions" above. Now open CodeWarrior's IDE preference dialog ("Preferences" in the Edit menu), and create two source tree entries. The first must be called "zoolib" (all lower case) and must point at the zoolib folder you just installed, the second must be called "zoolib-demos" and must point at the zoolib-demos folder (don't worry, you can remove them later if you wish).

Having created the source tree entries, you can either open the binary .mcp file, or import the .mcp.xml file into a new project -- they're entirely equivalent, we're just providing the xml file in case you're archive expansion tool munges the binary file.

Using the source trees entries makes it very easy to move the zoolib source directory elsewhere on your machine, or indeed on to a volume mounted over AppleShare or other network file system.

Build your demo application of choice as normal (selecting "Make" from the Project menu). There are several targets for each application: debug and release versions of PowerPC, 68K, Win32 and Carbon. NOTE: Support for Carbon is incomplete, the problems are well isolated though and will get fixed soon.

Michael D. Crawford GoingWare Inc. - Expert Software Development and Consulting http://www.goingware.com crawford@goingware.com

Tilting at Windmills for a Better Tomorrow.

[ZooLib Home] [info@zoolib.org]