Zig workbench
DarknessFX Zig templates, projects, programs, libs and tools.
.----------------. .----------------. .----------------. | .--------------. || .--------------. || .--------------. | | | ________ | || | _________ | || | ____ ____ | | | | |_ ___ `. | || | |_ ___ | | || | |_ _||_ _| | | | | | | `. \ | || | | |_ \_| | || | \ \ / / | | | | | | | | | || | | _| | || | > `' [!NOTE] > This is a student project, code will run and build without errors (mostly because I just throw away errors), it is not a reference of ... The project is written primarily in C, distributed under the MIT License license, first published in 2023. Key topics include: allegro5, cuda, dear-imgui, directx11, imgui.
.----------------. .----------------. .----------------.
| .--------------. || .--------------. || .--------------. |
| | ________ | || | _________ | || | ____ ____ | |
| | |_ ___ `. | || | |_ ___ | | || | |_ _||_ _| | |
| | | | `. \ | || | | |_ \_| | || | \ \ / / | |
| | | | | | | || | | _| | || | > `' < | |
| | _| |___.' / | || | _| |_ | || | _/ /'`\ \_ | |
| | |________.' | || | |_____| | || | |____||____| | |
| | | || | | || | | |
| '--------------' || '--------------' || '--------------' |
'----------------' '----------------' '----------------'
DarknessFX @ https://dfx.lv | Twitter: @DrkFX
About
I'm studying and learning Zig Language (started Nov 19, 2023), sharing here my Zig projects, templates, libs and tools.
Using Windows 10, Zig x86_64 Version : 0.16.0
[!NOTE]
This is a student project, code will run and build without errors (mostly because I just throw away errors), it is not a reference of "best coding practices". Suggestions or contributions changing the code to the "right way and best practices" are welcome.
Templates
| Folder | Description | /Subsystem |
|---|---|---|
| Base | Template for a console program. | Console |
| BaseEx | Template for a console program that hide the console window. | Console |
| BaseWin | Template for a Windows program. | Windows |
| BaseWinEx | Template for a Windows program, Windows API as submodule. | Windows |
| BaseImGui | Template with Dear ImGui via Dear Bindings. Extra: ImGui_Memory_Editor. Renderers: OpenGL2, OpenGL3, DirectX11, SDL3 OpenGL3, SDL2 OpenGL2, SDL3_Renderer, SDL2_Renderer | Both |
| BaseRayLib | Template with RayLib and RayGUI. | Console + Web |
| BaseRayLibImGui | Template with RayLib and RayGUI and Dear ImGui via Dear Bindings and rlImGui. | Console |
| BaseSDL2 | Template with SDL2. | Windows |
| BaseSDL3 | Template with SDL3. | Windows |
| BaseSDL3ImGui | Template with SDL3 and Dear ImGui. | Windows |
| BaseSFML2 | Template with SFML2 via CSFML2 C bindings. | Console |
| BaseSokol | Template with Sokol. Extras UI: Dear ImGui via cimgui, Nuklear. | Windows |
| BaseAllegro | Template with Allegro5. | Console |
| BaseNanoVG | Template with NanoVG using GLFW3 OpenGL3. | Console |
| BaseLVGL | Template with LVGL UI. | Console |
| BaseMicroui | Template with microui. Renderers: SDL2, Windows GDI. | Windows |
| BaseNuklear | Template with Nuklear UI using Windows GDI native. | Windows |
| BaseWebview | Template with Webview. | Console |
| BaseClay | Template with Clay UI and RayLib, using clay-zigibindings. | Windows |
| BaseGTK | Template with GTK . | Console |
| BaseFLTK | Template with FLTK via cFLTK . | Windows |
| BaseOpenGL | Template with OpenGL. | Windows |
| BaseDX11 | Template with DirectX Direct3D 11. | Windows |
| BaseVulkan | Template with Vulkan, versions: Win32API, GLFW3 . | Both |
| BaseGLFW | Template with GLFW and GLAD. | Console |
| BaseFreeglut | Template with freeglut. | Console |
| BaseWasm | Template with BaseWasm using Emscripten. | Web |
| BaseWebGPU | Template with WebGPU using Emscripten and Dawn. | Windows + Web |
| BaseLua | Template with Lua scripting language. | Console |
| BaseSQLite | Template with SQLite database. | Console |
| BaseLMDB | Template with LMDB database. | Console |
| BaseDuckDB | Template with DuckDB database. | Console |
| BaseODE | Template with ODE Open Dynamics Engine physics. | Console |
| BaseChipmunk2D | Template with Chipmunk2D physics. | Console |
| BaseBox2D | Template with Box2D physics. | Console |
| BaseLibpng | Template with libpng image format. | Console |
| BaseZlib | Template with zlib compression. | Console |
| BaseZstd | Template with Zstd fast lossless compression. | Console |
| BaseCUDA | Template with Nvidia CUDA . | Console |
| Steps | Path example |
|---|---|
| Duplicate the template folder. | C:\zig_workbench\BaseWin Copy\ |
| Rename copy folder to your project name. | C:\zig_workbench\MyZigProgram\ |
| Copy tools/updateProjectName.bat to your project Tools folder. | C:\zig_workbench\MyZigProgram\Tools\ |
| Run updateProjectName.bat. | C:\zig_workbench\MyZigProgram\Tools\updateProjectName.bat |
| Open YourProject VSCode Workspace. | C:\zig_workbench\MyZigProgram\MyZigProgram VSCode Workspace.lnk |
[!WARNING]
Current VSCode + ZLS extension do not accept @cInclude relative to project folder and will break builds.<br/>
After open your new project, remember to edit .zig files @cInclude including your full path and using / folder separator.
Zig have a useful built in feature: zig init that creates a basic project. I customized this basic project to fit my use cases, mostly to output to bin folder instead of zig-out\bin, have main.zig in the project root instead of src folder and use my VSCode Setup.
</details> <details> <summary><ins>About Dear ImGui</ins></summary> <pre>Using Dear ImGui Docking 1.92.8 Docking and Dear Bindings v0.21 (20260513) All necessary libraries are inside the template. <br/> Note: When changing renderers, make sure to rename all files (Main.zig, Build.zig, .vscode/Tasks.json). Check tools/RunAll.bat to get a list of **Zig Run** commands to launch rendereres without renaming files.ImGui_Memory_Editor: Edited from Dear Bindings output. Sample inside all ImGui templates
and usage details at <a href="BaseImGui/lib/imgui/cimgui_memory_editor.h" target="_blank">cimgui_memory_editor.h</a></pre>
If you get an error while installing CUDA SDK, use Custom Installation and disable the following:
Nsight VSE
Visual Studio Integration
Nsight Systems
Nsight compute
Nvidia GeForce Experience
Other components
Driver components
If you want, you can install Nsight with its own installer.</pre>
</details>Programs
| Folder | Description | /Subsystem |
|---|---|---|
| ToSystray | Give other Windows programs ability to "Minimize to Systray".<br/> Binary version ready to use is available to download at Releases Page - ToSystray_v.1.0.0 | Windows |
| zTime | Similar to Linux TIME command, add zTime in front of your command to get the time it took to execute.<br/> Binary version ready to use is available to download at Releases Page - zTime v1.0.1. | Console |
Projects
| Folder | Description |
|---|---|
| ModernOpenGL | Mike Shah ModernOpenGL Youtube Tutorials ported to Zig + SDL3.1.2 OpenGL 4.6. |
| zig_raylib_examples | WIP RayLib examples ported to Zig. |
| zTinyRasterizer | WIP Lisitsa Nikita tiny CPU rasterization engine ported to Zig. |
Libraries
| Folder | Description |
|---|---|
| dos_color.zig | Helper to output colors to console (std.debug.print) or debug console (OutputDebugString). |
| string.zig | WIP String Type. |
Tools
[!IMPORTANT]
All tools should be run from YourProjectFolder\Tools\ folder, <br/>
do not run it directly in the main folder.
| Folder | Description |
|---|---|
| updateProjectName.bat | Read parent folder name as your ProjectName and replace template references to ProjectName. |
| buildReleaseStrip.bat | Call "zig build-exe" with additional options (ReleaseSmall, strip, single-thread), emit assembly (.s), llvm bitcode (.ll, .bc), C header, zig build report. |
| clean_zig-cache.bat | Remove zig-cache from all sub folders. |
Tools_ContextMenu
| Folder | Description |
|---|---|
| zig.ico | Zig logo Icon file (.ico). (Resolutions 64p, 32p, 16p) |
| zig_256p.ico | Zig logo Icon file (.ico) with higher resolutions . (Resolutions 256p, 128p, 64p, 32p, 16p) |
| zig_contextmenu.bat | Launcher used by Windows Explorer context menu, copy to Zig folder PATH. |
| zig_icon.reg | Associate an icon for .Zig files, add Build, Run, Test to Windows Explorer context menu. Read more details in the file comments. |
| zig_icon_cascade.reg | Alternative of zig_icon.reg, groups all options inside a Zig submenu. Read more details in the file comments. |
Tools to help setup Windows Explorer to apply icons to .ZIG files and add context menu short-cuts to Build, Run and Test.
<details> <summary>📷<ins>zig_icon.reg - screenshot</ins></summary> <pre>After run zig_icon.reg, Windows Explorer will look like:<br/> <img src="/.git_img/zig_icon_contextmenu.png" width="480" /></pre> </details> <details> <summary>📷<ins>zig_icon_cascade.reg - screenshot</ins></summary> <pre>After run zig_icon_cascade.reg, Windows Explorer will look like:<br/> <img src="/.git_img/zig_icon_cascade_contextmenu.png" width="480" /></pre> </details>About VSCode (Tips and Tricks)
I'm using VSCode to program in Zig and using Zig Language extension from ZLS - Zig Language Server.
<details> <summary><ins>Extensions that I use and recommend</ins></summary> <pre> <a href="https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools" target="_blank">C/C++</a> from Microsoft. (**essential to enable Debug mode**.) <a href="https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack" target="_blank">C/C++ Extension Pack</a> from Microsoft. (non-essential) <a href="https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-themes" target="_blank">C/C++ Themes</a>. (non-essential) <a href="https://marketplace.visualstudio.com/items?itemName=ms-vscode.hexeditor" target="_blank">Hex Editor</a> from Microsoft. (**essential in Debug mode**) <a href="https://marketplace.visualstudio.com/items?itemName=DrMerfy.overtype" target="_blank">OverType</a> from DrMerfy. (non-essential? Add Insert key mode) <a href="https://marketplace.visualstudio.com/items?itemName=PKief.material-icon-theme" target="_blank">Material Icon Theme</a> from Philipp Kief. (non-essential, but make VSCode looks better)</pre> </details>VSCode RADDebugger
I'm using VSCode with Cppvsdbg for a while but its features are lackluster, recently I tried RadDebugger and it works surprisingly well.
I "hacked" a custom command into launch.json as a shortcut to start a RadDebugger session with the latest debug build.<br/>This is not feature in all .vscode/launch.json templates, if you are interested the additional launch.json settings are:
Remember to fix the hard-coded paths (at miDebuggerPath) to reflect your local folder to RADDebugger path.
Ctrl+R is the new F5
I changed a few VSCode keybindings for better use, mostly because Zig offer multiple options for Build, Run, Test, Generate Docs, and I setup VSCode Tasks.json with all available options.
The most important key binding change is CTRL+T to open TASKS menu, because VSCode keep the last task as first menu item, just pressing ENTER will: save current file and run the last task.
Zig Build is fast and Template/.vscode/launch.json is already setup so VSCode F5 key (Start with Debugger) will activate Zig Build and start debug, it works great and fast. But even better is Zig Run Main, the way zig run compile and start (without debugger) is a lot faster and helps a lot to iterate and productivity. CTRL+T, Enter became one of my most used keyboard shortcut inside VSCode and CTRL+R to repeat the last task.<br/>
<details> <summary>📷<ins>Task menu screenshot</ins></summary> <img src="/.git_img/vscode_tasks_menu.png" width="480" /> </details> <details> <summary><ins>VSCode Keybindings details</ins></summary> <br/>VSCode Keybindings file location at %APPDATA%\Code\User\keybindings.json<br/><br/>CTRL+T : Removed showAllSymbols and added runTask.<br/>
Reason : Easy access to Tasks menu and repeatable action to run last action.<br/>
CTRL+R : Removed all bindings.<br/>
Reason: Because this key binding try to reload the current document or display a different menu that also will try to close the current document... If I need I can go to menu File > Open Recent File instead of this shortcut that risk to close what I'm working.<br/>
Copy your libraries DLL to Zig folder
When using libraries that have .DLL (for example SDL2_ttf.dll) the task Zig Run Main will fail because it cannot find the DLL and the exe was built somewhere in zig-cache, the error is "The terminal process ... terminated with exit code: 53.". The easier way to fix this error is to copy the library DLL to your Zig PATH folder.
Personal observation about VSCode
I have a Love/Hate relationship with VSCode, I only used it to code for Arduino and ESP32 with Platform.io and the hate is always when the editor try to be "smart and helpful".
Yellow lightbulbs sometimes show up to notify "There are no fix", JSON files organized to easier read key items are reordered because "that is how JSON should be ordered", at least 10% of keys typed are wasted deleting things that VSCode put there to help me. And my favorite gripe: You select a function name in the Intellisense combo, it prints at your source code "YourFunction([cursor here])" BUT it don't display the arguments list, you need to backspace to delete the ( opening parenthesis, type ( and now the tooltip show up with the arguments list.
Credits
Zig Language from ZigLang.org.<br/>
SDL2, SDL3 from libSDL.org.<br/>
GLFW from GLFW.org.<br/>
GLAD from Dav1dde.<br/>
microui from rxi.<br/>
Dear ImGui from Omar Cornut.<br/>
Dear Bindings from Ben Carter.<br/>
LVGL from LVGL Kft.<br/>
ModernOpenGL from Mike Shah.<br/>
RayLib and RayGUI from Ramon Santamaria (@raysan5).<br/>
WebGPU and Wasm from World Wide Web Consortium.<br/>
Dawn from Google.<br/>
Sokol from Floooh.<br/>
cimgui from Sonoro1234.<br/>
Nuklear from Micha Mettke.<br/>
Clay from Nic Barker.<br/>
Allegro5 from Allegro 5 Development Team.<br/>
NanoVG from Memononen.<br/>
SFML2 from Laurent Gomila.<br/>
Webview from Webview Team.<br/>
Lua from PUC-Rio.<br/>
SQLite from SQLite Consortium.<br/>
LMDB from Symas Corporation.<br/>
DuckDB from DuckDB Foundation.<br/>
ODE from Russ L. Smith.<br/>
Chipmunk2D from Howling Moon Software.<br/>
Box2D from Erin Catto.<br/>
zstd from Meta.<br/>
TinyRasterizer from Lisitsa Nikita.<br/>
Vulkan from Khronos Group.<br/>
Nvidia CUDA from Nvidia.<br/>
Clay from Nic Barker.<br/>
clay-zig-bindings from johan0A.<br/>
GTK from GNOME Foundation.<br/>
libpng from The PNG Reference Library Authors.<br/>
zlib from Jean-loup Gailly and Mark Adler.<br/>
freeglut from Pawel W. Olszta.<br/>
FLTK from Bill Spitzak and others.<br/>
License
MIT - Free for everyone and any use.
DarknessFX @ https://dfx.lv | Twitter: @DrkFX<br/>
https://github.com/DarknessFX/zig_workbench
Contributors
Showing top 1 contributor by commit count.
