.----------------.  .----------------.  .----------------. 
| .--------------. || .--------------. || .--------------. |
| |  ________    | || |  _________   | || |  ____  ____  | |
| | |_   ___ `.  | || | |_   ___  |  | || | |_  _||_  _| | |
| |   | |   `. \ | || |   | |_  \_|  | || |   \ \  / /   | |
| |   | |    | | | || |   |  _|      | || |    > `' <    | |
| |  _| |___.' / | || |  _| |_       | || |  _/ /'`\ \_  | |
| | |________.'  | || | |_____|      | || | |____||____| | |
| |              | || |              | || |              | |
| '--------------' || '--------------' || '--------------' |
 '----------------'  '----------------'  '----------------' 

       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.12.0-dev.1245+a07f288eb

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

Zig have a useful built in feature: zig init-exe that create 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.

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: OpenGL3, DirectX11, SDL3 OpenGL3, SDL2 OpenGL2, SDL3_Renderer, SDL2_Renderer	Both
Basemicroui	Template with microui. Renderers: SDL2, Windows GDI.	Windows
BaseLVGL	Template with LVGL .	Console
BaseSDL2	Template with SDL2.	Windows
BaseSDL3	Template with SDL3 Preview.	Windows
BaseOpenGL	Template with OpenGL (GL.h).	Windows
BaseGLFW	Template with GLFW and GLAD.	Console
BaseDX11	Template with DirectX Direct3D 11.	Windows

Usage

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.
After open your new project, remember to edit .zig files @cInclude including your full path and using / folder separator.

About Dear ImGui

Using Dear ImGui Docking 1.90WIP and Dear Bindings (20231029)
All necessary libraries are inside the template.

Note: When changing renderers, make sure to rename all files (Main.zig, Build.zig, .vscode/Tasks.json).
ImGui_Memory_Editor: Edited from Dear Bindings output. Usage and sample inside cimgui_memory_editor.h

About microui

microui.c and microui.h are inside the project folder.
Normally I would recommend to download from the official repository 
but sadly microui is outdated (last update 3 years ago) and I applied 
community pull requests to the source code.
It was necessary because the original code crashed with runtime 
error: member access within misaligned address and without the 
fix this project would not work.

About LVGL

Using LVGL from source (20231105, 9.0 Preview).
Used parts of code from lv_port_pc_visual_studio (lv_conf and main source).
All necessary libraries are inside the template.
Download Demos and Examples folders from the GitHub source

(and don't forget to add all .C files necessary to build).

About SDL2

  Using SDL2 v2.28.4.
  Download SDL2 from: GitHub SDL2 Releases Page.
  For Windows devs: SDL2-devel-2.28.4-VC.zip 2.57 MB.
  Check BaseSDL2/lib/SDL2/filelist.txt for a description 
  of the folder structure and expected files path location.

About SDL3 Preview

  Built from source in 20231102.

About GLFW and GLAD

GLFW 3.3.8 (Win64 Static).
GLAD 2.0 (OpenGL 3.3 Compatibility).
All necessary libraries are inside the template.

Libraries

Folder	Description
dos_color.zig	Helper to output colors to console (std.debug.print) or debug console (OutputDebugString).
string.zig	Basic String Type.

Libraries usage

  Create a /lib/ folder in your project folder.
  Copy the library file to /lib/ .
  Add const libname = @Import("lib/lib_name.zig"); to your source code.

Programs

Folder	Description
zTime	Similar to Linux TIME command, add zTime in front of your command to get the time it took to execute. Binary version ready to use is available to download at Releases Page - zTime v1.0. (console program)

zTime Usage

  Examples, run in your Command Prompt, Windows Terminal or Powershell:
    C:\>zTime zig build
    C:\>zTime dir
    C:\>zTime bin\ReleaseFast\YourProject.exe

  Suggestion:
  Copy zTime.exe to your Zig folder, this way the application will 
  share the Environment Path and can be executed from anywhere.

Tools

Important

All tools should be run from YourProjectFolder\Tools\ folder,
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.
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_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.

zig_icon.reg - screenshot

After run zig_icon.reg, Windows Explorer will look like:

zig_icon_cascade.reg - screenshot

After run zig_icon_cascade.reg, Windows Explorer will look like:

About VSCode (Tips and Tricks)

I'm using VSCode to program in Zig and using Zig Language extension from ZLS - Zig Language Server.

Extensions that I use and recommend

  C/C++ from Microsoft. (**essential to enable Debug mode**.)
  C/C++ Extension Pack from Microsoft. (non-essential)
  C/C++ Themes. (non-essential)
  Hex Editor from Microsoft. (**essential in Debug mode**)
  OverType from DrMerfy. (non-essential? Add Insert key mode)
  Material Icon Theme from Philipp Kief. (non-essential, but make VSCode looks better)

Ctrl+T, Enter 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 more 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 ask.

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. So CTRL+T, Enter became my most used keyboard shortcut inside VSCode.
_{(at least until they add a keybiding for "Run Last Task" so I can bind to CTRL+R^un).}

Task menu screenshot

VSCode Keybindings details

VSCode Keybindings file location at %APPDATA%\Code\User\keybindings.json

CTRL+T : Removed showAllSymbols and added runTask.
Reason : Easy access to Tasks menu and repeatable action to run last action.

CTRL+R : Removed all bindings.
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.

[
  {
    "key": "ctrl+t",
    "command": "-workbench.action.showAllSymbols"
  },
  {
    "key": "ctrl+t",
    "command": "workbench.action.tasks.runTask"
  }
  {
    "key": "ctrl+r",
    "command": "-workbench.action.reloadWindow",
    "when": "isDevelopment"
  },
  {
    "key": "ctrl+r",
    "command": "-workbench.action.quickOpenNavigateNextInRecentFilesPicker",
    "when": "inQuickOpen && inRecentFilesPicker"
  },
  {
    "key": "ctrl+r",
    "command": "-workbench.action.openRecent"
  }
]

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 easier way to fix is to copy the library DLL to your Zig 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 reorder 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.

Projects

Folder	Description
soon	soon

Credits

Zig Language from ZigLang.org .
SDL2, SDL3 from libSDL.org .
GLFW from GLFW.org .
GLAD from Dav1dde .
microui from rxi .
Dear ImGui from Omar Cornut .
Dear Bindings from Ben Carter .
LVGL from LVGL Kft .

License

MIT - Free for everyone and any use.

DarknessFX @ https://dfx.lv | Twitter: @DrkFX
https://github.com/DarknessFX/zig_workbench

_{SEO Helper}

Giving Google a little help pairing Zig + LIB words, because it find my twitter posts easier than this repo:
BaseWinEx   = Zig Windows program template with Windows API as submodule.
BaseImGui   = Zig ImGui Windows program template with renderers: OpenGL3, DirectX11, SDL3 OpenGL3, SDL2 OpenGL2, SDL3_Renderer, SDL2_Renderer.
Basemicroui = Zig microui Windows program template with renderers: SDL2, Windows GDI.
BaseLVGL    = Zig LVGL Windows program template.
BaseSDL2    = Zig SDL2 Windows program template.
BaseSDL3    = Zig SDL3 Windows program template.
BaseOpenGL  = Zig OpenGL GL.h Windows program template.
BaseGLFW    = Zig GLFW GLAD Windows program template.
BaseDX11    = Zig DirectX Direct3D 11 DX11 Windows program template.