feat: add RECURSE option for subdirectory scanning

Author: ronan-fesselier

CHANGELOG.md

@@ -4,11 +4,14 @@
 
 ### Added
 
-- NIL
+- `RECURSE` option for `nfx_embed_resources()` to enable recursive subdirectory scanning
+- Automatic relative path preservation for resources in subdirectories when `RECURSE` is enabled
+- Optional 4th parameter for resource generator CLI to specify custom resource names
 
 ### Changed
 
-- NIL
+- Resource naming: with `RECURSE`, resources now use relative paths (e.g., `"shaders/vertex.glsl"`) instead of just filenames
+- Pattern handling: `RECURSE` mode uses `**` glob patterns to properly match files in subdirectories
 
 ### Deprecated
 

README.md

@@ -320,6 +320,7 @@ nfx_embed_resources(
     NAMESPACE <namespace>
     REGISTRY_NAME <registry_name>
     [PATTERN pattern1 pattern2 ...]
+    [RECURSE]
 )
 ```
 
@@ -330,6 +331,7 @@ nfx_embed_resources(
 - `NAMESPACE` - C++ namespace (supports nested namespaces like `my::app::resources`)
 - `REGISTRY_NAME` - Name for generated files (creates `<name>.h` and `<name>.cpp`)
 - `PATTERN` - Optional file glob patterns (default: `*` for all files)
+- `RECURSE` - Optional flag to enable recursive subdirectory scanning
 
 **Generated Functions:**
 
@@ -359,12 +361,37 @@ nfx_embed_resources(
 ```
 
 This will:
-1. Scan `${CMAKE_SOURCE_DIR}/assets` for files matching the patterns
+1. Scan `${CMAKE_SOURCE_DIR}/assets` for files matching the patterns (current directory only)
 2. Generate `assets.h` and `assets.cpp` in `${CMAKE_BINARY_DIR}/generated`
 3. Create `myapp::assets::all()` and `myapp::assets::find()` functions
 4. Add generated files to the `myapp` target
 5. Include directory automatically added so you can `#include <assets.h>`
 
+**Example with Recursive Scanning:**
+
+```cmake
+nfx_embed_resources(
+    TARGET myapp
+    RESOURCE_DIR "${CMAKE_SOURCE_DIR}/assets"
+    OUTPUT_DIR "${CMAKE_BINARY_DIR}/generated"
+    NAMESPACE "myapp::assets"
+    REGISTRY_NAME "assets"
+    PATTERN "*.json" "*.xml" "*.png"
+    RECURSE  # Scan subdirectories recursively
+)
+```
+
+With `RECURSE`, resources in subdirectories are named with their relative paths:
+- `assets/config.json` → resource name: `"config.json"`
+- `assets/shaders/vertex.glsl` → resource name: `"shaders/vertex.glsl"`
+- `assets/textures/ui/icon.png` → resource name: `"textures/ui/icon.png"`
+
+```cpp
+// Find resources by their relative paths
+auto* shader = myapp::assets::find("shaders/vertex.glsl");
+auto* icon = myapp::assets::find("textures/ui/icon.png");
+```
+
 ## Project Structure
 
 ```
@@ -466,13 +493,17 @@ nfx_embed_resources(
     NAMESPACE "myapp::shaders"
     REGISTRY_NAME "shaders"
     PATTERN "*.glsl" "*.hlsl"
+    RECURSE  # Include shaders from subdirectories
 )
 ```
 
 Then include the appropriate headers:
 ```cpp
 #include <config.h>   // Includes nfx::Resource, provides myapp::config::find()
 #include <shaders.h>  // Includes nfx::Resource, provides myapp::shaders::find()
+
+// Access shader with subdirectory path
+auto* vertShader = myapp::shaders::find("pbr/vertex.glsl");
 ```
 
 ### Custom Resource Registry
@@ -515,4 +546,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-_Updated on January 22, 2026_
+_Updated on January 25, 2026_

cmake/nfxResourceFunctions.cmake

@@ -6,7 +6,7 @@ function(nfx_embed_resources)
     cmake_parse_arguments(
         PARSE_ARGV 0
         ARG
-        ""
+        "RECURSE"
         "TARGET;RESOURCE_DIR;OUTPUT_DIR;NAMESPACE;REGISTRY_NAME"
         "PATTERN"
     )
@@ -36,10 +36,20 @@ function(nfx_embed_resources)
 
     set(GLOB_PATTERNS "")
     foreach(PATTERN ${FILE_PATTERN})
-        list(APPEND GLOB_PATTERNS "${ARG_RESOURCE_DIR}/${PATTERN}")
+        if(ARG_RECURSE)
+            # For recursive search, use ** to match subdirectories
+            list(APPEND GLOB_PATTERNS "${ARG_RESOURCE_DIR}/**/${PATTERN}")
+        else()
+            list(APPEND GLOB_PATTERNS "${ARG_RESOURCE_DIR}/${PATTERN}")
+        endif()
     endforeach()
 
-    file(GLOB RESOURCE_FILES CONFIGURE_DEPENDS ${GLOB_PATTERNS})
+    # Use GLOB_RECURSE if RECURSE option is set
+    if(ARG_RECURSE)
+        file(GLOB_RECURSE RESOURCE_FILES CONFIGURE_DEPENDS ${GLOB_PATTERNS})
+    else()
+        file(GLOB RESOURCE_FILES CONFIGURE_DEPENDS ${GLOB_PATTERNS})
+    endif()
 
     if(NOT RESOURCE_FILES)
         message(WARNING "No resources found in ${ARG_RESOURCE_DIR} matching: ${FILE_PATTERN}")
@@ -52,13 +62,23 @@ function(nfx_embed_resources)
     set(ALL_IDS "")
 
     foreach(RESOURCE_FILE ${RESOURCE_FILES})
-        get_filename_component(RESOURCE_NAME "${RESOURCE_FILE}" NAME)
-        string(MAKE_C_IDENTIFIER "${RESOURCE_NAME}" RESOURCE_ID)
+        # Get resource name (relative path for RECURSE, just filename otherwise)
+        if(ARG_RECURSE)
+            file(RELATIVE_PATH RESOURCE_NAME "${ARG_RESOURCE_DIR}" "${RESOURCE_FILE}")
+            # Convert path separators to underscores for unique identifier
+            string(REPLACE "/" "_" RESOURCE_ID_BASE "${RESOURCE_NAME}")
+            string(MAKE_C_IDENTIFIER "${RESOURCE_ID_BASE}" RESOURCE_ID)
+        else()
+            get_filename_component(RESOURCE_NAME "${RESOURCE_FILE}" NAME)
+            string(MAKE_C_IDENTIFIER "${RESOURCE_NAME}" RESOURCE_ID)
+        endif()
+
         set(OUTPUT_CPP "${ARG_OUTPUT_DIR}/resource_${RESOURCE_ID}.cpp")
 
+        # Pass the resource name explicitly to maintain path information
         add_custom_command(
             OUTPUT "${OUTPUT_CPP}"
-            COMMAND $<TARGET_FILE:nfx-resourcegenerator-cli> "${RESOURCE_FILE}" "${OUTPUT_CPP}" "${ARG_NAMESPACE}"
+            COMMAND $<TARGET_FILE:nfx-resourcegenerator-cli> "${RESOURCE_FILE}" "${OUTPUT_CPP}" "${ARG_NAMESPACE}" "${RESOURCE_NAME}"
             DEPENDS "${RESOURCE_FILE}" nfx-resourcegenerator-cli
             COMMENT "Embedding: ${RESOURCE_NAME}"
             VERBATIM

cmake/nfxResourceTarget.cmake

@@ -12,7 +12,7 @@ add_executable(nfx-resourcegenerator-cli
 set_target_properties(nfx-resourcegenerator-cli PROPERTIES
     CXX_STANDARD 20
     CXX_STANDARD_REQUIRED ON
-    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin"
+    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/bin"
 )
 add_executable(nfx::resourcegen ALIAS nfx-resourcegenerator-cli)
 

src/resourcefenerator-cli.cpp

@@ -248,26 +248,28 @@ bool generateCppFile(
  *
  * @details This tool converts binary files into C++ source files containing
  *          byte arrays. The generated code is placed in a specified namespace.
- *          The identifier and filename are automatically derived from the input path.
+ *          The identifier is automatically derived from the input path, but
+ *          the resource name can be explicitly specified.
  *
- * @param argc Argument count (must be 4)
+ * @param argc Argument count (must be 4 or 5)
  * @param argv Command-line arguments:
- *             [1] input_file  - Path to the binary file to embed
- *             [2] output_cpp  - Path for the generated .cpp file
- *             [3] namespace   - C++ namespace for the generated code
+ *             [1] input_file   - Path to the binary file to embed
+ *             [2] output_cpp   - Path for the generated .cpp file
+ *             [3] namespace    - C++ namespace for the generated code
+ *             [4] resource_name (optional) - Name for the resource (defaults to filename)
  *
  * @return 0 on success, 1 on error
  *
  * Generated code structure:
  * - {identifier}_data: const uint8_t array containing the binary data
  * - {identifier}_size: const size_t containing the data size
- * - {identifier}_name: const char array containing the filename
+ * - {identifier}_name: const char array containing the resource name
  */
 int main( int argc, char* argv[] )
 {
-    if( argc != 4 )
+    if( argc != 4 && argc != 5 )
     {
-        std::cerr << "Usage: " << argv[0] << " <input_file> <output_cpp> <namespace>\n";
+        std::cerr << "Usage: " << argv[0] << " <input_file> <output_cpp> <namespace> [resource_name]\n";
         return 1;
     }
 
@@ -294,12 +296,13 @@ int main( int argc, char* argv[] )
         return 1;
     }
 
-    const std::string filename = inPath.filename().string();
-    const std::string identifier = makeIdentifier( filename );
+    // Use provided resource name or default to filename
+    const std::string resourceName = ( argc == 5 ) ? argv[4] : inPath.filename().string();
+    const std::string identifier = makeIdentifier( resourceName );
 
     if( !isValidIdentifier( identifier ) )
     {
-        std::cerr << "Error: Could not generate valid C++ identifier from filename: " << filename << "\n";
+        std::cerr << "Error: Could not generate valid C++ identifier from resource name: " << resourceName << "\n";
         return 1;
     }
 
@@ -309,7 +312,7 @@ int main( int argc, char* argv[] )
         return 1;
     }
 
-    if( !generateCppFile( outPath, identifier, filename, ns, data ) )
+    if( !generateCppFile( outPath, identifier, resourceName, ns, data ) )
     {
         return 1;
     }