How to build IPK packages

One of the new features of RetroFW is the ability to install third-party software using a built-in packaging system. This is a massive improvement over previous firmwares which required the user to either have the technical understanding to install software manually or wait for the next release of the firmware. Which would then require a wipe and reload to flash the new firmware.

RetroFW uses the OPKG format. OPKG takes care of installing and uninstalling files from packages, even going as far as to remove previous files before installing new files and completely replacing other software packages if you instruct it to do so. The package extension of .ipk is due to OPKG being a fork of the older IPKG system.

Contents of an IPK file

At its core an IPK file is just an AR archive that stitches together three files. Two compressed tars and one meta-data file.

debian-binary - This file is nothing more than a version maker and always contains exactly four bytes: “2.0<newline>”.

control.tar.gz - This file contains instructions for the packaging system about what this package is and how to install it. Usually this archive only contains a control file, but it sometimes contain a postinst script..

control.tar.gz / control - The contents file is a set of properties about the package. It provides the package with a name, an author, a version number, and optionally dependencies and packages it should replace.

Here’s an example contents file from our rs-97-commander example:

Package: DinguxCommander
Version: 20190202
Description: Commander file management tool
Section: apps
Priority: optional
Maintainer: jbanes
Architecture: mipsel
Homepage: https://github.com/jbanes/rs97-commander
Depends:
Source: https://github.com/jbanes/rs97-commander

control.tar.gz / postinst (optional) - This is a shell script that will be run after the software has been installed. It is not required but can be useful for, say, creating a default roms directory for the system your emulator supports.

control.tar.gz / conffiles (optional) - This is a list of files that can be changed by the end user. If OPKG detects that one of these files has been modified it will avoid overwriting the user’s changes. This is not only useful for deploying default configuration files, but is also a great way to leave user changes to .lnk files intact. Here’s what the file would look like in the rs97-commander project:

home/retrofw/apps/gmenu2x/sections/applications/commander.lnk

data.tar.gz - This contains the software to install. Note that software should always be installed under /home/retrofw as the rest of the filesystem is read-only. The contents of this tarball are relative to the root of the filesystem. For example, here is the contents of our rs97-commander example:

home/retrofw/apps/commander/commander.dge
home/retrofw/apps/commander/commander.png
home/retrofw/apps/commander/res/up.png
home/retrofw/apps/commander/res/file.png
home/retrofw/apps/commander/res/background.png
home/retrofw/apps/commander/res/folder.png
home/retrofw/apps/commander/res/Fiery_Turk.ttf
home/retrofw/apps/commander/res/wy_scorpio.ttf
home/retrofw/apps/gmenu2x/sections/applications/commander.lnk

Key rules to pay attention to:

• The executable file should have the .dge extension
• The icon for the application should be a .png file of the same name
• A manual can be installed by including a text file called <name>.man.txt
• Include one or more .lnk file so your application shows up in the main menu

The .lnk files are explained in the Systems vs. Emulators section.

Tip: Integrating IPK files into your development process makes testing much easier. The OPKG system will automatically clean up old files meaning that you don’t have to worry about renaming files, deleting old files, or any other maintenance that might break your program.

Additional features like preinst, prerm, and postrm are described in detail in the following documentation: Construct ipk packages (for developers)

Systems vs. Emulators

A cool new feature in RetroFW is a conceptual separation between emulators as a standalone piece of software and the games they run. Many emulators expose useful menus and interfaces that can only be accessed by launching the emulator without a game file. DOSBox for example, launches a full DOS command line when no file is passed in.

To ensure access to the emulator while simultaneously providing the ability to launch roms, you’ll need to include two or more .lnk files in your distribution.

Let’s look at the DOSBox .lnk files for an example. The distribution contains the following two files:

home/retrofw/apps/gmenu2x/sections/emulators/dosbox.lnk
home/retrofw/apps/gmenu2x/sections/systems/dos.dosbox.lnk

Note that the first file is listed under the emulators section and matches the name of the executable. The second file has a prefix that’s related to the types of files it supports. In this case all files for DOS are in a single .lnk file.

In the example case where we had an emulator that supported both Game Gear and Sega Master System roms, we might have a gg.emuname.lnk file and an sms.emuname.lnk file. The user would be presented with two separate options with different filters to help them find their roms. They could potentially even have separate icons, default directories, and box art settings.

Getting back to our DOSBox example, let’s look at the emulator’s .lnk file.

title=DOSBox
description=Classic PC DOS Emulator
exec=/home/retrofw/emus/dosbox/dosbox.dge
clock=600

The title is what will be displayed under the icon on the menu screen while description is longer, more descriptive text that will be displayed when the user seeks more information on the icon.

The exec property is the executable that should be run when the link is selected by the user. You can optionally set the CPU speed with the clock property. It is only recommended that you set an explicit clock for more intensive emulators. The default clock is 528MHz. The clock you set should not exceed 600MHz. Since higher clock rates use more power, you can increase battery life by lowering the clock for your program.

Now let’s look at the system .lnk file.

title=DOS
description=DOSBox Emulator
icon=/home/retrofw/emus/dosbox/dos.png
exec=/home/retrofw/emus/dosbox/dosbox.dge
selectordir=/home/retrofw/roms/dosbox
selectorfilter=.exe,.bat,.com
clock=600

This is very similar to the emulator .lnk file. Which shouldn’t be surprising. The key difference is the addition of the selectordir and selectorfilter properties. These properties change which icon is being used and activate the file selector that prompts the user to choose which file to pass to the emulator.

The selectordir property sets the directory that the file chooser will start in. Generally this should be set to a directory under /home/retrofw/roms/. If the directory does not exist, the file chooser will start at /home/retrofw instead.

The selectorfilter property controls what files or file extensions will be visible in the file chooser. You generally want to set this to extensions that your emulator or application supports. In this example, DOSBox supports .exe, .bat, and .com files.

In addition, the icon property overrides the default DOSBox icon with an icon that better identifies what is being emulated. In this case, DOS programs.

Hopefully this gives you a good idea how to configure the system to support your application or emulator. The .lnk file is actually quite configurable, so check out the complete documentation at http://mtorromeo.github.io/gmenu2x/documentation/ for more info.

Creating your own IPK files

The easiest way to create an IPK file for your application or emulator is to integrate creation of the IPK into your build process. I typically add a script called package to the root of my project along with a directory called ipkg.

The ipkg directory will hold all of the files needed to create the .ipk file. The package script then pulls the compiled files into the hierarchy, assembles the tarballs and archive, then cleans up after itself.

Here’s an example package script from the DOSBox project.

#!/bin/bash

# Copy executable and manual into the correct location for packaging
cp dosbox ipkg/home/retrofw/emus/dosbox/dosbox.dge
cp README ipkg/home/retrofw/emus/dosbox/dosbox.man.txt

cd ipkg

# Create the two tar files and then create an IPK archive
tar -czvf control.tar.gz control postinst
tar -czvf data.tar.gz home
ar rv dosbox.ipk control.tar.gz data.tar.gz debian-binary

cd ..

# Clean up after ourselves
mv ipkg/dosbox.ipk bin/
rm ipkg/control.tar.gz
rm ipkg/data.tar.gz
rm ipkg/home/retrofw/emus/dosbox/dosbox.dge
rm ipkg/home/retrofw/emus/dosbox/dosbox.man.txt

Here’s the ipkg directory structure that the script is working against:

ipkg/home/retrofw/emus/dosbox/dos.png
ipkg/home/retrofw/emus/dosbox/dosbox.png
ipkg/home/retrofw/apps/gmenu2x/sections/emulators/dosbox.lnk
ipkg/home/retrofw/apps/gmenu2x/sections/systems/dos.dosbox.lnk
ipkg/debian-binary
ipkg/postinst
ipkg/control

Creating a .ipk file is now as easy as calling make and then running ./package. You can eliminate the extra step of calling the package script by integrating it into your Makefile. For example:

dosbox.ipk: dosbox.dge
	./package