README.md

June 3, 2026 ยท View on GitHub

IUP-Go

Build Status Go Reference

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, FLTK, EFL, Motif, GNUstep), Haiku (Interface Kit), WebAssembly (Emscripten), Android (Android), and iOS (CocoaTouch).

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

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 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 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 build tag. Install deps with pacman -S mingw-w64-x86_64-qt6-base.
  • You can build for GTK, with the gtk/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.

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 requirement is to have Microsoft.WindowsAppRuntime.Bootstrap.dll and resources.pri files next to the .exe file. You can find those files in Microsoft.WindowsAppSDK that you can install with nuget install Microsoft.WindowsAppSDK.

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 ~4 MB.

macOS

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

To create an .app bundle or .dmg image, check this gist.

  • You can build for Qt, with the qt build tag. Install deps with brew install qt.
  • You can build for GTK, with the gtk/gtk4 build tag. Install deps with brew install gtk+3 / gtk4.
  • You can build for FLTK, with the fltk build tag. Install deps with brew install fltk.

Linux

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

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

Note that 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.

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).

Stock distro packages are currently insufficient. Also, several bugs in gnustep-base, gnustep-gui, libs-opal and libs-corebase must be patched. 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. gnustep-config --objc-flags expands to this plus include paths; the Makefiles pick it up automatically, but CGo does not.

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 a Haiku nightly (or beta6 once released). haiku_devel ships with a stock Haiku install, no extra packages 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.

Tested with the gen2brain/go Haiku port of the Go toolchain.

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.

iup.EntryPoint(main) registers main as the callback the platform fires after launch; on desktop it is a no-op and the Go runtime calls main directly. iup.Close() and iup.MainLoop() are no-ops on mobile (the host platform owns the lifecycle), so avoid scheduling cleanup after iup.MainLoop().

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.

iOS

The Go binary IS the iOS executable; the CocoaTouch driver calls UIApplicationMain itself.

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

Build tags

  • gl - build with support for GLCanvas control
  • web - build with support for WebBrowser control
  • plot - build with support for Plot control
  • ctrl - build with support for Matrix, Cells, and Flat* controls
  • gtk - use GTK in macOS or Windows
  • gtk4 - build for GTK4, default is GTK3
  • gtk2 - build for GTK2 (Linux/Unix)
  • qt - build for the Qt framework
  • qt5 - build for Qt5 version, default is Qt6 (used with qt)
  • fltk - build for FLTK (Fast Light Toolkit)
  • efl - build for EFL (Enlightenment Foundation Libraries)
  • motif - build for X11/Motif 2.x environment
  • gnustep - build for GNUstep (Linux/BSD)
  • xft - build with Xft support (X FreeType interface) (used with motif)
  • xembed - use XEmbed tray protocol instead of SNI (GTK3/GTK2 and Motif)
  • nomanifest - do not include manifest in Windows build
  • nopkgconfig - do not use pkg-config for compile and link flags

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 nopkconfig

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

Documentation

API reference documentation is available in the docs directory. Each Go function link to its corresponding documentation page. Also check Go Reference and Examples. For the original IUP reference, visit IUP's website.

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.

Cross-compile (Linux)

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

License

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