SARibbon Build Instructions¶
- ✅ Static approach: add
SARibbon.h+SARibbon.cppdirectly — no build needed - ✅ Dynamic library build: CMake-based, with compiler/version-isolated install
- ✅ Optional QWindowKit: native OS window features (snap layout, multi-monitor)
Tip
You don't need to compile SARibbon — just add SARibbon.h and SARibbon.cpp (located in the src directory) to your project.
This document explains in detail how to build SARibbon dynamically.
If you are not familiar with building, we recommend the static approach: simply add SARibbon.h and SARibbon.cpp to your project and you are ready to go.
Sub-document Navigation¶
| Document | Content |
|---|---|
| Building SARibbon Library | CMake build options and detailed steps |
| Third-Party Library Build | Optional: build, upgrade or debug QWindowKit separately |
| Common Build Errors | Troubleshooting compilation issues |
| Internationalization | Translation file generation and new languages |
Build Workflow Overview¶
SARibbon builds from a single project: with SARIBBON_USE_FRAMELESS_LIB enabled, the top-level CMake automatically builds the bundled QWindowKit, so there is no separate third-party build step.
flowchart TD
A[Start Build] --> B{Need native window features?}
B -->|Yes| C[Set SARIBBON_USE_FRAMELESS_LIB=ON<br/>top-level build compiles QWindowKit]
B -->|No| D[Skip QWindowKit]
C --> E[Build SARibbon library]
D --> E
E --> F[Install to local directory]
F --> G[Reference library in project]
Note
SARibbon removed qmake-based builds after v2.6.3 and only supports CMake. If you need qmake support, use v2.6.2 or earlier.
QWindowKit Third-Party Library¶
SARibbon uses QWindowKit as its borderless-window solution, while also supporting a simple built-in borderless mode. If you need native OS window features, such as Windows 7+ snap-to-edge handling or Windows 11 Snap Layout effects, it is recommended to enable the QWindowKit library. This library also effectively addresses multi-monitor movement issues.
After enabling QWindowKit, you will be able to achieve effects like:

To enable QWindowKit, just turn on SARIBBON_USE_FRAMELESS_LIB in the top-level CMake:
1 | |
QWindowKit is resolved in this order:
- A package specified by
-DQWindowKit_DIR, or provided by vcpkg; - The bundled source at
src/SARibbonBar/3rdparty/qwindowkit, built directly as a subdirectory (recommended, no extra steps); - A package previously installed under
bin_qt.../lib/cmake/QWindowKit; - The system installation path.
Building from source requires CMake 3.19 or newer. The first configure also builds QWindowKit's qmsetup helper, so it takes a little longer; later configures reuse the cache.
Note
If the repository was cloned without --recursive (or nested submodules are incomplete), CMake runs git submodule update --init --recursive automatically at configure time (disable with -DSARIBBON_QWK_AUTO_INIT_SUBMODULE=OFF). Users who downloaded a source ZIP have no git metadata and must either place the QWindowKit source at src/SARibbonBar/3rdparty/qwindowkit manually or point -DQWindowKit_DIR at a prebuilt package.
To build, upgrade or debug QWindowKit separately, see Third-Party Library Build.
Building the SARibbon Library¶
SARibbon only supports the CMake build approach (qmake support was removed after v2.6.3). For detailed build steps and configuration options, see Building SARibbon Library.
If you encounter issues during the build process, see Common Build Errors.
Installation Location¶
After CMake finishes building, the install target will deploy all dependencies.
Consumers can simply call find_package to pull in libraries, dependencies and predefined macros—this is the recommended workflow.
During development, however, you often need to switch between compilers (MSVC, MinGW, …) and Qt versions.
Using the default global location (e.g. C:\Program Files on Windows) allows only one variant to be installed at a time.
To keep builds isolated, SARibbon defaults to local installation.
A folder is created whose name encodes the Qt version and compiler, e.g.
bin_qt{version}_[MSVC|GNU]_x[64|86].
You can control this behaviour with the CMake option
SARIBBON_INSTALL_IN_CURRENT_DIR (default ON).
When ON, the above local folder is used; when OFF, the standard system location is used.