diff options
Diffstat (limited to 'INSTALL.md')
| -rw-r--r-- | INSTALL.md | 124 |
1 files changed, 82 insertions, 42 deletions
@@ -6,27 +6,33 @@ The instructions below are for Windows and Linux. Building on macOS hasn't been tested but should work. -1. Install a host C compiler toolchain if you don't already have one (this is - required to build the tools). You can use MSVC or MinGW on Windows, or - install the `build-essential` package provided by most Linux distros. - -2. Install Git and CMake. Note that some Linux distros ship relatively old - versions of CMake, so make sure you have at least CMake 3.21. You will also - need [Ninja](https://ninja-build.org) (it is a single executable, you have to - copy it to any directory listed in the `PATH` environment variable) on - Windows as there is no preinstalled build system; on Linux you can use `make` - instead, but Ninja is still recommended. - -3. Build and install a GCC toolchain for `mipsel-unknown-elf`. As GCC is - notoriously hard to compile under Windows, you may download a precompiled +1. Set up a host compiler. Most Linux distros provide a `build-essential`, + `base-devel` or similar all-in-one package. You'll also need to install the + [Ninja](https://ninja-build.org) build engine (it's usually in a package + called `ninja-build`). On Windows install [MSys2](https://www.msys2.org), + then run the following command in the MSys2 shell to install MinGW and Ninja: + + ```bash + pacman -Syu mingw-w64-x86_64-gcc mingw-w64-x86_64-ninja + ``` + + Add `C:\msys64\mingw64\bin` (replace `C:\msys64` if you installed MSys2 to a + different location) to the `PATH` environment variable using System + Properties. + +2. Install Git and CMake. Note that MSys2 and some Linux distros ship relatively + old versions (PSn00bSDK requires 3.21+), so grab the latest CMake release + from [here](https://cmake.org) instead of through your package manager. + +3. Build and install a GCC toolchain for `mipsel-unknown-elf`, as detailed in + [TOOLCHAIN.md](TOOLCHAIN.md). On Windows, you may download a precompiled version from [Lameguy64's website](http://lameguy64.net?page=psn00bsdk) and - and extract it into Program Files instead. See [toolchain.txt](toolchain.txt) - for details on compiling GCC. + extract it into one of the directories listed below instead. -4. If you chose a non-standard install location for the toolchain, set the - `PSN00BSDK_TC` environment variable to point to the toolchain's root - directory. This step is unnecessary if you installed/extracted the toolchain - into any of these directories: +4. If you chose a non-standard install location for the toolchain, add the `bin` + subfolder (inside the top-level toolchain directory) to the `PATH` + environment variable. This step is unnecessary if you installed/extracted the + toolchain into any of these directories: - `C:\Program Files\mipsel-unknown-elf` - `C:\Program Files (x86)\mipsel-unknown-elf` @@ -35,49 +41,84 @@ tested but should work. - `/usr/mipsel-unknown-elf` - `/opt/mipsel-unknown-elf` -5. Clone/download the PSn00bSDK repo and run the following commands: +5. Clone/download the PSn00bSDK repo and run the following commands from its + directory: ```bash - cmake -S . -B ./build -G Ninja --install-prefix INSTALL_PATH + cmake -S . -B ./build -G Ninja cmake --build ./build + ``` + + If you want to install the SDK to a custom location rather than the default + one (`C:\Program Files\PSn00bSDK` or `/usr/local` depending on your OS), add + `--install-prefix <INSTALL_PATH>` to the first command. Remove `-G Ninja` to + use `make` instead of Ninja (slower, not recommended). + + If you run into errors, try passing `-DSKIP_TINYXML2=ON` to the first command + after installing `tinyxml2` manually. [See below](#advanced-build-options) + for more details. + +6. Install the SDK to the path you chose by running this command (add `sudo` if + necessary): + + ```bash cmake --install ./build ``` - Replace `INSTALL_PATH` with the directory you want PSn00bSDK to be installed - to (default is `C:\Program Files\PSn00bSDK` or `/usr/local`), and remove - `-G Ninja` if you want to use `make` instead (not recommended). The following - subdirectories will be created: + This will create and populate the following directories: - - `INSTALL_PATH/bin` - - `INSTALL_PATH/lib/libpsn00b` - - `INSTALL_PATH/share/psn00bsdk` + - `<INSTALL_PATH>/bin` + - `<INSTALL_PATH>/lib/libpsn00b` + - `<INSTALL_PATH>/share/psn00bsdk` -6. Set the `PSN00BSDK_LIBS` environment variable to - `INSTALL_PATH/lib/libpsn00b` and add `INSTALL_PATH/bin` to `PATH`. +7. Set the `PSN00BSDK_LIBS` environment variable to point to the `lib/libpsn00b` + subfolder inside the install directory. You might also want to add the `bin` + folder to `PATH` if it's not listed already. Although not strictly required, you'll probably want to install a PS1 emulator with debugging capabilities such as [no$psx](https://problemkaputt.de/psx.htm) -(Windows only) or [pcsx-redux](https://github.com/grumpycoders/pcsx-redux). +(Windows only), [DuckStation](https://github.com/stenzek/duckstation) or +[pcsx-redux](https://github.com/grumpycoders/pcsx-redux). **Avoid ePSXe and anything based on MAME** as they are inaccurate. -## Building installer packages +## Advanced build options + +### Skipping external dependency downloads + +By default [mkpsxiso](https://github.com/Lameguy64/mkpsxiso) (required for +building CD images) and [tinyxml2](https://github.com/leethomason/tinyxml2) +(required to build mkpsxiso and other SDK tools) are automatically cloned from +their respective repos and built as part of the PSn00bSDK build process, +*even if they are already installed*. + +If you wish to disable this behavior (e.g. because it leads to errors, or to +perform an offline build), invoke CMake with the `-DSKIP_MKPSXISO=ON` and/or +`-DSKIP_TINYXML2=ON` options when configuring the SDK. Note that you must have +`mkpsxiso` and/or `tinyxml2` already installed (either manually or via vcpkg or +your distro's package manager) to be able to skip them. + +### Building installer packages CPack can be used to build NSIS-based installers, DEB/RPM packages and zipped -releases. Note that currently none of the built packages include the toolchain, -thus their usefulness is limited. Distributing prebuilt releases is discouraged -anyway since PSn00bSDK is still far from being feature-complete. +releases that include built SDK libraries, headers as well as the GCC toolchain. +Distributing prebuilt releases is however discouraged since PSn00bSDK is still +far from being feature-complete. -1. Follow steps 1-4 above to set up the toolchain, then install NSIS on Windows - or `dpkg` and `rpm` on Linux. +1. Follow steps 1-4 above to set up the toolchain, then install + [NSIS](https://nsis.sourceforge.io/Download) on Windows or `dpkg` and `rpm` + on Linux. 2. Run the following commands from the PSn00bSDK directory: ```bash - cmake -S . -B ./build -G Ninja + cmake -S . -B ./build -G Ninja -DBUNDLE_TOOLCHAIN=ON cmake --build ./build -t package ``` - All built packages will be copied to the `build/cpack` folder. + All built packages will be copied to the `build/packages` folder. + + **NOTE**: do not use `-DSKIP_MKPSXISO=ON`, otherwise the mkpsxiso binary will + not be included in the packages. ## Creating a project @@ -89,7 +130,6 @@ anyway since PSn00bSDK is still far from being feature-complete. ```bash cmake -S . -B ./build -G Ninja cmake --build ./build - cmake --install ./build ``` If you did everything correctly there should be a `template.bin` CD image in @@ -99,10 +139,10 @@ Note that, even though the template relies on the `PSN00BSDK_LIBS` environment variable to locate the SDK by default, you can also specify the path directly on the CMake command line by adding `-DCMAKE_TOOLCHAIN_FILE=INSTALL_PATH/lib/libpsn00b/cmake/sdk.cmake` (replace -`INSTALL_PATH` as usual) to the first command. +`INSTALL_PATH`) to the first command. The toolchain script defines a few CMake macros to create PS1 executables, DLLs and CD images. See the [reference](doc/cmake_reference.md) for details. ----------------------------------------- -_Last updated on 2021-09-26 by spicyjpeg_ +_Last updated on 2021-10-18 by spicyjpeg_ |