{"id":18002949,"url":"https://github.com/achirkin/vulkan","last_synced_at":"2025-03-26T08:31:21.432Z","repository":{"id":53132069,"uuid":"116285484","full_name":"achirkin/vulkan","owner":"achirkin","description":"Low-level low-overhead haskell bindings to vulkan API","archived":false,"fork":false,"pushed_at":"2021-04-05T13:33:31.000Z","size":6132,"stargazers_count":64,"open_issues_count":12,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-21T12:22:12.702Z","etag":null,"topics":["graphics","haskell","haskell-library","vulkan","vulkan-api"],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/achirkin.png","metadata":{"files":{"readme":"README-macOS.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-04T16:58:40.000Z","updated_at":"2025-03-07T13:16:10.000Z","dependencies_parsed_at":"2022-08-25T14:40:51.396Z","dependency_job_id":null,"html_url":"https://github.com/achirkin/vulkan","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/achirkin%2Fvulkan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/achirkin%2Fvulkan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/achirkin%2Fvulkan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/achirkin%2Fvulkan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/achirkin","download_url":"https://codeload.github.com/achirkin/vulkan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245618763,"owners_count":20645064,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graphics","haskell","haskell-library","vulkan","vulkan-api"],"created_at":"2024-10-29T23:24:41.761Z","updated_at":"2025-03-26T08:31:20.367Z","avatar_url":"https://github.com/achirkin.png","language":"Haskell","readme":"# Getting started with Vulkan on macOS using Haskell\n\nThis is for the [vulkan-api](https://github.com/achirkin/vulkan) Haskell library.\nThere is another vulkan library for Haskell, see the README of vulkan-api for differences.\nInstructions tested with cabal v2-commands, not yet with stack.\n\n## Installing Vulkan SDK\n\nRegarding SDK documentation, go by\n[Getting Started with the Vulkan SDK (mac)](https://vulkan.lunarg.com/doc/sdk/latest/mac/getting_started.html) rather than\n[MoltenVK Runtime User Guide](https://github.com/KhronosGroup/MoltenVK/blob/master/Docs/MoltenVK_Runtime_UserGuide.md).\nThe latter one describes linking against MoltenVK directly (libMoltenVK.dylib) instead of the Vulkan loader (libvulkan.1.dylib),\nwhich doesn't yield a full Vulkan implementation.\nAdditional Information can be found in\n[Architecture of the Vulkan Loader Interfaces](https://vulkan.lunarg.com/doc/view/latest/windows/loader_and_layer_interface.html).\n\nWhile the SDK documentation claims it can't be installed, I recommend the following steps to make development easier:\n\n### Option 1, tested\n\n    cd ~\n    tar xzf Downloads/vulkan-sdk.tar.gz\n    # otherwise Gatekeeper prevents loading the lib because it was downloaded but is not signed:\n    sudo xattr -r -d com.apple.quarantine ~/vulkansdk-macos-1.2.131.2\n    cd vulkansdk-macos-1.2.131.2/macOS\n    mkdir ~/.local/lib\n    cp -a lib/*.dylib ~/.local/lib\n    mkdir ~/.local/share/vulkan\n    cp -a etc/vulkan/* ~/.local/share/vulkan\n    cp -a bin/* ~/bin\n\nMake sure $HOME/bin is on your path, or use another location.\n\nThe Vulkan loader searches for ICDs (installable client drivers) and layers in certain OS-specific locations, including\n~/.local/share/vulkan/icd.d and ~/.local/share/vulkan/explicit_layer.d respectively.\nThe layer search paths are described\n[here](https://vulkan.lunarg.com/doc/view/latest/mac/loader_and_layer_interface.html#user-content-macos-layer-discovery),\nICD search paths\n[here](https://vulkan.lunarg.com/doc/view/latest/mac/loader_and_layer_interface.html#user-content-icd-discovery-on-macos).\n\nMoltenVK is an ICD and is mandatory on macOS and iOS. It implements Vulkan via the Metal API, because Apple doesn't support Vulkan,\nso make sure the Vulkan loader can find MoltenVK.\n\n### Option 2, untested\n\n    cd ~\n    tar xzf Downloads/vulkan-sdk.tar.gz\n    # otherwise Gatekeeper prevents loading the lib because it was downloaded but is not signed:\n    sudo xattr -r -d com.apple.quarantine ~/vulkansdk-macos-1.2.131.2\n\nWhen developing:\n\n    VULKAN_SDK=\"${HOME}/vulkansdk-macos-1.2.131.2/macOS\"\n    export VK_LAYER_PATH=\"${VULKAN_SDK}/etc/vulkan/explicit_layer.d\"\n    export VK_ICD_FILENAMES=\"${VULKAN_SDK}/etc/vulkan/icd.d/MoltenVK_icd.json\"\n    export PATH=\"${VULKAN_SDK}/bin:${PATH}\"\n    ln -s ${VULKAN_SDK}/lib/libvulkan.1.dylib .\n\nRegarding the last line, see remarks about linking and dlopen below.\n\n### Workaround for compile-time linking vulkan-api\n\nThe cabal-install-option `--constraint=\"vulkan-api +useNativeFFI-1-1\"` enables compile-time linking of the Vulkan loader in vulkan-api.\nThis is not static linking, but linking via ld as opposed to dlopen at runtime.\nYou probably also need `--extra-lib-dirs $VULKAN_SDK/lib` for cabal to find the dylib file when doing this.\n\nAs of cabal version 2.4.1.0, cabal doesn't seem to respect DYLD_LIBRARY_PATH or `extra-libraries: vulkan` when linking the executables generated\nvia hsc2hs that are executed during compile time. The install name of `libvulkan.1.dylib` is `@rpath/libvulkan.1.dylib`, this is\nin the metadata of `libvulkan.1.dylib`. Because of that, the executables search for the library in `@rpath` only, which doesn't work.\nThe executables don't have any @rpath entries, and even if they had, @rpath is relative to the executable path, and the executables\nare generated in various build directories.\nIt can be worked around by changing the install name of the file to an absolute path (assuming $VULKAN_SDK is absolute as above):\n\n    install_name_tool -id \"${VULKAN_SDK}/lib/libvulkan.1.dylib\" \"${VULKAN_SDK}/lib/libvulkan.1.dylib\"\n\nYou don't need to do this if you use vulkan-api without the useNativeFFI-1-1 or useNativeFFI-1-0 flag.\n\n## Using GLFW and/or using vulkan-api without compile-time linking\n\nBefore launching Haskell programs that use the Haskell library bindings-GLFW\n(usually via the higher-level GLFW binding GLFW-b) and/or using vulkan-api\nwithout compile-time linking agaist Vulkan (which is the default), you need to\nmake sure that the Vulkan loader from the SDK (`libvulkan.1.dylib`) can be found\nby dlopen (see `man dlopen`).\n\nNote that bindings-GLFW doesn't do compile time linking against the Vulkan\nloader at the time of writing (version 3.3.1.0). It will dlopen the lib at\nruntime even if vulkan-api is compile-time linked against Vulkan.\n\nThere are no configuration files to control dlopen searching on macOS. Using\nenvironment variables does also not work reliably because of security\nrestrictions in recent versions of macOS. `dlopen` searches for library files in\nthe current working directory, if that fails it searches in `$HOME/lib`,\n`/usr/local/lib`, and `/usr/lib` (searching for frameworks is handled\ndifferently).\n\nIf you linked the Vulkan loader to `~/.local/lib` as described in the install\nsection, it's probably a good idea to unify `~/.local/lib` with `~/lib` by\nmaking one of them a symlink to the other one, for example:\n\n    mv ~/lib/* ~/.local/lib\n    rmdir ~/lib\n    ln -s ~/.local/lib ~/lib\n\nAlternatively, just make the Vulkan loader available in the working directory\nwhere the executable is launched, for example:\n\n    ln -s ~/.local/lib/libvulkan.1.dylib .\n\n## Pitfalls\n\nBe aware that GLFW and vulkan-api both need a dynamic library that implements Vulkan.\nThe recommended versions all use `libvulkan.1.dylib`. Older versions might use `libMoltenVK.dylib` or even do static linking.\nMake sure that GLFW and vulkan-api use the same library file, otherwise\n[bad things](https://github.com/achirkin/vulkan/issues/24) will happen.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fachirkin%2Fvulkan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fachirkin%2Fvulkan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fachirkin%2Fvulkan/lists"}