From 71496627f90071a2fda809b5460d9c1f99373968 Mon Sep 17 00:00:00 2001 From: spicyjpeg <88942473+spicyjpeg@users.noreply.github.com> Date: Sun, 12 Sep 2021 19:39:19 +0200 Subject: Updated docs, moved install guide to INSTALL.md --- doc/cmake_reference.md | 203 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 doc/cmake_reference.md (limited to 'doc/cmake_reference.md') diff --git a/doc/cmake_reference.md b/doc/cmake_reference.md new file mode 100644 index 0000000..8810ad4 --- /dev/null +++ b/doc/cmake_reference.md @@ -0,0 +1,203 @@ + +# PSn00bSDK CMake reference + +## Setup + +The only requirement to use the SDK in CMake is to set the +`CMAKE_TOOLCHAIN_FILE` variable to `INSTALL_PATH/lib/libpsn00b/cmake/sdk.cmake` +(where `INSTALL_PATH` is the install prefix PSn00bSDK is installed to). This +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() +``` + +See the [template](../template/CMakeLists.txt) for an example CMake script +showing how to build a simple project. + +## Targets + +These targets are defined when using PSn00bSDK. There is no need to explicitly +link against any of these, as the helper commands (see below) handle linking +behind the scenes. To avoid conflicts, however, no target should be given any +of these names. + +- `c`, `psxgpu`, `psxgte`, `psxspu`, `psxcd`, `psxsio`, `psxetc`, `psxapi`, `lzp` +- `psn00bsdk_common`, `psn00bsdk_object_lib` +- `psn00bsdk_static_exe` +- `psn00bsdk_dynamic_exe` +- `psn00bsdk_static_lib` +- `psn00bsdk_shared_lib`, `psn00bsdk_module_lib` + +## Commands + +- `psn00bsdk_add_executable( [EXCLUDE_FROM_ALL] [sources...])` + + A wrapper around `add_executable()` to create PS1 executables. Three files + will be generated for each call to this function: + + - `.elf` (regular ELF executable) + - `.exe` (executable converted to the format expected by the PS1) + - `.map` (symbol map file for dynamic linking/introspection) + + The `.exe` and `.map` extensions can be customized by overriding + `PSN00BSDK_EXECUTABLE_SUFFIX` and `PSN00BSDK_SYMBOL_MAP_SUFFIX` prior to + creating the executable. + + The second argument (mandatory) specifies whether the executable is going to + load DLLs at runtime. If set to `STATIC`, $gp-relative addressing (i.e. + reusing the $gp register normally used for DLL addressing) will be enabled, + slightly reducing executable size and RAM usage but breaking compatibility + with the dynamic linker. + +- `psn00bsdk_add_library( [EXCLUDE_FROM_ALL] [sources...])` + + Wraps `add_library()` to create static libraries or dynamically-linked + libraries (DLLs). + + The second argument (mandatory, unlike `add_library()`) specifies the type of + library to create. `STATIC` will create a static library named `lib.a`. + `SHARED` and `MODULE` will compile a DLL, producing the following files (note + that there is no `lib` prefix for DLLs): + + - `.so` (regular ELF shared library) + - `.dll` (raw binary with some ELF headers prepended) + + As with executables, the `.dll` extension can be customized by setting + `PSN00BSDK_SHARED_LIBRARY_SUFFIX`. + +- `psn00bsdk_add_cd_image( [...])` + + Creates a new target that will build a CD image using `mkpsxiso`. + + The first argument is the name of the target to create; next up is the name + of the generated image file (`.bin` + `.cue`). The + third argument is the path to the XML file passed to `mkpsxiso`. + + The XML file is "configured" by CMake, i.e. any `${var}` or `@var@` + expressions are replaced with the values of the respective variables. In + particular `${CD_IMAGE_NAME}` is replaced with the second argument passed to + `psn00bsdk_add_cd_image()`; the file must properly set the output file names + like this: + + ```xml + + + ``` + + Any additional argument is passed through to the underlying call to + `add_custom_target()`, so most of the options supported by + `add_custom_target()` are also supported here. + +## Definitions + +When compiling executables and libraries using the above commands the following +preprocessor macros are automatically `#define`'d: + +- `PLAYSTATION` + + Always set to 1. Can be used to implement different options or code paths for + libraries, so they can target both the host and PS1 (as it won't be defined + when compiling outside of the SDK). + +- `DEBUG` + + Defined and set to 1 in a debug configuration, i.e. when the + `CMAKE_BUILD_TYPE` variable is set to `Debug`. This value is used by the + PSn00bSDK libraries, and should be used in executables, to enable additional + debug logging. + + Note that the default CMake configuration is usually debug, so it's + recommended to specify `-DCMAKE_BUILD_TYPE=Release` to get rid of the logging + overhead in release builds and reduce executable size. + +## Cached settings + +These variables are stored in CMake's cache and can be edited by the project's +build script, from the CMake command line when configuring the project +(`-Dname=value`) or using an editor such as the CMake GUI. + +- `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. + + The following GCC target triplets have been confirmed to work with PSn00bSDK: + + - `mipsel-unknown-elf` + - `mipsel-none-elf` + +- `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). + + **IMPORTANT**: if the toolchain's target is not `mipsel-unknown-elf`, + `PSN00BSDK_TARGET` must be set regardless of whether or not `PSN00BSDK_TC` is + also set. + +- `PSN00BSDK_LIBGCC` (`FILEPATH`) + + Path to the `libgcc.a` library bundled with the GCC toolchain. The contents + of this library are merged into `libc` when building the SDK, so this + variable is only actually needed when compiling `libpsn00b`. Setting this + variable manually usually isn't necessary as CMake will locate `libgcc.a` + automatically after finding the toolchain. + +## Internal settings + +These settings are not stored in CMake's cache and can only be set from within +the build script. + +- `PSN00BSDK_LIBRARIES` + + List of libraries to link all created targets against. By default this + includes all PSn00bSDK libraries. + +- `PSN00BSDK_EXECUTABLE_SUFFIX`, `PSN00BSDK_SHARED_LIBRARY_SUFFIX`, + `PSN00BSDK_SYMBOL_MAP_SUFFIX` + + File extensions to use for generated PS1 files. The default values are + `.exe`, `.dll` and `.map` respectively. Note that file names and extensions + can be changed anyway when building a CD image. + +## Read-only variables + +- `PSN00BSDK_TOOLS`, `PSN00BSDK_INCLUDE`, `PSN00BSDK_LDSCRIPTS` + + Lists of paths used internally. Should not be set, manipulated or overridden + by scripts. + +- `TOOLCHAIN_NM` + + Path to the `nm` executable used to generate symbol maps. Although not used + internally by CMake, this program is part of the GCC toolchain. + +- `ELF2X`, `ELF2CPE`, `MKPSXISO`, `LZPACK`, `SMXLINK` + + Paths to the PSn00bSDK tools' executables. As no functions are currently + provided for building assets, `LZPACK` and `SMXLINK` can be used with + `add_custom_command()`/`add_custom_target()` to convert models and generate + LZP archives as part of the build pipeline. + +----------------------------------------- +_Last updated on 2021-09-12 by spicyjpeg_ -- cgit v1.2.3 From 49ea4e7561980d79ec3bed869982852b45b597e8 Mon Sep 17 00:00:00 2001 From: spicyjpeg <88942473+spicyjpeg@users.noreply.github.com> Date: Mon, 27 Sep 2021 22:27:17 +0200 Subject: Updated changelog and files missing from last commit --- changelog.txt | 16 ++++++++++++++++ doc/cmake_reference.md | 6 +++++- examples/demos/n00bdemo/data.h | 4 +++- examples/demos/n00bdemo/data.s.template | 6 +++--- examples/demos/n00bdemo/main.c | 6 ++++-- libpsn00b/cmake/internal_setup.cmake | 3 +++ libpsn00b/include/lzp/lzp.h | 18 +++++++++--------- libpsn00b/include/lzp/lzqlp.h | 23 ++++++++++++++--------- libpsn00b/lzp/bit.c | 2 +- libpsn00b/lzp/bit.h | 2 +- libpsn00b/lzp/crc.c | 6 +++--- tools/lzpack/main.cpp | 18 +++++++++--------- 12 files changed, 71 insertions(+), 39 deletions(-) (limited to 'doc/cmake_reference.md') diff --git a/changelog.txt b/changelog.txt index 03d2d10..046f4fe 100644 --- a/changelog.txt +++ b/changelog.txt @@ -2,6 +2,22 @@ PSn00bSDK changelog Items that are lower in the log are more recently implemented. +09-27-2021 by spicyjpeg: + +* liblzp, tools: Fixed tools not building on MSVC and cleaned up LZP API + declarations (replaced meaningless void* pointers with proper types). + +* libpsn00b: Added missing PSN00BSDK_VERSION CMake variable. + +* examples: Fixed childexec (parent.exe) example crashing due to the child + executable not being relocated in the new build script. Patched n00bdemo to + suppress liblzp pointer type warnings. + +* Fixed another MSVC linker error when building tinyxml2 automatically, as well + as various toolchain/compiler test errors sometimes thrown by CMake. Updated + INSTALL.md with more details. + + 09-13-2021 by spicyjpeg: * Migrated libpsn00b, tools, examples and template to CMake, added a top-level diff --git a/doc/cmake_reference.md b/doc/cmake_reference.md index 8810ad4..3b586ab 100644 --- a/doc/cmake_reference.md +++ b/doc/cmake_reference.md @@ -182,6 +182,10 @@ the build script. ## Read-only variables +- `PSN00BSDK_VERSION` + + The SDK's version number (`major.minor.patch`). + - `PSN00BSDK_TOOLS`, `PSN00BSDK_INCLUDE`, `PSN00BSDK_LDSCRIPTS` Lists of paths used internally. Should not be set, manipulated or overridden @@ -200,4 +204,4 @@ the build script. LZP archives as part of the build pipeline. ----------------------------------------- -_Last updated on 2021-09-12 by spicyjpeg_ +_Last updated on 2021-09-27 by spicyjpeg_ diff --git a/examples/demos/n00bdemo/data.h b/examples/demos/n00bdemo/data.h index 3be0e3d..9e64ea1 100644 --- a/examples/demos/n00bdemo/data.h +++ b/examples/demos/n00bdemo/data.h @@ -1,7 +1,9 @@ #ifndef _DATA_H #define _DATA_H -extern unsigned char lz_resources[]; +extern unsigned char _lz_resources[]; + +#define lz_resources ((const LZP_HEAD*) _lz_resources) /*extern unsigned char smd_mtekdisk[]; extern unsigned char smd_mtektext[]; diff --git a/examples/demos/n00bdemo/data.s.template b/examples/demos/n00bdemo/data.s.template index a7237cd..9fbef2e 100644 --- a/examples/demos/n00bdemo/data.s.template +++ b/examples/demos/n00bdemo/data.s.template @@ -1,8 +1,8 @@ .section .data -.global lz_resources -.type lz_resources, @object -lz_resources: +.global _lz_resources +.type _lz_resources, @object +_lz_resources: .incbin "${PROJECT_BINARY_DIR}/data.lzp" #.global smd_mtekdisk diff --git a/examples/demos/n00bdemo/main.c b/examples/demos/n00bdemo/main.c index fcd38b8..ba21d88 100644 --- a/examples/demos/n00bdemo/main.c +++ b/examples/demos/n00bdemo/main.c @@ -85,11 +85,12 @@ void loadTextures() { Unpack textures from an embedded LZP archive and upload them to VRAM. */ int i; - int *tex_buff,*ttim,j; + int *ttim,j; + QLP_HEAD *tex_buff; TIM_IMAGE tim; i = lzpSearchFile( "textures", lz_resources ); - tex_buff = (int*)malloc( lzpFileSize( lz_resources, i ) ); + tex_buff = (QLP_HEAD*)malloc( lzpFileSize( lz_resources, i ) ); lzpUnpackFile( tex_buff, lz_resources, i ); @@ -148,6 +149,7 @@ void loadTextures() { font_tpage = getTPage( 0, 1, tim.prect->x, tim.prect->y )|0x200; font_clut = getClut( tim.crect->x, tim.crect->y ); + free( tex_buff ); } void unpackModels() { diff --git a/libpsn00b/cmake/internal_setup.cmake b/libpsn00b/cmake/internal_setup.cmake index e9423a4..e3d4be7 100644 --- a/libpsn00b/cmake/internal_setup.cmake +++ b/libpsn00b/cmake/internal_setup.cmake @@ -7,6 +7,9 @@ cmake_minimum_required(VERSION 3.21) include(GNUInstallDirs) +# IMPORTANT TODO: set a version number +set(PSN00BSDK_VERSION 0.1.0) + ## Settings (can be overridden by projects) set(PSN00BSDK_EXECUTABLE_SUFFIX ".exe") diff --git a/libpsn00b/include/lzp/lzp.h b/libpsn00b/include/lzp/lzp.h index ffd7933..cfeeb72 100644 --- a/libpsn00b/include/lzp/lzp.h +++ b/libpsn00b/include/lzp/lzp.h @@ -111,7 +111,7 @@ extern "C" { * * \returns The size of the compressed data in bytes. */ -int lzCompress(void* outBuff, void* inBuff, int inSize, int level); +int lzCompress(void* outBuff, const void* inBuff, int inSize, int level); /*! Decompress a compressed block of data. * @@ -130,9 +130,9 @@ int lzCompress(void* outBuff, void* inBuff, int inSize, int level); * \returns Size of decompressed data in bytes or LZP_ERR_DECOMPRESS if a * decompression error occurred. */ -int lzDecompress(void* outBuff, void* inBuff, int inSize); +int lzDecompress(void* outBuff, const void* inBuff, int inSize); -int lzDecompressLen(void* outBuff, int outSize, void* inBuff, int inSize); +int lzDecompressLen(void* outBuff, int outSize, const void* inBuff, int inSize); /*! Sets the sizes of hash tables for data compression. * @@ -162,7 +162,7 @@ void lzResetHashSizes(); * * \returns CRC16 hash of specified buffer. */ -unsigned short lzCRC16(void* buff, int bytes, unsigned short crc); +unsigned short lzCRC16(const void* buff, int bytes, unsigned short crc); /*! Calculates a CRC32 hash of the specified buffer. * @@ -172,7 +172,7 @@ unsigned short lzCRC16(void* buff, int bytes, unsigned short crc); * * \returns CRC32 hash of specified buffer. */ -unsigned int lzCRC32(void* buff, int bytes, unsigned int crc); +unsigned int lzCRC32(const void* buff, int bytes, unsigned int crc); /*! @} */ @@ -189,9 +189,9 @@ unsigned int lzCRC32(void* buff, int bytes, unsigned int crc); * * \returns File index of found file or one of \ref libraryErrorCodes if an error occurred. */ -int lzpSearchFile(const char* fileName, void* lzpack); +int lzpSearchFile(const char* fileName, const LZP_HEAD* lzpack); -int lzpFileSize(void* lzpack, int fileNum); +int lzpFileSize(const LZP_HEAD* lzpack, int fileNum); /*! Get a pointer to a file entry inside of an LZP archive. * @@ -200,7 +200,7 @@ int lzpFileSize(void* lzpack, int fileNum); * * \returns A pointer to an LZP_FILE struct or NULL if an error occurred. */ -LZP_FILE* lzpFileEntry(void* lzpack, int fileNum); +const LZP_FILE* lzpFileEntry(const LZP_HEAD* lzpack, int fileNum); /*! Unpacks a file from an LZP archive to the specified memory buffer. * @@ -210,7 +210,7 @@ LZP_FILE* lzpFileEntry(void* lzpack, int fileNum); * * \returns Size of decompressed file in bytes or one of \ref libraryErrorCodes if an error occurred. */ -int lzpUnpackFile(void* buff, void* lzpack, int fileNum); +int lzpUnpackFile(void* buff, const LZP_HEAD* lzpack, int fileNum); /*! @} */ diff --git a/libpsn00b/include/lzp/lzqlp.h b/libpsn00b/include/lzp/lzqlp.h index fae6438..5b70b40 100644 --- a/libpsn00b/include/lzp/lzqlp.h +++ b/libpsn00b/include/lzp/lzqlp.h @@ -1,6 +1,11 @@ #ifndef _QLP_H #define _QLP_H +#include +#ifdef _WIN32 +#include +#endif + #define PACK_ERR_NONE 0 #define PACK_ERR_INVALID -1 #define PACK_ERR_NOTFOUND -2 @@ -8,19 +13,19 @@ #define PACK_ERR_READ_FAULT -4 typedef struct { - char id[3]; - unsigned char numfiles; + char id[3]; + u_char numfiles; } QLP_HEAD; typedef struct { - char name[16]; - unsigned int size; - unsigned int offs; + char name[16]; + u_int size; + u_int offs; } QLP_FILE; -int qlpFileCount(void* qlpfile); -QLP_FILE* qlpFileEntry(int index, void* qlpfile); -void* qlpFileAddr(int index, void* qlpfile); -int qlpFindFile(char* fileName, void* qlpfile); +int qlpFileCount(const QLP_HEAD* qlpfile); +const QLP_FILE* qlpFileEntry(int index, const QLP_HEAD* qlpfile); +const void* qlpFileAddr(int index, const QLP_HEAD* qlpfile); +int qlpFindFile(char* fileName, const QLP_HEAD* qlpfile); #endif // _QLP_H \ No newline at end of file diff --git a/libpsn00b/lzp/bit.c b/libpsn00b/lzp/bit.c index aefa45d..9678357 100644 --- a/libpsn00b/lzp/bit.c +++ b/libpsn00b/lzp/bit.c @@ -3,7 +3,7 @@ // Bit I/O // -unsigned char* inPtr = 0; +const unsigned char* inPtr = 0; int inBytes = 0; unsigned char* outPtr = 0; int outBytes = 0; diff --git a/libpsn00b/lzp/bit.h b/libpsn00b/lzp/bit.h index ff71025..321160a 100644 --- a/libpsn00b/lzp/bit.h +++ b/libpsn00b/lzp/bit.h @@ -1,7 +1,7 @@ #ifndef _LZP_BIT_H #define _LZP_BIT_H -extern unsigned char* inPtr; +extern const unsigned char* inPtr; extern int inBytes; extern unsigned char* outPtr; extern int outBytes; diff --git a/libpsn00b/lzp/crc.c b/libpsn00b/lzp/crc.c index 7cc7bf3..3c1ae57 100644 --- a/libpsn00b/lzp/crc.c +++ b/libpsn00b/lzp/crc.c @@ -73,9 +73,9 @@ unsigned short lzCRC16(const void* buff, int bytes, unsigned short crc) { unsigned int lzCRC32(const void* buff, int bytes, unsigned int crc) { int i; - unsigned char* byteBuff = (const unsigned char*)buff; - unsigned int byte; - unsigned int crcTable[256]; + const unsigned char* byteBuff = (const unsigned char*)buff; + unsigned int byte; + unsigned int crcTable[256]; initTable32(crcTable); diff --git a/tools/lzpack/main.cpp b/tools/lzpack/main.cpp index f684d18..506b76c 100644 --- a/tools/lzpack/main.cpp +++ b/tools/lzpack/main.cpp @@ -178,7 +178,7 @@ int CreateLZPfile(const char* packFile, FileListClass* fileList) { printf("ERROR: Entry '%s' has more than 15 characters.\n", name); fclose(packp); unlink(packFile); - delete entry; + delete[] entry; return(0); @@ -216,8 +216,8 @@ int CreateLZPfile(const char* packFile, FileListClass* fileList) { fwrite(compBuff, compSize, 1, packp); - delete compBuff; - delete fileBuff; + delete[] compBuff; + delete[] fileBuff; printf("Ok. (%.02f%%)\n", 100.f*((float)compSize/fileSize)); @@ -238,7 +238,7 @@ int CreateLZPfile(const char* packFile, FileListClass* fileList) { fwrite(entry, sizeof(LZP_FILE), fileList->EntryCount(), packp); fclose(packp); - delete entry; + delete[] entry; printf("Packed %d file(s) totaling %d bytes (%.02f%% compression ratio).\n", fileList->EntryCount(), @@ -285,7 +285,7 @@ int CreateQLPfile(const char* packFile, FileListClass* fileList) { printf("ERROR: Entry '%s' has more than 15 characters.\n", name); fclose(packp); unlink(packFile); - delete fileEntry; + delete[] fileEntry; return(0); @@ -328,7 +328,7 @@ int CreateQLPfile(const char* packFile, FileListClass* fileList) { } - delete copyBuff; + delete[] copyBuff; fclose(fp); fileEntry[i].fileSize = bytesCopied; @@ -345,7 +345,7 @@ int CreateQLPfile(const char* packFile, FileListClass* fileList) { fwrite(fileEntry, sizeof(QLP_FILE), head.numFiles, packp); fclose(packp); - delete fileEntry; + delete[] fileEntry; return(true); @@ -417,7 +417,7 @@ int CreatePCKfile(const char* packFile, FileListClass* fileList) { } fclose(fp); - delete buff; + delete[] buff; toc.file[i].size = bytesTotal; @@ -428,7 +428,7 @@ int CreatePCKfile(const char* packFile, FileListClass* fileList) { memset(padding, 0x00, pad); fwrite(padding, pad, 1, packp); - delete padding; + delete[] padding; } printf("Done.\n"); -- cgit v1.2.3