The Comprehensive Cydia Repo Tutorial

While attempting to create my own cydia repo, I’ve ran into many many bumps in the road. Jay Freeman aka Saurik, the father of Cydia, is a genius and all his work is greatly appreciated, but very little can be said about his documentation skills or his affinity to respond to support requests for repository issues. Especially for novices in developing like myself. So while his tutorial greatly assisted me in getting started, I had to gather little bits and pieces of information from all over to get a comprehensive understanding of how Cydia repositories work. The following is a list of key features that most tutorials neglect to cover that I will cover in my tutorial:

1. How do I give my repository an icon?
2. How do I give my sections an icon?
3. How do I give my apps dependencies?
4. How do I setup conflicts?
5. How do I setup firmware requirements?

First off I will show you show you how to create a very basic repository. There are a lot of MAC OSX tutorials out there, but since I do not own a Mac at the moment (saving up for my 15” i7 Macbook Pro), I will show you how to do it on a linux machine. If you do not own a linux machine, I strongly recommend you look into Virtualbox. It is a very useful application that runs on Windows/OSX/Linux that allows you to run an operating system inside an operating system. So currently I am using Windows 7, but this allows me to run Ubuntu in windows. So anyone can have a linux box. Also if a MAC is a must you can refer to many tutorials on the web. And you can refer to my tutorial for some of the advanced stuff that most tutorials do not answer.

Prerequisites for this tutorial:
1. A computer or Virtualbox running Ubuntu.
2. Internet access.
3. This software package.
4. Your apps or themes
5. A website to host your repo on.
6. Patience.

Part 1: Creating Your Repository

Step 1:
Once in linux, you must download the software package listed under the prerequisites. This compressed archive will contain two files, “dpkg-gettext.pl” and “dpkg-scanpackages”. These files are necessary in creating the repository files that Cydia understands. After you have it downloaded to the Deskop, extract them to the Desktop as well.

Step 2:
Open a Terminal Window and navigate to the repo files we just extracted by typing the following command.

cd ~/Desktop/cydiarepo/

Step 3:
Now type the following commands that will copy the dpkg-scanpackages file to the proper directory.

sudo cp dpkg-scanpackages /usr/bin

Step 4:
Now type the following command that will make the file dkpg-scanpackages executable.

sudo chmod 0777 /usr/bin/dpkg-scanpackages

Step 5:
We will now do the same thing for the dpkg-gettext.pl file. Use the following commands to copy it to the correct directory and to make it executable.

sudo cp dpkg-gettext.pl /etc/perl

sudo chmod 0777 /etc/perl/dpkg-gettext.pl

Step 6:
To verify that we copy the files and made them executable successfully, type the following commands.

cd /usr/bin

ls -l dpkg-scanpackages

It should result in an output similar to the following (note it is important that the first part reads -rwxrwxrwx. As this indicates that it is executable.):

-rwxrwxrwx 1 root root 8307 2010-08-28 01:07 dpkg-scanpackages

Step 7:
The same thing should be done for the dpkg-gettext.pl file. To do so type the following commands.

cd /etc/perl

ls -l dpkg-gettext.pl

The output should read:

-rwxrwxrwx 1 root root 513 2010-08-28 01:07 dpkg-gettext.pl

Step 8:
We are going to create a couple of folders that will help us organize our files. On the Desktop create a folder called “cydia”.

Step 9:
Inside the cydia folder we are going to create two folder named “apps” and “upload”.

Step 10:
Inside the upload folder we will create a folder called “deb”.

Step 11:
Inside the “upload” folder we will also create a text file called “Release”. Note how I did not put an extension on “Release”. It has to be that way. This file will contain information about your repo. Below is what it should look like. Most of the fields are quite arbitrary (meaning make it whatever you want), except I recommend you keep architecture the same.

Example Release File

Step 12:
At this point you need some apps or themes. A repo is nothing without apps or themes. As I won’t get into how to create a theme, I will now show you how to take a theme and turn it into a deb file. Deb files are debian installer files which iPhones can decipher to install your app or theme. To any deb file, there is a standard directory structure. Below is an example of the directory structure for a theme. Also please note that this is just an example. The term MyProgram can be interchanged with anything you want.

File Structure Example

Step 13
We will place the MyProgram folder inside the “cydia/app” folder.

Step 14:
Creating the control file. In the files structure example above, the control file should be inside MyProgram > DEBIAN. Below is an example of a control file for one of my themes.

Example Control File

The following are some known options for the control file:

Package: this is the identifier of the package and should be all lower case and it must be unique to all other programs in cydia.
Name: the name of your program as seen in Cydia.
Version: program version number.
Architecture: this field will always be “iphoneos-arm”.
Depends: program(s) that are needed for yours to work. note that this will also install the app along with yours if it hasn’t already. For instance, if you list winterboard as a depend and winterboard is not installed. And if someone tries to install your theme, it will automatically install winterboard as well. If the user tries to remove winterboard, it will also uninstall your theme as well. Under depend, you can also list the version. For instance “Depend: winterboard (>=3.0)”. This basically states your app must have winterboard version 3.0 or higher. Or you can even put in here the iOS Firmware version that is required. For instance, let say your theme only works on 3.x or higher, you can put “Depend: firmware (>=3.0)”. If can add multiple dependencies by separating them by comas. For example “Depend: firmware (>=3.0), winterboard”. *NOTE: You must use the Package field info and NOT the Name. You can find this by opening the app in Cydia and scrolling down to the ID field under package details. However I’ve found this very hard to read at time as the period is hard to read due to Saurik’s choice of font. You may have to email the dev to get the correct Package ID.*
Conflicts: works the same way as depends. However this will tell cydia that your app conflicts with another. For instance if my app conflicts with winterboard, I would add “Conflicts: winterboard”. Installing your app will cause cydia to automatically remove winterboard.
Description: a description of your program (ignored if you use Depiction).
Homepage: sends the user to the page of the packager’s choice (ignored if you use Depiction).
Depiction: this loads a URL into an iframe in place Description and Homepage. You should use this to display custom links and/or screenshots. Please refrain from using this field until you’ve read my section on depictions further down.
Maintainer: package builder, person to contact for problems, format “Name “.
Author: wrote the software, same format as Maintainer.
Sponsor: financial provider for package, format “Name .
Section: Location in Cydia.

Step 15:
Once you have the control file filed out and your files in the correct folder. We need to build our deb file. To do so we will need to navigate to the apps folder. Open a brand new terminal window and type the following command.

cd Desktop/cydia/apps/

Step 16:
Now run the following command to to build our deb file.

dpkg -b MyProgram

You may see some warnings. That is okay if you do. As long as you don’t see any errors and a deb file was created, you should be fine.

Step 17:
Now go ahead an take the “MyProgram.deb” file that was created and move over to the “cydia/upload/deb” folder that is on your Desktop.

Step 18:
Open up terminal and navigate to the upload folder by typing the following:

cd ~/Deskop/cydia/upload

Step 19:
We are now going to run the dpkg-scanpackages script that will create the files necessary for a repository. To do so, run the following command.

dpkg-scanpackages -m . /dev/null >Packages

Please note that there is a space before and after the .
Also the output of the script should look something like this:

** Packages in archive but missing from override file: **
com.anything.myprogram

Wrote 1 entries to output Packages file.

Step 20:
Now there should be a file named “Packages” that was created in your upload folder. Right click on that file and click compress. In the drop down menu where you select the extension, select .bz2. This is important as Cydia only likes BZ2 files. After you’ve done so just click create and a new file called “Packages.bz2” should have appeared.

Step 21:
Now to verify everything is in order, your “upload” folder should contain the following.

1. A deb folder with your app.deb file inside of it.
2. A “Release” file that contains information about your repo.
3. A “Packages” file that contains information about your apps.
4. A bz2 compressed version of your Packages file that should be called “Packages.bz2”

As long as these 4 are there. You are ready to upload to your website.

Step 22:
Upload everything to your website or a subdomain or a subdirectory on your website. You should now be able to add your website as a repo in cydia and you should be able to install and uninstall your themes or apps. If you have any questions or concerns, comment and I will try to get back with you.

Step 23:
Now in the future you will be adding more and more apps and themes. This is no problem. Just add the deb files to the cydia/upload/deb/ folder. And run Step 19 again. You’re Packages file will have all of your apps and themes in them. But please make sure you remove the old Packages.bz2 file and create a new bz2 version of your Packages file as outlined in Step 20. You will then need to upload any new debs to your websites and you will need to replace the Packages files on your website with the new ones. And that’s it.

This whole process gets getting used to. I found myself redoing my sections a bunch of times which is a pain in the behind. Especially later when you have MANY apps on your repo. Because you have to edit the control file for ALL your apps. My suggestion would be to plan out these things before starting. Make sure your sections are exactly the way you want it. And everything else as well. I would encourage you to read this entire tutorial first before starting. Especially the next part, because it is very relevant when selecting a Section for your apps and themes.

Part 2: Giving Icons To My Repo/Sections.

The absolute easiest way to do give your repo an icons is to email Saurik and ask him to upload one for you. However seeing how busy he is, he rarely does this and most people who knows how to do this, create an app that installs icons manually. I chose the latter method.

The same goes for sections. What I mean by sections is, did you notice that your themes or apps have a grey box with a question mark in Cydia? Well this is because you using a nonstandard name for the Section in your control file. For example, all of my themes use a section that starts with “SBK Themes”. I’ve done this intentionally as I liked to be able to pick out my sections quickly in Cydia. However the EASIEST way to give your app/themes an icon in Cydia would be to put your apps or themes in the standard Section. For instance if you set your theme’s Section in the control file to Themes, you will get a nice pretty icon of a window and a paintbrush. But your themes will show up in the Themes section in Cydia along with everyone elses. This really isn’t a big deal for some, but some just prefer a separate section for their own apps and themes. Or they prefer a unique icon for their themes/apps. So here comes the fun part. Creating an app that will install Repo Icon and Section Icons.

Step 1:
Create an app like you would any other theme or app. I called mine repoprep.

Step 2:
The following is a directory structure of what a repoprep app should look like.

Sample Repo Prep App

So just by looking at this example. If this app was installed. Any app or theme that listed “Your Themes” as a section. It will use that image as it’s icon in Cydia. Same goes with Your Ringtones and etc. Something to be careful about. You usually DO NOT want to use a preexisting section with a custom PNG for your Repo. For instance, if you decided that you want to put your Theme in the Theme section, but you want to use a custom image for the entire Theme section. I believe this will overwrite what is in Cydia making EVERYONE who lists Theme as their section, your custom icon. This method should really only be used if you use a non-standard section. Such as “SBK Themes” like I did for myself.

Also, you may add parenthesis to your section. For instance i used “SBK Themes (Lockscreen)” or SBK Themes (Background).” Cydia ignores whatever is inside the parenthesis. And it will use “SBK Themes.png” for both the sections I listed above.

As you can also see in the Sources folder you will see a www.yourdomain.com.png. You will want to rename the first part to match your domain. For example, if your domain name is www.superpowow.com, then you will want the file name to be www.superpowwow.com.png. NOTE. Subdirectories has no bearing on this. Meaning, even if your repo is http://www.superpowwow.com/repo/cydia/awesomeness/whatever, you don’t have to write all that out for your PNG file. In fact, a file with a / character inside isn’t even possible. You would still use www.superpowwow.com.png and cydia will know to give your repo “http://www.superpowwow.com/repo/cydia/awesomeness/whatever” the correct image. However for subdomains, (i am not sure on this, but I would just play around with it) I believe you have to make your png to match. For example, if your repo is http://kapow.superpowow.com/, then your icon should be named kapow.superpowwow.com.png. To be honest I am not 100% sure, but just play around with it.

Step 3:
Now you should already know how to create a deb file and how to add the deb to your repo (Refer to Step 15-22 in Part 1). GREAT. You’re done. You can instruct people to install this repoprep app OR you can do what I did. Make this repoprep app a dependency for all of your apps. So the first time a user installs any one of your apps or themes, it will also install this repoprep app, giving your repo and section pretty icons as long as they use any of your apps or themes. You should already know how to do this. Refer to Step 14 in Part 1 of this tutorial for dependency information.

Leave a Reply

Your email address will not be published. Required fields are marked *