PortMaster Packaging

PortMaster is the distribution mechanism for homebrew on handheld Linux devices (Knulli, ArkOS, AmberELEC, etc.).

The portmaster/ folder

The portmaster/ folder in the project root contains the source files that get packaged for distribution. It’s separate from src/ (application code) because these files are metadata and scripts for the PortMaster ecosystem, not the app itself.

The scripts/package-portmaster.sh script copies these files, adds the compiled binary, and creates the final zip.

Package structure

cardagain-0.1.0.zip
├── Cardagain.sh          # Launch script (extracted to roms/ports/)
└── cardagain/              # Game directory
    ├── cardagain          # ELF aarch64 binary
    ├── control.txt          # gptokeyb controller mapping
    ├── port.json            # PortMaster metadata
    ├── gameinfo.xml         # EmulationStation metadata
    ├── README.md            # PortMaster wiki docs
    └── fonts/
        └── DejaVuSans.ttf   # Bundled font

Required files

Cardagain.sh

The launch script. PortMaster sets environment variables like $GAMEDIR, $CONFDIR, $GPTOKEYB before calling it.

Key responsibilities:

• cd to the game directory
• Set XDG_DATA_HOME for save files
• Run gptokeyb for controller → keyboard mapping
• Launch the binary
• Clean up on exit

port.json

PortMaster metadata for the repository index:

{
  "version": 2,
  "name": "cardagain.zip",
  "items": ["Cardagain.sh", "cardagain"],
  "attr": {
    "title": "Cardagain",
    "desc": "Spaced Repetition Flashcards",
    "rtr": true,
    "arch": ["aarch64", "armhf"]
  }
}

gameinfo.xml

EmulationStation metadata:

<gameList>
  <game>
    <path>./Cardagain.sh</path>
    <name>Cardagain</name>
    <desc>...</desc>
    <genre>puzzle,educational</genre>
  </game>
</gameList>

control.txt

gptokeyb mapping file. Maps controller buttons to keyboard keys the game expects:

a = space    # A button → Space key
b = x        # B button → X key
x = c        # X button → C key
y = v        # Y button → V key
menu = esc   # Menu → Escape

Packaging script

scripts/package-portmaster.sh creates the zip:

1. Finds the aarch64 binary (or warns if using native)
2. Stages files into a temp directory
3. Bundles fonts from portmaster/fonts/
4. Creates the zip with Cardagain.sh at the root

Installation on device

1. Copy cardagain-0.1.0.zip to roms/ports/
2. Extract:

   cd /roms/ports
   unzip cardagain-0.1.0.zip
   

3. Launch from EmulationStation: Ports → Cardagain

Submitting to PortMaster

To add to the official repository:

1. Fork PortsMaster/PortMaster-New
2. Add your files under ports/cardagain/
3. Submit a PR

The PortMaster team reviews and merges. Once accepted, users can install directly from the PortManager GUI.