LibYUI - Widget Abstraction Library
Libyui is a widget abstraction library providing graphical (Qt) and text-based (NCurses) front-ends.
There is also a Gtk front-end with (limited) community support.
Originally, libyui was developed for YaST, but it can be also used in independent projects.
End User's Perspective: Selecting the UI plug-in
By default, libyui tries to load any of the available UI plug-ins in this order:
- if $DISPLAY is set
- NCurses is user-selected and stdout is not a TTY
- if $DISPLAY is set and Qt is not available,
- a GTK-based desktop environment is detected from the XDG_CURRENT_DESKTOP environment variable
- any of the above pre-conditions are met and NCurses is user-selected, but stdout is not a TTY
- if $DISPLAY is not set and stdout is a TTY
- Qt and Gtk are not available and stdout is a TTY
This default behaviour can be overridden by either:
unsetting the DISPLAY environment variable to force NCurses:
setting the environment variable YUI_PREFERED_BACKEND to one of
specifing one of the switches on the command line of the program:
This overrides the environment variable.
If the user-selected UI plug-in is not installed on the system, an installed UI plug-in will be chosen by the above criteria.
Developer's and Packager's Perspective
Components and Subprojects
This source repository contains the officially supported components as subprojects:
libyui: This is the base library that defines the API.
libyui-qt: The Qt UI front-end
libyui-qt-pkg: The package selector extension based on libzypp for the Qt UI
libyui-qt-graph: A Qt UI extension for displaying Graphviz files
libyui-ncurses: The NCurses (text-based) front-end
libyui-ncurses-pkg: The package selector extension based on libzypp for the NCurses UI
libyui-rest-api: A REST API for introspection and widgets remote control from a QA environment
libyui-qt-rest-api: The Qt UI extension for the REST API
libyui-ncurses-rest-api: The NCurses UI extension for the REST API
libyui-bindings: SWIG bindings for Python, Perl, Ruby and Mono
Notice that YaST does not use this, it uses yast-ycp-ui-bindings based on YCPValue container classes.
There are also community-maintained components in separate repositories like
- libyui-gtk: The Gtk UI front-end
- libyui-mga: Extensions for Mageia Linux
Each subproject is self-sufficient (except for the shared VERSION.cmake file in
the toplevel directory) and can be built separately. They all use CMake, and
most operations are available from a very simple
Makefile.repo file in the
subprojects directory. Of course you can also simply invoke cmake manually.
Building Manually in a Subproject
Using the Qt UI as an example:
cd libyui-qt make -f Makefile.repo cd build make sudo make install
cd libyui-qt make -f Makefile.repo build sudo make -C build install
Clean up with
rm -rf build
make -f Makefile.repo clean
Do all of this for the needed subprojects in order.
For non-YaST projects you may want to omit the -pkg and -graph parts, but build the bindings:
Building all Subprojects at Once
build-all script in the project toplevel directory; it will build
each needed subproject in the correct sequence.
Call it with
--dry-run) to see what it would do:
./build-all -n *** Dry run - not executing any make commands *** make -C libyui -f Makefile.repo build make -C libyui-qt -f Makefile.repo build make -C libyui-qt-graph -f Makefile.repo build make -C libyui-qt-pkg -f Makefile.repo build make -C libyui-ncurses -f Makefile.repo build make -C libyui-ncurses-pkg -f Makefile.repo build
For non-YaST projects, use
-s -b (
--small --bindings) for a small build
with the subprojects that are typically needed:
./build-all -n -s -b *** Dry run - not executing any make commands *** make -C libyui -f Makefile.repo build make -C libyui-qt -f Makefile.repo build make -C libyui-ncurses -f Makefile.repo build make -C libyui-bindings -f Makefile.repo build
--all) to build all subprojects:
./build-all -n -a *** Dry run - not executing any make commands *** make -C libyui -f Makefile.repo build make -C libyui-qt -f Makefile.repo build make -C libyui-qt-graph -f Makefile.repo build make -C libyui-qt-pkg -f Makefile.repo build make -C libyui-ncurses -f Makefile.repo build make -C libyui-ncurses-pkg -f Makefile.repo build make -C libyui-rest-api -f Makefile.repo build make -C libyui-qt-rest-api -f Makefile.repo build make -C libyui-ncurses-rest-api -f Makefile.repo build make -C libyui-bindings -f Makefile.repo build
or explicitly select subprojects to build with or without like
./build-all -h for an up-to-date complete list.
Daily Development Work: Keeping an Existing Build
When working on libyui, it is common to change or add a class on the abstract libyui level, then extend the concrete implementation in the Qt and NCurses UIs; you don't want to rebuild everything from scratch after every little change.
If you use
build-all build, it will do just that: It will remove each
build/ subdirectory in each subproject, recreate it, invoke
If you simply call it without any make target, however, it will check in each
subproject if there is an existing
build/ subdirectory, and if there is, just
make. If there is no
build/ subdirectory, it will call
make -f Makefile.repo build instead. Notice that this handles each subproject
individually, so you can have a mixture of existing and non-existing
This builds everything from scratch.
Now continue editing files in subprojects and then
This now just invokes
make in each subproject, keeping the object
files for unchanged sources.
Of course you need root permissions to install any file to the system:
./build-all sudo ./build-all install
Keeping Changes Locally in the Source Tree
The CMake environments in the subprojects are set up to prefer header files and
built libraries from sibling subprojects over those from the system; so you can
work for a long time in the source tree without a need for
sudo make install.
All packages in this source tree have the same version numer; that's why the
subprojects share the toplevel
The general idea is to enable transaction-like changes on the libyui base packages to avoid long delays in the distribution build cycle and broken builds:
Some parts may have become incompatible, yet the higher-level parts require the base lib parts to be published as a prerequisite for building. In the past, this resulted in staging projects not building; manual interaction was often needed to break depencency cycles.
The version numbers are also in all the .spec files in the
subdirectory, so they need to be kept consistent among each other and with the
For a simple version number increment, use
that does the required changes consistently.
This requires some more packages to be installed:
- rake (part of the ruby base package on SUSE distributions)
- the packaging_rake_tasks ruby gem
- the libyui-rake ruby gem
At the time of this writing, those packages were named
I.e. the package name of the gems contains the ruby version.
zypper search to find the current complete package name.
Binary Compatibility and SO Version
Whenever there is an ABI change, the SO version needs to be bumped to the next
higher number, also in the toplevel
VERSION.cmake and in all .spec files in
(same package requirements as above)
The abstract libyui class uses the PIMPL idiom for API classes such as the
widgets: Each of the widget classes only has one single data member, the
pointer that holds a pointer to a private class holding all the real data
(e.g. YPushButtonPrivate). Adding data members to that private class is
perfectly safe and does not change the ABI (Application Binary Interface).
However, beware of any of the following (incomplete list):
Data members are added to YUI or any similar class that is inherited in UI plug-ins
Virtual functions are added or removed in API classes (or, again, in general in classes like YUI that are inherited in UI plug-ins)
The order of virtual functions is changed (!) in any such class
The inheritance hierarchy between API classes changes
Enum values are added or removed
You can add a new virtual function at the end of a class.
You can add a new enum value at the end of the enum.
If there is any doubt, better bump the SO version once too many rather than once not enough. Making this easy and painless was one rationale behind the changed libyui build environment and repo structure in early 2021, so please use it.
Building with Prefix
To install to another directory than
/usr, set CMAKE_INSTALL_PREFIX;
either for each
cmake call individually with
-D or in the environment:
mkdir build cd build cmake -DCMAKE_INSTALL_PREFIX=/usr/local .. make && make install
CMAKE_INSTALL_PREFIX=/usr/local build-all -s
For reproducible builds it is best to use the libyui-rake Ruby gem like the Jenkins CI jobs do.
It can be installed from rubygems.org using this command (Ruby needs to be installed in the system):
gem install libyui-rake
Then to build the package run:
Tips and Tricks
- Interactive libyui dialog introspection with YDialogSpy
- Magic key combinations
Please visit the documentation at the doc folder for more information about how to branch libyui and about auto-tagging new versions.