PiTrex Wiki

PiTrexCore_Extensions

This guide describes how the "extensions" in the "tcz" directory on the PiTrexCore system are created. Except that the preferred (but not required) installation location of PiTrex software is in /opt/pitrex instead of /usr/local, the creating extensions page on the Tiny Core Linux wiki is also valid. It is suggested that -Ofast is used instead of -Os though, for maximum performance.

Ideally you should compile games on PiCore 13.1.0 to create PiTrexCore extensions (eg. boot with "debug" in cmdline.txt and connect via telnet and FTP to issue commands). This requires that you are familiar with using Tiny Core Linux, as described on their wiki . However it should be fine to use Raspberry Pi OS versions based on Debian 11 "Bullseye" for development and the binaries should work in PiTrexCore.

Manual extension creation

The aim is to create a SquashFS filesystem, which is basically like a ZIP or tar.gz archive, containing all the files you need to install. If you just have one file that builds when you compile your game, then this is easily done as follows for a game with source code in the "mygame" directory:

cd mygame
make
mkdir -p /tmp/mygame/opt/pitrex/bin
cp mygame /tmp/mygame/opt/pitrex/bin
strip /tmp/mygame/opt/pitrex/bin/mygame
chmod u+s /tmp/mygame/opt/pitrex/bin/mygame
mksquashfs /tmp/mygame mygame.tcz -all-root
rm -r /tmp/mygame

Skip the "chmod u+s" step if your game uses the X server instead of using the Vectrex Interface library directly.

If your game requires other files, then they would need to be copied to the location in /tmp/mygame/opt/pitrex/ where they are used.

If a configure script is used for building the game (such as for an existing game being ported to the PiTrex) and it supports the "DESTDIR" setting with the make command, you can build it as follows:

cd mygame
export CFLAGS="-Ofast -pipe" CXXFLAGS="-Ofast -pipe" LDFLAGS="-Wl,-O1"
./configure --prefix=/opt/pitrex
make
sudo make DESTDIR=/tmp/mygame install-strip
mksquashfs /tmp/mygame mygame.tcz -all-root
rm -r /tmp/mygame

Note that you might have to run "chmod u+s" on executables if you changed them to use the Vectrex Interface library now, so that they run with root permissions.

For Xlib games a default XF86Config file can be included at /usr/local/X11R6/etc/X11/<extension>/XF86Config.

Menu

If you name your extension after the name of the executable in /opt/pitrex/bin, then a working menu item will be automatically generated with the name of the extension.

If a mygame.tcz.mnu file is in the "tcz" directory, this will be used instead of the automatically generated menu entry which would have looked like this:

Linux|mygame|mygame|mygame

The second field is the menu text, so you might change it to something like this:

Linux|My Game|mygame|mygame

(try to keep the text short because lots of long menu lines will cause flicker)

If your extension contains multiple executables, you can include them grouped together like the hello_world.tcz.mnu file in tcz/defaults:

Linux|Example: Cube|hello_world|cube
Linux|Example: Draw Ships|hello_world|drawships
Linux|Example: Font Test|hello_world|fonttest
Linux|Example: Gimms|hello_world|gimms
Linux|Example: Hello World|hello_world|hello
Linux|Example: Maze|hello_world|maze
Linux|Example: Pacman|hello_world|pacman
Linux|Example: Perspective|hello_world|perspective
Linux|Example: Window|hello_world|window

You can also use command-line arguments:

Linux|My Game|mygame|mygame
Linux|My Game Autofire|mygame|mygame -autofire

Note that the first field must always be "Linux".

Dependencies

Basic games generally don't need any other libraries or support files besides the Vectrex Interface Library which is compiled statically and therefore does not need to be loaded separately. If your game uses libX11 or other dynamically-linked libraries, it will need associated extensions to be listed in a mygame.tcz.dep file. These extensions are loaded from the tce/optional directory on the MicroSD card.

If you're unsure about which libraries are used by your game, compile it and run "ldd mygame" to see all the libraries required by the executable. On PiCore/PiTrexCore any libraries in the /usr/local directory require an extension to be included in the .tcz.dep file. You can see which extension is used by running eg. "readlink /usr/local/lib/libX11.so.6 | cut -d / -f 4".

If a dependency extension isn't in the tce/optional directory in the PiTrexCore ZIP file, it will need to be added there from the Tiny Core Linux repo . If there is no extension for Tiny Core Linux that already provides your library, then you will have to build this as well. All dependencies should go into tce/optional on the MicroSD card rather than tcz/, so that they don't get displayed in the menu.

Automated extension creation

The games and emulators in the PiTrex git repo are automatically packaged into extensions by running the distro/piext .sh script in the main directory of the git repo. This works in two different stages.

First it scans all the program directories for <extension>.tcz.list files. These list all the files in the same directory in the full path where they are to be installed. Where a file is in a sub-directory of where the <extension>.tcz.list file is, a symlink to that file must be placed there. Symlink to a symlink if you want to include a symlink in the extension. For X games a default XF86Config file can be included at /usr/local/X11R6/etc/X11/<extension>/XF86Config by adding it in the <extension>.tcz.list file.

These extensions are placed in distro/tcz/<extension>.tcz, along with <extension>.tcz.list, <extension>.tcz.md5.txt, and if there is an <extension>.tcz.dep file then it will be copied there too.

For program directories one level deep with a Makefile.raspbian file that contains an install rule, "make install" is run after deleting /opt/pitrex, then everything in /opt/pitrex is included in the extension for that program. Note that this means anything in /opt/pitrex before the script is run will be deleted. The extension is again placed in distro/tcz/ with the name of the directory in which the Makefile.raspbian file was found. <extension>.tcz.list and <extension>.tcz.md5.txt are automatically generated, and if there is an <extension>.tcz.dep file then it will be copied there too. If there is an XF86Config file in the program's directory, it will be included in the extension at /usr/local/X11R6/etc/X11/<extension>/XF86Config.

At the end the script will report the names of any programs where Makefile.raspbian failed. This could be caused by compiling errors if the programs were not all already compiled.