Create your own pacman package for Batocera

In Batocera v27 and higher, you can utilize pacman to install and manage packages. It is the underlying tool behind the content downloader. It is a straightforward package manager that's easy to work with.

You don't need development skills to create a package, just a bit of patience. If you've copied files too and from directories before, you already have the skill-set required for this.

The way packages work is that they are essentially just a compressed folder that contains the folder structure that you wish to copy onto the user's machine, starting at root, along with a script file. Essentially, you'll be creating a “userdata” folder inside of the beginning folder of your package, and go from there.

It's easiest to explain with an example. Let's use the NES free homebrew ROM Alter Ego available from https://www.romhacking.net/homebrew/1/. Click “Download” from the Links section and fill out the captcha to get the ZIP and open it up, it will contain the following contents:

This contains everything we might need to create a package including media and all!

On your Batocera machine, create a new folder in /userdata/system/ and call it package/. This folder can technically be anywhere but this is what we will be using for our example.

Then inside of this folder, recreate the folder structure for every relevant file that needs to be copied over to the user's machine. For instance, if all you want to add is a ROM for the NES system, then you would simply create the userdata/roms/nes/ folders inside of each other and place the ROM in the final nes/ folder:

In our example package, which includes the media we want to install, the setup would look like this:

/userdata/system/packaging/nes-alterego/
                           └─ userdata/
                              └─ roms/
                                 └─ nes/
                                    ├─ images/
                                    │  └─ label.png
                                    ├─ manuals/
                                    │  └─ manual.pdf
                                    └─ Alter_Ego.nes

However, these filenames simply won't do! Batocera won't be able to recognize the media files as belonging to Alter Ego. Let's rename them:

/userdata/system/packaging/nes-alterego/
                           └─ userdata/
                              └─ roms/
                                 └─ nes/
                                    ├─ images/
                                    │  └─ Alter_Ego.png
                                    ├─ manuals/
                                    │  └─ Alter_Ego-manual.pdf
                                    └─ Alter_Ego.nes

Next we need to create the file that contains meta-information about the package itself. Create a new text file in the package's folder. For our example, this would be /userdata/system/packaging/nes-alterego/.

This can be named anything, but a logical one would be package-info.txt.

Open the file for editing and paste the following in (or just download the file and place it there):

package-info.txt

pkgname = nes-alter-ego 
pkgver = 1.0.0-1
pkgdesc = NES freeware puzzle game by Shiru, Kulor, Denis Grachev
arch = any
group = sys-nes
packager = your_name 
url = https://wiki.batocera.org/start

Replace the lines as appropriate! Here are the required lines:

• pkgname: The internal name of the package. This needs to remain the same for updates that become available for the package.
• pkgver: The version of the package. If this number is higher than the one currently installed, Batocera will offer the user to update the package in the store. The only acceptable format for this is X.Y.Z-R, following pacman's conventions.
• pkgdesc: The description.
• arch: What platforms should this package be available to? Most packages are fine to leave this as “any”, but some may only work on x86_64 for example.
• group: What category should the store show this under? If you are creating a package for a specific system, it must be prefixed with sys-, eg. sys-megadrive for Megadrive/Genesis. For the other groups, read below.

The remaining lines are optional, but can provide extra information to users choosing to install them:

• packager: The author of the package.
• url: URL for the user to go to if they desire more information.

In addition to the sys-<system> groups that are available, you have the following to choose from:

• music: Add some more bangin' tunes.
• theme: Add an additional theme for the menu.
• bezel: Various decorations!
• misc: All the other junk.

The other file is .BATOEXEC and it gives you the ability add metadata or execute commands. The first line describes the action you want to do. Currently, BATOEXEC accepts two commands: gamelist and exec. Create a new blank document name .BATOEXEC and place it in the same folder next to package-info.txt.

Typically, for a package that adds a new ROM, you want to add it into the gamelist.xml. Add gamelist = <system>, where <system> is the shortname of the system you'd like to edit the gamelist.xml for, and then follow it with the data you'd like to append to the list. For example:

.BATOEXEC

gamelist = nes
<game>
  <path>./Alter_Ego.nes</path>
  <name>Alter Ego</name>
  <desc>Freeware puzzle game for NES, a port of the original (by Denis Grachev for the ZX Spectrum). Swap positions with your 'alter ego' to move about the level and obtain all the bouncing pixels.</desc>
  <rating>0.6</rating>
  <releasedate>20110827T000000</releasedate>
  <developer>Shiru</developer>
  <publisher></publisher>
  <genre>Puzzle</genre>
  <players>1</players>
  <image>./images/Alter_Ego.png</image>
  <manual>./manuals/Alter_Ego-manual.pdf</manual>
</game>

This is for any other command you might want to run when installing the package. Its syntax depends on which executable you call in exec = <bin>.

For a basic example that will be executed every time the package is called (whether you are installing, upgrading or uninstalling it):

.BATOEXEC

exec = /bin/bash
echo "You have successfully run a command in a script of a package!"

If you define sections between .INSTALL_START and .INSTALL_END or .UNINSTALL_START and .UNINSTALL_END, those commands will be executed only on install/upgrade or removal of the package respectively. Commands outside those sections will be executed in any case (ex: date in the example below).

.BATOEXEC

exec = /bin/bash
date
.INSTALL_START
echo "Installing bezels with glazed effect..."
.INSTALL_END
.UNINSTALL_START
echo "Uninstalling bezels with glazed effect..."
.UNINSTALL_END

A .BATOEXEC file is not mandatory to use batocera-makepkg. Many installable objects don't require it, such as adding themes, music, etc.

This is what the package setup should look like:

/userdata/system/packaging/nes-alterego/
                           ├─ userdata/
                           │  └─ roms/
                           │     └─ nes/
                           │        ├─ images/
                           │        │  └─ Alter_Ego.png
                           │        ├─ manuals/
                           │        │  └─ Alter_Ego-manual.pdf
                           │        └─ Alter_Ego.nes
                           ├─ package.txt
                           └─ .BATOEXEC

Batocera uses a custom tool to create its packages: batocera-makepkg.

To use it:

1. Access Batocera via SSH.
2. Change the current working directory to the package's folder. In our example, this can be achieved with cd /userdata/system/package/nes-alterego.
3. Run batocera-makepkg package-info.txt to create the package. It will output something similar to the following:

   Creating package ../nes-alter-ego-1.0.0-1-any.pkg.tar.zst ...
   /*stdin*\            : 45.08%   ( 46592 =>  21005 bytes, ../nes-alter-ego-1.0.0-1-any.pkg.tar.zst)
   SUCCESS: package ../nes-alter-ego-1.0.0-1-any.pkg.tar.zst correctly generated

   This may take a while depending on the size of your package's contents.

When complete, a package file named <system>-<pkgname>-<pkgver>-<arch>.pkg.tar.zst will be created one level above your current working directory. In this example, it would be /userdata/system/package/nes-alter-ego-1.0.0-1-any.pkg.tar.zst

batocera-makepkg will not overwrite already existing packages with the same name.

If you'd like to test installing your package, you can do so with the following command:

pacman -U <package>

If you were following the example above, the command for it would be:

pacman -U /userdata/system/package/nes-alter-ego-1.0.0-1-any.pkg.tar.zst

Most likely you didn't change the current working directory to the folder of the package you wanted to create. By default, the current working directory will be in /userdata/system, so all the folders and files in there will be added to your package.

Run cd /userdata/system/package/nes-alterego if you were following the example above and try again.

The simplest answer is to install it and see what files were added. But that's not always easy, especially when there are multiple files in deep-rooted folder levels. If you'd like to “extract” a package file, you can use the zstd tool in Batocera:

zstd -d /userdata/system/package/nes-alter-ego-1.0.0-1-any.pkg.tar.zst

This will give you a standard .tar file that you can use any ordinary compression program to decompress.