How to build OPK packages

OPK files are a new form of application packaging that provide users with a single, easy to install file that starts working as soon as the system is made aware of the package.

The OPK package is a self-contained file system that can hold any files the developer wishes to include. When executed, the file system is mounted to /tmp/.opk and the executable inside is run.

It’s important to keep in mind that OPK files are read-only. While OPKs are convenient for users, they put a heavier load on the application developer. The directory of your executable is not fixed and it is not possible to write to or update the application directory. Your software must store its settings in another location such as the user's home directory.

This also means that OPK files cannot change the system in any useful manner. If you absolutely must install software on to the system, consider using the IPK format instead.

Contents of an OPK file

At a minimum an OPK file needs a .desktop file and an executable. The OS will scan for .desktop files that can be used by the OS. The file should be named <variant>.<os>.desktop. For RetroFW, most programs will have a file called default.retrofw.desktop. Here is the contents of a typical .desktop file:

[Desktop Entry]
Name=GnGeo
Comment=NeoGeo MVS/AES emulator
Exec=gngeo.dge
Terminal=false
Type=Game
StartupNotify=true
Icon=gngeo
Categories=emulators;
Version=20191130
X-OD-Manual=gngeo.man.txt

Note that the empty line at the end of the file is required. The name is what will be displayed under the icon for your game while the description will be shown when the user moves the cursor over the icon. The exec parameter points to the executable file.

Categories puts the program in different sections of GMenu. Typically this will be “emulators”, “emulators.systems”, and “games”. Each category should be separated by a semi-colon.

Only the name of the icon is required. The extension will be figured out by GMenu.

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 .desktop files in your distribution.

For example, here is the GnGeo neogeo.retrofw.desktop file: \

[Desktop Entry]
Name=NeoGeo
Comment=NeoGeo MVS/AES emulator
Exec=gngeo.dge
Terminal=false
Type=Game
StartupNotify=true
Icon=neogeo
Categories=emulators.systems;
Version=20191130
X-OD-Manual=gngeo.man.txt
X-OD-Selector=/home/retrofw/roms/neogeo
X-OD-Filter=.zip,.bin,.gno
X-OD-Alias=aliases.txt

The primary differences are in the addition of the X-OD-Selector attribute to activate the file selector and set a default directory, the X-OD-Filter attribute to filter the file selector by file types, and X-OD-Alias to provide an aliases file.

Creating your own OPK files

To construct an OPK file, just put all your files into a single directory. Commonly a directory named “opkg” would be used to stage the files for the OPK file. For example, here is the directory for GnGeo:

alias.txt
default.retrofw.desktop
gngeo.dge
gngeo.man.txt
gngeo.png
neogeo.png
neogeo.retrofw.desktop
roms/

The following command is then used to create the OPK package:

mksquashfs opkg gngeo.opk -noappend -no-xattrs

The “no-append” option tells mksquashfs to create the file from scratch rather than modifying the existing file. The “no-xattrs” method prevents extra filesystem attributes from being recorded.

Fat Binaries

A key advantage of the OPK format is that the .desktop files can be customized by operating system. Thus versions of the program for multiple systems can be combined into a single, cross-platform package.

The most common system in use that also supports OPK files is OpenDingux. These systems use “gcw0” to identify compatible programs. Here is an example default.gcw0.desktop file from GnGeo:

[Desktop Entry]
Name=GnGeo
Comment=NeoGeo MVS/AES emulator
Exec=gngeo.mips
Terminal=false
Type=Game
StartupNotify=true
Icon=gngeo32
Categories=emulators;
Version=20191130
X-OD-Manual=gngeo.man.txt
X-OD-NeedsDownscaling=true

Note that RetroFW programs typically use a .dge extension for their executable files while OpenDingux uses .mips.