Add psn00bsdk_target_incbin() CMake function

1 files changed, 29 insertions, 3 deletions

diff --git a/doc/cmake_reference.md b/doc/cmake_reference.md
index 3c89da3..60c46c0 100644
--- a/doc/cmake_reference.md
+++ b/doc/cmake_reference.md
@@ -102,13 +102,14 @@ of these names.
   As with executables, the `.dll` extension can be customized by setting
   `PSN00BSDK_SHARED_LIBRARY_SUFFIX`.
 
-- `psn00bsdk_add_cd_image(<name> <image name> <config file> [...])`
+- `psn00bsdk_add_cd_image(<name> <image name> <config file> [DEPENDS ...] [...])`
 
   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 (`<image name>.bin` + `<image name>.cue`). The
-  third argument is the path to the XML file passed to `mkpsxiso`.
+  third argument is the path to the XML file (relative to the source directory)
+  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
@@ -126,7 +127,32 @@ of these names.
 
   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.
+  `add_custom_target()` (including `DEPENDS`) are also supported here.
+
+- `psn00bsdk_target_incbin(<target> <PRIVATE|PUBLIC|INTERFACE> <symbol name> <binary file>)`
+
+  Embeds the contents of a binary file into an executable or a library.
+
+  A new symbol/object will be created with the given name, escaped by replacing
+  non-alphanumeric characters with underscores. The contents of the file will
+  be aligned to 4 bytes and placed in the `.data` section. Once added the file
+  and its size can be accessed by C/C++ code by declaring the symbol as an
+  extern array and `<symbol name>_size` as an integer, like this:
+
+  ```c
+  extern const uint8_t my_file[];
+  extern const size_t  my_file_size;
+  ```
+
+  The fourth argument specifies the path to the binary file relative to the
+  source directory. This path can be prepended with `${PROJECT_BINARY_DIR}/` to
+  reference a file generated by the build script (such as an LZP archive): in
+  that case a file-level dependency will also be created, ensuring CMake does
+  not attempt to compile the executable or library before the file is built.
+
+  **IMPORTANT**: in order for this command to work, assembly language support
+  must be enabled by specifying `LANGUAGES C ASM` (or `LANGUAGES C CXX ASM` if
+  C++ is also used) when invoking `project()`.
 
 ## Definitions