Instructions - The Assembly Language Examples

Copyright Apple Computer, Inc. 1987-1990
All rights reserved.


About the Examples

	Three sample assembly language programs are included with MPW:
	an application, a tool, and a desk accessory:
	
		Sample   - a simple MultiFinder-Aware Sample application
		Count		- an MPW tool
		Memory 	- a sample desk accessory

	The source files for each of these examples are in the
	"Examples:AExamples:" folder.  In addition, a makefiles
	that contains the commands needed to build each of the
	examples is provided in the same folder.
	

Building the Examples

	You can easily build each of the sample programs using the Directory
	and Build menus.  (See Chapter 2 of the MPW Reference.)
	
	Set the default directory to "AExamples:"

		The simplest way to do this is to select from the Directory menu
		the menu item that ends in "AExamples:".  You can also set the
		default directory by using the Directory and SetDirectory commands.
		

	Build the program
	
		You can use any of the four Build items at the bottom of the Build
		menu to build the program you have selected.  Each of these menu
		items displays a dialog box that asks for the name of the program
		you want to build.  When this dialog box appears, type the name of
		one of the sample programs (Sample, Count, or Memory).
		
		Each of the Build menu items behaves slightly differently:
		
			Build…  -  The program is automatically built.  The commands
			used, and any error messages, are displayed in the Worksheet.
			Only files that have been changed since you last built the
			program are compiled, saving considerable time.
	
			Full Build…  -  The program is completely rebuilt, ignoring
			any object files or intermediate files that may already exist
			from a previous build.  The commands used, and any errors, are
			displayed in the Worksheet.
			
			Show Build Commands…  -  The commands needed to build the program
			are written to the Worksheet, but not executed.  You can then
			select any or all of the commands and execute them yourself.
			(To execute the commands select them and press Enter.)
			
			Show Full Build Commands…  -  The commands needed to completely
			rebuild the program are written to the Worksheet.  This is a
			convenient way to see all of the commands used in building
			the program you have selected.


   Note: For more information about building the sample programs, see
   Chapter 2 of the MPW Reference.



Sample - A Simple MultiFinder-Aware Sample Application

	Sample is an example application that demonstrates how to initialize
	the commonly used toolbox managers, operate successfully under 
	MultiFinder, handle desk accessories and create windows.
	The source for Sample provides an excellent framework for basing 
	new applications. The source is contained in the files Sample.a
	and SampleMisc.a and Sample.inc1.a, resource descriptions are
	contained in the files Sample.h and Sample.r. The make dependency
	file is named Sample.make.

   To build Sample, simply select the line below and press Enter.

		BuildProgram Sample ∑∑ {Worksheet}

   To execute Sample, select the line below and press Enter.

		Sample



Count - A Sample MPW Tool

	Count, a tool that runs in the MPW environment, counts characters and
	lines in files.  A version of Count is included with MPW, and is
	documented in the MPW Reference, Part II.  The source for Count is in
	the files Count.a, FStubs.a, and Count.r.  MakeFile contains the
	commands for building Count.

   To build Count, simply select the line below and press Enter.

		BuildProgram Count ∑∑ {Worksheet}

   To test Count, try counting the characters in file Count.a.

	  Count -c Count.a



Memory - A Sample Desk Accessory


   Memory is a sample desk accessory written in assembly language.  It
   displays the memory available in the application and system heaps,
   and on the boot disk.  MakeFile contains the commands for building
   Memory.

   To build Memory, simply select the line below and press Enter.

		BuildProgram Memory ∑∑ {Worksheet}

   The build process puts the desk accessory into a Font/DA Mover file.
   To install the Memory desk accessory, use the Font/DA Mover to copy
   resource Memory from the file Memory into the System file.
   
   After quitting the Font/DA Mover and returning to the MPW Shell, select
   "Memory" from the Apple menu.



Writing Your Own Programs

	After building (and perhaps modifying) the sample programs, you will
	undoubtedly want to write a program of your own.  Use the New… item in
	the File menu, to create the source files.  Remember that assembly
	language source filenames should end in .a.
	
	Create Build Commands…  -  The Create Build Commands… item in the 
	Build menu runs a script that creates a makefile containing the
	commands for building programs written in C, Assembly Language, Pascal, 
	and/or Rez.  Selecting Create Build Commands… displays a dialog box that 
	allows you to enter information about your program.  Type the program's
	name, select its source files by clicking the Files… button, and click
	one of the radio buttons to indicate your choice of an application, tool,
	or desk accessory.  
	
	Create Build Commands… puts the makefile for your program in the file
	<program>.make.  Now you can use the Build menu to build and rebuild
	your program, just as with the examples.
	
	Larger Programs  -  If you add source files as your program grows,
	use Create Build Commands… again to add the new source files to the build
	instructions.  If you out-grow the capabilities of the simple Create
	Build Commands… script (perhaps by using tools other than Asm, C, Pascal,
	Rez, and Link in your builds) you can modify the makefile yourself.
	
	Modifying the Directory and Build Menus  -  The Directory and Build
	menus are both implemented using scripts written in the MPW Shell
	command language.  This has the big advantage that you can modify
	or customize them to match the way you work.
