docs/palmos/readme.txt

   1                               wxPalm README
   2                               =============
   3
   4 NB: wxPalm is currently in pre-alpha stage -- but it's already fun!
   5
   6 I. Building wxPalm under Windows
   7 --------------------------------
   8
   9 First, you need the freely distributable Palm OS Developer Studio available at
  10
  11                 http://www.palmos.com/dev/tools/dev_suite.html
  12
  13 Beware, its installation takes about 500Mb (+ 150 Mb of cygwin if not installed
  14 yet), so make sure you have enough disk space for it and for wxWidgets build
  15 tree (another 50Mb). Last tested set: PODS 1.2, SDK 6.1, wxWidgets 2.7.0.
  16
  17 The Developer Studio is Eclipse-based and so is a GUI environment, however it
  18 is also possible to build Palm applications from the command line using the
  19 usual GNU tools. Both methods are covered below, choose one which you prefer.
  20
  21 a) Using command line tools:
  22     - If you have installed Developer Studio in a non default location (e.g.
  23       d:\PalmOS), you will need to set the environment variables:
  24
  25                 set TOOLS_DIR=D:/PalmOS/PalmOSTools/
  26                 set SDK_LOCATION=D:/PalmOS/sdk-6/
  27
  28       Don't use backslashes and don't forget the trailing slash. On the bright
  29       side, spaces don't need to be escaped in any way.
  30
  31     - create a lib/gcc_lib/palmos/wx directory
  32     - copy include/wx/palmos/setup0.h to lib/gcc_lib/palmos/wx/setup.h
  33         TODO: modify Makefile to do it automatically
  34
  35     - ensure that the directories d:\PalmOS\PalmOSTools and the one containing
  36       GNU tools (i.e. cygwin bin directory) are in your PATH
  37
  38     - go to build/palmos and run make
  39
  40     - you should end up with DebugSim/wxWidgets.prc: this is the Palm database
  41       which you can load into the emulator
  42
  43     - to test it, run the emulator (you need PalmOS 6 one!) after seting
  44       another env var:
  45
  46                 set PALMSOURCE_SIM_PATH=wxWindows\build\palmos\DebugSim
  47
  48       wait until the emulator finishes to boot, right click it and choose
  49       "Install" in the menu, select wxWindows.prc in the file open dialog.
  50       You should see "Minimal App" with a familiar icon appear in the list,
  51       click it and it should start.
  52
  53
  54 b) Using IDE:
  55     TODO: write this after checking that the instructions below work
  56
  57
  58
  59
  60 Original note from William Osborne follows:
  61
  62 wxWidgets 2.5.3 CVS 10-18-2004
  63 ------------------------------
  64
  65 This is a Palm OS 6 port of the wxWidgets toolkit.  Included in the source
  66 package is the complete source necessary to build the Palm OS port using the
  67 Palm OS Developer Studio.  Also included is the diff showing the changes that
  68 need to be incorporated into the wxWidgets 2.5.3 CVS source tree before the
  69 Palm OS port can be integrated.
  70
  71 I am releasing this port to the wxWidgets team under the terms of the wxWindows
  72 license.  A copy of the wxWindows license is included in the source package.
  73
  74 No third party libraries or code were used in making this port.  The port consists
  75 entirely of code I personally wrote combined with code that was included in the
  76 wxWidgets 2.5.3 CSV source tree.  Whenever possible, I have used the Palm OS 6 API,
  77 in places where the API was not practical to use, I wrote my own functions.
  78
  79 I am submitting this source package as an entry in the wxWidgets Palm OS 6 port
  80 challenge.  Details on this challenge are available at:
  81 http://www.wxwidgets.org/about/news/palmos.htm
  82
  83 Please note that this port is in a very early state.  Currently the port
  84 provides limited functionality for the wxFrame, wxMenu, wxStatusBar,
  85 wxTopLevelWindow, and wxWindow classes.  The other classes in the wxWidgets
  86 toolkit still need to be ported.  In it's current state, the Palm OS 6 port
  87 is capable of running the minimal wxWidgets sample
  88
  89 The easiest way to see the port in action is to build the source package with
  90 the Palm OS Developer Studio available at http://www.palmos.com/dev/dl/dl_tools/dl_pods/
  91 Here are the steps that you need to follow to build the package:
  92
  93 1) Unpack the ZIP file into a directory located within the Palm OS Developer
  94    Studio workspace directory.  The path to the folder should look something
  95    like this: "C:\Program Files\PalmSource\Palm OS Developer Suite\workspace\wxWidgets"
  96
  97 2) Open Palm OS Developer Studio and click on File->Import.
  98
  99 3) Select "Existing Project into Workspace" as the import source and click Next.
 100
 101 4) On the next screen click the Browse button next to Project contents and select
 102    the folder you unpacked the source package into.  Click on Finish to continue.
 103
 104 5) You should now see the project listed in the Project pane on the right side of the
 105    window.  Click on the name of the project.  Now click on the Project menu and select
 106    "Rebuild Project"
 107
 108 6) After the build is complete, click on the Run menu and select ""  The Palm OS 6 simulator
 109    should start.  If this is the first time you have used the simulator, you will be prompted
 110    to choose a ROM file.  You can find the ROM files in a folder like "C:\Program
 111    Files\PalmSource\Palm OS Developer Suite\sdk-6\tools\Simulator\6.0.1\ROM"  It doesn't
 112    really matter whether you choose a Release or a Debug ROM (the debug ROM generates extra
 113    reports when an application crashes.)
 114
 115 7) You should see the Palm logo appear in the simulator window.  You may get a dialog box
 116    asking you to choose a language.  Click OK to continue.  You should see the simulator
 117    initialize the built-in Palm applications.  After a few moments, the wxWidgets minimal
 118    sample should start.  Have fun!
 119
 120 Since this source package was based on the wxWidgets 2.5.3 CVS source tree dated October 18,
 121 2004 I don't anticipate any problems with merging the sources into the 2.5.3 source tree.
 122
 123 If you have any questions or comments about the port, please feel free to send an email to
 124 the wxWidgets developer list or directly to me at wbo@freeshell.org
 125
 126 Enjoy!
 127 William Osborne
 128 wbo@freeshell.org