README review #165
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,121 +1,131 @@ | ||
| [](./LICENSE) | ||
| [](https://github.com/ps3dev/PSL1GHT/actions/workflows/build.yml) | ||
|
|
||
| # PSL1GHT | ||
|
|
||
| PSL1GHT is an open-source PlayStation 3 homebrew SDK. It provides libraries for | ||
| GameOS homebrew applications created using the PS3 toolchain. | ||
|
|
||
| > [!NOTE] | ||
| > This is the SDK repository. | ||
| > For the full development environment, please use | ||
| > [ps3dev](https://github.com/ps3dev/ps3dev). | ||
|
|
||
| ## 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. | ||
|
|
||
| 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. | ||
|
|
||
| ## Building | ||
|
|
||
| Building PSL1GHT directly is useful when developing PSL1GHT itself or testing changes. | ||
| A working PS3 toolchain must already be installed. | ||
|
|
||
| > [!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. | ||
|
|
||
| ```sh | ||
| git clone https://github.com/ps3dev/PSL1GHT.git | ||
| cd PSL1GHT | ||
| make install-ctrl | ||
| make | ||
| make install | ||
| ``` | ||
|
|
||
| `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`. | ||
|
|
||
| To remove generated build files: | ||
| ```sh | ||
| make clean | ||
| ``` | ||
|
|
||
| ## Building Applications | ||
|
|
||
| PSL1GHT programs are built using their Makefile. The repository currently provides | ||
| samples organised by subsystem, such as `audio`, `graphics` and `input`. | ||
|
|
||
| To build an individual sample: | ||
| ```sh | ||
| 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. Quitting from the XMB requires the | ||
| application to register a callback to handle the event; an example can be found in the | ||
| camera sample. | ||
|
|
||
| ## Optional Dependencies | ||
|
|
||
| ### ps3libraries | ||
|
|
||
| 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. | ||
|
|
||
|
Member
There was a problem hiding this comment. This information is rather important. Is the idea to put all the removed info into the wiki (which right now just links back to this README)?
Author
There was a problem hiding this comment. I think this particular line should be readded, it is important. Some core information like this can remain in the README - if you have any other suggestions on this point, I'd appreciate them. Foundational points like callbacks are unlikely to change as PSL1GHT develops, so unlike the longer feature trivia, I think they're safe to include. |
||
| ### NVidia Cg Toolkit | ||
|
|
||
| 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. | ||
|
|
||
| ## Documentation | ||
|
|
||
| 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. | ||
|
|
||
| The public headers contain Doxygen documentation for many APIs. Generate it with: | ||
| ```sh | ||
| make doc | ||
| ``` | ||
|
|
||
| Doxygen must be installed. | ||
|
|
||
| ## Current Status | ||
|
|
||
| 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`. | ||
|
|
||
| Contributions that improve compatibility, sample coverage and documentation are welcome. | ||
| For runtime changes, please describe the toolchain and hardware used for testing. | ||
|
|
||
| ## Credits | ||
|
|
||
|
|
||
| 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 | ||
|
|
||
| Thanks to all [contributors](https://github.com/ps3dev/PSL1GHT/graphs/contributors) who have | ||
| helped to maintain and improve PSL1GHT over the years. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hm, removing this will make
make installoverwrite the global installation of PSL1GHT, which might not be what you want when making some experimental development of PSL1GHT itself (which is what this section is about)?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How would you suggest reframing or rephrasing this section? PSL1GHT is not going to be manually rebuilt by most users unless they are developing PSL1GHT specifically.
Your concern is valid, in that a developer may not want to overwrite their global installation - I'm just wondering if the solution here is to add a disclaimer or change the commands.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Indeed. And it is good that the new version makes this clear. But I guess that's also why I find it notable that the new version removes a step specifically geared at this use case. 😄
I think there should at least be a sentence before the
make installline pointing out that you might want to change $PSL1GHT when working on a locally modified version.The fact that
make installalso install stuff in $PS3DEV makes this a little bit more messy, that wasn't even mentioned in the old README. You can't just point $PS3DEV to an empty directory because then the Makefiles won't find the toolchain... 😩There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, the dependency of the toolchain and PSL1GHT upon each other has been something bucanero and I have been working to untangle. Hence the creation of the PS3DEV master repository, similar to PSPDEV, so these parts can be built separately then packaged. This is just one of those leftovers that could be messy to fix properly.
This separation of concerns is hard to do now when the environment has been structured this way for so long. For now, I think the best course of action is a notice before the
make installline warning of the potential to overwrite the global installation.