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 filename	What it is and what it contains
MYourApp.cp	This code file contains the main routine.
UYourApp.h	This interface file contains class definitions and function prototypes. This file is not required but is almost always included.
UYourApp.cp	This implementation file contains the actual code. (It can also be named UYourApp.xx.cp with the xx used to number multiple files.)
YourApp.r	This file contains resource definitions. It is optional; if you do not provide it, MABuild uses MacApp's defaults.r resource file.
YourApp.MAMake	This 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:

• Any option can be specified on the command line.
• You can specify as many options as you like. To continue a command on the next line, type the continuation character (Option-d) and press Return. When you've finished typing, select the whole command and press Enter.
• Each option is preceded by a hyphen, and case is not significant. Some options take parameters, however, and case in parameters may be significant.
• If the parameter has a space in it, you must enclose the whole parameter in single or double quotation marks. If you aren't familiar with the use of quotation marks in the MPW command line, read the section "Quoting Special Characters" in the Macintosh Programmer's Workshop Reference.

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.

Note

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.

• -Attachable

  Using this option tells MABuild to set the qAttachable flag to TRUE, which causes the build to include MacApp's support for attaching scripts to application objects. You can include code for attaching scripts with a command line like the following:

  MABuild "{MASamples}Calc:Calc" -Attachable

• -AutoBuild

  Using this option tells MABuild to also build the version of the MacApp library that corresponds to the version of your application you are building. MABuild uses the file MacApp.lib.MAMake to aid in building MacApp.

  For example, to build a Power Macintosh version of the Calc sample application, and to make sure the corresponding MacApp library is built, you could use the following command line:

  MABuild "{MASamples}Calc:Calc" -cp MrC -AutoBuild

• -Debug

  Using this option tells MABuild to create a debug version of your application. The application is placed in a folder called

  {YourAppFolder}xDebug:

  where x is a character specified by the MASeparateObjectsPrefix shell variable. For example, the complete folder name might be

  YourHardDisk:YourApp:%Debug:

  When you turn debugging on, MacApp embeds conditional debugging assertions in your code. It also builds your application to include symbols. Be aware that the debugging code adds considerable size to your code. (See also -NoDebug and -Sym below.)

• -Drag

  This option builds a version of MacApp with code support for drag and drop. Drag and drop is a Macintosh feature based on the Drag Manager that lets a user drag selected information between windows or applications. For more information, see Chapter 28, "Working With Drag and Drop."

• -ExpandEnvVars

  This option is useful as a debugging aid when you're having a problem building your application and you're not sure what's happening in the build system. This option causes all build environment variables to be expanded in the YourApp.MakeIt file that is generated during the build. You can then examine the file to look for clues to what went wrong.

• -ModelCFM

  This option specifies that the application will use CFM-68K, the 68K Macintosh version of the Power Macintosh Code Fragment Manager.

• -ModelFar

  This option specifies full 32-bit addressing--the application can use 32-bit addressing for global data and have code segments larger than 32 KB. Keep in mind that your application will have faster, more compact code if you avoid using full 32-bit addressing. For example, if you have a segment that is larger than 32 KB, you may be able to rearrange your code to minimize the segment size, instead of using the -ModelFar option.

• -Names

  To use a low-level debugger such as MacsBug, you must build your code with the -Names option on. This option embeds MacsBug debugging symbols in your code. It is a good idea to include this option when you are debugging a serious problem, since it may be necessary to switch from a source-level debugger to a low-level debugger when you encounter unrecoverable errors.

  MacApp turns on the -Names option automatically whenever you build with the -Debug option on. And like the -Debug option, the -Names option automatically builds your application with symbol information (see -Sym).

• -NoDebug

  When your application is ready to ship, you use this option to turn off MacApp's debugging features. This will reduce the size of the executable application and make it run faster. Your object files and the nodebug version of the executable application will appear in a separate folder. You don't generally need to specify this option, because it's the default. (See also -Debug.)

• -PowerTalk

  This option builds a version of MacApp with code support for PowerTalk electronic mailers. To take advantage of this support, your application must supply certain code as well, as described in Chapter 29, "Working With PowerTalk Mailers."

• -P and -PP

  These options are useful for learning about the MABuild system and for tracking down problems in your build. -P tells the MABuild system to show progress statements. -PP specifies that all tools invoked by the MABuild system should also show progress statements. Keep in mind that using -P or -PP can generate a large amount of output to your MPW worksheet and slow down the build process significantly.

• -Sym

  To create a version of your application that is compatible with Apple Computer's source code debuggers, you should specify the -Sym flag. Your object files and executable application will be stored in a folder named %68k Sym (where the % character is set according to the variable MASeparateObjectsPrefix). If you want to create a version compatible with source-level debugging, but with MacApp's own debugging options turned on, you should specify both the -Sym and the -Debug options. Object files and applications created with both those options will be placed in a folder called %Debug.

  For example, to build a 68K debug version of the DemoDialogs sample application for use with a source-level debugger, you could use the following command line:

  MABuild "{MASamples}DemoDialogs:DemoDialogs" -debug

  The -Sym option is turned off by default, unless you change the UserStartupMacApp file to specify otherwise. You can turn it on specifically by using -Sym or, as in this case, by specifying -debug, which automatically turns on symbol support.

  You can specify a specific symbol table format that is compatible with your debugger. To do so, use the documentation for your linker to determine how to specify the desired symbol format, then pass on the required information to the linker in your MABuild command line.

  For example, to specify the 3.2 symbol format to the MPW Link tool, you use a build line like the following:

  MABuild -sym -link "-sym 3.2"

  The "-sym 3.2" option is passed on to the Link tool.

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 option	Result
-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.
-E	Pass 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.
-R	Pass through -R to Make and write results of Make to stdout.
-Rez option [option...]	Pass through options to Resource compiler.
-S	Pass 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 MacApp.help. 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.

Note

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.

• AppName. AppName is the name of the application (it must be defined when you create a custom makefile).
• BuildingBlocksCPlusIntf. BuildingBlockCPlusIntf is a list of the MacApp building-block interface files the application uses and is dependent on. For example, if your application uses MacApp's printing unit, you would add a line like the following:

  BuildingBlockCPlusIntf = "{MACPlusIncludes}UPrinting.h"

  If you are not using any of the interfaces (as defined in the file Definitions_Common), define this interface to nothing, so your files won't depend on it:

  BuildingBlocksCPlusIntf = 

• NeededSysLibs. NeededSysLibs is a list of required system libraries (you don't normally need to add any libraries to this variable, since the default includes the full set).
• OtherAsmOptions. The OtherAsmOptions variable allows you to define options for assembling assembly-language modules, in addition to those specified by the AsmOptions variable defined by the MABuild tool.
• OtherCOptions. The OtherCOptions variable allows you to define options for compiling C language modules, in addition to those specified by the OtherCOptions variable defined by the MABuild tool.
• OtherCPlusOptions. The OtherCPlusOptions variable allows you to define options for compiling C++ language modules, in addition to those specified by the CPlusOptions variable defined by the MABuild tool.
• OtherCreatorAndBundleOptions. The OtherCreatorAndBundleOptions variable allows you to define options for the CreatorAndBundle MPW tool, in addition to those specified by the CreatorAndBundleOptions variable defined by the MABuild tool. The CreatorAndBundle tool sets the creator type and bundle bit for the application file. You rarely need to use the OtherCreatorAndBundleOptions variable.
• OtherInterfaces. OtherInterfaces is a list of interfaces the application uses in addition to those found in the {MACPlusIncludes}, {MARIncludes}, and {MAAIncludes} directories (which are specified in the 1Startup file).
• OtherLibOptions. The OtherLibOptions variable allows you to define options for the current library tool (such as MPW's Lib tool), in addition to those specified by the OtherLibOptions variable defined by the MABuild tool.
• OtherLinkFiles. The OtherLinkFiles variable allows you to specify object files that should be linked into the application, in addition to the default file YourApp.o.
• OtherLinkFiles68K. The OtherLinkFiles68K variable allows you to specify object files that should be linked into the application for a 68K build. It is used by the Dependencies_68K file.
• OtherLinkFilesPPC. The OtherLinkFilesPPC variable allows you to specify object files that should be linked into the application for a Power Macintosh build. It is used by the Dependencies_PPC file.
• OtherLinkOptions. The OtherLinkOptions variable allows you to define options for the current linker, in addition to those specified by the LinkOptions variable defined by the MABuild tool.
• OtherMakeSymOptions. The OtherMakeSymOptions variable allows you to define options for the MakeSYM tool, in addition to those specified by the MakeSymOptions variable defined by the MABuild tool.

  The MakeSYM tool extracts debugging information from an XCOFF file. XCOFF (Extended Common Object File Format) is a container format recognized by the Code Fragment Manager. By default, MacApp does not build a symbol file for Power Macintosh builds. If your debugger is unable to extract symbol information directly from an XCOFF file, you can modify the file Dependencies_PPC to instruct the MakeSYM tool to generate a symbol file. Simply uncomment the lines that invoke MakeSYM.

• OtherRezFiles. OtherRezFiles is a list of resource definition files, other than AppName.r, that should be included in the Rez command. Resources from files in this list will be compiled and included in your output file.
• OtherRezOptions. The OtherRezOptions variable allows you to define options for the Rez tool, in addition to those specified by the RezOptions variable defined by the MABuild tool. Rez is a resource compiler that converts text resource definitions into compiled resource format.
• OtherRsrcFiles. This is a list of resource files, other than the Debug.rsrc and MacApp.rsrc files, that should be part of dependency checking. Files in this list are not automatically included in your output file--you must include them into one of your resource definition files with an Include statement.

  Your resource definition files, such as AppName.r, can include text resource definition files and compiled resources (the output of the Rez resource compiler). You include a text resource definition file with a line like

  #include "MacAppTypes.r"

  However, OtherRsrcFiles is used only for files that are included as compiled resources (and that need to be built before they are included). You include a compiled resource file with a line like

  include "MacApp.rsrc" not 'ckid';

  This line excludes the 'ckid' resource, used for source code version control. For more information, see the Macintosh Programmer's Workshop Reference.

• OtherSegMappings. OtherSegMappings is a list of -sn (segment name) commands for the linker. Segmentation is described in "Segment Management (68K-Based Applications Only)" on page 75 in Chapter 3, "Core Technologies."
• OtherViewTypesSrc. When the Rez tool builds a view resource from a text description of a view, it uses the file ViewTypes.r to obtain view template definitions. If you have custom view types you wish to initialize from text descriptions, you can use the OtherViewTypesSrc variable to specify a file containing view template definitions for your custom views, to be included into the ViewTypes.r file. (For more information on view templates, see "Working With View Resource Templates," beginning on page 425.)

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 
   "{SRCAPP}"MyApp.a 
   "{SRCAPP}"AnInclude.a

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.

Note

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