Source Code

From wikiPodLinux

Table of contents

Subversion Repository

All of iPodLinux's projects have been migrated into our Subversion (http://subversion.tigris.org/) (SVN) repository on SourceForge.net (http://sourceforge.net). You can browse the repository online (http://ipodlinux.svn.sourceforge.net/viewvc/ipodlinux/), or check it out using the guide below. A log of the most recent commits to repository (http://cia.navi.cx/stats/project/ipodlinux) is also available online.

All code in Subversion is undergoing active development and liable to change at any moment - it is not an official release. The developers cannot offer end-user technical support for this code, or even guarantee that it works at all at any given moment.

To install Subversion:

  • Linux: use your package manager to install the svn package.
  • Windows: using Cygwin's (http://www.cygwin.com/) original setup.exe, install the svn package listed under devel/.
  • Mac OS X: install both Fink (http://www.finkproject.org/) and FinkCommander (http://finkcommander.sourceforge.net/), and use FinkCommander to install the svn-client (http://pdb.finkproject.org/pdb/package.php/svn-client) package.

Once you've installed svn, you can "check out" (download) certain modules. See the Subversion website (http://subversion.tigris.org/) for a full tutorial, but in brief:

 svn co https://ipodlinux.svn.sourceforge.net/svnroot/ipodlinux/apps/ipod/podzilla2

Layout

Unlike the Subversion repositories on svn.ipodlinux.org or opencsie.org/courtc, the current repository has a very different layout.

apps
  desktop
  ipod
legacy
libs
linux
  2.4
  2.6
  tags
  vendor
uclibc

Hopefully this new layout explains itself.

Compiling

Source from SVN can be compiled for use on both the desktop and the iPod. You will need to install the 3.4.3 Toolchain if you intend to compile for the iPod. See Building Podzilla or Building Installer for a complete tutorial.

Linux Kernel

In CVS we have the iPod-specific patches to build iPodLinux from a uClinux 2.4 based kernel (uClinux-2.4.24-uc0 currently). This kernel is outdated and currently compiles only with the GCC 2.95 Toolchain. You can find a tutorial to compile the kernel at Kernel Building. Work is ongoing to update the kernel for use with newer compilers (see Experimental Kernel for a version that uses uClinux 2.4.32 and builds with GCC 3.4).

2.4
 \_ arch
 |   \_ armnommu
 |       \_ mach-ipod - This contains the core drivers for the iPod
 \_ drivers
 \_ fs
 \_ include
 |   \_ asm-armnommu
 |       \_ arch-ipod - The iPod specific include files
 \_ kernel
 \_ Makefile

Nightly Builds

The iPodLinux software is undergoing constant development. For those who can't or don't want to compile their own, we have nightly builds for certain components.

  • Builds for the kernel and legacy podzilla are at http://ipodlinux.org/builds (Currently down. For the lates kernel go to Downloads) and are updated once daily, no matter what. Make sure you scroll all the way to the bottom; there is a year's worth of builds in this directory.
  • Builds for podzilla 2 (core, modules, and fonts+schemes) are at http://josh.sys-techs.com/svnbuilds and are updated four times daily. They are only built if something has actually changed.

Note: If you download one of these files, you will find them given a number. Choose the one with the highest number go get the most recent version. If you downloaded podzilla (or podzilla2), rename the file to "podzilla" before you place it into /sbin, and also set its executable file flag, e.g. using the command: sudo chmod +x /sbin/podzilla

You can also view an outline of the latest and greatest features, or check the most recent changes to the kernel (http://cia.navi.cx/stats/project/ipodlinux) or Subversion tree (http://trac.ipodlinux.org/log/).

What to do with your modifications

Okay, so you've made some changes, and you want to distribute them... that's great. We have a few guidelines we'd like you to follow though;

First, submit your changes as a patch as described below to the developer of the application. For example, changes to podzilla should go to the email address listed below. Changes to iPodMame should go to the maintainer of that code base, and so on.

If the maintainer is not accepting patches, fork the source code and executable name appropriately. If you modify iPodMame to include video output, call it something like iPodMame-VideoOut.

If your changes are minor; things like a behavioral change or visual difference, do not just take the package and put your own snappy name on it. That is to say that if you decide to change the input mechanism for podzilla2, don't just call it "BleuZilla" or something like that. Instead name it "podzilla2-SnappyInput" or whatever is appropriate.

Instead of distributing a binary and full source code, it is much easier to provide patches to apply to upstream. This enables developers to incorporate changes or apply patches to future versions.

Do not just immediately redistribute your own version of your executable and source. Please try to follow the proper channels as outlined above.

As far as application names, we prefer that you keep your names differentiated using the hyphen as shown above (podzilla-mz, etc) than completely new personal names. We also would like for you to not try to make it seem like your application is the "next step" from one of the core-developed applications. That is to say that you should not call your application "podzilla3", or "ipodloader7". Consider the base names to be reserved.

For modular applications like podzilla2, please try to accomplish your changes through the module interface. podzilla2 allows for just about every aspect of it to be changed via modules. By exploiting this modularity, you don't have to worry about supporting the entire application in perpetuity, nor do you have to re-implement "the wheel" as it were.

Submitting Patches

The rapid advancement of the iPodLinux project is based primarily on user contributions. We welcome any improvements you can make to the project! You can subscribe to the patches mailing list and view the archive here (http://ipodlinux.org/mailman/listinfo/patches_ipodlinux.org).

Please observe these guidelines before generating your snazzy patch. Make sure that your modifications, as well as any new files:

  • conform to the linux kernel style guide (http://www.chris-lott.org/resources/cstyle/LinuxKernelCodingStyle.txt) - do not change from our style of coding to yours
  • do not contain any proprietary information or non publicly distributable code or data (GPL preferred)
  • are adequately commented
  • observe idiosyncrasies and scale well between models, i.e. screen size and color
  • use standard C99. Generally, we do not accept patches that use C++. We're trying to keep the core software ANSI-C/gnu C99 pure.
  • represent an honest debugging effort ("It compiles! Ship it!" is not a good mantra.) If you're testing using the desktop builds, try all of the standard iPod resolution and color depths, etc.
  • do not contain unnecessary code changes - reformatting, DOS-style newlines, etc.

Generating the patch

First, make sure that you're working with the most recent version of the SVN repository;

svn up

Next, hand-fix any merge errors.

Now diff all of your changes with the SVN repository, and store the results in a text file. Name the text file something related to what you modified. For this example, we'll assume you added "burrito support", whatever that might be.

svn diff > ~/burrito_patch.diff

This will catch any changes made between when you checked out the files from Subversion repository and the way they currently stand.

If you only want to diff one file, and not your whole folder -- for instance, if you are working on other files and you don't want that work to be included into your patch as well -- you can specify your file:

svn diff burrito.c> ~/burrito_patch.diff

Any new files you have created will not be contained in the above, so we need to add them onto the patch file like so:

diff -u /dev/null my_cool_new_file.c>> ~/burrito_patch.diff
diff -u /dev/null my_cool_new_file.h>> ~/burrito_patch.diff
etc...


Submitting the patch

Attach your patch in an email to mailto:patches@ipodlinux.org.

Be sure to include in the subject of the message: PATCH so that it gets through our spam filters.

Be sure to include in the body of the message:

  • What portion of the iPod Linux source tree this is for... kernel, podzilla, etc.
  • What the patch accomplishes.
  • Why your patch should be incorporated into the distribution.

There is currently no feedback mechanism, so you may not be notified if your patch was received, or the current state of that patch. Perhaps this will be changed in the future.

Be aware that although your efforts are greatly appreciated, not all patches will be integrated in. If your patch provides good functionality, is coded well, and is safe to use (no buffer overrun type possible errors), we may accept it. (ie, use snprintf() instead of printf() and such.) Also, be patient: we work on the project in our free time, and we might not get to your patch immediately.

Applying a patch

If you happen across a patch you want to try out, first update your CVS directory, then apply the patch like so:

patch -Np1 < /path/to/patch.diff 

If the patch happens to be compressed:

bzcat /path/to/patch | patch -Np1

If you get errors like "missing header for unfiled diff at line 8 of patch" then try the following parameters instead:

patch -Np0 < /path/to/patch.diff

You should 'make clean' before applying the patch, to kill any straggling files that might not be current.

Views