ASDK Overview

Darrin Massena (darrin@massena.com)
9 Nov 96

 Introduction

In late June I wrote an article titled Writing Pilot Applications Under Windows in which I detailed what I imagined as the dream PC-based software development kit for building Pilot applications. Then I compared it against what was available at the time -- only some crude tools I wrote that required Visual C++ Macintosh Cross Development Edition ($1999). I included a handful of ideas on how this might be remedied and invited others to join the effort to create tools everyone could afford and use on their PC.

Since then a number of people have combined efforts to create several tools which are now being used to create Pilot applications. These tools and their documentation are bundled here into what has become known as the Alternative Software Development Kit (ASDK). The ASDK includes an assembler, a resource compiler, a Pilot emulator and debugger, a disassembler, header files, API documentation, and a handful of utilities to aid in the development of Pilot applications. In the future we expect to add a C compiler and other languages to the kit as well as more enhancements to make Pilot software development easier.

For PC owners the ASDK is the alternative to purchasing a Macintosh and the USRobotics/MetroWerks SDK. If you have a Macintosh or are willing to spend the money to buy one the USRobotics/MetroWerks still has a number of advantages over the ASDK, chiefly a complete C compiler, source-level debugger, and an integrated development environment.

Contributors

The ASDK would not be possible without the great contributions of the following people. Each provided one or more essential ASDK components.

NOTE: USRobotics has given me permission to redistribute their header files and MemoPad sample in the ASDK. However, they retain the copyright to those files so if you are creating an SDK or development tool of your own and wish to redistribute any USRobotics copyrighted files you must contact them (devsupp@palm.com).

Installation

Create a directory on your hard disk to contain the ASDK files and subdirectories. I recommend naming the directory "ASDK". Extract the ASDK .ZIP file into this directory. IMPORTANT: make sure your unzip program correctly handles long filenames and creates subdirectories as it unzips. For PKUNZIP users this means you must specify the '-d' switch. WinZIP users make sure the "Use Folder Names" checkbox is checked. The 32-bit WinZIP 5.0 or newer running on Windows 95 or Windows NT will do the job.

Before using Copilot you must create a Pilot.ROM file and place it in the bin directory. This involves using the GetROM utilities to copy the ROM code and data from your Pilot. See doc\Copilot.htm for details.

For your convenience, you may want to add the ASDK bin directory to your PATH. This is not required by any of the tools currently included in the ASDK.

Contents

This section briefly describes each of the major components of the ASDK and points to their documentation and World Wide Web support sites for more information.

Additional Documentation

USRobotics provides, via FTP, fairly complete API documentation as well as some step-by-step instruction on building a Pilot application (with their SDK tools). This information is essential. Download it from their FTP site, ftp://ftp.netcom.com/pub/pa/palm. You'll need Adobe Acrobat to read it.

Motorola makes the MC68328 "DragonBall" integrated processor that is the heart of the Pilot and they have some great documentation online in PDF form. I highly recommend downloading and digesting the documentation on Motorola's DragonBall page particularly the Motorola M68000 Family Programmer's Reference Manual and the MC68328 (DragonBall) Integrated Processor User's Manual. You'll need Adobe Acrobat to read them.

You should definitely check out the great Pilot Software Development site (http://www.massena.com/darrin/pilot/index.html) hosted by me for the latest dirt on the ASDK and for other Pilot programming tools, tips and tidbits, etc. There's a new page devoted to the latest ASDK News (http://www.massena.com/darrin/pilot/asdk/asdknews.htm).

Some newsgroups for discussing Pilot software development topics are hosted on Pilot Software Development (news.massena.com). Please join us! You can read these newsgroups with your favorite news reader or most Web browsers (Netscape 2.0 or newer, Internet Explorer 3.0 or newer). With a browser, follow these links:

Files

This packing list gives a breakdown, by directory, of the files included in the ASDK package.

bin                     - Tool binaries
    Copilot.exe         - Pilot Emulator/Debugger (ver b8)
    debugger.hlp        - Copilot's debugger commands
    exe2prc.exe         - Convert Win32 EXE to PRC (ver
    getrom.exe          - Receives ROM file from Pilot
    getrom.prc          - Sends ROM file from Pilot to PC
    Pila.exe            - Pilot Assembler (ver b3)
    PilDis.exe          - Pilot Disassembler (ver a2)
    PilHack.prc         - Hacking aid (ver 1.1)
    PilotCPU.dll        - Copilot DLL
    PilRC.exe           - Resource Compiler (ver 1.0)
    PilRCUI.exe         - GUI Resource Previewer
    prc2bin.exe         - Resource Extractor
    prc2bmp.exe         - PRC icon extractor/converter

doc                     - Tool documentation
    Copilot.htm         - Copilot documentation
    exe2prc.txt         - exe2prc documentation
    PilaUM.htm          - Pila documentation
    PilHack.txt         - PilotHack documentation
    PilotAPI.hlp        - PalmOS API help file
    PilRC.htm           - PilRC documentation
    prc2bin.txt         - prc2bin documentation
    Read this first for Copilot.txt  - Copilot readme
    Read this first for Pila.txt     - Pila readme
    Read this first for PilDis.txt   - PilDis readme
    Read this first for PilRC.txt    - PilRC readme
    Read this first for prc2bmp.txt  - prc2bmp readme

inc
|   AppBuildRules.h     - USRobotics header file
|   BuildRules.h        - USRobotics header file
|   Common.h            - USRobotics header file
|   Pilot.h             - USRobotics header file
|   Pilot.inc           - Pila header file
|   Pilot.pch           - USRobotics header file
|   Startup.inc         - Pila standard startup file
|   SysBuildRules.h     - USRobotics header file
|
+---Hardware            - USRobotics header files
+---System              - USRobotics header files
+---UI                  - USRobotics header files

lib                     - empty (for now)

Samples
+---MemoPad             - USRobotics MemoPad sample
|       memopad.c
|       memopadr.h
|
+---Pila                - Pila samples
|   +---Sample          -
|           SAMPLE.ASM
|           SAMPLE.BMP
|           SAMPLE.RCP
|   +---HackMaster      - HackMaster extensions using VC/Mac
|           ahack.asm
|           ahack.inc
|           ahack.rcp
|           ahack2.prc
|           mk.bat
|           readme.txt
|           sndtrap.asm
|
+---PilRC               - PilRC samples
|       alhack.rcp
|       resource.h
|       resource.inc
|       resource.rc
+---VCMac               - Visual C++ Macintosh Cross Development Edition samples

src                     - Source code to tools
+---prc2bmp             - prc2bmp source code
        prc2bmp.cpp
        prc2bmp.mak
        swapper.h