Repository files navigation

Libyui is a widget abstraction library providing graphical (Qt) andtext-based (NCurses) front-ends.

There is also a Gtk front-end with (limited) community support.

Originally, libyui was developed forYaST, but itcan be also used in independent projects.

By default, libyui tries to load any of the available UI plug-ins in this order:

• Qt:

  • if $DISPLAY is set
  • NCurses is user-selected and stdout isnot a TTY

• Gtk:

  • if $DISPLAY is set and Qt is not available,
  • a GTK-based desktop environment is detected from the XDG_CURRENT_DESKTOPenvironment variable
  • any of the above pre-conditions are met and NCurses is user-selected, butstdout isnot a TTY

• NCurses:

  • if $DISPLAY isnot 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:

  DISPLAY="" myprogram

• setting the environment variable YUI_PREFERED_BACKEND to one of

  • gtk
  • ncurses
  • qt

• specifing one of the switches on the command line of the program:

  • --gtk
  • --ncurses
  • --qt

  This overrides the environment variable.

If the user-selected UI plug-in is not installed on the system, an installedUI plug-in will be chosen by the above criteria.

This source repository contains the officially supported components assubprojects:

• 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 theNCurses UI

• libyui-rest-api: A REST API for introspection and widgets remote control froma 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 onYCPValue 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 inthe toplevel directory) and can be built separately. They all use CMake, andmost operations are available from a very simpleMakefile.repo file in thesubprojects directory. Of course you can also simply invokecmake manually.

Using the Qt UI as an example:

cd libyui-qtmake -f Makefile.repocd buildmakesudo make install

or

cd libyui-qtmake -f Makefile.repo buildsudo make -C build install

Clean up with

rm -rf build

or

make -f Makefile.repo clean

Do all of this for the needed subprojects in order.

For YaST:

• libyui
• libyui-qt
• libyui-qt-pkg
• libyui-qt-graph
• libyui-ncurses
• libyui-ncurses-pkg

For non-YaST projects you may want to omit the -pkg and -graph parts, but buildthe bindings:

• libyui
• libyui-qt
• libyui-ncurses
• libyui-bindings

Use thebuild-all script in the project toplevel directory; it will buildeach needed subproject in the correct sequence.

Call it with-n (--dry-run) to see what itwould do:

./build-all -n*** Dry run - not executing any make commands ***make -C libyui -f Makefile.repo buildmake -C libyui-qt -f Makefile.repo buildmake -C libyui-qt-graph -f Makefile.repo buildmake -C libyui-qt-pkg -f Makefile.repo buildmake -C libyui-ncurses -f Makefile.repo buildmake -C libyui-ncurses-pkg -f Makefile.repo build

For non-YaST projects, use-s -b (--small --bindings) for a small buildwith the subprojects that are typically needed:

./build-all -n -s -b*** Dry run - not executing any make commands ***make -C libyui -f Makefile.repo buildmake -C libyui-qt -f Makefile.repo buildmake -C libyui-ncurses -f Makefile.repo buildmake -C libyui-bindings -f Makefile.repo build

or-a (--all) to build all subprojects:

./build-all -n -a*** Dry run - not executing any make commands ***make -C libyui -f Makefile.repo buildmake -C libyui-qt -f Makefile.repo buildmake -C libyui-qt-graph -f Makefile.repo buildmake -C libyui-qt-pkg -f Makefile.repo buildmake -C libyui-ncurses -f Makefile.repo buildmake -C libyui-ncurses-pkg -f Makefile.repo buildmake -C libyui-rest-api -f Makefile.repo buildmake -C libyui-qt-rest-api -f Makefile.repo buildmake -C libyui-ncurses-rest-api -f Makefile.repo buildmake -C libyui-bindings -f Makefile.repo build

or explicitly select subprojects to build with or without like-p (--no-pkg) or-g (--no-graph) or-r (--rest-api).See./build-all -h for an up-to-date complete list.

When working on libyui, it is common to change or add a class on the abstractlibyui level, then extend the concrete implementation in the Qt and NCursesUIs; you don't want to rebuild everything from scratch after every littlechange.

If you usebuild-all build, it will do just that: It will remove eachbuild/ subdirectory in each subproject, recreate it, invokecmake, thenmake.

If you simply call it without any make target, however, it will check in eachsubproject if there is an existingbuild/ subdirectory, and if there is, justcallmake. If there is nobuild/ subdirectory, it will callmake -f Makefile.repo build instead. Notice that this handles each subprojectindividually, so you can have a mixture of existing and non-existingbuild/subdirectories.

./build-all

This builds everything from scratch.

Now continue editing files in subprojects and then

./build-all

This now just invokesmake in each subproject, keeping the objectfiles for unchanged sources.

Of course you need root permissions to install any file to the system:

./build-allsudo ./build-all install

The CMake environments in the subprojects are set up to prefer header files andbuilt libraries from sibling subprojects over those from the system; so you canwork for a long time in the source tree without a need forsudo make install.

All packages in this source tree have the same version numer; that's why thesubprojects share the toplevelVERSION.cmake file.

The general idea is to enable transaction-like changes on the libyui basepackages to avoid long delays in the distribution build cycle and broken builds:

Some parts may have become incompatible, yet the higher-level parts require thebase lib parts to be published as a prerequisite for building. In the past,this resulted in staging projects not building; manual interaction was oftenneeded to break depencency cycles.

The version numbers are also in all the .spec files in thepackage/subdirectory, so they need to be kept consistent among each other and with theVERSION.cmake file.

For a simple version number increment, use

rake version:bump

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

• ruby2.7
• ruby2.7-rubygem-libyui-rake
• ruby2.7-rubygem-packaging_rake_tasks

I.e. the package name of the gems contains the ruby version.Usezypper search to find the current complete package name.

Whenever there is an ABI change, the SO version needs to be bumped to the nexthigher number, also in the toplevelVERSION.cmake and in all .spec files inthepackage/ subdirectory.

Use

rake so_version:bump

(same package requirements as above)

The abstract libyui class uses the PIMPL idiom for API classes such as thewidgets: Each of the widget classes only has one single data member, theprivpointer that holds a pointer to a private class holding all the real data(e.g. YPushButtonPrivate). Adding data members to that private class isperfectly 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 UIplug-ins

• Virtual functions are added or removed in API classes (or, again, in generalin 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

Exceptions:

• 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 thanonce not enough. Making this easy and painless was one rationale behind thechanged libyui build environment and repo structure in early 2021, so pleaseuse it.

To install to another directory than/usr, set CMAKE_INSTALL_PREFIX;either for eachcmake call individually with-D or in the environment:

mkdir buildcd buildcmake -DCMAKE_INSTALL_PREFIX=/usr/local ..make && make install

or

CMAKE_INSTALL_PREFIX=/usr/local build-all -s

For reproducible builds it is best to use thelibyui-rakeRuby gem like theJenkins CI jobs do.

It can be installed fromrubygems.orgusing this command (Ruby needs to be installed in the system):

gem install libyui-rake

Then to build the package run:

rake osc:build

• C++ API documentation
• Widgets documentation
• UI layout and events

• Interactive libyui dialog introspection withYDialogSpy
• Magic key combinations

Please visit the documentation at thedoc folderfor more information abouthow to branchlibyui and aboutauto-taggingnew versions.