Nana C++ Library: A Standard-Style GUI Toolkit for Modern C++

What Nana Is For, and Who Ends Up Using It

Nana is a C++ GUI library whose stated goal is to let developers create cross-platform GUI applications in modern C++ style. The README describes it as standard-like, which is the design claim that separates it from older C++ toolkits: the API is meant to read like the rest of the standard library rather than like a separate dialect. The repository topics list c-plus-plus-11, c-plus-plus-14 and c-plus-plus-17 alongside template-metaprogramming, so the intended audience is a developer already comfortable with modern C++ who wants a window and a widget set without adopting a framework that dictates the build system.

The practical target is a desktop tool. The README's own example is a form, which is the Nana name for a window, and the library ships the pieces a small application needs: widgets, an event loop, and drawing. It is not a web view wrapper and it is not a retained-mode application framework with data binding. If your program is a utility that opens a window, takes input, and draws something, that is the shape Nana is built for.

How the Source Tree Is Organized and What the Runtime Does

The repository is a source distribution. The top level holds CMakeLists.txt, LICENSE, README.md, how-to-install.txt, and the two directories that matter for reading the code: include/ and source/. There is also extrlib/, which the README does not describe but which sits alongside the library directories, and build/, plus CI configuration in .travis.yml and appveyor.yml. Those two files are consistent with the README's claim that the library is regularly tested on Linux X11 and Windows.

The platform story is explicit in the README: Linux(X11) and Windows are regularly tested, while macOS and FreeBSD are experimental. That is a statement about where the maintainers run the test matrix, not about what compiles. Treat the experimental label as a warning that macOS and FreeBSD paths receive less attention.

The runtime model is conventional. You construct a form, show it, and hand control to nana::exec(), which runs the event loop and does not return until the loop ends. Widgets are created against a form and events are attached to them. Because the library is header-and-source rather than header-only, an application links against the compiled library, and the include path is the include/ directory. The template-metaprogramming topic suggests some of the widget and event plumbing is resolved at compile time, which is where the standard-like feel comes from: you get typed callbacks rather than void pointers.

Installing Nana and Opening a First Window

The repository points at how-to-install.txt at the top level for build instructions, and the documentation site at https://nana.acemind.cn/documentation is where the README sends you for help. The build is driven by CMakeLists.txt, so the first step is configuring with CMake and then building the library target. The README does not spell out the exact CMake invocations, so read how-to-install.txt for the platform-specific steps before running anything.

Once the library is built and installed, the README's own example is the smallest useful program. It includes one header, creates a form, shows it, and enters the event loop:

#include <nana/gui.hpp>

int main()
{
    nana::form fm;
    fm.show();
    nana::exec();
}

Compile that against the Nana include directory and link the library. When it runs you should see an empty window appear and stay open until you close it; nana::exec() blocks until the loop exits, so a program that returns immediately means the form was never shown or the loop was never entered.

The next step is adding a widget to the form rather than drawing on it directly. The README does not walk through widget placement, so the documentation site is the place to look for the widget classes and their event hooks. What the README does establish is the branching rule for contributions, and it is worth knowing before you file a patch: do not commit directly to master. Choose the hotfixes branch or the develop branch depending on what your change is.

Release Tags, Branch Policy, and the Cost of Upgrading

The release history is the weakest part of the project's public surface. The most recent release is v1.7-alpha, tagged on 2019-02-20. Before that, v1.3.0-beta was tagged on 2016-01-31 as a pre-release. Both of the tags the repository exposes are pre-releases, and the newest one is an alpha. That means there is no stable, recent release tag to pin against, and an adopter has to decide whether to track a branch instead.

The branch layout is documented and deliberate. master is the main branch and is marked at every version release. develop carries the latest delivered development changes for the next release. Feature work goes on branches named feature-FEATURENAME, and hotfix branches prepare a new release and fix bugs from the corresponding tag on master. This is a standard git-flow arrangement, and the practical consequence is that if you want the newest code you are tracking develop, which by definition is not the released state. If you want the released state you are on master, whose last tag is an alpha from 2019.

The last push to the repository was on 2026-08-01, so the project is not abandoned at the commit level even though the tags are old. That gap between commit activity and tagged releases is the thing to weigh: you can get current code, but you cannot get a current version number. Upgrading later means diffing against a moving branch rather than moving between two tags, and there is no changelog in the repository listing that would tell you what changed.

Where Nana Is the Wrong Choice

The clearest limitation is platform coverage. The README states that macOS and FreeBSD are tested experimentally. If macOS is a shipping target for you, that sentence should decide the question, because experimental support in a GUI library means the windowing and drawing paths on that platform have not been through the same testing as X11 and Windows. You would be the one finding the gaps.

The second limitation is documentation depth. The README is short, and it delegates to the documentation site for anything beyond the window example. It does not document widget layout, event signatures, drawing, or the build options in any detail. The repository does include how-to-install.txt, which suggests the install path is covered somewhere, but the README itself gives no install commands. A team that needs to answer questions from a single repository checkout will be reading source code.

The third is the release situation described above. A project with an alpha as its newest tag is hard to fit into a dependency policy that expects versioned, stable artifacts. If your process requires pinning to a stable release and reviewing a changelog before upgrading, Nana does not currently offer that.

Nana Against Qt and Dear ImGui

The obvious comparison is Qt. Qt is a full application framework: it brings its own build system, meta-object compiler, signal and slot mechanism, and a widget set that spans desktop and mobile. Nana's approach is narrower. It is a library you link, not a framework you build inside, and its API is meant to look like the C++ standard library rather than like a Qt-specific dialect with generated code. If you want a small window and a handful of controls, Qt's machinery is more than you asked for; if you want a mature widget set with a long release history, Qt is the safer pick and Nana is not competing on that axis.

Dear ImGui takes a different approach again: it is an immediate-mode GUI, where you redraw the interface every frame and the UI state lives in your code rather than in persistent widget objects. Nana is a retained-mode toolkit, so a form and its widgets exist as objects and events are dispatched to them. That makes Nana a better fit for a conventional desktop application with a fixed layout, and immediate-mode tooling a better fit for tools with dynamic, data-driven panels. The two are not substitutes; the choice follows from whether your interface is a form or a frame.

Licence and What It Means for Linking

Nana is licensed under the Boost Software License, identified in the repository as BSL-1.0, and the README links to the canonical text at boost.org. The BSL is a permissive licence: it allows use in both open source and proprietary software, and it does not require you to release your own source. For a library you link into a desktop application, that is the permissive end of the spectrum and it removes the licence as a reason not to evaluate Nana.

The repository ships a LICENSE file at the top level, which is the text that governs your use; read that file rather than the badge. This is not legal advice, and if your organization has a policy on permissive licences or on attribution notices, the exact wording in LICENSE is what your policy needs to be checked against.

Editorial conclusion

Adopt Nana if you are writing a small or medium desktop tool in C++11 or later and want a form, a button and an event loop without pulling in a framework with its own build system. Do not adopt it if you need macOS or FreeBSD as a first-class target, since the README calls those experimental, or if you need a release cadence you can plan around, because the newest tag is v1.7-alpha from 2019. Before committing, read how-to-install.txt at the repository root, check CMakeLists.txt for the options on your platform, and build the five-line form example from the README to confirm your toolchain links against the library.

Frequently asked questions

Official sources

1. cnjinhao/nana on GitHub
2. License: BSL-1.0
3. Project website
4. README
5. Releases