447 lines
18 KiB
Plaintext
447 lines
18 KiB
Plaintext
Palm OS 5 SDK (68K) R3 - Readme File
|
|
|
|
IMPORTANT: Read Before Using the Accompanying Software
|
|
|
|
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
|
|
P a l m O S S o f t w a r e D e v e l o p m e n t K i t
|
|
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
|
|
|
|
IMPORTANT: This Software Development Kit (SDK) is at a "pre-Alpha"
|
|
stage. PalmSource makes no guarantees as to the usability of this SDK.
|
|
|
|
**********************************************************************
|
|
* ENHANCEMENTS AND FIXES -- WHAT'S NEW *
|
|
**********************************************************************
|
|
|
|
- Palm OS Support Folder
|
|
|
|
All header files now include the following version string
|
|
in their header blocks: Palm OS 5 SDK (68K) R3.
|
|
|
|
- Palm OS APIs
|
|
|
|
"Palm OS Programmer's Companion" and "Palm OS Programmer's API
|
|
Reference" contain new sections documenting additions and changes
|
|
to the Palm OS APIs.
|
|
|
|
Graffiti 2 Feature Set: Support for the Graffiti(R) 2 handwriting
|
|
recognition engine.
|
|
|
|
- PalmRez
|
|
|
|
o Support for QVGA (1.5X) density screens. This support is added
|
|
for app icon families, bitmap families, and font families.
|
|
o Support for the "hidden" menu item attribute.
|
|
|
|
- Constructor for Palm OS 1.9
|
|
|
|
Constructor for Palm OS includes the following new features:
|
|
|
|
o Support for Simplified Chinese as a Palm OS target setting and
|
|
as a default text encoding for editing PRC files.
|
|
o Support for QVGA (1.5X) density screens. This support is added
|
|
for app icon families, bitmap families, and font families.
|
|
o Support for adding custom data resources.
|
|
o Support for the "hidden" menu item attribute.
|
|
|
|
For more information, see the "Constructor for Palm OS" book.
|
|
|
|
- PRC2OVL
|
|
|
|
Additional Chinese locale support.
|
|
|
|
- Virtual Phone 1.7
|
|
|
|
Additional functions for testing SIM, Speech, and GPRS functions.
|
|
|
|
**********************************************************************
|
|
* MULTI-SEGMENT APPLICATION SUPPORT *
|
|
**********************************************************************
|
|
|
|
This is a stationery project for a multi-segment application that runs
|
|
on Palm OS devices. Even though you can create applications with
|
|
multiple segments, you must follow the example used in this project.
|
|
See the "Targeting Palm OS" manual in the CodeWarrior Documentation
|
|
folder for more information on working with multi-segment
|
|
applications.
|
|
|
|
Segments are numbered from 0. Segment 0 contains information for
|
|
the segment loader and is created by the linker. Segment 1 contains
|
|
your application code and the startup code. This segment __must__
|
|
contain "MSL Runtime Palm OS (xx).lib", PilotMain(), and any code that
|
|
is executed when PilotMain() receives a launch command other than
|
|
sysAppLaunchCmdNormalLaunch. This stipulation is caused by the fact
|
|
that A5-relative data is not relocated when the application is called
|
|
with any other launch code, thus all global variable addresses will be
|
|
wrong and cause a crash.
|
|
|
|
The best way to determine what files can go into segments other than 1
|
|
is to comment out the code in PilotMain() that handles the
|
|
sysAppLaunchCmdNormalLaunch command, select the "Link Map" option from
|
|
the 68K Linker preferences, and rebuild. Any file that shows up in
|
|
the link map on a line beginning with "Code:" must be in the first
|
|
segment.
|
|
|
|
If you follow the coding style used by the Palm OS examples, form
|
|
handlers and the static functions called by the form handlers are good
|
|
candidates to be placed in secondary segments.
|
|
|
|
**********************************************************************
|
|
* IMPORTANT INFORMATION REGARDING FUTURE OS COMPATIBILITY *
|
|
**********************************************************************
|
|
|
|
Starting with the Palm OS SDK 4.0 Update 1, the default compilation
|
|
options disallow direct access to Palm OS internal data structures.
|
|
The file BuildDefaults.h (which is located within the "Incs" folder
|
|
inside the "Palm OS Support" folder) contains the compiler flags
|
|
correctly set:
|
|
|
|
#define DO_NOT_ALLOW_ACCESS_TO_INTERNALS_OF_STRUCTS
|
|
|
|
Compile your application as you normally do, and fix the potential
|
|
incompatibilities that are identified.
|
|
|
|
Some samples shipped with older versions of the SDK may have used
|
|
direct access of internal structures instead of using APIs. Those
|
|
samples will no longer build correctly as a result of this change to
|
|
the default compilation options. To work around this problem, you
|
|
can edit the header file buildDefaults.h and comment out the
|
|
following line near the end of the file:
|
|
|
|
// #define DO_NOT_ALLOW_ACCESS_TO_INTERNALS_OF_STRUCTS
|
|
|
|
With this change, the old samples will compile properly. However,
|
|
Palm engineering recommends that developers DO NOT directly access
|
|
internal data structures.
|
|
|
|
**********************************************************************
|
|
* IMPORTANT INFORMATION REGARDING METROWERKS CODEWARRIOR *
|
|
**********************************************************************
|
|
|
|
- Palm OS SDK 5 SDK (68K) R3 and CodeWarrior for Palm OS R8
|
|
|
|
All of the examples and other Metrowerks project (MCP) files were
|
|
last saved using CodeWarrior for Palm OS R8.
|
|
|
|
- Checking for updates for Metrowerks components
|
|
|
|
Metrowerks occasionally provides updates to some components, such
|
|
as the IDE and other plug-ins. To make sure that your Metrowerks
|
|
components are up to date, please check for updates and patches on
|
|
the Metrowerks web site:
|
|
|
|
http://www.metrowerks.com/download/
|
|
|
|
*********************************************************************
|
|
* KNOWN ISSUES *
|
|
*********************************************************************
|
|
|
|
- Constructor for Palm OS
|
|
|
|
No font editor: Constructor does not provide a native font editor.
|
|
You can use Constructor to create Font Families, but you must first
|
|
create the fonts with an external font editor.
|
|
|
|
|
|
Windows limitations:
|
|
|
|
Chinese double-byte support makes use of the Altura emulation
|
|
library, which does not have support for Simplified Chinese. In
|
|
general, Constructor still supports Simplified Chinese, but you
|
|
may see some text drawing flickering, garbage drawing results, or
|
|
text editing issues due to double-byte characters not being handled
|
|
correctly.
|
|
|
|
Chinese features are not supported on the English version of
|
|
Windows XP with Chinese regional support. Some third-party
|
|
utilities may solve this problem, such as NJStar Communicator 2.30
|
|
(www.njstar.com).
|
|
|
|
Supported CodeWarrior IDE on Windows:
|
|
|
|
Constructor requires version 3.1.0.0 of ASINTPPC.DLL, which is
|
|
shipped with the Metrowerks CodeWarrior for Palm OS R-series
|
|
environments. If you want to use Constructor with a Pro-series
|
|
version of CodeWarrior, you need to copy ASINTPPC.DLL and SHW32.DLL
|
|
(version 4.0.0.0) into the same directory as the "Constructor for
|
|
Palm OS.EXE" file.
|
|
|
|
*********************************************************************
|
|
* INSTALLATION INSTRUCTIONS *
|
|
*********************************************************************
|
|
|
|
+--------------------------------------------------------------------+
|
|
+ Manual Installation +
|
|
+--------------------------------------------------------------------+
|
|
|
|
Macintosh
|
|
|
|
1. Locate the "CodeWarrior Support" folder which is in the "SDK"
|
|
folder.
|
|
|
|
2. Move the items located inside the "Codewarrior plugins" folder in
|
|
the "SDK" folder into their respective folders where CodeWarrior
|
|
is installed on your local drive. (Make sure to use the correct
|
|
version of a tool depending on the OS version you are running when
|
|
both a classic version and a Carbonized versions are present.)
|
|
|
|
This will include the following:
|
|
|
|
- Move "PalmRez Post Linker" from the "Linkers" folder on the SDK
|
|
to the "Linkers" folder inside the "CodeWarrior Plugins" folder
|
|
where your CodeWarrior is installed on your local drive. This
|
|
will replace the old "PalmRez Post Linker" file.
|
|
|
|
- Move "PalmRez Panel" from the "Preference Panels" folder on the
|
|
SDK to the "Preference Panels" folder inside the "CodeWarrior
|
|
Plugins" folder where CodeWarrior is installed on your local
|
|
drive. This will replace the old "PalmRez Panel" file.
|
|
|
|
Note: If you are doing development on a Japanese system, then
|
|
replace the "PalmRez Panel" file with "PalmRez-J Panel" file.
|
|
You can have only one PalmRez Preference Panel on your system
|
|
at a time.
|
|
|
|
- Move the "Support" folder from the SDK to the "Codewarrior
|
|
Plugins" folder on your local system. If a "Support" folder
|
|
already exists, then copy only the "PalmRez Japanese Support"
|
|
and "PalmRez ChinSimp Support" files to your existing "Support"
|
|
folder.
|
|
|
|
- Merge the "Palm OS Support" folder from the SDK into the
|
|
directory where CodeWarrior is installed on your local drive.
|
|
|
|
- Manually copy any other files located on the SDK or downloaded
|
|
from the web to your local drive.
|
|
|
|
|
|
Windows - CodeWarrior
|
|
|
|
1. Locate the "CodeWarrior Support" folder which is in the "SDK"
|
|
folder.
|
|
|
|
2. Move the items located inside the "Codewarrior plugins" folder on
|
|
the SDK into their respective folders where CodeWarrior is
|
|
installed on your local drive.
|
|
|
|
This will include the following:
|
|
|
|
- Move the "PalmRezPostLinker.dll" from the "Linkers" folder on
|
|
the SDK to the "Linkers" folder inside the "Bin\Plugins" folder
|
|
where CodeWarrior is installed on your local drive. This will
|
|
replace the old "PalmRezPostLinker.dll" file.
|
|
|
|
- Move the "PPalmRez.dll" from the "Preference Panels" folder on
|
|
the SDK to the "Preference Panels" folder inside "Bin\Plugins"
|
|
folder where CodeWarrior is installed on your local drive. This
|
|
will replace the old "PPalmRez.dll" file.
|
|
|
|
Note: If you are doing development on a Japanese system replace
|
|
the "PPalmRez.dll" with "PPalmRez-J.dll". You can have only one
|
|
PalmRez Preference Panel in your system at a time.
|
|
|
|
- Move the "Support" folder from the SDK to the "Bin\Plugins"
|
|
folder on your local system. If a "Support" folder already
|
|
exists, copy only the "PalmRez Japanese Support" and "PalmRez
|
|
ChinSimp Support" files to your existing "Support" folder.
|
|
|
|
- Merge the content of the "Palm OS Support" folder from the SDK
|
|
with the "Palm OS Support" folder contained in your CodeWarrior
|
|
environment.
|
|
|
|
- Manually copy any other files located on the SDK or downloaded
|
|
from the web to your local drive.
|
|
|
|
+--------------------------------------------------------------------+
|
|
+ Installation for prc-tools / GCC +
|
|
+--------------------------------------------------------------------+
|
|
|
|
This archive contains the GCC versions of the NetSocket and PalmOSGlue static
|
|
linker libraries that were omitted from the initial 5.0 R3 SDK archive. It is
|
|
available in three formats:
|
|
|
|
- Header files and libraries packaged as an RPM
|
|
|
|
This RPM contains the SDK header files and static libraries and is suitable
|
|
for RPM-based Linux distributions and other Unix-like operating systems
|
|
which support RPM.
|
|
|
|
- A tarball containing header files (with Unix line termination) and libraries
|
|
|
|
This tar archive contains the SDK header files and static libraries and is
|
|
suitable for any Unix-like operating system.
|
|
|
|
- A zipfile containing the libraries
|
|
|
|
This zip archive contains the SDK static libraries only; it can be used,
|
|
on Windows or any other operating system, to add GCC SDK libraries to an
|
|
existing installation of the SDK header files.
|
|
|
|
This archive does not contain the SDK examples or documentation; you can obtain
|
|
those from the initial full 5.0 R3 SDK archive. Windows users who need the SDK
|
|
header files will find these too in the initial full 5.0 R3 SDK archive.
|
|
|
|
The RPM can be installed in the usual RPM way; check the package's information
|
|
(rpm -qip) for considerations for users of non-Linux operating systems or
|
|
non-standard PalmDev tree locations.
|
|
|
|
Unpacking the tar or zip archives will create a hierarchy of files underneath
|
|
a "sdk-5r3" directory. The archive, whichever of the two you use, should be
|
|
unpacked directly within your PalmDev tree (e.g., /opt/palmdev), so that its
|
|
files are arranged underneath /opt/palmdev/sdk-5r3.
|
|
|
|
If you are using the zip archive to add the libraries alongside an existing
|
|
installation of the 5.0 R3 SDK header files, you should unpack the archive so
|
|
that the "lib" directory is a sibling of the "Incs" or "include" directory
|
|
containing the header files. (Most likely the header files are in
|
|
/PalmDev/sdk-5r3/include or /PalmDev/sdk-5r3/Incs, so this means that the
|
|
libraries will be in /PalmDev/sdk-5r3/lib.)
|
|
|
|
To recap: you need to unpack this archive so that the SDK header files and
|
|
libraries are arranged in a directory tree as follows:
|
|
|
|
/opt/palmdev/sdk-5r3/include
|
|
/opt/palmdev/sdk-5r3/include/PalmTypes.h ...etc...
|
|
/opt/palmdev/sdk-5r3/include/Core/...etc...
|
|
/opt/palmdev/sdk-5r3/lib
|
|
/opt/palmdev/sdk-5r3/lib/m68k-palmos-coff
|
|
/opt/palmdev/sdk-5r3/lib/m68k-palmos-coff/libPalmOSGlue.a ...etc...
|
|
/opt/palmdev/sdk-5r3/lib/m68k-palmos-coff/mown-gp/...etc...
|
|
|
|
(On Windows, replace "/opt/palmdev" here by "/PalmDev". It is also
|
|
acceptable for the header files to be under a directory named "Incs" rather
|
|
than "include"; this may be more convenient if you have unpacked the initial
|
|
Windows 5.0 R3 SDK archive or used the installer.)
|
|
|
|
Remember to rerun palmdev-prep after installing these libraries!
|
|
|
|
To verify that the SDK libraries have been detected, check the report
|
|
generated when palmdev-prep is run; it should include a line such as
|
|
|
|
sdk-5r3 headers in 'include', libraries in 'lib'
|
|
|
|
rather than a line containing "no libraries".
|
|
|
|
+--------------------------------------------------------------------+
|
|
+ Installation Using Installers +
|
|
+--------------------------------------------------------------------+
|
|
|
|
NOTE: The installer will replace any older version of Palm OS SDK.
|
|
|
|
Macintosh
|
|
|
|
This installer will only install the components needed by CodeWarrior
|
|
to your local drive. For all other items you can drag the folder to
|
|
the necessary place.
|
|
|
|
1. Start the "Palm OS 5 SDK (68K) R3 Installer" application.
|
|
|
|
2. Follow the instructions displayed by the installer.
|
|
|
|
3. The following items will be installed by this installer:
|
|
|
|
- "PalmPlugin" will be added to your
|
|
"Metrowerks CodeWarrior:CodeWarrior Plugins:Debuggers" folder.
|
|
|
|
- "PalmRez Post Linker" will be added to your
|
|
"Metrowerks CodeWarrior:CodeWarrior Plugins:Linkers" folder.
|
|
|
|
- "PalmRez Panel" will be added to your
|
|
"Metrowerks CodeWarrior:CodeWarrior Plugins:Preference Panels"
|
|
folder.
|
|
|
|
- "PalmRez Japanese Support" will be added to your
|
|
"Metrowerks CodeWarrior:CodeWarrior Plugins:Support" folder.
|
|
|
|
- "PalmRez ChinSimp Support" will be added to your
|
|
"Metrowerks CodeWarrior:CodeWarrior Plugins:Support" folder.
|
|
|
|
- "Constructor for Palm OS" will be added to your "Palm OS
|
|
Constructor" folder and remove the old version.
|
|
|
|
- "Palm OS Support" folder in the "Metrowerks CodeWarrior" folder
|
|
will be updated with the latest header files.
|
|
|
|
- On English systems, the PalmRez-J panel plug-in will be
|
|
installed to your "Palm OS Extras:Japanese" folder.
|
|
|
|
- "Palm OS 5 SDK 68K R3 Readme.txt" will be installed to the
|
|
root of your CodeWarrior installation.
|
|
|
|
- The Palm documentation will be added to your "Palm
|
|
Documentation:Palm OS 5 SDK (68K) Docs"
|
|
folder.
|
|
|
|
- The Palm examples will be added to your "(CodeWarrior
|
|
Examples):Palm OS 5 SDK (68K) R3 Examples" folder.
|
|
|
|
- The Palm Stationery will be added to your "Stationery:Palm OS
|
|
Application" folder. Any existing stationery will be replaced.
|
|
|
|
- The Palm debugger will be added to your "Palm Tools:Palm OS 5
|
|
SDK (68K) Other Tools:PalmDebugger" folder.
|
|
|
|
- The overlay tools will be added to your "Palm Tools:Palm OS 5
|
|
SDK (68K) Other Tools:Overlay Tools" folder.
|
|
|
|
|
|
Windows - CodeWarrior
|
|
|
|
This installer will only install the components needed by CodeWarrior
|
|
to your local drive. For all other items you can drag the folder to
|
|
the necessary place.
|
|
|
|
1. Start the "Palm OS 5 SDK (68K) R3.exe" application. This will
|
|
unarchive and start the installer.
|
|
|
|
2. Follow the instructions displayed by the installer.
|
|
|
|
3. The following items will be installed by this installer:
|
|
|
|
- "PalmRezPostLinker.dll" will be added to your
|
|
"bin\plugins\Linker" folder.
|
|
|
|
- "PPalmRez.dll" will be added to your "bin\plugins\Preference
|
|
Panel" folder.
|
|
|
|
- "PalmRez Japanese Support" will be added to your
|
|
"bin\plugins\Support" folder.
|
|
|
|
- "PalmRez ChinSimp Support" will be added to your
|
|
"bin\plugins\Support" folder.
|
|
|
|
- "Constructor for Palm OS.exe" will be added to your "Palm
|
|
Tools\Constructor" folder.
|
|
|
|
- "Palm OS Support" folder in the "Metrowerks CodeWarrior" folder
|
|
will be updated with the latest header files and libraries. Any
|
|
existing version will be renamed "(old Palm OS Support)"
|
|
|
|
- "PPalmRez-J.dll" will be installed to your "Palm Tools\Palm OS 5
|
|
SDK (68K) Other Tools\Palm OS Extras\Japanese Support\
|
|
CodeWarrior Support\Plugins\Preference Panel" folder.
|
|
|
|
- "Palm OS 5 SDK 68K R3 Readme.txt" will be installed to the
|
|
root of your CodeWarrior installation.
|
|
|
|
- The Palm documentation will be added to your "Palm
|
|
Documentation\Palm OS 5 SDK (68K) Docs" folder.
|
|
|
|
- The Palm examples will be added to your "(CodeWarrior
|
|
Examples)\Palm OS 5 SDK (68K) R3 Examples" folder.
|
|
|
|
- The Palm Stationery will be added to your "Stationery\Palm OS
|
|
Application" folder. Any existing stationery will be replaced.
|
|
|
|
- The Palm debugger will be added to your "Palm Tools\Palm OS 5
|
|
SDK (68K) Other Tools\PalmDebugger" folder.
|
|
|
|
- The overlay tools will be added to your "Palm Tools\Palm OS 5
|
|
SDK (68K) Other Tools\Overlay Tools" folder.
|
|
|
|
|
|
PalmSource, Inc.
|
|
1240 Crossman Avenue
|
|
Sunnyvale, California 94089
|
|
(408) 400-3000
|