diff --git a/README.md b/README.md index b451f5ad..4d189db1 100644 --- a/README.md +++ b/README.md @@ -1,121 +1,131 @@ [![License](https://img.shields.io/github/license/ps3dev/PSL1GHT.svg)](./LICENSE) [![CI](https://github.com/ps3dev/PSL1GHT/actions/workflows/build.yml/badge.svg)](https://github.com/ps3dev/PSL1GHT/actions/workflows/build.yml) -PSL1GHT -======= +# PSL1GHT -PSL1GHT is a lightweight PlayStation 3 homebrew SDK that uses the open-source -PlayStation 3 toolchains to compile user applications that will run from the -XMB menu (GameOS homebrew). +PSL1GHT is an open-source PlayStation 3 homebrew SDK. It provides libraries for +GameOS homebrew applications created using the PS3 toolchain. -Credits -------- +> [!NOTE] +> This is the SDK repository. +> For the full development environment, please use +> [ps3dev](https://github.com/ps3dev/ps3dev). - AerialX - Founder, Author - Parlane - Author - phiren - Author - Tempus - PSL1GHT Logo - lousyphreak - libaudio - Hermes - sysmodule, libpngdec, libjpgdec - BigBoss - EyeToy support added to libcamera sample, libgem sample. - ooPo - ps3libraries - ElSemi - Vertex Program Compiler - zerkman - SPU sample code - shagkur - Author - miigotu - Author +## Environment + +The master repository, [ps3dev](https://github.com/ps3dev/ps3dev), combines +the toolchain, libraries and PSL1GHT into a complete environment; this is the +recommended way for most users to get started with PSL1GHT. -Environment ------------ +PSL1GHT is built and tested with the toolchain provided by +[ps3toolchain](https://github.com/ps3dev/ps3toolchain). The toolchain supplies +compilers for the PPU and SPU, patched newlib environment, binutils, signing +tools and other programs required by PSL1GHT. -A GCC toolchain that supports the PowerPC 64bit architecture is required to -build PSL1GHT and its samples. It also requires the toolchain to provide -a patched newlib environment; at the moment only one toolchain does so: +## Building -* [ps3toolchain](http://github.com/ps3dev/ps3toolchain) +Building PSL1GHT directly is useful when developing PSL1GHT itself or testing changes. +A working PS3 toolchain must already be installed. -The SDK also includes a few standalone tools to help compilation. A host gcc -is required to build raw2h, ps3load, and sprxlinker requires libelf. ps3load -requires zlib installed. Python 2.x is required to run fself.py, sfo.py, and -pkg.py. Nvidia's [Cg Toolkit](http://developer.nvidia.com/object/cg_toolkit.html) -is required for compiling vertex programs. The signing tools require libgmp. +> [!NOTE] +> `make install` will overwrite the global PSL1GHT installation. +> If you do not want this, you may want to temporarily change $PSL1GHT to a separate location +> while working on a locally modified version. +> +> `make install` also installs parts into $PS3DEV; however, you cannot point $PS3DEV to an +> empty location, as the Makefiles will then fail to find the toolchain. -Most of the PSL1GHT samples included in the samples/ directory require various -libraries from [ps3libraries](http://github.com/ps3dev/ps3libraries) to be -installed. +```sh +git clone https://github.com/ps3dev/PSL1GHT.git +cd PSL1GHT +make install-ctrl +make +make install +``` -Building --------- +`make install-ctrl` installs the shared build rules required during the SDK build. +`make install` installs the completed headers, libraries, rules, and host utilities +into `$PSL1GHT` and `$PS3DEV`. -Run make install in the psl1ght directory to build it all, and make sure to -set the environment variable $PSL1GHT to the folder where you wish to -install it to, for example... +To remove generated build files: +```sh +make clean +``` - cd /path/to/psl1ght.git/ - export PSL1GHT=/path/to/psl1ght.git/build - make install-ctrl - make - make install +## Building Applications -... for a local build of it. Ensure that $PSL1GHT is set when you are -building any of the examples or other apps that use PSL1GHT. +PSL1GHT programs are built using their Makefile. The repository currently provides +samples organised by subsystem, such as `audio`, `graphics` and `input`. -Current Status --------------- +To build an individual sample: +```sh +cd samples// +make +``` +A typical sample build produces `.elf` and `.self` outputs. Samples that define a package +target can be packaged with +```sh +make pkg +``` -### Graphics +Package metadata is set by the application's Makefile. Quitting from the XMB requires the +application to register a callback to handle the event; an example can be found in the +camera sample. -PSL1GHT supports hardware accelerated 3d graphics. -Vertex and Fragment shaders are a work in progress. +## Optional Dependencies -### Input +### ps3libraries -PS3 controllers are fully supported, and pressing the PS button brings up the -in-game XMB menu, assuming the framebuffer is working. +Some samples and applications use libraries from +[ps3libraries](https://github.com/ps3dev/ps3libraries/). It is a collection of libraries +ported to the PS3 such as SDL and zlib. -Quitting from the XMB requires the application to register a callback to handle the event. An example using this is the camera example. +### NVidia Cg Toolkit -### Filesystem Access +The current shader workflow relies upon the discontinued proprietary NVidia Cg Toolkit +when compiling `.vcg` and `.fcg` shader sources. Cg Toolkit cannot be included in the +PS3DEV environment - it must be installed separately. It is not required for applications +that don't need shaders. -Full filesystem support is available, with access to the internal PS3 hard -drive, game disc contents, and external devices like USB drives. Only directory -iteration is missing, though it can be done using the lv2 filesystem interface -directly (see include/psl1ght/lv2/filesystem.h) +## Documentation -### Networking +There is a [DeepWiki](https://deepwiki.com/ps3dev/PSL1GHT) set up for PSL1GHT that +contains information about the SDK and allows you to ask it questions. This can +provide a start for basic questions; the source code and public headers remain the +authority. -Berkeley sockets are available for use in PSL1GHT, though some -implementation remains incomplete at this time (hostname lookups, for example). +The public headers contain Doxygen documentation for many APIs. Generate it with: +```sh +make doc +``` -### STDOUT Debugging +Doxygen must be installed. -By default, PSL1GHT applications redirect stdout and stderr to the lv2 TTY -interface. Kammy's ethdebug module can be used to retrieve this live debugging -information over UDP broadcast packets. -See [Kammy](http://github.com/AerialX/Kammy) for more information and a -precompiled ethdebug hook loader. +## Current Status -### SPUs +The core PSL1GHT SDK is built in CI with the PS3 toolchain. +Coverage of samples is currently incomplete - some samples are excluded from the +top sample build script, and CI does not yet verify anything beyond a top-level +`make`. -PSL1GHT provides access to running programs on the raw SPUs, and communication -with it from the PPU. See sputest in the samples directory for a simple -example. +Contributions that improve compatibility, sample coverage and documentation are welcome. +For runtime changes, please describe the toolchain and hardware used for testing. -### SPRX Linking +## Credits -Any dynamic libraries available to normal PS3 applications can be used with -PSL1GHT, they just need to be made into a stub library and have the exports -filled out. See any of the examples in sprx/ for information on the -creation of SPRX stub libraries. -The following libraries are currently supported: + AerialX - Founder, Author + Parlane - Author + phiren - Author + Tempus - PSL1GHT Logo + lousyphreak - libaudio + Hermes - sysmodule, libpngdec, libjpgdec + BigBoss - EyeToy support added to libcamera sample, libgem sample. + ooPo - ps3libraries + ElSemi - Vertex Program Compiler + zerkman - SPU sample code + shagkur - Author + miigotu - Author -* libio - * libpad - * libmouse -* liblv2 -* libsysutil -* libgcm_sys -* libsysmodule -* libpngdec -* libjpgdec -* libgem +Thanks to all [contributors](https://github.com/ps3dev/PSL1GHT/graphs/contributors) who have +helped to maintain and improve PSL1GHT over the years.