organicmaps/CMake-MetalShaderSupport
13
Fork 0
mirror of https://github.com/dpogue/CMake-MetalShaderSupport.git synced 2025-04-04 13:05:06 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions

Update README to refer to MetalShaderSupport module

Browse source
This commit is contained in:
Darryl Pogue 2024-06-02 02:06:04 -07:00
parent 6594c420e2
commit 49220f7dfa
No known key found for this signature in database
GPG key ID: CB824715C3E6FD41
1 changed files with 47 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
README.md
View file

@ -3,6 +3,7 @@
This project aims to allow compiling, linking, and embedding Apple Metal shader libraries in projects using CMake, without the need to write custom build steps or be restricted to only using the Xcode project generator.
The **MetalShaderSupport** module provides helper functions to create Metal shader library targets and embed shaders within application bundles.
Project Setup
-------------
@ -14,6 +15,8 @@ Project Setup
```cmake
# In the top-level CMakeLists.txt file for your project:
set(CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH};${CMAKE_SOURCE_DIR}/cmake")
include(MetalShaderSupport)
```
3. Enable the Metal language for your project:
@ -45,16 +48,27 @@ Shader Library Setup
> **Shaders must be in their own CMake target!**
> You cannot mix them with C++ or Objective-C code sources in a library or executable target.
Your final shader library will need to be a `.metallib` file that can be included in your application as a resource. You should define these as `MODULE` libraries rather than `SHARED` libraries because they do not expose symbols that can be linked with other targets.
Your final shader library will need to be a `.metallib` file that can be included in your application as a resource. Use the `add_metal_shader_library` function (from the MetalShaderSupport module) to set up the library target containing your shader sources:
```cmake
add_library(shaders MODULE
add_metal_shader_library(MyShaders
shader1.metal
shader2.metal
)
```
<details>
<summary><h3>Implementation Details</h3></summary>
The `add_metal_shader_library` helper creates a `MODULE` library containing the sources, and also sets up some Xcode-specific properties to ensure everything works with the Xcode project generator. Effectively, it implements the following:
```cmake
add_library(MyShaders MODULE
shader1.metal
shader2.metal
)
# To make it work properly in Xcode with the Xcode project generator:
set_target_properties(shaders PROPERTIES
set_target_properties(MyShaders PROPERTIES
XCODE_PRODUCT_TYPE com.apple.product-type.metal-library
XCODE_ATTRIBUTE_MTL_FAST_MATH "YES"
XCODE_ATTRIBUTE_MTL_ENABLE_DEBUG_INFO[variant=Debug] "INCLUDE_SOURCE"
@ -62,41 +76,46 @@ set_target_properties(shaders PROPERTIES
)
```
</details>
Embedding Shaders
-----------------
As a final step to make your shader library available to your application, you will need to ensure that it gets embedded as a resource.
As a final step to make your shader library available to your application, you will need to ensure that it gets embedded as a resource. Use the `target_embed_metal_shader_libraries` function (from the MetalShaderSupport module) to list the shader targets to be included as resources.
1. First, you need to ensure that the shader library itself is built as a dependency of the application target.
```cmake
add_executable(MyApp MACOSX_BUNDLE)
```cmake
add_executable(MyApp MACOSX_BUNDLE)
target_embed_metal_shader_libraries(MyApp
MyShaders
)
```
add_dependencies(MyApp
shaders
)
```
<details>
<summary><h3>Implementation Details</h3></summary>
2. Then you'll need to include the shader libraries as resources:
The `target_embed_metal_shader_libraries` helper adds the shader library as a dependency of the target executable, and tells CMake to ensure each shader target's `.metallib` is included in the application bundle as a resource.
If you are using CMake 3.28 or newer with the Xcode generator, you can refer to the shader targets directly:
If you are using CMake 3.28 or newer with the Xcode generator, the shader targets can be referred to directly:
```cmake
set_target_properties(MyApp PROPERTIES
XCODE_EMBED_RESOURCES shaders
)
```
```cmake
set_target_properties(MyApp PROPERTIES
XCODE_EMBED_RESOURCES MyShaders
)
```
Otherwise, you'll need a custom post-build step to copy the resulting `.metallib` into the Resources folder of the target app bundle.
Otherwise, a custom post-build step is used to copy the resulting `.metallib` into the Resources folder of the target app bundle.
```cmake
add_custom_command(TARGET MyApp POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy "$<TARGET_FILE:shaders>" "$<TARGET_BUNDLE_CONTENT_DIR:MyApp>/Resources/$<TARGET_FILE_NAME:shaders>"
VERBATIM
)
```
```cmake
add_custom_command(TARGET MyApp POST_BUILD
DEPENDS MyShaders
COMMAND ${CMAKE_COMMAND} -E copy "$<TARGET_FILE:MyShaders>" "$<TARGET_BUNDLE_CONTENT_DIR:MyApp>/Resources/$<TARGET_FILE_NAME:MyShaders>"
VERBATIM
)
```
</details>
Remaining Work
@ -109,7 +128,8 @@ Remaining Work
Licence
-------
CMake files are distributed under the OSI-approved BSD 3-clause License. See [LICENCE.txt][1] for details.
CMake files are distributed under the OSI-approved BSD 3-clause License. See [LICENCE.txt][1] for details.
Copyright © 2024 Darryl Pogue and Contributors.
The example project is based on sample code from Apple, under its own licence. See [LICENSE.txt][2] in the example folder for details.