Nuklear GUI Library - Deployment & Usage Guide

A single-header ANSI C immediate mode graphical user interface library.

Prerequisites

C Compiler: GCC, Clang, or MSVC supporting C89/C90 standard or later
Graphics Drivers: OpenGL 3.3+ (recommended), DirectX 9/11/12, Vulkan, or platform-specific APIs
Window/Input Backend (choose one):
- GLFW3: libglfw3-dev (Ubuntu/Debian), glfw (macOS/Homebrew), or glfw.org (Windows)
- SDL2: libsdl2-dev (Ubuntu/Debian), sdl2 (macOS/Homebrew)
- X11: libx11-dev (Linux only)
- Win32: Windows SDK (Windows only)
Build Tools: make, cmake, or direct compiler access
Math Library: Standard C math library (-lm on Unix systems)

Installation

Method 1: Direct Download (Production)

curl -O https://raw.githubusercontent.com/vurtun/nuklear/master/nuklear.h

Copy nuklear.h into your project's source directory.

Method 2: Git Clone (Development/Examples)

git clone https://github.com/vurtun/nuklear.git
cd nuklear

Method 3: Git Submodule (Version Control)

git submodule add https://github.com/vurtun/nuklear.git vendor/nuklear
git submodule update --init

Configuration

Required Implementation Macro

In exactly one source file (typically main.c), define before including:

#define NK_IMPLEMENTATION
#include "nuklear.h"

Optional Feature Flags

Define these before including nuklear.h to enable features:

#define NK_INCLUDE_FIXED_TYPES          // Use <stdint.h> fixed-size types
#define NK_INCLUDE_DEFAULT_ALLOCATOR    // Use standard malloc/free
#define NK_INCLUDE_STANDARD_IO          // Enable nk_strtod/nk_ftoa utilities
#define NK_INCLUDE_STANDARD_VARARGS     // Enable nk_printf-style formatting
#define NK_INCLUDE_VERTEX_BUFFER_OUTPUT // Enable vertex buffer rendering (required for OpenGL/DirectX backends)
#define NK_INCLUDE_FONT_BAKING          // Enable font atlas baking (requires stb_truetype.h)
#define NK_INCLUDE_DEFAULT_FONT         // Include built-in ProggyClean font (6KB)
#define NK_INCLUDE_COMMAND_USERDATA     // Add userdata field to draw commands

Backend Setup Example (GLFW + OpenGL 3)

#define NK_IMPLEMENTATION
#define NK_INCLUDE_FIXED_TYPES
#define NK_INCLUDE_DEFAULT_ALLOCATOR
#define NK_INCLUDE_STANDARD_VARARGS
#define NK_INCLUDE_VERTEX_BUFFER_OUTPUT
#define NK_INCLUDE_FONT_BAKING
#define NK_INCLUDE_DEFAULT_FONT

#include "nuklear.h"
#include "nuklear_glfw_gl3.h"  // From demo/glfw_opengl3/

Build & Run

Building Demo Examples

GLFW + OpenGL 3 (Linux/macOS):

cd demo/glfw_opengl3
make
./bin/demo

SDL + OpenGL 3:

cd demo/sdl_opengl3
make
./bin/demo

X11 (Linux native):

cd demo/x11
make
./bin/demo

Windows (MinGW):

cd demo/glfw_opengl3
mingw32-make
demo.exe

Compiling Your Project

Basic GCC compilation (Linux):

gcc -o myapp main.c -std=c89 -Wall -Wextra -pedantic \
    -I. -I/path/to/nuklear \
    -lglfw -lGL -lm -ldl

With SDL2:

gcc -o myapp main.c -std=c89 -Wall \
    -I. -I/path/to/nuklear \
    `sdl2-config --cflags --libs` -lGL -lm

macOS with Homebrew GLFW:

gcc -o myapp main.c -std=c89 -Wall \
    -I/opt/homebrew/include -L/opt/homebrew/lib \
    -lglfw -framework OpenGL -framework Cocoa -framework IOKit -framework CoreVideo

Static linking (Windows/MinGW):

gcc -o myapp.exe main.c -std=c89 -O2 -s -static \
    -lglfw3 -lopengl32 -lgdi32 -lm

CMake Integration:

add_executable(myapp main.c)
target_include_directories(myapp PRIVATE ${CMAKE_SOURCE_DIR}/vendor/nuklear)
target_link_libraries(myapp glfw OpenGL::GL ${CMAKE_DL_LIBS})

Deployment

Static Binary Distribution

Since Nuklear is header-only, deployment involves distributing your compiled binary:

Linux (portable):

# Verify minimal dependencies
ldd ./myapp | grep -v "linux-vdso\|libc\|libm\|libdl\|libpthread"

# Create distribution package
tar -czvf myapp-linux-x64.tar.gz myapp assets/ README.md

Windows:

Link runtime statically (-static with MinGW, /MT with MSVC) to avoid VC++ redistributables
Include nuklear.h MIT license in your distribution
Ship with glew32.dll if using GLEW, or link statically

macOS App Bundle:

mkdir -p MyApp.app/Contents/MacOS
cp myapp MyApp.app/Contents/MacOS/
cp -r assets MyApp.app/Contents/MacOS/
# Code sign if distributing: codesign --force --deep --sign - MyApp.app

Web Deployment (Emscripten)

emcc main.c -s USE_GLFW=3 -s WASM=1 -O3 \
    -o index.html \
    --shell-file shell.html

Asset Management

Fonts: Either bake TTF files at compile-time using nk_font_bake(), or ship TTF files and load at runtime
Icons: Use stb_image to embed PNGs as C arrays, or load from filesystem
Styles: Define color schemes in code; no external theme files required

Troubleshooting

Compilation Errors

multiple definition of 'nk_*'

Cause: #define NK_IMPLEMENTATION appears in multiple files
Fix: Ensure it appears in exactly one .c file; use header guards in other files

undefined reference to 'nk_*'

Cause: Missing implementation macro
Fix: Add #define NK_IMPLEMENTATION before the `#

How to Deploy & Use vurtun/nuklear