README review

README.md

@@ -1,121 +1,122 @@
 [![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
+and build tools for creating GameOS homebrew applications as SELF executables
+and installable PKG packages.
 
-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
------------
+## Environment
 
-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:
+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.
 
-* [ps3toolchain](http://github.com/ps3dev/ps3toolchain)
+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.
 
-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.
+## Building
 
-Most of the PSL1GHT samples included in the samples/ directory require various
-libraries from [ps3libraries](http://github.com/ps3dev/ps3libraries) to be
-installed.
+Building PSL1GHT directly is useful when developing PSL1GHT itself or testing changes.
+A working PS3 toolchain must already be installed.
 
-Building
---------
+```sh
+git clone https://github.com/ps3dev/PSL1GHT.git
+cd PSL1GHT
+make install-ctrl
+make
+make install
+```
 
-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...
+`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`.
 
-    cd /path/to/psl1ght.git/
-    export PSL1GHT=/path/to/psl1ght.git/build
-    make install-ctrl
-    make
-    make install
+To remove generated build files:
+```
+make clean
+```
 
-... 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.
+## Building Applications
 
-Current Status
---------------
+PSL1GHT programs are built using their Makefile. The repository currently provides
+samples organised by subsystem, such as `audio`, `graphics` and `input`.
 
-### Graphics
+To build an individual sample:
+```
+cd samples/<category>/<sample>
+make
+```
+A typical sample build produces `.elf` and `.self` outputs. Samples that define a package
+target can be packaged with
+```sh
+make pkg
+```
+Package metadata is set
+by the application's Makefile.
 
-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.