IFCTF PalmOS GNU Programming Environment (IPGPE) Alpha version @(#)README 1.1 00/09/05 What is IPGPE? IPGPE is the solution designed by the Embedded Systems Engineering (ESE) group of the International Free Computing Task Force (IFCTF) for programming for the PalmOS handheld embedded system with the Cygnus/GNU software development toolchain. It is one of the many possible solutions, but IFCTF considers it to be the right one. IPGPE replaces our group's previous work on PRC-Tools, which we have stopped as we have found that PRC-Tools are not the right solution in our opinion. The full IPGPE when it is ready will be fully integrated into the Cygnus toolchain as a regular target. See the file cygnus-tree-intro in the /pub/embedded directory of this site for information about the Cygnus toolchain. The full IPGPE is not ready yet, however. Instead, we currently have an alpha version. The toolchain for this alpha version is built in a single tree, as it should be and as it will be in the final version. However, when putting this single tree together, one must use the special version of the gcc module available from this site (details below). This special gcc module is a leftover from PRC-Tools that we haven't eliminated yet. The official current CVS versions of all other modules are used. In addition to the toolchain with this special gcc module, IPGPE-Alpha needs a support package with components that fall outside the scope of the Cygnus toolchain (in its present state at least). This package is available from this site. Thus to build and install IPGPE-Alpha, you need to build and install two things: the toolchain and the support package. The two are described below. Toolchain for IPGPE-Alpha Before you tackle the special toolchain for IPGPE-Alpha, you must be familiar with the standard Cygnus toolchain. See the file cygnus-tree-intro in the /pub/embedded directory of this site. In particular, see section 3 in that article for the description of how to put this toolchain together in a single tree. The special toolchain for IPGPE-Alpha generally follows that procedure with these differences: 1. Required modules. The tree for IPGPE-Alpha must contain the top-level files, the config, include, and texinfo support subdirectories, and the following modules: * etc, intl, libiberty (used by everything) * bfd, opcodes, binutils, gas, ld, gprof (Binutils components) * gcc (see below) * newlib 2. Special modules. A special version of the gcc module must be used. gcc modules for use with IPGPE-Alpha will be put up on this site as they become available. Look for files named gcc-module-* in this directory. Use the latest if there is more than one. The current version is 2.95.3-ipgpe-alpha-2. This special gcc module does not include any non-C language front ends. No non-C languages are supported in IPGPE-Alpha. 3. Special version of top-level Makefile.in. The special gcc module used for IPGPE is based on an old version of mainline gcc that no longer works correctly with the current CVS version of the top-level Makefile.in. You must replace the latter with the version provided in this directory. (It's actually a one line change relative to the current CVS version.) 4. Supported modules. None of the language target library modules are supported and none should be included in the tree. This is obvious since no non-C languages are supported and no non-C language front ends are included in the IPGPE-Alpha gcc module. There is currently no debugging support. You can include the gdb module (the official current CVS version) and it will probably build, but it will be of little use since it doesn't know how to talk to the Pilot ROM debugger or how to locate your program in the PalmOS address space. This will be fixed real soon. Most of the other non-target-specific modules in the Cygnus tree will probably work, although they will probably be of limited usefulness for PalmOS. 5. libgloss conflict. The libgloss module is not supported or needed for IPGPE. It is not supported or needed for many other targets either. However, normally the configure system automatically determines when it is needed or not and enables or disables it accordingly. However, because IPGPE-Alpha still uses the m68k-palmos-coff target left over from PRC-Tools, which is the wrong target to use for this, libgloss is erroneously enabled when it is present in the tree and clashes with IPGPE. Therefore, libgloss must be removed from the tree. 6. Configure target. When you have pieced the tree together, configure it for --target=m68k-palmos-coff. This target is left over from PRC-Tools. Do not use the tree constructed as directed here for any other targets. The IPGPE-Alpha gcc module, which is of PRC-Tools origin, is not a clean port and won't work for anything else. IPGPE Support Package After you've built and installed the toolchain, you need to download, build, and install the IPGPE support package. Look for files named ipgpesup-* in this directory. Use the latest if there is more than one. The current version is ipgpesup-0.1. This version has one slight gotcha. Until a new fixed one is ready, see below about PalmOS SDKs. IPGPE-Alpha and Palm SDKs IPGPE is designed to be usable without Palm SDKs. That is, it should be possible to build IPGPE itself, including all target libraries, without any Palm SDKs. The full IPGPE will allow users to write pure GNU code instead of Palm code without using or needing any Palm SDKs. However, building Palm code is also supported, as are all PalmOS SDKs. IPGPE-Alpha supports Palm SDKs in the same way as the recent versions of PRC- Tools (0.6.0beta and 2.x), i.e., you must use SDKs in the same format as you would use for PRC-Tools. Specifically, IPGPE-Alpha supports the PalmOS 1, 2, 3.1, and 3.5 SDKs. They must be installed in your sharedstatedir. Yes, I know, this is a very odd place for them. But don't blame me, it's a leftover from PRC-Tools. If, let's say, your prefix is /usr/local/ipgpe, your sharedstatedir will normally be /usr/local/ipgpe/com, and this is where you have to put your SDKs. The PalmOS 1, 2, 3.1, and 3.5 SDKs go into sdk-1, sdk-2, sdk-3.1, and sdk-3.5 subdirectories, respectively. Specifying -palmos1, -palmos2, -palmos31, and -palmos35 on the gcc command line will select the corresponding SDKs. If you don't specify any of these options, gcc will look in the plain sdk subdirectory. You can make sdk a symlink to your SDK of choice to make it the default. Otherwise, there will be no default SDK, requiring all projects that need a Palm SDK in order to build to specify which one they need. This is what I recommend. As I've said, IPGPE itself, including all target libraries, should be buildable without any Palm SDKs. The goal was for this to be achieved even in IPGPE- Alpha, and all target libraries except one have been converted to build without a Palm SDK. Unfortunately, there is still one target library in ipgpesup-0.1 that hasn't been converted yet and still uses the PalmOS 3.1 SDK. Therefore, until that is fixed (which will be real soon), you must have the PalmOS 3.1 SDK installed in order to build ipgpesup, regardless of which SDK(s), if any, you want to use for your own software development. You need to install it after building and installing the toolchain, but before building ipgpesup. You can also install any other SDKs you want at the same time. There is no need to set the PalmOS 3.1 SDK as the default. Miscellaneous MANUAL.old in this directory contains the old manual from prc-tools-0.6.0beta, IPGPE's predecessor. Some things have changed, but a lot of it is still relevant. An updated manual is on the to-do list. All questions about IPGPE should be directed to the ESE PalmOS Tools mailing list, ese-palmos-tools@ivan.Harhan.ORG. To subscribe, send a message to ese-palmos-tools-request@ivan.Harhan.ORG. Enjoy IPGPE! (If you can handle all this, that is... :-) Michael Sokolov Public Service Agent International Free Computing Task Force msokolov@ivan.Harhan.ORG