How-To

QPE on the iPAQ running the Intimate/Debian Distribution

This is Version 1.18, dated July 26, 2001.

The Qt Palmtop, a Palm-like environment based on Qt, offers some advantages over the default X distribution that comes with the Intimate / Debian distribution for linux-capable handhelds such as the Compaq iPAQ 3600 series. These include readability, availability of a bunch of PIM tools, and a framework for compiling one's own programs in the widely-used (read: KDE) Qt environment.

The question is, will it run under intimate. The answer: Sure 'nuff (that's Texan for yes)!

Here's how (do this stuff over the serial port running PPP from your host computer):

Stop X and remove X initiation

      #cd /etc/rc2.d/
      #./S99x stop    (stops the X server)
      #rm S99x        (or copy it someplace: it's just a link)

      B.  Copy ipkg from familiar to intimate
      #mount /boot
	
      	Note:  
		If 'mount /boot' fails because its not defined in your '/etc/fstab' then try:

      		#mount -t jffs2 /dev/mtdblock/3 /boot

		Better yet for the future you can add the following line in your '/etc/fstab' so
		mount automatically knows about your Familiar partition:

		/dev/mtdblock/3	/boot	jffs2	defaults,noauto 0 0

		After you add this line you should be able to just 'mount /boot'

      #cp -p /boot/usr/bin/ipkg /usr/bin
      #cp -p /boot/etc/ipkg.conf    /etc
      #umount /boot
      #mkdir /usr/lib/ipkg
      #cd /usr/lib/ipkg
      #touch available pending status
      #mkdir info

Get the version of libc6 needed by QPE. If you overwrite your existing libc6 library (which is what I did), just run ldconfig and all should be well (at least so far).

      #cd /usr/lib
      #cp -p /usr/lib/libstdc++-3-libc6.2-2-3.*.0.so
             < someplace safe >  (this appears to be optional)
      #ipkg update
      #ipkg install libc6 (from the familiar site.  Note that this
          will overwrite the libc6 library you just copied, 
          which is why you copied it.  ipkg will ask if you
          want to install a bunch of familiar packages on 
          which ipkg depends.  I answered No.)
      You will find that many system commands, like ls, won't
      work now because they can't find the libc6 library.
      Do either:
      #ldconfig       (in case you didn't copy the libc6 lib)
      or
      copy the libc6 library back into /usr/lib.
      You might want to run   ls   to make sure it works!

Edit /etc/ipkg.conf (per http://qpe.sourceforge.net/ipaq.html):

      #vi /etc/ipkg.conf
        Comment out the exiting IPKG_SOURCE line, then add
        IPKG_SOURCE="http://qpe.sourceforge.net/packages/ipaq/"
        to the file

	Note:  If you happen to have upgraded to ipkg-0.9 then
	       follow the newer format for your qpe repository:

	src qpe.sourceforge.net http://qpe.sourceforge.net/packages/ipaq/	

      #ipkg update      (to get the list of qpe packages)

Now download the desktop

      #ipkg install qpe-qipkg
        (This should do the trick.  In my case, the load
         aborted because I didn't have the right libc6 lib,
         and reinstalling qpe-qipkg didn't add any more
         packages.  So, I did
           #ipkg install qpe-base
         and that brought over everything else for the
         initial installation.)
      #ls -l /opt/QtPalmtop/bin/qpe
        (If this file doesn't exist, the install wasn't
         successful and the new desktop won't start - see
         /etc/init.d/qpe for details.)

Now reboot, and watch in amazement as the iPAQ screen now becomes useful!
```
      #sync;sync;sync;reboot
```
Load the packages you want (e.g., spreadsheet, date/calendar planner, to-do list, etc).
```
      #ipkg list
      #ipkg install (your choice of what's on the list)
```
Tips and Suggestions
- PPPD: in /etc/ppp/options, add the following:
```
      # this causes PPPD to make the host computer the default target for
      # IP addresses outside this machine
      defaultroute

      # this causes PPPD to wait until it receives a packet from the host PPPD 
      # daemon before sending any packets.  Hopefully this will avoid the 
      # "serial line is looped back" problem.  Thanks to Michael Beach via
      # http://www.geocrawler.com/archives/3/59/1997/7/0/2206064/
      silent
```
- Compiling programs under Qt/Embedded and QPE.
  To compile software, you will need to follow the instructions here and here. If you follow those instructions carefully, you don't need to read much below. But in case you don't want to read those, here is what I found to work.
  - The uic preprocessor The instructions have a passing reference to uic, a preprocessor needed for Qt programs. The suggestion was made to run that on the host computer. Fortunately, the iPAQ with a 1 GB microdrive can handle native compilation easily so you might want to have a copy on your iPAQ also.
    After running apt-get install xlib6g-dev to get the files and libraries for X client development, you can compile the full X11 version of Qt. The compilation broke in the designer files, which exhausted RAM and swap space. But, uic compiled just fine. I had to download the X11 development files because it was way too much work to strip out the X11 references in the library files on which uic depends.
    When you are done with this compilation, you will have to rename the directory tree because the Qt/embedded tree has the same name as that of the X11 distribution. When you have finished compiling Qt/embedded, remember to copy uic to from the renamed directory tree to the new $QTDIR/bin directory.
  - Patching Qt/embedded 2.3.1 to work with QPE 1.3.1 There are several important patches that need to be applied, and they are provided in $QPEDIR/qt/qte231-for-qpe.patch. This patch modifies Qt/Embedded 2.3.1 so as to be sufficient for Qt Palmtop: The Transformations feature is split into Painter Transformations and Pixmap Transformations so the latter is still available, fonts are found in $QTDIR/lib/fonts, not $QTDIR/etc/fonts, and screen blanking is fixed for the iPAQ (workaround+bugfix).
```
cd $QTDIR
patch -p0 < $QPEDIR/qt/qte231-for-qpe.patch 
```
    If you don't apply this patch, you will encounter the following error when compiling konqueror. (I provide the error messages so that people can retrieve this document when they use search engines to look for help with individual error messages.):
```
render_image.cpp: In method `void
  khtml::RenderImage::printObject(QPainter *, int, int, int, int,
  int, int)':
render_image.cpp:205: aggregate `class QWMatrix matrix' has
  incomplete type and cannot be initialized        
```
    Thanks to Simon Hausmann hausmann@kde.org for explaining patiently that this patch will fix this problem.
  - Excluding Qt features in your compiled libraries Then, I compiled the Qt/embedded and the QPE libraries (see here for the source code). There is a major gotcha that actually has a simple solution. The gotcha is that Qt can be compiled without certain features. The QPE disables some features out of the box. The Qt/embedded configuration script allows you to disable various quantities of features but doesn't say what they are. What you want to do is make the list of disabled features identical during the two compilations. The following is documented on the QPE site, but I didn't understand it when I read it (probably in too much of a hurry) and maybe you won't either.
    If you don't make the two lists identical, you may get the infamous "undefined reference to `QMetaObject::new_metaobject(..." error. (I provide the error messages so that people can retrieve this document when they use search engines to look for help with individual error messages.)
    This error results when the QT_NO_PROPERTIES flag is defined for one library and not for the other. It turns out that the number of arguments in the instantiator for QMetaObject::new_metaobject() is reduced by 4 when this flag is defined during Qt/embedded (libqte.so) compilation, so the linker doesn't find an instantiator with a matching argument list when the other library was compiled with this flag undefined.
    The easiest way to make the two lists identical is:
    - Link or copy the list of excluded features in $QPEDIR to the directory that the Qt/embedded configure program uses:
```
ln -s $QPEDIR/qt/qconfig-qpe.h $QTDIR/src/tools
```
    - Run configure -qconfig qpe. This will cause configure to load qconfiq-qpe.h from the QPE directory tree so that the two libraries will be compiled with the same feature list.
    As I mentioned, the above is documented on the QPE site, but I didn't understand it when I read it (probably in too much of a hurry) and maybe you won't either.
- Increasing memory to compile large/complex programs
  The iPAQ comes with 32 or 64 MB of RAM. The intimate distribution instructions suggest making swap space less than 32 MB to avoid system lockups. The problem is that this is not enough memory to compile large or complex programs. The error message you will see is something like "compiler received signal 15".
  One example is konqueror-embedded, which has a module helper.cpp that requires 136.6 MB of memory for compilation. How to deal with this (and how did I know how much memory it takes)? The key is that Linux can use files for swap space as well as it can use swap partitions. You can create extra swap space as follows:
```
mkdir /swap2  (or whereever you want to put the swap file(s))
dd if=/dev/zero of=/swap2/swapfile bs=1024 count=31000
mkswap -f /swap2/swapfile
/sbin/swapon /swap2/swapfile
```
  I created an extra 31 MB swap file and recompiled konqueror-embedded. The compiler ran out of memory. I created another 31 MB swap file (total of 32 MB RAM and 94 MB swap). The compiler ran out of memory :( . I created a 130 MB swap file for a total of 32 MB RAM and 214 MB swap! Then I watched top as it compiled that module. The peak memory usage was 29.9 MB RAM and 106.7 MB swap, for a total of 136.6 MB memory usage.
  The only gotcha with this approach is that you probably shouldn't run swapoff on these files. I don't know whether that's true for Linux, but I read that it was true for SunOs. When you are done using them, just reboot the system. Since you didn't add them to /etc/fstab, they won't be put back into use unless you do so explicitly after the reboot. That means you can delete them after rebooting, if you wish.
Strengths and Limitations of QPE
- Strengths: as noted above. Also, input is amazingly easy, with a choice of graffiti (that comes with a great tutor), keyboard, pickboard, unicode (for kanji) and something called opti. You should be able to write your own programs using Qt on your desktop and compile them on the iPAQ (I haven't tried this yet.)
- Limitations: it's not X, so X applications like emacs will boot but won't interact with the mouse. In the case of emacs, the control keys entered via the keyboard work just fine, and this is probably true for all applications.

Please send questions and comments to widman-qpe@cardiothink.com. I have only one iPAQ and I haven't erased everything and repeated the process, so I can't promise that I didn't omit something or get something wrong in the list above. Please let me know of any inaccuracies as well as how the document could be more clear.

Copyright (C) 2001 Lawrence E. Widman. Unabridged reproduction in any form is authorized as long as the copyright notice is retained. Corrections and updates are welcome, but inaccurate changes are not :), so let me know if you want me to change this, or feel free to write your own!

Maintained and slightly corrected by pisymbol