How to build OPK packages - retrofw/retrofw.github.io GitHub Wiki
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.
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.
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.
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.
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
.