Podzilla 2 & 0 Compiling Tutorial for Newbies (via Slax)

Contributor Joined: 26 Jul 2007

Update:
A new, more complete tutorial-in-progress can be found on the Introduction_to_Compiling_for_iPodLinux page. Please try it out and leave feedback in the Talks page.

To do:
- Update libraries and sample source code
- Update tutorial with kernel and loader 2 compiling instructions
- Update all to Slax 6 and possibly add a pre-built ISO file

==========================================================================================
==========================================================================================

Foreword...

This is a tutorial that helps you compile podzilla 2, podzilla 0 and related applications using a non-install, user-friendly environment. This tutorial uses the live Linux distro Slax and some Slax modules that I created for iPL application compiling, which were release > here <. Since Slax is a live-CD distro (ie. it boots from a CD and requires no installation nor leave any traces), compiling can be done on almost any computer anywhere (as long as Slax has the right drivers). Since Slax is also a Linux distro, it can also directly access the iPod's Linux partition that iPL uses ; )

It is suggested that you first have some basic knowledge in using Linux/Unix/Terminal/Command Prompts and a general idea of what "compiling" is. I have set up the building environment (created from the modules) as user-friendly as possible, complete with auto-building scripts and sample source. Although there is no "ReadMe" file of such, all documentation on usage can either be found in this thread, the release thread, or within the script files (open them with KWrite by right clicking > Open with > KWrite).

Apart from that, the only other requirement for this tutorial is patience and a lot of free time. Getting things started will take a while (you might have to retry a few times if you mess up a bit), but once you've got it all set up, compiling and building will be easy from then on. If you are having any problems following this tutorial or getting errors you shouldn't, please retry (from scratch if necessary) before posting your questions. If it's a Slax related issue, search their forums first. If you have no choice but to post your problems here, make sure that you include all relevant information (ie. what step you were on, what the error was, etc.) so we can help you better (short, unclear posts shan't be answered).

Nevertheless, I hope that you are successful in following this tutorial and are able to compile podzilla 2 and legacy applications. This is just so that you can compile them yourself though - please don't go on to release hundreds of "custom" zillae (ie. Floydzilla-like). Instead, continue on to develop new applications and release them for the general good. This tutorial is not for compiling "because-I-can" - this is for helping new and potential developers join in the iPodLinux community. That said, looking forward to those new applications! Wink

~Keripo

==========================================================================================
==========================================================================================

Downloads...

It is suggested that you start downloading these files now (or asap) so that by the time you're done looking over the tutorial, things are already part-way done ; )

Slax 5:

Latest Slax 5 ISO (KillBill recommended)
Official Development Module

iPL-Dev Modules:

Main Download Folder (get all files)
(iPL_Compiling_Environment_v_1_1.mo, iPL_Toolchain_v_2_95_3.mo and iPL_Toolchain_v_3_4_3.mo)

Note: More mirrors found > here <. Please try downloading each file from separate locations to ease bandwidth use and also to speed things up ; )
Note2: Both toolchains have been split into 10 MB chunks; use 7-zip or any standard archiver to merge them.

Other Requirements:

- computer capable of booting from CD
- computer capable of burning a CD
- blank CD (preferably rewritable)
- stable internet connection (for downloading)
- basic knowledge on using the command prompt/terminal/bash shell (at least how to use the "cd " function)
- time, patience and a bit of good logic and common sense ; )

==========================================================================================
==========================================================================================

Tutorial...

Setting up and burning Slax

There are many ways of setting up (ie. MySlax, uselivemod, etc.) and running (ie. boot via CD, USB, Grub4DOS, ISOEmu, etc.) Slax in different environments (ie. live, hard-drive install, USB install, colinux, VMware, QEMU, etc.). I personally boot with the Slax files on my Windows hard drive (NTFS D:/ partition) and booting via Grub4DOS's chainloader (no MBR modification or partitioning method). This tutorial just uses a basic, workable method via live-CD. If you want easier and more customized methods (ie. using virtualization instead of physical booting, or booting from your iPod or files-on-local-hard-drive), you can ask and I may write up a "Jumping into Slax for Newbies (by a Newbie)" tutorial ; )

You'll notice that this part is probably the longest and most difficult part of the tutorial for those unfamiliar with using Linux. Once you get the basics, however, things are much easier from there. You won't need to limit yourself to Slax; there are hundred of different live distros just like Slax, booting from a CD/DVD/USB, requiring no setup, and leaving no traces ; ) (My iPL compiling modules are packaged specifically for Slax, however - if you want, you can make your own rpm or slackware package). If you're stubbornly refusing to switch from Winblows to Linux, try PCLinuxOS, now with Beryl (better example) Wink

1. Download Slax ISO:

Since this is a tutorial using Slax, the first thing to do is to download it (see download section). Choose either the Standard Edition or the KillBill Edition (KillBill comes prepackaged with wine, allowing for you to run many Windows applications on Linux). Do not, however, use Slax 6 as it uses a different module system (.lzm vs .mo) and is incompatible (I may update things when Slax 6 becomes stable though). What you want in the end is a slax-*.iso file. This .iso file is basically a copy of the contents of a CD. You will be modifying and burning the iso file onto a CD, then booting from it.

If you are using Windows, the next few steps can easily be done using MySlax. This tutorial, however, does not assume the host OS and so everything is done manually.

2. Modifying ISO:

Extract the content of the .iso into a single folder. Most standard file archivers or CD programs will be able to do this (ie. 7-zip for Windows, Stuffit Expander for Mac OS X, ISO Master for Linux). If things extracted correctly, you should see folders like "boot", "modules", etc. and lots of files like "livecd.sgn".

Copy the downloaded Slax modules into the previously empty "modules" folder. At the least you should have in there the following files (not necessarily the same versions though):

Code:

iPL_Compiling_Environment_v_1_1.mo
iPL_Toolchain_v_2_95_3.mo
iPL_Toolchain_v_3_4_3.mo
Official_Development_module_5_1_4.mo

3. Building new ISO:

Now, using the command prompt/terminal/bash shell, cd to the directory that you extracted the files from. If you do not know how to do that, stop following this tutorial right now. See "Other Requirements" in the download section - you must first learn how to basically use your OS's command shell before you even think about "compiling" - do not ask here or anywhere else as we will not answer.

Once you are in the extracted iso's root directory (ie. "C:/slax-killbill-5.1.8.1/"), you need to run the make_iso script.

Code:

For Windows: make_iso.bat C:\Slax-Mod.iso
For Linux: make_iso.sh [ /tmp/Slax-Mod.iso ]

The script will run for a while and finally give you a new iso file in the designated location (ie. "C:\" or "/temp"). There is no iso-making script for Mac OS X, however, so you will need to find another way to build an iso (not sure if the Linux script works for Mac though - try it and report results).

4. Burning ISO to CD:

Now that you have a modified Slax iso, you need to burn that iso to a CD. For Windows, there are numerous open, free and commercial burning programs. My favourite free, simple but functional one is Active(c) ISO Burner.
Mac OS X already comes with Disk Utility and should be able to burn an .iso right in Finder. For Linux, ISO Master should be able to handle things easily.

5. Booting the Live CD:

This is the tricky part and depends on your computer. The important part is that you need your BIOS to be able to boot from CD. Most computers should allow for that by default (how else would you reinstall an OS?). If you are unsure how to do this, try this page for Windows-defaulted-systems and this page for Macs. If you still can't find a method, use Google. Each computer's BIOS may be different - when you boot up your computer, look quickly for something like "Press F12 to enter Boot Menu/Setup" or other hot-keys. What you ultimately want in the end is your BIOS' boot order to look for and boot from CD first.

Once you've got your BIOS all set up, restart your computer with the Slax CD inside. If you set the BIOS to boot from CD first, after the computer has powered on, you should hear the CD drive whirl a bit and see a brief but important line containing the word "ISOLINUX" and some version number.

6. Welcome to Slax:

If things worked properly and isolinux ran correctly, you will be seeing a lot of scrolling lines and possibly a nice, clover, Slax bootsplash. After a while of text scrolling, you'll be asked to log in.

Code:

user: root
pass: toor

Once you've logged in, you'll need configure Slax for your computer monitor, then start KDE, the default GUI (graphical user interface).

Code:

xconf
startx

After a few seconds of loading, first you'll see your cursor as an "X", then you'll see it as a circle and duck foot thingy and KDE will start up. Wait for the startup box to disappear and the cursor to stop bouncing, et voila! Welcome to the world of Slax!

Double-checking

Now that you've got Slax set up and running, it's finally time to start doing things. For next time, it'll just be pop in CD, reboot computer, root/toor/xconf/startx and you're in (or you can use some quick cheats 0_o). But before you jump into compiling, you need to check to make sure you did things right.

1. Checking the iPL_Compiling_Environment module:

If the module was properly implemented, you should see a shortcut on the Desktop named "iPL Environment" that links to "/root/iPodLinux". Clicking on the shortcut should open up a new window. Inside the "/root/iPodLinux" directory should be two folders: "PZ0" and "PZ2". In both of those folders you should find a few scripts (ie. "Build-source.sh"), a "BuildDir" folder and a sample source folder (ie. "podzilla(2)-sample" folder). In the sample source folder will be many .c or .h files for the podzilla 0 source and a few folders and files for the podzilla 2 source. The "BuildDir" folder should contain an empty "source" folder and a few other folders containing pre-compiled libraries needed for compiling.

2. Checking the toolchain modules:

Using Konqueror, browse to "/usr/local". You can open up Konqueror (KDE's default file browser and web browser) by opening up the "Home" or "System" shortcut (or even the "iPodLinux Environment" shortcut) on desktop, then changing the "Location" bar to "/usr/local".

These toolchain modules are the same as the original .sh files used to manually install them. I have just extracted them and repackaged them as Slax modules for convenience. Podzilla 0 and legacy applications use the 2.95.3 toolchain, which should appear as the "arm-elf" folder in "/usr/local", while podzilla 2 uses the 3.4.3 toolchain, which should appear as the "arm-uclinux-tools2" folder in "/usr/local". If you decided that you only wanted to compile one type of application and didn't install both toolchains, you will only have one of the two folders.

3. Checking the official development module:

Open up Konsole, KDE's default shell (like Windows's command prompt and Mac OS X's terminal). You can open up Konsole by clicking on the black box with a ">_" on your bottom left corner beside the "K" start button. A black box titled "Shell - Konsole" should appear and you should see the line "root@slax:~#". Now type "make". If you see the returned line "make: *** No targets specified and no makefile found. Stop.", you've installed the official development module correctly. If you get the line "-sh make: command not found", that means that you didn't install the official development module (the official one has over 1000 votes and is rated 5). Since the official development module is too big to "uselivemod", you will have to rebuild a new iso containing the module (ie. go back to the "Modifying ISO" step).

Compiling at last!

If you've made it to this step, be happy cause your set-up worries are all over and done for. This section should be the easiest ever as I've already prepared everything for you using the auto-compiling scripts and provided sample source files. Compiling from source can be done automatically or semi-automatically via script, or manually via Konsole. I'll show you all three.

1. Adding the source file:

Source files go into the BuildDir/source folder. Obtain source files from either the accompanying sample source folders (CVS for podzilla 0 is no longer updated - the sample source found in "/root/iPodLinux/PZ0/podzilla-sample" is the most "recent")or from SVN for podzilla 2 (you will have to install the subversion module separately from Slax's modules page, then run the "PZ2-svn-update.sh" script, though I've never tried it). Copy all the files, to the BuildDir/source folder so that there exists the file "/root/iPodLinux/PZ*/BuildDir/source/Makefile" (where * is 0 or 2). If you want to do things manually via Konsole:

Code:

cd /root/iPodLinux/
cp -r PZ0/podzilla-sample/* PZ0/BuildDir/source (for podzilla 0)
cp -r PZ2/podzilla2-sample/* PZ2/BuildDir/source (for podzilla 2)

2a. Compiling podzilla 0:

Compiling can be done three ways. The automatic method is just a simple point-and-click and wait. While easiest, you will have no indication of when it finishes compiling nor if there are any errors (apart from inspecting the build.log file). The semi-automatic method takes a few more steps but is much better as you'll know when things are done and if there was a problem (though not what the problem is). The manual method involves all the typing, but gives you a full picture of the entire process and outputs all the errors. Only try one of these methods. You can retry them after you've cleaned things and want to recompile (see step 4)

Automatically: (shows nothing) <- extremely lazy way

Navigate to "/root/iPodLinux/PZ0" via Konqueror. Double click the "Build-source.sh" file. A "build.log" file should appear. Wait at least 15 seconds to allow the script to finish compiling (wait time depends on computer power). Since you are just running the script without Konsole, you will have no indication of when the compiling is complete. For podzilla 0, compiling time should be relatively quick. Once compiling is complete, you should find an extension-less, icon-less file named "podzilla" in the Build/source folder (if you don't that means the script is not done compiling yet!). If you compiled from the sample podzilla 0 source, the size of the "podzilla" binary should be 850.2 KB (bigger than the old "daily builds" since it is auto-compiled with MPD - to compile differently [ie. with MikMod support, no MPD, both or neither], edit the "Build-source.sh" file).
Note: If you have any Konqueror window open at BuildDir/source while things are compiling, you will not see the final "podzilla" binary after the "podzilla.elf" file appears. Instead, you'll have to refresh the browser a few times (click the circular arrow icon [Reload] beside the house icon [Home]) for it to appear.

Semi-Automatically: (shows notifications) <- first-timers

Open up Konsole and type:

Code:

cd /root/iPodLinux/PZ0
sh Build-source.sh

The script will automatically set up the build environment and compile with "make IPOD=1 MPDC=1". Once it's done, the script will output a "Compiled successfully!" message. You will find a compiled "podzilla" binary in the BuildDir/source folder. If the script stops before that message, there was an error in compiling. Check the "build.log" file to see the exact error.

Manually: (shows everything) <- suggested

Open up Konsole and type:

Code:

cd /root/iPodLinux/PZ0/BuildDir/source
export PATH=/usr/local/arm-elf/bin:$PATH
make IPOD=1 MPDC=1
chmod ugo+rwx podzilla

Note: the last make line can be "make IPOD=1", "make IPOD=1 MPDC=1", "make IPOD=1 MIKMOD=1" or "make IPOD=1 MPDC=1 MIKMOD=1", but for MikMod support, read the comments of the "Build-source.sh" file for modification instructions)
Note 2: make sure you typed the "export" line correctly, otherwise you will get an error about a non-existing "arm-elf-gcc" command)
Note 3: the extra "chmod" line is to change the permissions of the podzilla binary, thus allowing it to be completely executable on iPL)

You will get a lot of scrolling text as each file is compiled, then finally all linked together. The last outputted line you should have is "arm-elf-gcc " followed by a lot of .o files and .a files, then a return to the command line ("root@slax:~/iPodLinux/PZ0/BuildDir/source# "). If you had any errors, you would see them directly in Konsole. If there were no errors, you'll find a "podzilla" binary in the BuildDir/source folder.

2b. Compiling podzilla 2:

Compiling podzilla 2 is almost exactly the same as compiling podzilla 0. The only difference is changing "PZ0" to "PZ2" in all Konsole commands, slightly different manual commands, and the possible use of SVN. Since I use Windows to retrieve SVN (as my internet connection doesn't work with Slax except via VM), I won't include the steps. If you want, however, I did write a short SVN-retrieving script that retrieves files from SVN, then copies it to the BuildDir/source folder. Although it's based on my Windows batch file, I have no idea if it works.

Automatically: (shows nothing) <- extremely lazy way

Same as for podzilla 0. Navigate to "/root/iPodLinux/PZ2" via Konqueror. Double click the "Build-source.sh" file. A "build.log" file should appear. Since podzilla 2 requires many more steps than podzilla 0, wait a much longer time to allow the script to finish compiling (wait time depends on computer power). For my computer, it took over 30 seconds.
Note: If you have any Konqueror window open at BuildDir/source while things are compiling, you will not see the final "podzilla" binary after the "podzilla.elf" file appears. Instead, you'll have to refresh the browser a few times (click the circular arrow icon [Reload] beside the house icon [Home]).

Semi-Automatically: (shows notifications) <- first-timers

Also same as for podzilla 0. Open up Konsole and type:

Code:

cd /root/iPodLinux/PZ2
sh Build-source.sh

The script will automatically set up the build environment and compile with "make IPOD=1". Once it's done, the script will output a "Compiled successfully!" message. You will find a compiled "podzilla" binary in the BuildDir/source folder. If the script stops before that message, there was an error in compiling. Check the "build.log" file to see the exact error.

Manually: (shows everything) <- suggested

Slightly different from podzilla 0 since it uses a different toolchain. Open up Konsole and type:

Code:

cd /root/iPodLinux/PZ2/BuildDir/source
export PATH=/usr/local/arm-uclinux-tools2/bin:$PATH
make IPOD=1
chmod ugo+rwx podzilla

Note: to compile only the core podzilla 2 and not the modules, see the comments of the "Build-source.sh" file)
Note 2: make sure you typed the "export" line correctly, otherwise you will get an error about a non-existing "arm-elf-uclinux-gcc" command)
Note 3: the extra "chmod" line is to change the permissions of the podzilla binary, thus allowing it to be completely executable on iPL)

The podzilla 2 makefile includes a bunch of echo lines, things will look nicer and smooth (except when you get an error of course). If you don't have SVN installed, you'll get a bunch of "make: svnversion: Command not found" lines - you can just ignore those. For compiling modules, you may get a variety of minor errors, but unless they stop the script or prevent stuff from compiling, it's fine. The sample podzilla 2 source I've included outputs two "/tmp/ccl9BpwF.s" errors (apart from the SVN errors) - I have no idea what they mean but it doesn't seem to affect anything ; P. Compiling will be finished when you get the "Podzilla and modules have been built..." message and return to the command line. If there were no errors, you'll find a "podzilla" binary in the BuildDir/source folder and the module folders in the BuildDir/source/modules folder (for usage, however, you will only need the .o and "Module" file of each folder).

3. Copying onto your iPod:

Slax is a Linux distro, meaning it can read Linux partitions, meaning that you can directly install your compiled files to your iPod. Yay! (If you're clever and booted Slax up directly from your iPod, however, things will be a bit trickier ; P)

First off, plug in your iPod. Wait a while and KDE should automatically create 3 "Removable Device/What do you want to do?" pop-ups (assuming you created a Linux partition via the official iPodLinux Installer 2). The first one (ie. assigned "(sda)" but not necessarily the first to pop up) is the firmware partition and cannot be mounted properly - just click cancel for that one. The second one (ie. "(sda2)") is the main data partition and will contain the "iPod_Control" folder. The third one (ie. "(sda3)") is the Linux partition used by iPodLinux. Select "Open in New Window" and click "OK" for sda3. You should see a bunch of Linux folders such as "bin", "etc", "usr", "var", etc. Podzilla and other binaries usually go into the /bin folder, so that's where you'll put your compiled version.
Note: If you have other USB devices attached (ie. a flash drive), instead of "sda3" you will get "sd*3" where * can be any letter (ie. for me, it's "sdb3").

Open up another instance of Konqueror so you can see both windows at the same time. One window should be navigated to the /bin folder of the iPod's Linux partition (ie. "system:/media/sda3/bin") while the other should be at where the wanted "podzilla" binary is (ie. "/root/iPodLinux/PZ2/BuildDir/source/"). In the iPod's window, find and rename the original "podzilla" binary to "podzilla-old" in case you need it. Then click and drag the compiled "podzilla" file from your compiled source window to the iPod's /bin folder and choose "Copy here". If you are installing podzilla 2, you should also copy all the module folders into "/usr/lib". If you prefer using the shell/Konsole instead of the GUI:

Code:

mv /mnt/sda3_removable/bin/podzilla /mnt/sda3_removable/bin/podzilla-old
cp -f /root/iPodLinux/PZ2/BuildDir/source/podzilla /mnt/sda3_removable/bin/
cp -r /root/iPodLinux/PZ2/BuildDir/source/modules/* /mnt/sda3_removable/usr/lib/

Now that the files have copied over, you need to safely remove your iPod (unlike Windows, you can't just yank it out or else you'll get corrupt files ; / ). To do this, open the "System" shortcut on desktop, then enter "Storage Media". You should see your iPod as three USB icons named "Removable Device (sda*)" (where * is nothing, 2 and 3). Right click any one of them with a green arrow in the bottom right corner of the icon and select "Safely Remove". Wait until all three icons have disappeared, then yank out your iPod. Now restart your iPod and boot into iPodLinux as usual. If you copied things over correctly, you should be in podzilla 0 or podzilla 2 (the compiled PZ0 works on the video, but is extremely slow - such is due to old coding, not compiling). Since these are generally unmodified source files (podzilla 0 is slightly modified to remove some toolchain errors), things will look just like normal ; ).
Note: If you get some type of permission denied error for podzilla, you probably forgot to do the "chmod ugo+rwx podzilla" command if you compiled things manually. Just right click the binary and check everything under Permissions > Advanced Permissions.

4. Cleaning up and Recompiling:

Now that you've compiled something, you may want to change something or fix an error. Again, you can rebuild automatically via scripts or manually. If you are just updating via the SVN script, you won't need to do this step since the script automatically deletes the old source folder and makes a new one.

Automatically/Semi-Automatically: <- easy way

Same steps as in compiling, except run the Clean-source.sh script, which finishes in less than 5 seconds. After you've run that script, you can make your modifications and then recompile.

Manually: <- meh

Its just one easy command to clean. Takes longer though since you need to cd to the right directory. Since I usually don't close Konsole after compiling, though, its just the simple first line for me:

Code:

cd /root/iPodLinux/PZ*/BuildDir/source
make clean

Now you can make your modifications and then recompile.

Logical method:

Just delete everything in the "BuildDir/source" folder and copy in all the new stuff ; )

Giving back to the community!

Congratulations on successfully compiling from source!

Now that you are able to compile the basic podzilla 0 or podzilla 2 that the official installer uses, it's time for you to start making your own stuff and contributing to the iPodLinux community. First step of course is to learn C, the language that it's all programmed in (or first learn C++/Java and then work backwards). Also look at a few other applications for iPL and try poking around and compiling them (older versions of iBoy compile nearly error-less-ly with the 2.95.3 toolchain). Once you've mastered a few HelloWorlds and such (just search the wiki or even Google for tons of resources), you can start contributing new stuff ; )

==========================================================================================
==========================================================================================

Thats it for now. If you have any reasonable questions, have any reasonable suggestions, or need any reasonable help, just post. Remember, if you encounter a problem, Google is your friend (for Slax-related questions, search and post in the Slax forums). For all the thanks and credits, see my Slax modules' release thread. Otherwise, go out there, compile, and come back with goodies. Eat, drink and be merry, cause tomorrow we blow up the world (with new iPL applications)* Wink

~Keripo

* = quote from Iain Bank's The Crow Road
Last updated: August 2, 2007

Joined: 22 Nov 2005 Location: Pennsylvania

Awesome, thanks for this tutorial, I'll definately use it.

Joined: 22 Jul 2006 Location: At SuperMario290.co.nr

Sweet tutorial, I can't wait to try it out! Keep up the good work! Razz

Joined: 29 Dec 2006 Location: The Matrix

Will this work on ubuntu?

Posted: Sun Aug 19, 2007 11:46 pm

No.

Joined: 08 Sep 2007

thank you so much
does this automatically install a few modules like the installer does?
and if so is there a way i can remove those cuz i have no need for most of em and i just dont want em there

Joined: 10 Apr 2008

Sweet tutorial,thank you for posting it!