  Palm OS アプリケーション開発
  by David H. Silber palm@orbits.com

  v0.6.7, 20 September 1998
  川島 浩、kawashima@iname.com

  v0.6.7j, 25 June 1999

  この文書には、Palm OS デバイス上のアプリケーションを開発するために必要
  な情報が書かれています。文書中の例や説明は Linux を前提として書かれて
  いますが、これらのツールが動作する環境ならば(訳注: 種々の Unixや、GNU
  Win32環境ですね。)、ほとんどの情報がそのまま役立つはずです。
  ______________________________________________________________________

  目次

  1. はじめに
     1.1 この文書について
     1.2 参考
     1.3 メイリングリスト
     1.4 メイリングリストのアーカイブ
     1.5 FTP サイト

  2. ツール
     2.1 pilot-link
     2.2 prc-tools
        2.2.1 Prc-tools のインストール
        2.2.2 Prc-tools を使う

  3. Hello, World -- Palm OS プログラミングへの招待
     3.1 まずはやってみよう
        3.1.1 プログラムのソースコード
        3.1.2 コンパイル
        3.1.3 インストール
        3.1.4 プログラムを起動する
     3.2 この(簡単な)プログラムの解説
        3.2.1 SysAll.h -- おおもとのシステムインクルードファイル
        3.2.2 UIAll.h -- おおもとのユーザインタフェースインクルードファイル
        3.2.3 PilotMain() -- アプリケーションのメイン関数
        3.2.4 Launch Code をチェックする
        3.2.5 出力
        3.2.6 メイン・イベントループ
        3.2.7 イベントを獲得する
        3.2.8 イベントを処理する
        3.2.9 Hello, World プログラムに関する注記

  4. 結論
  A. 協力してくれた人々
  B. 謝辞
  C. 用語

  ______________________________________________________________________

  1.  はじめに

  こんなに小さくてすばらしい Palm OS デバイスを持っていたら、きっとあな
  たも自分でプログラムを書きたくなるに決まってますよね。一見すると、まず
  市販されている開発キットを買う必要があるように思えるかもしれませんが、
  実はこれらのキットは MacOS か Windows の上でしか動作しないのです。しか
  し、さまざまな人たちのたゆみない努力により、(付録の``謝辞''を参照)
  Palm OS 上のプログラムを開発するためのフリーウエアツールが開発されまし
  た。

  この文書では、これらのツールをインストールする方法とその使い方について
  述べ、さらに Palm OS プログラムを書くためのチュートリアルを提供してい
  ます。最初に prc-tools を、私の説明と例を交えて紹介します。 prc-tools
  は、GNU gcc コンパイラの上に作成された、`C' 言語のクロスコンパイル環境
  を提供します。また、prc-tools には pilrc という、リソースをコンパイル
  するためのツールも含まれています。

  チュートリアルの章では、読者はすでに一般的なプログラミングや `C' 言語
  や UNIX の ``make'' などのコマンドに慣れ親しんでいることを前提としてい
  ます。

  さて、チュートリアルの章で説明しているプログラムをインストールするつも
  りならば、まずあなたの Palm OS デバイスのデータをバックアップしておき
  ましょう。

  ``参考文献''で説明されている API 文書も参考になります。

  1.1.  この文書について

  このドキュメントの最新版は以下のURLで読むことができます:
  http://www.orbits.com/Palm/PalmDevelopment-HOWTO.html 正誤表、将来計
  画、いろいろな注意点や Palm 関係のリンクは以下からたどることができると
  思います: http://www.orbits.com/Palm/.  この文書は Linux Documentation
  Project (LDP) の一部です。 LDP に関しての詳細や、他の HOWTO 文書に関し
  ては: http://sunsite.unc.edu/LDP/ をご覧ください。

  この文書に関して、修正の必要な箇所や、もっとよい説明などありましたら、
  上に書いたメイルアドレスまでメイルをください。その時には文書のバージョ
  ン情報も添えてくださいね。

  この文書を翻訳したいという方がいらっしゃいましたら、
  http://www.orbits.com/Palm/ をまずチェックしてみてください。すでに他の
  方が翻訳をしているかもしれません。翻訳ができあがったら、私に SGML のソ
  ースをぜひ送ってください。元の英語文書と一緒に参照できるようにしたいと
  思っていますので。

  この文書は Copyright (C) 1997 - 1998 by David H. Silber です。 LDP
  HOWTO-INDEX 文書の著作権条件のもとに配布されています。

  1.2.  参考

  The Palm OS Linux Desktop HOWTO http://www.orbits.com/Palm/PalmOS-
  HOWTO.html この文書では、HotSync クレードルや pilot-link ソフトウエア
  のインストール方法など、より基本的なことを解説しています。

  C 言語に詳しくない方には、チュートリアルの章を読む前に

       The C Programming Language, by Brian W. Kernighan and Dennis M.
       Ritchie

  を読まれることをお勧めします。 (訳注: この本は日本語訳があります。「プ
  ログラミング言語C(第２版)」共立出版 ISBN 4-320-02483-4)

  この文書で解説している内容よりも詳しいことを知りたい場合には、 Palm
  Computing の以下の文書を読むことをお勧めします。

  o  Developing Palm OS 3.0 Applications -- Part I: Interface Management
     http://palm.3com.com/devzone/docs/Ref1.zip

  o  Developing Palm OS 3.0 Applications -- Part II: System Management
     http://palm.3com.com/devzone/docs/Ref2.zip

  o  Developing Palm OS 3.0 Applications -- Part III: Memory and
     Communications Management
     http://palm.3com.com/devzone/docs/Ref3.zip

  (訳注: 上記ドキュメントの日本語訳が販売されています。「PalmOSバイブ
  ル」監訳：山田達司さん(日経BP社刊) また、「ここまででき
  るPalm/WorkPadプログラミングWindows版」著者：漆畑広樹さん(オーム社刊)
  もとても参考になります。)

  The Palm OS Conduit Development HOWTO
  http://www.orbits.com/Palm/PalmConduit-HOWTO.html この文書は、pilot-
  link ライブラリを使って Linux 用のコンジットプログラムを書く方法につい
  て書かれています。

  1.3.  メイリングリスト

  Pilot-unix メイリングリストは、 Matthew Cravit <mailto:pilot-unix-
  owner@lists.best.com>.  によって運営されています。このメイリングリスト
  のルール(mandate)は:

       pilot-unix メイリングリストは、US Robotics Pilot PDA を UNIX システムと
       一緒に使うことに興味のある人のための、議論と知識共有のためのものです。
       これには、Pilot を UNIX と一緒に使うためのツール開発や、
       Unix 上の Pilot 用 SDK の開発の助けをすることに興味のある人なども含まれます。

  さらに詳細な情報(メイリングリストへの参加も含めて)については、
  ``INFO'' という単語を含むメイルを pilot-unix-request@lists.best.com.
  宛てに送ってください。Subject 行は無視されますので注意してください。

  1.4.  メイリングリストのアーカイブ

  pilot-unix メイリングリストのアーカイブ(過去の記録)は、
  http://www.acm.rpi.edu/~albert/pilot/.
  http://www.acm.rpi.edu/~albert/pilot/ にあります。このアーカイブは、
  Chris Stevens <mailto:albert@acm.rpi.edu> によって運営されています。

  1.5.  FTP サイト

  Unix 上で使う Pilot 用のツール類のアーカイブは
  ftp://ryeham.ee.ryerson.ca/pub/PalmOS/ にあります。 Jeff Dionne
  <mailto:jeff@ryeham.ee.ryerson.ca> によって運営されています。

  Free Software Foundation (FSF) は、gcc や gdb や binutils などなどのた
  くさんのフリーな開発ツールを提供してくれています。 URL は、
  ftp://prep.ai.mit.edu/pub/gnu/.  です。

  2.  ツール

  まずは、 pilot-link, prc-tools, gcc, binutils と gdb の配布パッケージ
  が必要です。これらのツールをインストールするためには、Linux 上にすでに
  make, gcc, patch, ncurses ライブラリが既にインストールされていなければ
  なりません。ツールパッケージからファイルが参照される時は、それらをイン
  ストールしたプレフィックスディレクトリからの相対参照でおこなわれるはず
  です。

  2.1.  pilot-link

  まだインストールしていなければ、 pilot-linkをインストールしてくださ
  い。インストールの方法については、 http://www.orbits.com/Palm/PalmOS-
  HOWTO.html.  を参照してください。 pilot-linkに含まれている pilot-
  xferは、PalmOS アプリケーションを (訳注: Palm に)インストールするため
  のツールです。

  2.2.  prc-tools

  Prc-tools パッケージは、FSF の GNU ユーティリティ、コンパイラ、デバッ
  ガをベースとして、いくつか特殊なツールを付加した開発ツールキットです。
  これらを使うことで、Linux 上で Palm OS ソフトウエアを開発することがで
  きるようになります。

  開発方法に関する文書はあまり多くありませんが、以下が役に立つでしょう
  Pilot Software Development web page at
  http://www.massena.com/darrin/pilot/.

  2.2.1.  Prc-tools のインストール

  Prc-tools の最新バージョンは以下からダウンロードできます:
  ftp://ryeham.ee.ryerson.ca/pub/PalmOS.  GNU ツールは以下から:
  ftp://prep.ai.mit.edu/pub/gnu.  binutils-2.7.tar.gz,
  gcc-2.7.2.2.tar.gz と gdb-4.16.tar.gz をダウンロードしてください。上に
  書いた GNU ツールのバージョンは、prc-tools のリリース 0.5.0 が必要とし
  ているバージョンです。より新しい prc-tools リリースでは、GNU ツールの
  もっと新しいバージョンが必要かもしれません。

  上で述べた配布パッケージを全部同じディレクトリに置きます。まず、prc-
  tools だけを展開(unpack)します。その他のパッケージに関しては、 prc-
  tools の Makefile が展開などをおこなってくれます。デフォルトでは、prc-
  tools は /usr/local/gnu にインストールされます。他のディレクトリにイン
  ストールしたい場合には、Makefile の中の INSTALLDIR を変更する必要があ
  ります。また、GNUARCHを、 GNU ツールを置いたディレクトリに変更してくだ
  さい (展開(unpack)する必要はありません。make プログラムがやってくれま
  すから)。

  つまり、次のような手順になります:

  tar -xvzf prc-tools.0.5.0.tar.gz
  cd prc-tools-0.5.0
    (必要なら Makefile を編集する)
  make gnuuntar
  make patch
    (Debian Linux の場合には、gbd-4.16/gdb/Makefile.in と gbd-4.16/readline/Makefile.in
    の中で参照されている termcap を、ncurses ライブラリを参照するように変更する
    必要があります。)
  make gnutools
    (ここで root ユーザになります。)
  make
  make install

  2.2.2.  Prc-tools を使う

  Prc-toolsの一般的な使い方を知るためには、example ディレクトリの中身、
  特にMakefileを参照するのが良いと思います。この文章のチュートリアルの章
  でも、Palm OS アプリケーションをコンパイルする方法について述べていま
  す。

  3.  Hello, World -- Palm OS プログラミングへの招待

  どんなプログラムのチュートリアルでもまず最初に要求されるのは、どうやら
  例の``Hello world'' プログラムみたいですね。このプログラムを動作させる
  ことで、少なくとも、Palm OS プログラムの作成方法、コンパイル方法とイン
  ストールの仕方を把握できるはずです。

  ひとつ注意しておくべきなのは、Palm OS プログラムはイベントドリブンだと
  いうことです。基本的には、他の(make や more や pilot-xfer などのよう
  な)直線的なプログラムとはちょっと違って、Palm OS アプリケーションはお
  おむね、イベントを待ち、それを処理するというような構造をしています。イ
  ベントというのは、ペンダウン・アップ、グラフィティ入力、アラームなど
  の、それぞれ異なるイベントが発生したことを指します。

  3.1.  まずはやってみよう

  3.1.1.  プログラムのソースコード

  これは、``Hello World'' プログラムのソースコードです: (訳注: 以下では
  参考のために、ソースコードのコメント部分も日本語に訳出していますが、実
  際に gcc で日本語のコメントが通るかどうかは確認していません)

  #include <System/SysAll.h>
  #include <UI/UIAll.h>

  // ---------------------------------------------------------------------
  // PilotMain は、初期化コード(startup)から呼び出され、単純なイベントを
  // 処理するループから成ります。
  // ---------------------------------------------------------------------
  DWord PilotMain( Word cmd, Ptr cmdPBP, Word launchFlags )
  {
      EventType event;

      if (cmd == sysAppLaunchCmdNormalLaunch) {

          //  文字列を表示する
          WinDrawChars( "Hello, world!", 13, 55, 60 );

          //  メインのイベントループ:
          do {
              //  イベントが到着するまで眠る
              EvtGetEvent( &event, evtWaitForever );

              // まずはシステムにイベントを処理する機会を与える
              SysHandleEvent( &event );

              // 通常はここでその他のイベントの処理をおこなう。

          // appStopEvent を受け取ったら PilotMain からリターンする
          } while (event.eType != appStopEvent);
      }
      return;
  }

  以上のコードをお好きな方法で、``hello.c'' というファイル名のテキスト
  ファイルとして保存してください (実際にはファイルの名前は最後が ``.c''
  でありさえすればなんでもよいのですが、ここではこういう名前を使いま
  す)。

  3.1.2.  コンパイル

  Prc-tools で使われている bin ディレクトリがちゃんとデフォールトパスに
  含まれている(パスが通っている)ことを確認して、以下のコマンドを入力して
  ください:

       m68k-palmos-coff-gcc -O2 -g hello.c -o hello
       m68k-palmos-coff-obj-res hello
       build-prc hello.prc "Hello, World" WRLD *.hello.grc

  m68k-palmos-coff-gccは、prc-tools によって生成された GCC クロスコンパ
  イラ。 m68k-palmos-coff-obj-resは、m68k-palmos-coff-gccによって生成さ
  れたプログラムを、Palm OS アプリケーションに必要ないくつものセクション
  に分割してくれます。 build-prcはプログラムセクションを組み立て、コマン
  ドラインで指定された情報を付加して最終的な Palm OS プログラムを生成し
  ます。

  3.1.3.  インストール

  さて、Palm OS デバイスのメモリ内容のバックアップは既に済んでいますよ
  ね。いよいよhello.prcをインストールしてみましょう。インストール方法は
  以下の通りです:

       pilot-xfer --port /dev/ttyS1 --install hello.prc

  (ここで指定したシリアルデバイスは、あなたの環境にあわせて変更してくだ
  さい)

  さあ、クレードルの HotSync ボタンを押しましょう。

  3.1.4.  プログラムを起動する

  HotSync が完了したら、アプリケーションランチャーから ``Hello, World''
  という名前のアプリケーションが見えるはずです。これをダブルタップすれ
  ば、画面の真ん中あたりに、``Hello, World!'' という文字が現れるはずで
  す。

  3.2.  この(簡単な)プログラムの解説

  さて、この``Hello, World''プログラムの構成要素を説明したいと思います。

  3.2.1.  SysAll.h -- おおもとのシステムインクルードファイル

  System/SysAll.h をインクルードすることで、実はたくさんのシステムインク
  ルードファイルを一度にインクルードすることになります。この中でいくつか
  見ておきたいファイルがあるかもしれませんね。たとえば、m68k-palmos-
  coff/include/PalmOS2/Common.h では Palm OS ライブラリ全体で使われるよ
  うな typedef 宣言が含まれているので目を通しておいて損はないと思いま
  す。

  3.2.2.  UIAll.h -- おおもとのユーザインタフェースインクルードファイル

  UI/UIAll.h は、ユーザインターフェースに関するたくさんのインクルード
  ファイルをインクルードしています。

  3.2.3.  PilotMain() -- アプリケーションのメイン関数

  すべての Palm OS アプリケーションには(訳注: Hack や DA は除く)、この
  PilotMain()関数が存在しなければなりません。これは通常の C 言語におけ
  る、main()関数と同じ役割を果たすものです。

       DWord PilotMain( Word cmd, Ptr cmdPBP, Word launchFlags )

  プログラムが起動された時に、cmdには Launch Codeが渡されます。こ
  のLaunch Code によって、アプリケーションに対して通常とは異なる動作を要
  求することも可能です。

  3.2.4.  Launch Code をチェックする

  Launch Code は、cmd引数で渡されます。それぞれのプログラムはこの Launch
  Code の値をチェックして、自分がそれに応答できるかどうかを調べます。
  ``Hello, World'' プログラムでは、「normal program launch」以外のコード
  は無視するようになっています。

       if (cmd == sysAppLaunchCmdNormalLaunch) {

  Launch codeには、いろいろな状況に対処するためにたくさんの種類がありま
  す。どんなコードが存在するのかを全部知るためには、 m68k-palmos-
  coff/include/PalmOS2/System/SystemMgr.h を読んでください。

  3.2.5.  出力

  WinDrawChars()関数は、指定された画面上の座標に文字列を表示します。

       WinDrawChars( "Hello, world!", 13, 55, 60 );

  3.2.6.  メイン・イベントループ

  アプリケーションは、appStopEventを受け取るまで(その意味の通り) 走り続
  けます。

       //  メイン・イベントループ
       do {
               .
               .
               .
       // appStopEvent を受け取ったら PilotMain からリターンする
       } while (event.eType != appStopEvent);

  アプリケーションがこのイベントを受け取った場合には、必要な後始末をした
  後に、 PilotMainからリターンするようにします。

  3.2.7.  イベントを獲得する

  EvtGetEvent関数は最初の引数を変更するので副作用があります。この関数か
  ら帰ってくるときには、すなわちいくつかのイベントが発生して、OS がアプ
  リケーションに対してそれを通知しているという状態です。

       EvtGetEvent( &event, evtWaitForever );

  3.2.8.  イベントを処理する

  実は、アプリケーションは自分に渡されるすべての制御権を握っています。し
  かし、通常のアプリケーションではほとんどのイベントを Palm OS に処理し
  て欲しい場合が多いでしょう。このために、システムが提供しているイベント
  処理ルーチン関数が提供されています。 SysHandleEvent()を呼び出すこと
  で、ボタンや Graffiti 関連のイベントをシステムに処理させることができま
  す。この関数を呼び出さないと Palm OS は、別のアプリケーションを起動す
  るためにボタンが押されたというイベントを処理することができません。これ
  はすなわち現在のアプリケーションに対して appStopEventが送られないこと
  を意味します。その結果、``Hello, World''プログラムはどうやっても終了で
  きなくなってしまうことになります。実際、電源オフのボタンもきかなくなっ
  てしまうんです!

  さあ、試してみましょう。 SysHandleEvent()を呼び出しているところをコメ
  ントアウトして、再コンパイル、再インストールしてなにが起こるか試してみ
  てください。ソフトリセットするためのゼムクリップを用意しておいてくださ
  いね!

  3.2.9.  Hello, World プログラムに関する注記

  恐らく気がついたと思いますが、このプログラムはイベントに関しては、オペ
  レーティングシステムに処理させるためにそのイベントを渡し直すこと以外に
  はなにもおこなっていません。次の機会にはもっとエキサイティングな例を書
  くことを約束します!

  4.  結論

  もっといろいろとカバーすべき点があることはわかっています。例えば、フォ
  ームの使い方とかメニューやそのほかのリソースに関してです。おもちゃのプ
  ログラムでない限り、こういう機能はとても重要なものですからね。まあとに
  かく、このままの状態でリリースしたいと思います。ここで書いた事柄が、み
  なさんがプログラムを始めるきっかけになれば幸いです。

  この文書の新しい版を見逃さないためには、 http://www.orbits.com/Palm/
  をブックマークに入れておいてください。

  建設的な意見は大歓迎です。こちらにお願いします: palm@orbits.com

  A.  協力してくれた人々

  Kenneth Albanowski <mailto:kjahds@kjahds.com> は pilot-link 関連のツー
  ルを保守してくれています。

  Wes Cherry <mailto:wesc@ricochet.net> Pilrc の作者です。

  Matthew Cravit <mailto:pilot-unix-owner@lists.best.com> Pilot-unixメイ
  リングリストの運営者です。

  Jeff Dionne <mailto:jeff@ryeham.ee.ryerson.ca> Pilot-link 関連ソフトウ
  エアの原作者であり、prc-tools の作者でもあります。また、UNIX Palm
  OS/Pilot 開発プロジェクトのFTP関連の管理者でもあります。

  David H. Silber <mailto:palm@orbits.com> この文書の著者です。

  Chris Stevens <mailto:albert@acm.rpi.edu> Pilot-unix メイリングリスト
  のアーカイブを管理してくれています。

  B.  謝辞

  linux -- Linus Torvalds と何千人もの人々に対して。

  gcc -- Free Software Foundation に対して。

  binutils -- Free Software Foundation に対して。

  gdb -- Free Software Foundation に対して。

  pilot-link -- Jeff Dionne & Kenneth Albanowski に対して。

  pilrc -- Wes Cherry に対して。

  prc-tools -- Jeff Dionne に対して。

  GPL -- Free Software Foundation に対して。

  C.  用語

  API -- Application Programming Interface.  プログラムが特定のサービス
  を要求するための関数ライブラリの仕様です。この文書では、Palm OS API を
  指し、アプリケーションがオペレーティングシステムや Palm OS デバイスと
  うまくインターフェースすることを可能にします。

  アプリケーション名 -- プログラムの名前アイコンの下や、アプリケーション
  ランチャーのリストに表示されます。

  アプリケーション識別子 -- 4文字の文字列で、Palm OS のアプリケーション
  をユニークに識別するための識別子です。

  コンジット -- デスクトップで動作するプログラムで、デスクトップアプリケ
  ーションと Palm OS デバイスの間でデータの移動を行うものです。

  イベント -- アプリケーションの外側で発生した事象で、アプリケーションに
  通知されるものです。

  イベントドリブン -- プログラム構造の一種で、あらかじめ記述された順序で
  データを処理するかわりに、イベントが発生した時にそれに反応するような構
  造のものを指します。

  フォーム -- Palm デバイスの画面の領域を指します。

  GPL -- GNU General Public License です。

  ランチコード -- Palm OS アプリケーションが起動されたさまざまな理由を指
  定します。

  linux -- Unix ライクな、POSIX コンパチブルなオペレーティングシステム
  で、GPL のもとに配布されています。

