_    _                      ____                       _
   / \  | | __ _ _ __ _ __ ___ |  _ \ ___ _ __   ___  __ _| |_ ___ _ __
  / _ \ | |/ _` | '__| '_ ` _ \| |_) / _ \ '_ \ / _ \/ _` | __/ _ \ '__|
 / ___ \| | (_| | |  | | | | | |  _ <  __/ |_) |  __/ (_| | ||  __/ |
/_/   \_\_|\__,_|_|  |_| |_| |_|_| \_\___| .__/ \___|\__,_|\__\___|_|
-----------------------------------------|_|--------------------------------
README.code                                             version 1.0, 7/21/98

Copyright 1998 Douglas I. Anderson


Introduction
============

This file contains technical information about AlarmRepeater and gives at
least some idea of what is needed to do hacks with Codewarrior.  It isn't
meant for people who haven't written programs for the Pilot.  In it, I
assume knowledge of Pilot programming and some knowledge of the Hackmaster
API (sorry, I'm not going to explain A-TRAPS here).  I also assume that you
have played with AlarmRepeater on the device and know how it works.

This document focuses on the full version of AlarmRepeater (not the skim
version).

This readme is probably a little rough.  If you have questions, find parts
confusing, or notice bugs/typos, please let me know.  Thanks!


What the hack consists of
=========================

AlarmRepeater consists of two basic parts.
1.  A patch for the system trap "SndPlaySystemSound".
2.  A configuration form and handler.

Because of the way Hackmaster works, code for each part of the hack must
exist in a separate code resources with distinct IDs (all patches must
have code ID 1000-1499, all form handlers must have code ID 2000-2999, etc).
This is not something that Codewarrior was designed to do.  However, with a
bit of creativity, it is possible.

AlarmRepeater has a separate project file for each part that needs its
own code resource.  The project file for each part generates a ".o" file
that contains a code resource with the correct ID and all resources
associated with that part.  AlarmRepeater also has a single main project
file that combines all the parts into one big file, runs PilotRez to
post-process the file, and then generates the final ".prc"


About the parts
===============

As I said, each of the smaller project files is set up to generate a ".o"
file.  This file is really nothing new.  It is simply the ".tmp" file that
you may have noticed when doing other Pilot programming, but with a
different name.  Normally, Codewarrior generates this ".tmp" file and then
immediately feeds it into PilotRez to generate the finished ".prc" file.
Because the individual pieces don't generate their own ".prc" files, I
simply rename the ".tmp" file to ".o" (as a visual reminder of what I'm
doing) and then turn off PilotRez post-processing (this means that the
PilotRez panel is ignored in the preferences of the individual projects).

Thus, each smaller project part contains a ".c" file with the code for
this part (either a trap and its helpers or a form handler and its helpers);
any resources needed for UI; and a resource mapping the code to the
right A-TRAP (if this part is a patch).

Summary of changes for each part (from the standard project stationary):
------------------------------------------------------------------------
* Target Setting Panel ==> Post-linker is "none"
* 68K Target Panel ==> File Name is "<outputname>.o"
                   ==> Resource Name is a descripition of this segment.
                   ==> Entry Point is this segment's main function name.
                   ==> ResType is 'code'
                   ==> ResID is the resource ID of thie part.
* PilotRez Panel ==> I've put in bogus value here (not used).
.
* If this part is a patch (as opposed to a configuration form and handler),
  a Resedit resource file is included that maps the ID of this part's code
  segment to an A-TRAP.  See the Hackmaster documentation for details.

AlarmRepeater's standard naming convention labels all the part specific
files with their code ID.  There are some other conventions that I have
tried to follow that you may pick up on as well.


About the main project
======================

The main project really isn't much itself.  Its main job is to combine all
of the subprojects and provide any information that the overall patch
needs (such as a creator code, icon, etc).

To make everything work, the main project utilizes Codewarrior's support
for subprojects.  The main project includes the project files for each of
the subprojects.  It then tells Codewarrior to build those projects and
include their output whenever the main project is built.  How does it do
that?  If you open the main project and click on the "Targets" tab, you
can see all the targets for the main project (there are two...just
ignore the skim version for now).  Expand the standard target and you
will see items for each subproject.  Expand a subproject and you will
see items for each of the targets of that subproject.  Clicking on the
bullseye for the items toggles whether that target is build when the main
project is.  Clicking in the link column for the items toggles whether
the output of that target is included in the main project.  AlarmRepeater's
standard target builds and includes the output of the configuration form
and builds and includes the output of the standard SndPlaySysSndPatch.

All that stuff imports all subproject's ".o" files into the main project.
Now, we need to make the main project build the ".o" files and import them.
Ideally, all we need to do is run these merged ".o" files through PilotRez
and be done with it.  However, Codewarrior won't let a project simply do
merging.  It must also compile code itself.  Thus, the main project is in
charge of compiling "Bogus.c", a really simple source file.  After it does
that, it can glom everything together.  Only one problem: where do you put
the compiled code for "Bogus.c"?  Do you put it in a code resource and then
send it to the final output?  That seems like a waste.  After some playing
around, I learned that PilotRez ignores 'µMWC' resources (this is a resource
type in Constructor files).  Thus, bogus.c gets compiled and stored in a
'µMWC' resource type, which then get promptly ignored.

Summary of changes to the main proj (from the standard project stationary):
---------------------------------------------------------------------------
* 68K Target Panel ==> File name is "AlarmRepeaterHack.tmp"
                   ==> Resource Name is "Bogus".
                   ==> Entry Point is "Bogus".
                   ==> ResType is 'µMWC'
                   ==> ResID is 1000 (arbitrary).
* PilotRez Panel ==> Mac Resource Files is "AlarmRepeaterHack.tmp"
                 ==> Output File is "AlarmRepeaterHack.prc"
                 ==> Creator is 'ARep' (my creator code...get your own)
                 ==> Type is 'HACK'


Legal Junk & Distribution
=========================
You may freely modify and distribute modifications of this code.  However,
if you do this, you _must_ claim ownership of the new code (please don't
list me as the creator of something I didn't do.  I wouldn't be happy).  You
_must_ also list me somewhere in the credits.  If you do distribute any
modifications, you _MAY NOT_ include any of my readme files or derivates of
them without my permission.  Any distributed modifications must also have
a unique creator code (register it with Palm).


Contact Info
============
Probably the easiest way to contact me is via e-mail.  However, I always
appreciate getting real mail...if you want to, you can consider yourself
officially registered if you send me any piece of "real mail."
      e-mail:  dianders@cs.stanford.edu
      address: Doug Anderson
               PO Box 3506
               Stanford, CA 94309
...hope to hear from you.