### Add Simple Test with Resources

Source: https://github.com/vector-of-bool/cmrc/blob/master/tests/CMakeLists.txt

Example of using cmrc_add_test to define a test named 'simple' with a pass regex and multiple resources, including nested paths.

```cmake
cmrc_add_test(
    NAME simple
    PASS_REGEX "^Hello, world!"
    RESOURCES
        hello.txt
        # Resources not used by the test, but just make sure we get no compilation
        # errors with the more complex paths:
        subdir_a/subdir_b/file_a.txt
        subdir_a/subdir_b/file_b.txt
    )
```

--------------------------------

### Add Test for Iterating Over Multiple Resources

Source: https://github.com/vector-of-bool/cmrc/blob/master/tests/CMakeLists.txt

Example of a test named 'iterate' designed to check output when processing multiple resources from a subdirectory.

```cmake
cmrc_add_test(
    NAME iterate
    PASS_REGEX "^subdir_a\nfile_a.txt\nfile_b.txt\n$"
    RESOURCES
        subdir_a/subdir_b/file_a.txt
        subdir_a/subdir_b/file_b.txt
    )
```

--------------------------------

### Get Filesystem Handle

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

Call get_filesystem() within the generated namespace (e.g., cmrc::foo::get_filesystem()) to obtain a handle to the embedded resource filesystem. This function is declared by the CMRC_DECLARE macro.

```cpp
int main() {
    auto fs = cmrc::foo::get_filesystem();
}
```

--------------------------------

### Add a Resource Library

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

Use this command to create a resource library from a list of files. The ALIAS argument is recommended for easier linking.

```cmake
cmrc_add_resource_library(foo-resources ...)
```

```cmake
cmrc_add_resource_library(foo-resources ALIAS foo::rc ...)
```

--------------------------------

### Add Resource Library with WHENCE and PREFIX Options

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

This CMake code demonstrates how to add a resource library with custom path rewriting using WHENCE and PREFIX. WHENCE specifies the source directory for resources, and PREFIX prepends a path to the resource in the compiled binary.

```cmake
cmrc_add_resource_library(
    flower-images
    NAMESPACE flower
    WHENCE images
    PREFIX flowers
    images/rose.jpg
    images/tulip.jpg
    images/daisy.jpg
    images/sunflower.jpg
    )
```

--------------------------------

### Accessing Resources with Custom Paths

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

This C++ code shows how to access a resource that has been added with a custom PREFIX. The 'open' function uses the prefixed path to retrieve the file.

```cpp
int foo() {
    auto fs = cmrc::flower::get_filesystem();
    auto rose = fs.open("flowers/rose.jpg");
}
```

--------------------------------

### Add Test with WHENCE and PREFIX

Source: https://github.com/vector-of-bool/cmrc/blob/master/tests/CMakeLists.txt

Combines WHENCE and PREFIX arguments to define resource origin and a custom prefix for the 'whence_prefix' test.

```cmake
cmrc_add_test(
    NAME whence_prefix
    PASS_REGEX "^I am a file!"
    RESOURCES subdir_a/subdir_b/file_b.txt
    WHENCE subdir_a
    PREFIX imaginary-prefix/
    )
```

--------------------------------

### Add Test with Specific Resource Origin (WHENCE)

Source: https://github.com/vector-of-bool/cmrc/blob/master/tests/CMakeLists.txt

Illustrates using the WHENCE argument to specify a subdirectory as the origin for resources in the 'whence' test.

```cmake
cmrc_add_test(
    NAME whence
    PASS_REGEX "^I am a file!"
    RESOURCES subdir_a/subdir_b/file_a.txt
    WHENCE subdir_a
    )
```

--------------------------------

### Add Test with Image Resource and Test Argument

Source: https://github.com/vector-of-bool/cmrc/blob/master/tests/CMakeLists.txt

Demonstrates adding a test named 'flower' that includes an image resource and passes the resource path as a test argument.

```cmake
cmrc_add_test(
    NAME flower
    RESOURCES flower.jpg
    TEST_ARGV "${CMAKE_CURRENT_SOURCE_DIR}/flower.jpg"
    )
```

--------------------------------

### Link Resource Library to Executable

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

Link the generated resource library target to your executable using target_link_libraries.

```cmake
add_executable(my-program main.cpp)
target_link_libraries(my-program PRIVATE foo::rc)
```

--------------------------------

### cmrc::embedded_filesystem Methods

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

Provides methods to interact with the embedded filesystem, such as opening files, checking existence, and iterating directories.

```APIDOC
## cmrc::embedded_filesystem

### Description

Acts as a handle to statically allocated resource library data. It is trivially copyable and destructible.

### Methods

- **open**(const std::string& path) -> cmrc::file
  - Opens and returns a non-directory `file` object at `path`.
  - Throws `std::system_error()` on error.

- **is_file**(const std::string& path) -> bool
  - Returns `true` if the given `path` names a regular file, `false` otherwise.

- **is_directory**(const std::string& path) -> bool
  - Returns `true` if the given `path` names a directory, `false` otherwise.

- **exists**(const std::string& path) -> bool
  - Returns `true` if the given path names an existing file or directory, `false` otherwise.

- **iterate_directory**(const std::string& path) -> cmrc::directory_iterator
  - Returns a directory iterator for iterating the contents of a directory.
  - Throws if the given `path` does not identify a directory.
```

--------------------------------

### Add Test with Custom Prefix for Resources

Source: https://github.com/vector-of-bool/cmrc/blob/master/tests/CMakeLists.txt

Shows how to use the PREFIX argument in cmrc_add_test to prepend a custom string to resource paths for the 'prefix' test.

```cmake
cmrc_add_test(
    NAME prefix
    PASS_REGEX "^Hello, world!"
    RESOURCES hello.txt
    PREFIX some-prefix
    )
```

--------------------------------

### Add Resource Library with Namespace

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

Specify a custom namespace for the resource library if the library target name is not a valid C++ namespace identifier.

```cmake
cmrc_add_resource_library(foo-resources ALIAS foo::rc NAMESPACE foo  ...)
```

--------------------------------

### Add Failing Test Case

Source: https://github.com/vector-of-bool/cmrc/blob/master/tests/CMakeLists.txt

Demonstrates how to mark a test as expected to fail using the WILL_FAIL option in cmrc_add_test for the 'enoent' test.

```cmake
cmrc_add_test(
    NAME enoent
    WILL_FAIL
    )
```

--------------------------------

### Define cmrc_add_test CMake Function

Source: https://github.com/vector-of-bool/cmrc/blob/master/tests/CMakeLists.txt

This snippet defines the cmrc_add_test function, which parses arguments for test configuration, adds executables, links resources, and sets up test properties.

```cmake
function(cmrc_add_test)
    set(options WILL_FAIL)
    set(args NAME PASS_REGEX WHENCE PREFIX)
    set(list_args RESOURCES TEST_ARGV)
    set(unparsed_args)
    cmake_parse_arguments(PARSE_ARGV 0 ARG "${options}" "${args}" "${list_args}" "${unparsed_args}")

    if(DEFINED ARG_WHENCE)
        set(whence_arg WHENCE "${ARG_WHENCE}")
    endif()
    if(DEFINED ARG_PREFIX)
        set(prefix_arg PREFIX "${ARG_PREFIX}")
    endif()

    add_executable("${ARG_NAME}" "${ARG_NAME}.cpp")
    cmrc_add_resource_library(rc_${ARG_NAME} NAMESPACE "${ARG_NAME}" ${whence_arg} ${prefix_arg} ${ARG_RESOURCES})
    target_link_libraries("${ARG_NAME}" PRIVATE rc_${ARG_NAME})
    add_test("${ARG_NAME}" "${ARG_NAME}" ${ARG_TEST_ARGV})
    if(DEFINED ARG_PASS_REGEX)
        set_property(
            TEST "${ARG_NAME}"
            PROPERTY PASS_REGULAR_EXPRESSION "${ARG_PASS_REGEX}"
            )
    endif()
    if(ARG_UNPARSED_ARGUMENTS)
        message(WARNING "Invalid test arguments: ${ARG_UNPARSED_ARGUMENTS}")
    endif()
    set_property(TEST "${ARG_NAME}" PROPERTY WILL_FAIL "${ARG_WILL_FAIL}")
endfunction()
```

--------------------------------

### Declare Resource Namespace in C++

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

Use the CMRC_DECLARE macro in your .cpp file at global scope to declare the namespace for the resource library. Use the library name if no namespace was specified.

```cpp
#include <cmrc/cmrc.hpp>

CMRC_DECLARE(foo);

int main() {
    // ...
}
```

--------------------------------

### cmrc::directory_iterator Members

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

Defines the members and iterator semantics for cmrc::directory_iterator, used to traverse directory contents.

```APIDOC
## cmrc::directory_iterator

### Description

An iterator for traversing the contents of a directory within the embedded filesystem.

### Members

- **value_type**
  - Type: `cmrc::directory_entry`

- **iterator_category**
  - Type: `std::input_iterator_tag`

- **directory_iterator()**
  - Default constructor.

- **begin()** -> directory_iterator
  - Returns `*this`.

- **end()** -> directory_iterator
  - Returns a past-the-end iterator corresponding to this iterator.

- **operator*()** -> value_type
  - Returns the `directory_entry` for which the iterator corresponds.

- **operator==, operator!=, operator++**
  - Implement standard iterator semantics.
```

--------------------------------

### Include cmrc Header in C++

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

Include the cmrc/cmrc.hpp header in your C++ source files to access embedded resources. This header becomes available to targets linked to a resource library.

```cpp
#include <cmrc/cmrc.hpp>

int main() {
    // ...
}
```

--------------------------------

### cmrc::file Members

Source: https://github.com/vector-of-bool/cmrc/blob/master/README.md

Details the members and iterator types for the cmrc::file object, used to represent files within the embedded filesystem.

```APIDOC
## cmrc::file

### Description

Represents a file within the embedded filesystem.

### Members

- **iterator** and **const_iterator**
  - Type: `const char*`
  - Provide iterators to the resource data.

- **begin() / cbegin()** -> iterator
  - Returns an iterator to the beginning of the resource.

- **end() / cend()** -> iterator
  - Returns an iterator past the end of the resource.

- **file()**
  - Default constructor, refers to no resource.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.