Previous Book Contents Book Index Next

Inside Macintosh: Programmer's Guide to MacApp / Part 2 - Working With MacApp
Appendix A - Working With the MacApp Build System

Inputs You Provide to MABuild

The inputs you provide for MABuild include source code files, build option parameters, and changes you make to shell variables. In all but the simplest programs, you must also supply your own resource definition file and your own makefile (named YourApp.MAMake). If your program fits the "magic five" filename configuration discussed in the next section, you won't need a makefile.

The Magic Five Files

During the build process, MABuild looks for five files that are named after your application. In a simple application you may have only four--the first four in Table A-1--or even fewer. In the most trivial programs you may put all your code into the main program module. In these two cases, MABuild can manage without the makefile. (See also "Creating a Makefile" on page 683.) Table A-1 lists the magic five filenames for the application named YourApp.

MABuild Options

MABuild has more than 50 command-line options. They range from options passed directly to the compiler to options that control the level of diagnostics printed while MABuild is running.

Each option has a default written into MABuild, and that default can in turn be modified by setting a global MPW shell variable. Options specified on the command line override or extend options specified by the MPW shell variable MABuildDefaults. (See the note on page 672.) The shell variable in turn overrides or extends defaults written into the MABuildTool code.

Table A-1 Table A-1 The five default filenames MABuild looks for
Template for filenameWhat it is and what it contains
MYourApp.cpThis code file contains the main routine.
UYourApp.hThis interface file contains class definitions and function prototypes. This file is not required but is almost always included.
UYourApp.cpThis implementation file contains the actual code. (It can also be named UYourApp.xx.cp with the xx used to number multiple files.)
YourApp.rThis file contains resource definitions. It is optional; if you do not provide it, MABuild uses MacApp's defaults.r resource file.
YourApp.MAMakeThis is an MPW script you write to tell MPW's Make tool how to build any additional files included in your application.

Modifying MABuild's Default Behavior

Many builds will not fall into the categories described thus far. Perhaps your application has neither the "magic five" file configuration nor a one-file configuration, or perhaps you'd like to modify MABuild's default behavior.

If your application does not have a simple file configuration, you need to provide a makefile called YourApp.MAMake, as described in "Creating a Makefile," beginning on page 683. If you want to override MABuild's default behavior, you can simply specify command-line options or you can modify the global shell variables defined in MacApp's 1Startup file (see page 672).

Specifying Command-Line Options

When specifying command-line options in MPW, keep the following in mind:

Building Native Applications

"Types of Macintosh Computers" on page 4 describes the different flavors of Macintosh computer. The MABuild system defaults to building a native 68K application.

Native Power Macintosh Applications

To build a Power Macintosh application, you specify a Power Macintosh compiler. For example, to build a native Power Macintosh application using the MrC RISC compiler, you type a command line like the following:

MABuild YourApp -cp MrC

Fat Applications

A fat application is an application that contains 68K Macintosh code in its resource fork and native Power Macintosh code in its data fork so that it can run native on either machine. To build a fat application, you first build a 68K version of your application, with a command line like the following:

MABuild YourApp [-options]
You then build a Power Macintosh version, and include the code from the 68K version, with a command line using the -Fat option:

MABuild YourPPCApp -cp MrC -Fat YourApp [-options]

Building Noncode Resources

You can build a version of your application that contains all resources except 'CODE' resources by using the -RSRC option on your command line:

MABuild YourApp -RSRC
MPW's Rez compiler can translate a text resource definition file (for example, YourResourceFile.r) into a compiled resource file (YourResourceFile.rsrc). Since it may be easier to build compiled resources with MPW and Rez than to do so in an integrated development environment (IDE), MABuild provides the -RSRC option. It allows you to generate all the compiled resources for your application, except for any 'CODE' resources (which an IDE is quite comfortable with).

Common Command-Line Options

Some of the most commonly used MABuild command-line options are -[no]Attachable, -[no]AutoBuild, -[no]Debug, -[no]Drag, -[no]ExpandEnvVars, -[no]ModelCFM, -[no]ModelFar, -[no]Names, -[no]PowerTalk, -[no]P, -[no]PP, and -[no]Sym.

The syntax "-[no]" indicates that an option can have the word no prepended to it to specifically turn the option off. However, for all the options shown here, except P for show progress, the option defaults to off, so you don't need to specifically turn them off.

For an exhaustive list of MABuild options, type the following line in your MPW worksheet and press Enter:
Help -f "{MacApp}"MacApp.Help MABuild           

The most commonly used command-line options are discussed next.

Pass-Through Options

Table A-2 shows MABuild command-line syntax that allows you to pass options through to specific build tools.
Table A-2 MABuild command-line pass-through options
Command-line optionResult
-Asm option [option...]Pass through options to assembler.
-C option [option...]Pass through options to C compiler.
-CFront option [option...]Pass through options to MPW C++ (AT&T CFront).
-CPlusPlus option [option...]Pass through generic C++ compiler options.
-CreatorAndBundle option [option...]Pass through options to CreatorAndBundle tool.
-EPass through -E to Make--rebuild everything, regardless of date.
-Lib option [option...]Pass through options to librarian.
-Link option [option...]Pass through options to linker.
-Make option [option...]Pass through options to Make.
-MakeSYM option [option...]Pass through options to MakeSYM.
-MrC option [option...]Pass through options to Macintosh RISC C/C++ compiler.
-MWC68K option [option...]Pass through options to Metrowerks C/C++ 68K compiler.
-MWCPPC option [option...]Pass through options to Metrowerks C/C++ PPC compiler.
-PPCAsm option [option...]Pass through options to PPC assembler.
-PPCLib option [option...]Pass through options to PPC librarian.
-PPCLink option [option...]Pass through options to PPC linker.
-RPass through -R to Make and write results of Make to stdout.
-Rez option [option...]Pass through options to Resource compiler.
-SPass through -S to Make--write results of Make to stdout.
-SCpp option [option...]Pass through options to the Symantec C++ compiler.

Other Command-Line Options

You can read about MABuild's other command-line options in the file To display just the MABuild options, type the following line in your MPW worksheet and press Enter:

Help -f "{MacApp}"MacApp.Help MABuild

Creating a Makefile

You can build simple MacApp applications using MABuild's default configuration, but most applications created with MABuild need to have a makefile. You should name the makefile after your application, in the form YourApp.MAMake. In the makefile you specify the application name, the signature, and the files your application depends on.

The makefile you create is really a partial makefile, also called an MAMakefile (or MacApp Makefile). The MABuild system allows you to specify just the make information necessary for your own files, then combines it with other information to build your application. For convenience, we refer to both kinds of files as makefiles.
To create your own makefile, in the simplest case you can copy an existing makefile and perform a global search and replace, changing the setting for the variable AppName from the old application's name to the name of your new application.

In the {MACPlusExamples} folder, MacApp provides several sample applications that use makefiles. These makefiles include DemoDialogs.MAMake, DemoText.MAMake, Skeleton.MAMake, and Calc.MAMake. You'll find another makefile, called MacApp.lib.MAMake, in the {MALibraries} folder.

The First Half of the Makefile Contains Definitions

You may want to define values in your makefile for any of the following variables.

The MABuild script calls the MABuild tool, passing the command-line parameters you specify. The MABuild tool invokes the Make tool, using the makefile for the specified application (YourApp.MAMake). Make uses input files in the following order: Definitions_Common, Definitions_68K (Definitions_PPC for a Power Macintosh build), YourApp.MAMake (if supplied), and Dependencies_68K (Dependencies_PPC for a Power Macintosh build). Because of this order, you can use your makefile to redefine any of the variables set in Definitions_Common or one of the other definitions files. You can read about the Make tool in the Macintosh Programmer's Workshop Reference.

The Second Half of the Makefile Contains Dependencies

If you want to specify any additional files (such as assembly-language files) that need to be linked with your application, you must provide Make with dependencies (or build rules) for them in your makefile. For example,

OtherLinkFiles = "{OBJAPP}"MyApp.a.o

"{OBJAPP}"MyApp.a.o florin 
The florin character indicates a build dependency. The file MyApp.a.o depends on the files that follow, and should be updated if any of the following files has a more recent modification date. The character is used to indicate that a line is continued on the next line, so this whole dependency is interpreted as one line.

Note that the florin character is produced by pressing Option-f and the character by pressing Option-d.

A build rule must begin against the left margin of the file, or it will be ignored by Make. There must be no blank lines between the specified files.

You don't need to specify build rules for assembly-language files unless the default rules specified in the Dependencies_68K file (or Dependencies_PPC for a Power Macintosh build) are not sufficient.

There are third-party products that can generate a makefile for the files in a project.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
25 JUL 1996