{"id":13711109,"url":"https://github.com/floooh/sokol-zig","last_synced_at":"2025-04-08T09:09:38.725Z","repository":{"id":37575981,"uuid":"135613400","full_name":"floooh/sokol-zig","owner":"floooh","description":"Zig bindings for the sokol headers (https://github.com/floooh/sokol)","archived":false,"fork":false,"pushed_at":"2024-10-25T13:57:18.000Z","size":3531,"stargazers_count":371,"open_issues_count":11,"forks_count":49,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-29T17:31:26.093Z","etag":null,"topics":["crossplatform","sokol","zig","zig-package"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"zlib","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/floooh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-31T17:10:41.000Z","updated_at":"2024-10-27T13:13:26.000Z","dependencies_parsed_at":"2023-10-26T19:27:37.911Z","dependency_job_id":"c302a2d8-999e-46a6-888a-ba081a1ed75a","html_url":"https://github.com/floooh/sokol-zig","commit_stats":{"total_commits":462,"total_committers":19,"mean_commits":24.31578947368421,"dds":"0.41774891774891776","last_synced_commit":"727f2c4da84ee0eeff5d5cd205e4f50858420114"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floooh%2Fsokol-zig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floooh%2Fsokol-zig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floooh%2Fsokol-zig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floooh%2Fsokol-zig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/floooh","download_url":"https://codeload.github.com/floooh/sokol-zig/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809964,"owners_count":20999816,"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":["crossplatform","sokol","zig","zig-package"],"created_at":"2024-08-02T23:01:04.593Z","updated_at":"2025-04-08T09:09:38.674Z","avatar_url":"https://github.com/floooh.png","language":"C","readme":"[![build](https://github.com/floooh/sokol-zig/actions/workflows/main.yml/badge.svg)](https://github.com/floooh/sokol-zig/actions/workflows/main.yml)[![Docs](https://github.com/floooh/sokol-zig/actions/workflows/docs.yml/badge.svg)](https://github.com/floooh/sokol-zig/actions/workflows/docs.yml)\n\nAuto-generated Zig bindings for the [sokol headers](https://github.com/floooh/sokol).\n\n[Auto-generated docs](https://floooh.github.io/sokol-zig-docs) (wip)\n\nFor Zig version 0.14.0+\n\nIn case of breaking changes in Zig, the bindings might fall behind. Please don't hesitate to\nping me via a Github issue, or even better, provide a PR :)\n\nSupport for stable Zig versions is in branches (e.g. `zig-0.12.0`), those versions are 'frozen in time' though.\n\nRelated projects:\n\n- [pacman.zig](https://github.com/floooh/pacman.zig)\n- [chipz emulators](https://github.com/floooh/chipz)\n- [Dear ImGui sample project](https://github.com/floooh/sokol-zig-imgui-sample)\n\n## Building the samples\n\nSupported platforms are: Windows, macOS, Linux (with X11) and web\n\nOn Linux install the following packages: libglu1-mesa-dev, mesa-common-dev, xorg-dev, libasound-dev\n(or generally: the dev packages required for X11, GL and ALSA development)\n\nTo build the platform-native samples:\n\n```sh\n# build all examples:\nzig build examples\n# build and run individual examples\nzig build run-clear\nzig build run-triangle\nzig build run-quad\nzig build run-bufferoffsets\nzig build run-cube\nzig build run-noninterleaved\nzig build run-texcube\nzig build run-offscreen\nzig build run-instancing\nzig build run-mrt\nzig build run-saudio\nzig build run-sgl\nzig build run-sgl-context\nzig build run-sgl-points\nzig build run-debugtext\nzig build run-debugtext-print\nzig build run-debugtext-userfont\nzig build run-shapes\n```\n\n(also run ```zig build -l``` to get a list of build targets)\n\nBy default, the backend 3D API will be selected based on the target platform:\n\n- macOS: Metal\n- Windows: D3D11\n- Linux: GL\n\nTo force the GL backend on macOS or Windows, build with ```-Dgl=true```:\n\n```\n\u003e zig build -Dgl=true run-clear\n```\n\nThe ```clear``` sample prints the selected backend to the terminal:\n\n```\nsokol-zig ➤ zig build -Dgl=true run-clear\nBackend: .sokol.gfx.Backend.GLCORE33\n```\n\nFor the web-samples, run:\n\n```sh\nzig build examples -Dtarget=wasm32-emscripten\n# or to build and run one of the samples\nzig build run-clear -Dtarget=wasm32-emscripten\n...\n```\n\nWhen building with target `wasm32-emscripten` for the first time, the build script will\ninstall and activate the Emscripten SDK into the Zig package cache for the latest SDK\nversion. There is currently no build system functionality to update or delete the Emscripten SDK\nafter this first install. The current workaround is to delete the global Zig cache\n(run `zig env` to see where the Zig cache resides).\n\nImproving the Emscripten SDK integration with the Zig build system is planned for the future.\n\n\n## How to integrate sokol-zig into your project\n\nAdd a build.zig.zon file to your project which has at least a `.sokol` dependency:\n\n```zig\n.{\n    .name = \"my_project\",\n    .version = \"0.1.0\",\n    .paths = .{\n        \"src\",\n        \"build.zig\",\n        \"build.zig.zon\",\n    },\n    .dependencies = .{\n        .sokol = .{\n            .url = \"git+https://github.com/floooh/sokol-zig.git#[commit-hash]\",\n            .hash = \"[content-hash]\",\n        },\n    },\n}\n```\n\nThe easiest way to populate or update the `sokol` dependency is to run this on the cmdline:\n\n```\nzig fetch --save=sokol git+https://github.com/floooh/sokol-zig.git\n```\n\nThis will automatically use the latest sokol-zig commit.\n\nFor a native-only project, a `build.zig` file looks entirely vanilla:\n\n```zig\nconst std = @import(\"std\");\nconst Build = std.Build;\nconst OptimizeMode = std.builtin.OptimizeMode;\n\npub fn build(b: *Build) !void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const dep_sokol = b.dependency(\"sokol\", .{\n        .target = target,\n        .optimize = optimize,\n    });\n   const hello = b.addExecutable(.{\n        .name = \"hello\",\n        .target = target,\n        .optimize = optimize,\n        .root_source_file = b.path(\"src/hello.zig\"),\n    });\n    hello.root_module.addImport(\"sokol\", dep_sokol.module(\"sokol\"));\n    b.installArtifact(hello);\n    const run = b.addRunArtifact(hello);\n    b.step(\"run\", \"Run hello\").dependOn(\u0026run.step);\n}\n```\n\nIf you also want to run on the web via `-Dtarget=wasm32-emscripten`, the web platform\nbuild must look special, because Emscripten must be used for linking, and to run\nthe build result in a browser, a special run step must be created.\n\nSuch a 'hybrid' build script might look like this (copied straight from [pacman.zig](https://github.com/floooh/pacman.zig)):\n\n```zig\nconst std = @import(\"std\");\nconst Build = std.Build;\nconst OptimizeMode = std.builtin.OptimizeMode;\nconst sokol = @import(\"sokol\");\n\npub fn build(b: *Build) !void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n    const dep_sokol = b.dependency(\"sokol\", .{\n        .target = target,\n        .optimize = optimize,\n    });\n\n    // special case handling for native vs web build\n    if (target.result.cpu.arch.isWasm()) {\n        try buildWeb(b, target, optimize, dep_sokol);\n    } else {\n        try buildNative(b, target, optimize, dep_sokol);\n    }\n}\n\n// this is the regular build for all native platforms, nothing surprising here\nfn buildNative(b: *Build, target: Build.ResolvedTarget, optimize: OptimizeMode, dep_sokol: *Build.Dependency) !void {\n    const pacman = b.addExecutable(.{\n        .name = \"pacman\",\n        .target = target,\n        .optimize = optimize,\n        .root_source_file = b.path(\"src/pacman.zig\"),\n    });\n    pacman.root_module.addImport(\"sokol\", dep_sokol.module(\"sokol\"));\n    b.installArtifact(pacman);\n    const run = b.addRunArtifact(pacman);\n    b.step(\"run\", \"Run pacman\").dependOn(\u0026run.step);\n}\n\n// for web builds, the Zig code needs to be built into a library and linked with the Emscripten linker\nfn buildWeb(b: *Build, target: Build.ResolvedTarget, optimize: OptimizeMode, dep_sokol: *Build.Dependency) !void {\n    const pacman = b.addStaticLibrary(.{\n        .name = \"pacman\",\n        .target = target,\n        .optimize = optimize,\n        .root_source_file = b.path(\"src/pacman.zig\"),\n    });\n    pacman.root_module.addImport(\"sokol\", dep_sokol.module(\"sokol\"));\n\n    // create a build step which invokes the Emscripten linker\n    const emsdk = dep_sokol.builder.dependency(\"emsdk\", .{});\n    const link_step = try sokol.emLinkStep(b, .{\n        .lib_main = pacman,\n        .target = target,\n        .optimize = optimize,\n        .emsdk = emsdk,\n        .use_webgl2 = true,\n        .use_emmalloc = true,\n        .use_filesystem = false,\n        .shell_file_path = dep_sokol.path(\"src/sokol/web/shell.html\"),\n    });\n    // attach Emscripten linker output to default install step\n    b.getInstallStep().dependOn(\u0026link_step.step);\n    // ...and a special run step to start the web build output via 'emrun'\n    const run = sokol.emRunStep(b, .{ .name = \"pacman\", .emsdk = emsdk });\n    run.step.dependOn(\u0026link_step.step);\n    b.step(\"run\", \"Run pacman\").dependOn(\u0026run.step);\n}\n```\n\n## Using sokol headers in C code\n\nThe sokol-zig build.zig exposes a C library artifact called `sokol_clib`.\n\nYou can lookup the build step for this library via:\n\n```zig\n    const dep_sokol = b.dependency(\"sokol\", .{\n        .target = target,\n        .optimize = optimize,\n    });\n    const sokol_clib = dep_sokol.artifact(\"sokol_clib\");\n```\n\n...once you have that library artifact, 'link' it to your compile step which contains\nyour own C code:\n\n```zig\n    const my_clib = ...;\n    my_clib.linkLibrary(sokol_clib);\n```\n\nThis makes the Sokol C headers available to your C code in a `sokol/` subdirectory:\n\n```c\n#include \"sokol/sokol_app.h\"\n#include \"sokol/sokol_gfx.h\"\n// etc...\n```\n\nKeep in mind that the implementation is already provided in the `sokol_clib`\nstatic link library (e.g. don't try to build the Sokol implementations yourself\nvia the `SOKOL_IMPL` macro).\n\n\n## wasm32-emscripten caveats\n\n- Zig allocators use the `@returnAddress` builtin, which isn't supported in the Emscripten\n  runtime out of the box (you'll get a runtime error in the browser's Javascript console\n  looking like this: `Cannot use convertFrameToPC (needed by __builtin_return_address) without -sUSE_OFFSET_CONVERTER`.\n  To link with `-sUSE_OFFSET_CONVERTER`, simply set the `.use_offset_converter` option\n  in the Emscripten linker step in your build.zig:\n\n  ```zig\n      const link_step = try sokol.emLinkStep(b, .{\n        // ...other settings here\n        .use_offset_converter = true,\n    });\n  ```\n\n- the Zig stdlib only has limited support for the `wasm32-emscripten`\n  target, for instance using `std.fs` functions will most likely fail\n  to compile (the sokol-zig bindings might add more sokol headers\n  in the future to fill some of the gaps)\n\n## Dear ImGui support\n\nThe sokol-zig bindings come with sokol_imgui.h (exposed as the Zig package\n`sokol.imgui`), but integration into a project's build.zig requires some extra\nsteps, mainly because I didn't want to add a\n[cimgui](https://github.com/cimgui/cimgui) dependency to the sokol-zig package\n(especially since cimgui uses git submodule which are not supported by the Zig\npackage manager).\n\nThe main steps to create Dear ImGui apps with sokol-zig are:\n\n1. 'bring your own cimgui'\n2. tell the sokol dependency that it needs to include sokol_imgui.h into\n  the compiled C library:\n    ```zig\n    const dep_sokol = b.dependency(\"sokol\", .{\n        .target = target,\n        .optimize = optimize,\n        .with_sokol_imgui = true,\n    });\n    ```\n3. inject the path to the cimgui directory into the sokol dependency so\n  that C compilation works (this needs to find the `cimgui.h` header)\n\n    ```zig\n    dep_sokol.artifact(\"sokol_clib\").addIncludePath(cimgui_root);\n    ```\n\nAlso see the following example project:\n\nhttps://github.com/floooh/sokol-zig-imgui-sample/\n","funding_links":[],"categories":["Libraries","C","Interoperability"],"sub_categories":["FFI Bindings"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloooh%2Fsokol-zig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffloooh%2Fsokol-zig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloooh%2Fsokol-zig/lists"}