HOWTOEN
Or how to convert the ipk packages for the Zaurus (for those who don't know what that is, a Zaurus is a Linux based PDA, using the same flavor of Linux as the PMA400 does.) into ipk packages for the PMA.
If you have a problem, you can contact me on yannickd@gmail.com
I hope I didn't do any mistake in this Howto. in anyway I will NOT be held responsible for any damage you might do to your computer or your PMA/Zaurus using this Howto!
Contents:
Prerequisite: have Linux
The PMA400 : why don't the Zaurus packages work out of the box on it?
Now that we understand a little better how it works, how can we adapt Zaurus packages to the PMA?
A few examples :
JustReader
ogg123
Some remarks for beginners
PREREQUISITE : Have Linux.
I don't think you can do all of that under Windows, or it's much more difficult. Anyway to develop on the PMA, Linux will have to be used.
For those who don't really know what Linux is, it's an Operating System (just like Windows) except that it's both Free and Open-Source (anyone can modify and improve it).
Installing Linux on a computer requires the user to create new partitions on the hard drive of the computer, which is rather stressful, especially for beginners. So here we'll have to be satisfied with a Linux Live-CD. I hope this will work with a Live CD at least. It has a reasonable enough amount of cache memory to do that, I think.
So a Linux Live CD will enable you to launch Linux on your computer without any installation, nor any trace (or scars ;) ) left by Linux on your computer. it's completely risk-free. The problem is that since everything runs from the CD, it's kind of low.
As far as Live CD go, I can avise you both Knoppix and SimplyMEPIS, which can be found there :
ftp://ftp.free.fr/pub/Distributions_Linux/knoppix/KNOPPIX_V3.7-2004-12-08-EN.iso
ftp://ftp.nluug.nl/pub/metalab/distributions/mepis/released/SimplyMEPIS-2004.06.iso
You just have to download one of the two files and burn it on a CD (a small remark for those who are really not used to doing that : avoid killing your CD-Rs, make sure you tell your CD-burning application to “burn a CD image” and then select the iso file. Don't burn the iso file directly on the CD).
If you can't download that, you can go to the nearest book store, look at the magazines for some Linux magazines, and some might have Live-CDs (or complete distributions) with them.
In the whole Howto, I'm going to give you instructions in the command line, because that's the standard in many Linux distributions and it always works. Even though it's not the simplest. For those unused to Linux, to launch a terminal from Linux you can hit ALT-F2 and then type xterm in the box. A command line terminal appears (a very ugly one at that ;) ).
You'll have to get used to Linux before doing everything that is done in this tutorial. I'll still do a quick summary of the main command I'll use and you'll use too :
cd : this command makes you change directory. You can browse the whole filesystem in that way. cd /home/yourlogin will bring you into your home directory for example. One little tip : try to use the TAB key to see what it does (basically it's autocompletion) it comes in really handy. And don't forget Linux is case-sensitive!
If you're a complete newbie, don't be afraid by the command line, since you just have to follow my instructions. If you experience some problems with a command, you can type in a terminal :
nameofthecommand --help
or:
man nameofthecommand
Else you can do almost everything using the graphical interface (by default it's KDE in most Live CDs I know).
So go ahead, use Linux through the trial and error method, and then, read further.
The PMA400 : why don't the Zaurus packages work out of the box on it?
In a nutshell it's because the OS of the PMA is on the hard drive. he PMA loads a part of in memory (22 MB, it's the aimage.img file) at each reboot (it's the progression black bar your can see at the bottom of the screen). The big problem is that it's the whole filesystem and with this method it's read-only! It cannot be modified (well just a little, but the changes will be gone at the next reboot).
On a desktop computer or on a Zaurus, no problem, it can me modified (for a Zaurus, only part of it can be modified, but you get the point). And many Zaurus programs take advantage of this fact and on the PMA try to write files where they cannot... Or simply where the files shouldn't go. SO it's necessary at first to change the ipk files and the way they install the programs on the PMA.
More on that very soon.
Another thing about the PMA400 : the whole filesystem is read-only, except for /media, which is where your hard drive is (the Archos explorer launches in /media, even though you don't see it).
Another directory is read-write, and this one will be of interest to us : it's the /progfs directory. that's where all the PMA additional programs get installed by default. As far as they're concerned, /progfs looks just like the Linux filesystem.
So if a Zaurus package wanted to install files in /usr/bin, it will install them in /progfs/usr/bin.... SO of course it doesn't find what it needs after installation and fails to launch.
To understand better, you have to know how Linux is organized : Linux has (just like Windows) what we call environment variables, which tells Linux where to look for binary executable files and libraries (libraries are most often needed by the binaries).
In the PMA, the environment variables tell Linux to look for the binaries (among other places) in /opt/QtPalmtop/lib and the libraries (among other places) into /opt/QtPalmtop/lib.
So logically, if the files are placed in /opt/QtPalmtop/lib and /opt/QtPalmtop/bin, well Linux should know where to find them and everything will work.
Of course, need I remind you that the file system is read-only, except for /media and /progfs? So in our case, /opt/QtPalmtop is too. Well not to worry, as it goes, /opt/QtPalmtop is a copy automatically updated of /progfs/opt/QtPalmtop, which isn't read-only!
So if the programs get installed into /progfs/opt/QtPalmtop, then the binary files and the libraries will be immediately shown into /opt/QtPalmot, which is recognized by the environment variables, so that Linux can find them! That way everything works!
Now that we understand a little better how that works, how can the Zaurus packages be translated to the PMA?
Well, you should first download the file ipkg-build from my site. You can do that with a browser or from a command line :
cd ~
wget http://elelome.files5.free.fr/Applicationsmodif/ipkg-build.sh
Then in the command line :
su
(A password will be requested, it's the Super-User/root/administrator password).
cp ~/ipkg-build.sh /usr/bin
chmod 755 /usr/bin/ipkg-build.sh
exit
Now you can build packages for the PMA400 (doesn't that rule? ;) )
Now I'll tell you how to adapt a package, generally speaking :
first in your home directory, create a directory called Test :
mkdir ~/Test
Then in this directory create the directories as shown there :
mkdir -p ~/Test/opt/QtPalmtop/bin
mkdir ~/Test/opt/QtPalmtop/lib
mkdir -p ~/Test/opt/QtPalmtop/apps/Applications/
mkdir ~/Test/opt/QtPalmtop/apps/Games
mkdir ~/Test/opt/QtPalmtop/apps/Settings
mkdir ~/Test/opt/QtPalmtop/pics
mkdir ~/Test/CONTROL
Then download the package you want to adapt into your home directory and then type :
cd ~
tar xvfz nameofthepackage.ipk
I'll remind you that hitting the TAB key is a very powerful tool.
If you get an error at this point, don't go any further, the package won't be converted to the PMA using this method.
If it works, you'll get files in your home directory, most notably control.tar.gz, data.tar.gz. You'll have to untar them in your home directory :
tar xvfz control.tar.gz
tar xvfz data.tar.gz
New
directories will appear in your Home. (they come from data.tar.gz) as
well as a control file (from control.tar.gz) Edit the control file
and change the architecture line from arm to pma400.
Then, copy
the file control into the directory Test/CONTROL :
cp ~/control ~/Test/CONTROL
Then you'll have to look into all the directories created by data.tar.gz. In these directories you'll undoubtedly find binary files (no extension, most of the time in a directory called “bin”) and librairies (with an .so extension, most of the time in a directory called “lib”)
Then copy all the binaries into ~/Test/opt/QtPalmtop/bin and all the librairies in ~/Test/opt/QtPalmtop/lib. Copy the images into ~/Test/opt/QtPalmtop/pics . If in the data.tar.gz directories some aren't called pics and contain images, then copy the directory containing the images into ~/Test/opt/QtPalmtop/pics. If there's a file with a .desktop extension copy it into one of the directories in ~/Test/opt/QtPalmtop/apps (System if you want the icons to appear under the system tab, etc.)
Sometimes there is a problem with this .desktop files. You'll encounter one in one of the following examples (justreader).
Once everything is done, you can type in a terminal :
cd ~
ipkg-build.sh Test
A file nameofthepackage_pma400.ipk then appears in your home directory (if you're using KDE, you might have to refresh Konqueror to see it). You then just have to transfer it to the PMA and install it.
That's it!
A few expamples.
Prerequisite : have read what's before and have created all the folders ~/Test/opt/QtPalmtop/etc as shown before. These folders should be empty.
justreader.
Let's start with somethin simple :
get the just reader package into your home drectory :
cd ~
wget http://ovh.dl.sourceforge.net/sourceforge/justreader/justreader_2.0k_arm.ipk
Then uncompress it (just as before) :
tar xvfz justreader_2.0k_arm.ipk
tar xvfz control.tar.gz
tar xvfz data.tar.gz
Modify the control file thus created and change Architecture: arm into Architecture: pma400 . Then copy the control file thus modified into ~/Test/CONTROL :
cp ~/control ~/Test/CONTROL
Into your home folder is now also a directory called opt
If you look at it, it looks wonderful : the binary files are well placed, the libraries too, the pictures too. That's great! Nothing will have to be modified, we'll just erase the folder ~/Test/opt that we had created and copy ~/opt (from data.tar.gz) in its stead :
rm -r ~/Test/opt
cp -r ~/opt ~/Test
Then we launch :
ipkg-build.sh Test
We get the PMA package, which, once installed on the PMA......... doesn't work... Yet if in the terminal of the PMA you type :
justreader
The program launches.
So the problem is not with the program, but with the icon and the way it works. The way the app launches is detailed in the .desktop file of justreader, which is now in the folder ~/Test/opt/QtPalmtop/apps/Applications and is called justreader.desktop. Change it. You'll notice that the last line refers to a 640x480 resolution, which is unfortunately not the case on the PMA. Actually this file is quite useless, erase it, or better comment it (which means that you should add # at the beginning of the line). Then save the changes. We'll then pack the Test folder once again :
rm ~/justreader_2.0k_pma400.ipk
cd ~
ipkg-build.sh Test
There, you just made an ipk file that will work flawlessly on the PMA! Congratulations!
ogg123 and ogglibs.
The well-known ogg vorbis reader for the Zaurus. If you just followed the first example, make sure the Test folder is clean. the best way to do that is to do :
rm -r ~/Test
mkdir -p ~/Test/opt/QtPalmtop/bin
mkdir ~/Test/opt/QtPalmtop/lib
mkdir -p ~/Test/opt/QtPalmtop/apps/Applications/
mkdir ~/Test/opt/QtPalmtop/apps/Games
mkdir ~/Test/opt/QtPalmtop/apps/Settings
mkdir ~/Test/opt/QtPalmtop/pics
mkdir ~/Test/CONTROL
You'll have to remove the following files as well :
rm -r ~/opt
rm control
rm control.tar.gz
rm data.tar.gz
Good. Now we're ready. Let's begin. First we'll get the packages off the Net :
cd ~
wget http://ipaq.vmlinuz.org/ogg/ogg123_1.0rc3_arm.ipk
wget http://ipaq.vmlinuz.org/ogg/ogglibs_1.0rc3_arm.ipk
Then uncompress ogg123 :
tar xvfz ogg123_1.0rc3_arm.ipk
tar xvfz control.tar.gz
tar xvfz data.tar.gz
You're used to it now, you should modify the control file which appeared, save it, and place it into the ~/Test/CONTROL folder.
Then you'll notice that data.tar.gz created a folder called /usr/bin where the binary of ogg123 is located. This way it won't work on the PMA (as I explained earlier). We'll then copy this binary file into the right directory :
cp ~/usr/bin/ogg123 ~/Test/opt/QtPalmtop/bin
Now the package is ready, you just have to build it :
ipkg-build.sh Test
That's it, you now have ogg123_1.0rc3_pma400.ipk in your home folder.
Yet ogg123 needs the libraries from the package ogglibs to workk. We'll adapt this package as well.
So first we have to get a clean platform, so we do as usual :
rm -r ~/usr
rm control
rm control.tar.gz
rm data.tar.gz
rm -r ~/Test
mkdir -p ~/Test/opt/QtPalmtop/bin
mkdir ~/Test/opt/QtPalmtop/lib
mkdir -p ~/Test/opt/QtPalmtop/apps/Applications/
mkdir ~/Test/opt/QtPalmtop/apps/Games
mkdir ~/Test/opt/QtPalmtop/apps/Settings
mkdir ~/Test/opt/QtPalmtop/pics
mkdir ~/Test/CONTROL
And yet again :
cd ~
tar xvfz ogglibs_1.0rc3_arm.ipk
tar xvfz control.tar.gz
tar xvfz data.tar.gz
Then do what's to be done with the control file.
You then notice that the librairies of the package are in ~/usr/lib
We'll copy that into the right directory :
cp -r ~/usr/lib/* ~/Test/opt/QtPalmtop/lib
There that's done :
ipkg-build.sh Test
A file ogglibs_1.0rc3_pma400.ipk has now been created.
Is it over just yet?
No, we need curl and libcurl. Well get them at :
cd ~
wget http://ipaq.vmlinuz.org/ogg/curl_7.9.6_arm.ipk
wget http://ipaq.vmlinuz.org/ogg/libcurl_7.9.6_arm.ipk
curl and libcurl work in exactly the same was as ogg123 and ogglibs. Doing the same commands as before will work. I'll let you repackage curl and libcurl by yourself.
You'll then copy ogg123, ogglibs, curl, and libcurl to the PMA400 and install them.
That's it!
For Linux beginners.
When I say that you should copy the files on the PMA, it's not that easy on some flavors of Linux, even though it will work almost automatically on many.
Yet if you don't know how to copy files over to your PMA, do :
su
(your root password is requested)
mkdir /mnt/sda1 (ignore any error message)
And then each time you'll want to copy files to the PMA, you'll have to plug the PMA in, wait for a few seconds, and then type in a termina :
Et à chaque fois que vous voudrez copier des fichiers sur le PMA, branchez le PMA. Attendez quelques instants, puis tapez :
su
(your root password is requested)
mount -o rw /dev/sda1 /mnt/sda1
The PMA is then available under /mnt/sda1, and you can copy files over to it. For example :
cd ~
cp ogg123_1.0rc3_pma400.ipk /mnt/sda1
When everything's done, you should close ANY application that might have access to the PMA and type :
umount /dev/sda1
This is vital.
This method is the most “difficult” one on Linux but it works on nearly all the flavors of Linux, which is why I chose it.
In case you wondered what the sign ~ that i use in many commands it (or you have guessed it), it's a shortcut to a user's home directory.