Contributing to PKGi PS3

We welcome pull requests for bug fixes, architectural improvements, new features, and localizations! This document outlines how to set up your environment, debug the application, and submit contributions.

Setting up the Build Environment

To compile the PlayStation 3 executable (.self) and package (.pkg) locally, you must utilize the PS3 homebrew toolchain.

Required Dependencies

You must have the following installed and exported in your environment:

• PS3 toolchain (ps3dev)
• PSL1GHT SDK
• Libraries: Tiny3D, YA2D, PolarSSL (v1.3.9), libcurl (v7.64.1), MikMod, Mini18n, dbglogger.

Building Locally

If your host machine is fully configured (with $PSL1GHT and $PS3DEV paths exported):

1. Run make to compile the source code into pkgi-ps3.elf and subsequently wrap it into pkgi-ps3.self.
2. Run make pkg to package the executable, sfo.xml, and assets into an installable pkgi-ps3.pkg file.
3. Run make run to immediately push the executable to the console via PS3LoadX (requires PS3LOAD=tcp:x.x.x.x environment variable).

Building with Docker (Recommended)

Configuring the PSL1GHT toolchain natively can be prone to dependency conflicts. The easiest and most reproducible way to build the project is via the included Dockerfile.

1. Ensure you have Docker installed and running on your system.
2. Execute the following command from the root of the repository:

make -f Makefile.docker docker-pkg

What this does:

• Builds an Ubuntu 22.04 base image.
• Injects the pre-compiled PSL1GHT SDK via curl.
• Clones and compiles the required ya2d_ps3 and mini18n dependencies.
• Mounts your current working directory and executes the make pkg command.
• Outputs the resulting pkgi-ps3.pkg directly into your host directory.

Debugging

Standard printf statements do not output to a visible console on the PS3. To debug the application, you must utilize network logging.

1. Build the application with the debug flag appended:

   make DEBUGLOG=1

2. This enables the dbglogger library, converting all LOG() macros in the C code to network packets.

3. Run the resulting debug .pkg on your PS3.
4. On your PC (connected to the same local network), use socat to listen to the UDP multicast address:

socat udp4-recv:30000,ip-add-membership=239.255.0.100:0.0.0.0 -

You will see a live stream of extensive internal state logs, memory allocations, and network trace errors.

Translating (Localization)

PKGi PS3 utilizes the standard gettext .po (Portable Object) format for dynamic localization via the mini18n library.

To add a new language or fix an existing translation:

1. Navigate to pkgfiles/USRDIR/LANG/.
2. Copy the translate.po template and rename it to your target language code (e.g., sv.po for Swedish).
3. Open the file in a tool like Poedit, or any standard text editor.

4. Edit the msgstr fields to correspond with the msgid strings. Example:

   #: pkgi.c:82
   msgid "Installing"
   msgstr "Instalando" 

5. Submit a Pull Request with your .po file. The application (pkgi_ps3.c) uses sysUtilGetSystemParamInt to automatically map the system language to these files.