Merge pull request #38 from spicyjpeg/cmake

Full CMake support (in place of makefiles)

1 files changed, 108 insertions, 0 deletions

diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..6547c2b
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,108 @@
+
+# Getting started with PSn00bSDK
+
+## Building and installing
+
+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
+   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.
+
+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:
+
+   - `C:\Program Files\mipsel-unknown-elf`
+   - `C:\Program Files (x86)\mipsel-unknown-elf`
+   - `C:\mipsel-unknown-elf`
+   - `/usr/local/mipsel-unknown-elf`
+   - `/usr/mipsel-unknown-elf`
+   - `/opt/mipsel-unknown-elf`
+
+5. Clone/download the PSn00bSDK repo and run the following commands:
+
+   ```bash
+   cmake -S . -B ./build -G Ninja --install-prefix INSTALL_PATH
+   cmake --build ./build
+   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:
+
+   - `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`.
+
+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).
+**Avoid ePSXe and anything based on MAME** as they are inaccurate.
+
+## 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.
+
+1. Follow steps 1-4 above to set up the toolchain, then install NSIS 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 --build ./build -t package
+   ```
+
+   All built packages will be copied to the `build/cpack` folder.
+
+## Creating a project
+
+1. Copy the contents of `INSTALL_PATH/share/psn00bsdk/template` (or the
+   `template` folder within the repo) to your new project's root directory.
+
+2. Configure and build the template by running:
+
+   ```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
+   the `build` folder. Test it in an emulator to ensure it works.
+
+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.
+
+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_