IUP-Go

Go library based on IUP, a multi-platform toolkit for building graphical user interfaces.

IUP-Go provides system native UI controls for Windows (Win32, WinUI), macOS (Cocoa), Linux/BSD (GTK, Qt, Qt Quick, FLTK, EFL, Motif, GNUstep), Haiku (Interface Kit), WebAssembly (Emscripten), Android (Android), and iOS (Cocoa Touch).

C/C++/Obj-C source code is included and compiled together with bindings. Note that the first build can take a few minutes.

Alternatively, build with CGO_ENABLED=0 and no C compiler. A prebuilt library for the platform's default backend is bundled and loaded at runtime, for linux, darwin, and windows on amd64 and arm64. Other backends and platforms require the cgo build.

To build the IUP C library standalone (without Go bindings), see iup/external for CMake build instructions.

Requirements

Go 1.21 is the minimum required version.

Windows

• To remove a console window, i.e., compile a GUI app with a WinMain entry point, build with -ldflags "-H=windowsgui".
• You can add an icon resource to an .exe file with the rsrc tool.
• Windows manifest is included in the build by default. See below how to disable the manifest if you want to include your own.

Win32

For Win32, you need a C compiler, like MinGW-w64 or TDM-GCC. You can also build a binary in the MSYS2 shell.

• For MSYS2, install pacman -S mingw-w64-x86_64-go mingw-w64-x86_64-gcc mingw-w64-x86_64-pkg-config.
• You can build for Qt, with the qt/qml build tags. Install deps with pacman -S mingw-w64-x86_64-qt6-base / -qt6-declarative.
• You can build for GTK, with the gtk3/gtk4 build tags. Install deps with pacman -S mingw-w64-x86_64-gtk3 / -gtk4.
• You can build for FLTK, with the fltk build tag. Install deps with pacman -S mingw-w64-x86_64-fltk.
• The WebBrowser control uses WebView2 with every backend.

WinUI

For WinUI 3, you need a Clang C++ compiler.

The easiest method is to install MSYS2 and to start a MSYS2/CLANG64 session, then install pacman -S mingw-w64-clang-x86_64-go mingw-w64-clang-x86_64-clang in that session.

You can also use LLVM MinGW.

The Windows App Runtime must be installed, any of 1.5 to 1.8 or 2.x.

Add -ldflags "-s -w" to strip symbols and DWARF info; the C++/WinRT headers generate huge amounts of debug info, dropping it shrinks a typical .exe from ~30 MB to ~5 MB.

macOS

On macOS, you need Command Line Tools for Xcode (if you have brew, you already have this).

To create an .app bundle, see Packaging.

• You can build for Qt, with the qt/qml build tags. Install deps with brew install qt.
• You can build for GTK, with the gtk3/gtk4 build tags. Install deps with brew install gtk+3 / gtk4.
• You can build for FLTK, with the fltk build tag. Install deps with brew install fltk.
• The WebBrowser control uses WKWebView with every backend.

Linux

On Linux, you need a C/C++ compiler and the GTK or Qt development packages.

GTK

GTK3 (default)

• Debian/Ubuntu: apt-get install libgtk-3-dev
• RedHat/Fedora: dnf install gtk3-devel

GTK4

• Debian/Ubuntu: apt-get install libgtk-4-dev
• RedHat/Fedora: dnf install gtk4-devel

You can also build for GTK2.

For the WebBrowser control, libraries are loaded at runtime. You do not need to install WebKitGTK development packages.

For the GLCanvas control, install libegl-dev libgl-dev or libglvnd-devel.

Qt

Qt6 (default)

• Debian/Ubuntu: apt-get install qt6-base-dev
• RedHat/Fedora: dnf install qt6-qtbase-devel

Qt5

• Debian/Ubuntu: apt-get install qt5base-dev
• RedHat/Fedora: dnf install qt5-qtbase-devel

For the WebBrowser control, install qt6-webengine-dev or qt6-qtwebengine-devel.

Qt Quick

• Debian/Ubuntu: apt-get install qt6-declarative-dev
• RedHat/Fedora: dnf install qt6-qtdeclarative-devel

For the GLCanvas control, install libegl-dev libgl-dev or libglvnd-devel.

FLTK

Requires FLTK 1.4.x.

• Debian/Ubuntu: apt-get install libfltk1.4-dev
• RedHat/Fedora: dnf install fltk-devel

For the GLCanvas control, install libegl-dev libgl-dev or libglvnd-devel.

EFL

• Debian/Ubuntu: apt-get install libefl-all-dev
• RedHat/Fedora: dnf install efl

EFL needs this patch applied. You can still compile with distro packages, but you will not be able to open any modal window.

For the GLCanvas control, install libegl-dev libgl-dev or libglvnd-devel.

Other

The library should work on other Unix-like systems, FreeBSD, NetBSD, OpenBSD, DragonFly, Solaris, Illumos, and AIX.

Motif

You can also compile for a time-tested Motif library if GTK or Qt are not available.

• Debian/Ubuntu: apt-get install libmotif-dev libxmu-dev libxpm-dev
• RedHat/Fedora: dnf install motif-devel libXpm-devel

To compile with Xft support, install libxft-dev or libXft-devel.

For the GLCanvas control, install libgl-dev or libglvnd-devel.

GNUstep

The Cocoa driver can also be compiled against GNUstep on Linux/BSD. This relies on the modern Objective-C stack, not the legacy GCC runtime.

Required combo:

• Clang as the compiler (GCC won't do)
• libobjc2 - the Apple-compatible Objective-C runtime, not the legacy libobjc from gcc.
• libdispatch (GCD) - Apple's mainline libdispatch.
• libs-opal - Apple CoreGraphics-compatible drawing layer built on Cairo.
• libs-corebase - CoreFoundation.
• gnustep-base + gnustep-gui 0.32+ (earlier versions are missing APIs the driver uses).
• gnustep-back with the Cairo graphics engine.

Stock distro packages are currently insufficient. Also, several bugs in gnustep-base, gnustep-gui, libs-opal and libs-corebase must be patched. The tarball with the required patches is at gnustep.tar.gz.

-fobjc-runtime=gnustep-2.2 tells Clang to emit Objective-C 2 ABI metadata compatible with libobjc2. Cgo sanitizes compiler/linker flags by default, so you have to pass the flag and unblock it via the env vars:

CC=clang \
CGO_CFLAGS='-fobjc-runtime=gnustep-2.2' \
CGO_LDFLAGS='-fobjc-runtime=gnustep-2.2' \
CGO_CFLAGS_ALLOW='-fobjc-runtime.*' \
CGO_LDFLAGS_ALLOW='-fobjc-runtime.*' \
go build -tags gnustep

Haiku

Native Interface Kit driver. Requires Haiku beta6, haiku_devel ships with a stock Haiku install, so no extra packages are needed.

• For WebBrowser, install haikuwebkit_devel via pkgman install haikuwebkit_devel.
• You can also build for Qt, with the qt build tag. Install deps with pkgman install qt6_base_devel.

Emscripten

Compiles the IUP C driver to WebAssembly and runs the Go app in the browser; every widget renders as a DOM element.

See iup/external/wasm/README.md for prerequisites, build flow, and serving.

Mobile

The same main() compiles as a desktop binary, an Android shared library, and an iOS executable. Every example under examples/ builds unchanged on all three. Most examples are laid out for desktop windows and will overflow a phone screen though; production mobile apps need a layout tuned for small screens. See mobile_sample and mobile_hello for examples designed for mobile. Also check demo_chat that handles both desktop and mobile layouts.

Examples without a top-level Dialog (e.g., alarm, message) will not run on mobile, the host platform requires a real Dialog as the root.

Android

Builds the Go program as a c-shared .so consumed by a Gradle library.

See iup/external/android/README.md for prerequisites, build flow, permissions, and packaging.

For a one-command .apk without the Gradle project, see Packaging.

iOS

The Go binary is the iOS executable; the Cocoa Touch driver calls UIApplicationMain itself.

See iup/external/ios/README.md for prerequisites, signing, and distribution.

For a one-command .ipa, see Packaging.

Build tags

Controls:

Drivers:

Options:

Compiler flags

You can provide explicit compiler and linker flags instead of using the defaults provided by pkg-config. For example, if dependencies are in a non-standard location:

CGO_CFLAGS="-I<include path> ..." CGO_LDFLAGS="-L<dir> -llib ..." go build -tags nopkgconfig

You can also point PKG_CONFIG_LIBDIR to some local directory with custom modified .pc files.

Packaging

iupkg builds and packages a program for distribution: a Windows .exe with icon, version info and manifest, or an .msix, a macOS .app, Linux .tar.gz/.deb/.rpm, an Android .apk, an iOS .ipa, a WebAssembly site or a Haiku .hpkg. Signing is built in: Authenticode, Apple code signing with notarization, APK signing and OpenPGP for the Linux packages, all without platform tools.

$ go install github.com/gen2brain/iup-go/cmd/iupkg@latest

See cmd/iupkg/README.md for every target, flag, and the signing setup.

Documentation

API reference documentation is available at gen2brain.github.io/iup-go, generated from the docs directory. Each Go function links to its corresponding documentation page. Start with the guides on Attributes, Callbacks, Layout and Keyboard. Also check Go Reference and Examples.

Thread-Safety

User interfaces (and OpenGL) are usually not thread-safe, and IUP is not either. Most platforms enforce running UI on the main thread.

The secondary threads (goroutines) should not directly update the UI; instead, use PostMessage, which is expected to be thread-safe. See example that uses PostMessage to send data to an element, which will be received by a callback when the main loop regains control. You can also use Idle and Timer.

Once MainLoop is running, an attribute call from another goroutine panics instead of crashing inside the toolkit. Callbacks of IupThread are exempt, they run on a thread IUP started itself.

Cross-compile (Linux cgo)

To cross-compile for Win32, install MinGW toolchain.

$ CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc GOOS=windows GOARCH=amd64 go build -ldflags "-s -w"
$ file alarm.exe
alarm.exe: PE32+ executable (console) x86-64, for MS Windows

$ CGO_ENABLED=1 CC=i686-w64-mingw32-gcc GOOS=windows GOARCH=386 go build -ldflags "-s -w"
$ file alarm.exe
alarm.exe: PE32 executable (console) Intel 80386, for MS Windows

To cross-compile for WinUI, install LLVM MinGW toolchain.

$ CGO_ENABLED=1 CC=x86_64-w64-mingw32-clang CXX=x86_64-w64-mingw32-clang++ GOOS=windows GOARCH=amd64 go build -tags winui -ldflags "-s -w"
$ file alarm.exe
alarm.exe: PE32+ executable (console) x86-64, for MS Windows, 7 sections

To cross-compile for macOS, install OSXCross toolchain. Ready-made SDK tarballs are available here.

$ CGO_ENABLED=1 CC=x86_64-apple-darwin25-clang GOOS=darwin GOARCH=amd64 go build -ldflags "-s -w"
$ file alarm
alarm: Mach-O 64-bit x86_64 executable, flags:<NOUNDEFS|DYLDLINK|TWOLEVEL|WEAK_DEFINES|BINDS_TO_WEAK>

$ CGO_ENABLED=1 CC=aarch64-apple-darwin25-clang GOOS=darwin GOARCH=arm64 go build -ldflags "-s -w"
$ file alarm
alarm: Mach-O 64-bit arm64 executable, flags:<NOUNDEFS|DYLDLINK|TWOLEVEL|WEAK_DEFINES|BINDS_TO_WEAK|PIE>

Screenshots

See more screenshots.

Credits

• Tecgraf/PUC-Rio
• matwachich

License

iup-go is MIT licensed, same as IUP. View LICENSE.