Switch to mipsel-none-elf, move docs, add template presets

9 files changed, 123 insertions, 71 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 87980a5..720ca8c 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -26,11 +26,11 @@ include(GNUInstallDirs)
 # These are passed through to libpsn00b and the examples (they are defined in
 # the toolchain file).
 set(
-	PSN00BSDK_TC $ENV{PSN00BSDK_TC}
-	CACHE PATH   "Path to the GCC toolchain's installation directory"
+	PSN00BSDK_TC ""
+	CACHE PATH   "Path to the GCC toolchain's installation directory (if not in PATH)"
 )
 set(
-	PSN00BSDK_TARGET mipsel-unknown-elf
+	PSN00BSDK_TARGET mipsel-none-elf
 	CACHE STRING     "GCC toolchain target triplet"
 )
 
@@ -38,6 +38,10 @@ set(
 	SKIP_EXAMPLES OFF
 	CACHE BOOL    "Skip building SDK examples (not required for installation)"
 )
+set(
+	BUILD_INFO   ""
+	CACHE STRING "Information about this build to be included in build.json"
+)
 
 # Forward some important variables to mkpsxiso and to the subprojects (they are
 # not inherited automatically as they are not environment variables). This also
@@ -49,6 +53,8 @@ set(
 	COMMON_ARGS
 	-DPSN00BSDK_TC:PATH=${PSN00BSDK_TC}
 	-DPSN00BSDK_TARGET:STRING=${PSN00BSDK_TARGET}
+	-DPSN00BSDK_VERSION:STRING=${PROJECT_VERSION}
+	-DPSN00BSDK_BUILD_INFO:STRING=${BUILD_INFO}
 	-DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}
 )
 set(
@@ -118,6 +124,11 @@ install(
 	DESTINATION ${CMAKE_INSTALL_DATADIR}/psn00bsdk
 	COMPONENT   docs
 )
+install(
+	DIRECTORY   examples
+	DESTINATION ${CMAKE_INSTALL_DATADIR}/psn00bsdk
+	COMPONENT   examples
+)
 
 ## CPack configuration
 
diff --git a/README.md b/README.md
index a8807df..6fd4cd1 100644
--- a/README.md
+++ b/README.md
@@ -80,7 +80,7 @@ As of August 16, 2021
 ## Obtaining PSn00bSDK
 
 PSn00bSDK has switched to a CMake-based build and installation system. See
-[INSTALL.md](INSTALL.md) for details.
+[installation.md](doc/installation.md) for details.
 
 Because PSn00bSDK is updated semi-regularly due to this project being in
 a work-in-progress state, it is better to obtain this SDK from source and
diff --git a/doc/cmake_reference.md b/doc/cmake_reference.md
index 3b586ab..9e134d9 100644
--- a/doc/cmake_reference.md
+++ b/doc/cmake_reference.md
@@ -10,15 +10,44 @@ can be done on the command line (`-DCMAKE_TOOLCHAIN_FILE=...`), in
 `CMakeLists.txt` (before calling `project()`) or using a
 [preset](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html).
 
-It's recommended to put this snippet in `CMakeLists.txt` to automatically set
-the toolchain file according to the `PSN00BSDK_LIBS` environment variable:
-
-```cmake
-if(NOT DEFINED CMAKE_TOOLCHAIN_FILE AND DEFINED ENV{PSN00BSDK_LIBS})
-  set(CMAKE_TOOLCHAIN_FILE $ENV{PSN00BSDK_LIBS}/cmake/sdk.cmake)
-endif()
+It's suggested to have a default preset that sets `CMAKE_TOOLCHAIN_FILE` to
+`$env{PSN00BSDK_LIBS}/cmake/sdk.cmake`, so the `PSN00BSDK_LIBS` environment
+variable (used by former PSn00bSDK versions) is respected. Such a preset can be
+created by placing a `CMakePresets.json` file in the project's root with the
+following contents:
+
+```json
+{
+  "version": 2,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 20,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name":        "default",
+      "displayName": "Default configuration",
+      "description": "Use this preset to build the project using PSn00bSDK.",
+      "generator":   "Ninja",
+      "binaryDir":   "${sourceDir}/build",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE":     "Debug",
+        "CMAKE_TOOLCHAIN_FILE": "$env{PSN00BSDK_LIBS}/cmake/sdk.cmake",
+        "PSN00BSDK_TC":         "",
+        "PSN00BSDK_TARGET":     "mipsel-none-elf"
+      }
+    }
+  ]
+}
 ```
 
+To avoid having to pass variables to CMake each time the project is built, a
+second presets file named `CMakeUserPresets.json` can be created and populated
+with hardcoded values in the `cacheVariables` section. This file can be kept
+private (e.g. by adding it to `.gitignore`); CMake will automatically load
+presets from it instead of `CMakePresets.json` if it exists.
+
 See the [template](../template/CMakeLists.txt) for an example CMake script
 showing how to build a simple project.
 
@@ -130,28 +159,24 @@ build script, from the CMake command line when configuring the project
 - `PSN00BSDK_TARGET` (`STRING`)
 
   The GCC toolchain's target triplet. PSn00bSDK assumes the toolchain targets
-  `mipsel-unknown-elf` by default, however this can be changed to e.g. use a
-  MIPS toolchain that was compiled for a slightly-different-but-equivalent
-  target.
+  `mipsel-none-elf` by default, however this can be changed to e.g. use a MIPS
+  toolchain that was compiled for a slightly-different-but-equivalent target.
 
   The following GCC target triplets have been confirmed to work with PSn00bSDK:
 
-  - `mipsel-unknown-elf`
   - `mipsel-none-elf`
+  - `mipsel-unknown-elf`
+  - ~~`mipsel-linux-gnu`~~ (has issues with linking)
 
 - `PSN00BSDK_TC` (`PATH`)
 
-  Path to the GCC toolchain's installation prefix/directory. By default this is
-  initialized to the value of the `PSN00BSDK_TC` environment variable (if set).
-  Note that modifying the environment variable after the project has been
-  configured will *NOT* update this cache entry unless the project's cache is
-  cleared manually.
-
-  If not set, CMake will attempt to find the toolchain in the `PATH`
-  environment variable and store its path in this variable (so the search does
-  not have to be repeated).
+  Path to the GCC toolchain's installation prefix/directory. If not set, CMake
+  will attempt to find the toolchain in the `PATH` environment variable and
+  store its path in the project's variable cache (so the search does not have
+  to be repeated). It is recommended to add the toolchain's `bin` subfolder to
+  `PATH` rather than setting this variable.
 
-  **IMPORTANT**: if the toolchain's target is not `mipsel-unknown-elf`,
+  **IMPORTANT**: if the toolchain's target is not `mipsel-none-elf`,
   `PSN00BSDK_TARGET` must be set regardless of whether or not `PSN00BSDK_TC` is
   also set.
 
@@ -204,4 +229,4 @@ the build script.
   LZP archives as part of the build pipeline.
 
 -----------------------------------------
-_Last updated on 2021-09-27 by spicyjpeg_
+_Last updated on 2021-11-24 by spicyjpeg_
diff --git a/doc/dev notes.txt b/doc/dev notes.txt
index 3aa2db5..65a3976 100644
--- a/doc/dev notes.txt
+++ b/doc/dev notes.txt
@@ -109,13 +109,14 @@ your exception handler must do the following:
    controller- or interrupt-related function is being called. This is necessary
    (although ugly) as libpsn00b often calls such functions internally.
 
-* For some reason mipsel-unknown-elf-nm (symbol map generator) insists on
-outputting 64-bit addresses (with the top 32 bits set, e.g. FFFFFFFF80010000)
-even when feeding it a regular 32-bit MIPS executable, while the standard x86
-nm tool that ships with most GCC packages prints the proper 32-bit address.
-Unclear whether this is a bug, intended behavior or the result of some ancient
-ELF ABI flag crap. DL_ParseSymbolMap() will ignore the top 32 bits, so this
-should only bother you if you're implementing your own symbol map parser.
+* For some reason mipsel-unknown-elf-nm and mipsel-none-elf-nm (symbol map
+generators) insist on outputting 64-bit addresses (with the top 32 bits set,
+e.g. FFFFFFFF80010000) even when feeding it a regular 32-bit MIPS executable,
+while the standard x86 nm tool that ships with most GCC packages prints the
+proper 32-bit address. Unclear whether this is a bug, intended behavior or the
+result of some ancient ELF ABI flag crap. DL_ParseSymbolMap() will ignore the
+top 32 bits, so this should only bother you if you're implementing your own
+symbol map parser.
 
 * I haven't worked on psxspu but, for those willing to write some code, this is
 the formula to calculate SPU pitch values for playing musical notes ("^" is the
diff --git a/INSTALL.md b/doc/installation.md
index 5ae56f5..576eb7a 100644
--- a/INSTALL.md
+++ b/doc/installation.md
@@ -17,8 +17,8 @@ and installed properly.
      [here](https://cmake.org/download) if your package manager only provides
      older versions)
 
-   On Windows install [MSys2](https://www.msys2.org), then open the "MSys2
-   MSYS" shell and run this command:
+   On Windows you can obtain these dependencies by installing
+   [MSys2](https://www.msys2.org), opening the "MSys2 MSYS" shell and running:
 
    ```bash
    pacman -Syu git mingw-w64-x86_64-make mingw-w64-x86_64-ninja mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc
@@ -36,28 +36,27 @@ and installed properly.
    - `C:\msys64\mingw64\bin`
    - `C:\msys64\usr\bin`
 
-2. 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
-   extract it into one of the directories listed below instead.
+2. Download a precompiled copy of the GCC toolchain for `mipsel-none-elf` from
+   the releases page and extract it into one of the directories listed in
+   step 3. If you want to build the toolchain yourself, see
+   [toolchain.md](toolchain.md).
 
    **NOTE**: PSn00bSDK is also compatible with toolchains that target
-   `mipsel-none-elf`. If you already have such a toolchain (e.g. because you
-   have another PS1 SDK installed) you can skip this step. Make sure you pass
-   `-DPSN00BSDK_TARGET=mipsel-none-elf` to CMake when configuring the SDK
-   though (see step 5).
+   `mipsel-unknown-elf`. If you already have such a toolchain, you can use it
+   by passing `-DPSN00BSDK_TARGET=mipsel-unknown-elf` to CMake when configuring
+   the SDK (see step 5).
 
 3. 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`
-   - `C:\mipsel-unknown-elf`
-   - `/usr/local/mipsel-unknown-elf`
-   - `/usr/mipsel-unknown-elf`
-   - `/opt/mipsel-unknown-elf`
+   - `C:\Program Files\mipsel-none-elf`
+   - `C:\Program Files (x86)\mipsel-none-elf`
+   - `C:\mipsel-none-elf`
+   - `/usr/local/mipsel-none-elf`
+   - `/usr/mipsel-none-elf`
+   - `/opt/mipsel-none-elf`
 
 4. Clone the PSn00bSDK repo, then run the following command from the PSn00bSDK
    repository to download additional dependencies:
diff --git a/TOOLCHAIN.md b/doc/toolchain.md
index 2a78ccb..8e28c24 100644
--- a/TOOLCHAIN.md
+++ b/doc/toolchain.md
@@ -77,12 +77,12 @@ for a compatibility table.
 
    ```bash
    ../binutils-<VERSION>/configure \
-     --prefix=/usr/local/mipsel-unknown-elf --target=mipsel-unknown-elf \
+     --prefix=/usr/local/mipsel-none-elf --target=mipsel-none-elf \
      --disable-docs --disable-nls --with-float=soft
    ```
 
    Replace `<VERSION>` as usual. If you don't want to install the toolchain into
-   `/usr/local/mipsel-unknown-elf` you can change the `--prefix` option.
+   `/usr/local/mipsel-none-elf` you can change the `--prefix` option.
 
 3. Compile and install binutils (this will take a few minutes to finish):
 
@@ -116,7 +116,7 @@ options.
 
    ```bash
    ../gcc-<VERSION>/configure \
-     --prefix=/usr/local/mipsel-unknown-elf --target=mipsel-unknown-elf \
+     --prefix=/usr/local/mipsel-none-elf --target=mipsel-none-elf \
      --disable-docs --disable-nls --disable-libada --disable-libssp \
      --disable-libquadmath --disable-libstdc++-v3 --with-float=soft \
      --enable-languages=c,c++ --with-gnu-as --with-gnu-ld
@@ -144,7 +144,7 @@ options.
    earlier, but keep the `/bin` at the end):
 
    ```bash
-   export PATH=$PATH:/usr/local/mipsel-unknown-elf/bin
+   export PATH=$PATH:/usr/local/mipsel-none-elf/bin
    ```
 
    Restart the shell by closing and reopening the terminal window or SSH
@@ -171,7 +171,7 @@ that runs on Windows.
    ```bash
    ../binutils-<VERSION>/configure \
      --build=x86_64-linux-gnu --host=x86_64-w64-mingw32 \
-     --prefix=/tmp/mipsel-unknown-elf --target=mipsel-unknown-elf \
+     --prefix=/tmp/mipsel-none-elf --target=mipsel-none-elf \
      --disable-docs --disable-nls --with-float=soft
    ```
 
@@ -187,7 +187,7 @@ that runs on Windows.
    ```bash
    ../gcc-<VERSION>/configure \
      --build=x86_64-linux-gnu --host=x86_64-w64-mingw32 \
-     --prefix=/tmp/mipsel-unknown-elf --target=mipsel-unknown-elf \
+     --prefix=/tmp/mipsel-none-elf --target=mipsel-none-elf \
      --disable-docs --disable-nls --disable-libada --disable-libssp \
      --disable-libquadmath --disable-libstdc++-v3 --with-float=soft \
      --enable-languages=c,c++ --with-gnu-as --with-gnu-ld
@@ -200,13 +200,13 @@ that runs on Windows.
    make install-strip
    ```
 
-5. Copy the entire `/tmp/mipsel-unknown-elf` directory over to your Windows
+5. Copy the entire `/tmp/mipsel-none-elf` directory over to your Windows
    machine using VM shared folders, a network share, `scp` or whichever method
    you prefer. It's recommended to put the toolchain in
-   `C:\Program Files\mipsel-unknown-elf` or `C:\mipsel-unknown-elf`.
+   `C:\Program Files\mipsel-none-elf` or `C:\mipsel-none-elf`.
 
 6. If you want to keep the toolchain in another location and/or use it from the
-   command line, add the `bin` subdirectory inside `mipsel-unknown-elf` to the
+   command line, add the `bin` subdirectory inside `mipsel-none-elf` to the
    `PATH` environment variable (as you did on Linux) using System Properties.
 
 ## Note regarding C++ support
@@ -221,4 +221,4 @@ implemented due to bloat concerns that it may introduce. Besides, the official
 SDK lacks full C++ support as well.
 
 -----------------------------------------
-_Last updated on 2021-10-31 by spicyjpeg_
+_Last updated on 2021-11-23 by spicyjpeg_
diff --git a/libpsn00b/cmake/sdk.cmake b/libpsn00b/cmake/sdk.cmake
index ae23a06..1dfa431 100644
--- a/libpsn00b/cmake/sdk.cmake
+++ b/libpsn00b/cmake/sdk.cmake
@@ -4,11 +4,11 @@
 cmake_minimum_required(VERSION 3.20)
 
 set(
-	PSN00BSDK_TC $ENV{PSN00BSDK_TC}
-	CACHE PATH   "Path to the GCC toolchain's installation directory"
+	PSN00BSDK_TC ""
+	CACHE PATH   "Path to the GCC toolchain's installation directory (if not in PATH)"
 )
 set(
-	PSN00BSDK_TARGET mipsel-unknown-elf
+	PSN00BSDK_TARGET mipsel-none-elf
 	CACHE STRING     "GCC toolchain target triplet"
 )
 
@@ -56,7 +56,7 @@ cmake_path(GET _bin PARENT_PATH _toolchain)
 if(NOT IS_DIRECTORY PSN00BSDK_TC)
 	set(
 		PSN00BSDK_TC ${_toolchain}
-		CACHE PATH   "Path to the GCC toolchain's installation directory"
+		CACHE PATH   "Path to the GCC toolchain's installation directory (if not in PATH)"
 		FORCE
 	)
 endif()
diff --git a/template/CMakeLists.txt b/template/CMakeLists.txt
index c0c05d0..4aa648f 100644
--- a/template/CMakeLists.txt
+++ b/template/CMakeLists.txt
@@ -3,14 +3,6 @@
 
 cmake_minimum_required(VERSION 3.20)
 
-# CMAKE_TOOLCHAIN_FILE must be set to point to cmake/sdk.cmake in the PSn00bSDK
-# installation directory *before* calling project(). You don't have to hardcode
-# the path in your CMakeLists.txt as you can set it from the command line when
-# configuring (-DCMAKE_TOOLCHAIN_FILE=...) or using CMake presets.
-if(NOT DEFINED CMAKE_TOOLCHAIN_FILE AND DEFINED ENV{PSN00BSDK_LIBS})
-	set(CMAKE_TOOLCHAIN_FILE $ENV{PSN00BSDK_LIBS}/cmake/sdk.cmake)
-endif()
-
 project(
 	PSn00bSDK-template
 	LANGUAGES    C CXX ASM
@@ -20,6 +12,7 @@ project(
 )
 
 psn00bsdk_add_executable(template STATIC main.c)
+
 psn00bsdk_add_cd_image(
 	iso      # Target name
 	template # Output file name (= template.bin + template.cue)
diff --git a/template/CMakePresets.json b/template/CMakePresets.json
new file mode 100644
index 0000000..d08b334
--- /dev/null
+++ b/template/CMakePresets.json
@@ -0,0 +1,23 @@
+{
+	"version": 2,
+	"cmakeMinimumRequired": {
+		"major": 3,
+		"minor": 20,
+		"patch": 0
+	},
+	"configurePresets": [
+		{
+			"name":        "default",
+			"displayName": "Default configuration",
+			"description": "Use this preset to build the project using PSn00bSDK.",
+			"generator":   "Ninja",
+			"binaryDir":   "${sourceDir}/build",
+			"cacheVariables": {
+				"CMAKE_BUILD_TYPE":     "Debug",
+				"CMAKE_TOOLCHAIN_FILE": "$env{PSN00BSDK_LIBS}/cmake/sdk.cmake",
+				"PSN00BSDK_TC":         "",
+				"PSN00BSDK_TARGET":     "mipsel-none-elf"
+			}
+		}
+	]
+}