Setting up the Symbolibre OS and applications

Warning

This page is a work in progress, instructions are incomplete.

This page describes the installation of a desktop environment along with the Symbolibre applications on a Raspbian image. To generate the base system, see Generating an OS from a static-QEMU Raspbian chroot.

The main parts here are:

  • Installing a desktop environment: either X with i3, or Wayland with sway

  • Setting up graphics acceleration

  • Installing Qt libraries and QML modules

  • Compiling and running Symbolibre apps

Quality-of-life settings

Getting privileged access

Graphical applications will run under the unprivileged symbolibre user.

su should be sufficient to switch between users but it can be convenient to set up sudo if you are used to it.

% apt install sudo
% usermod -aG sudo symbolibre

If you don’t, you will have to become root with su root so you should set a password for this account.

% passwd root

For the rest of this tutorial, log into the user account with either su - symbolibre or sudo -iu symbolibre.

Keyboard layout

If you don’t have a QWERTY keyboard, you might want to change the layout of the TTY console. You can do so in the post-install script of console-tools.

% apt install console-tools
# ... follow instructions to select a keyboard layout

  • For the French AZERTY keyboard, select 22 (Other) then 37 (French) then 1 (French).

If prompted, you should set UTF-8 as the encoding on the console (27), and leave the character set of the console to guess (23).

Generate locales

If you plan on using any other locale than the default C/English, edit the list in /etc/locale.gen and run locale-gen. You should always prefer UTF-8 locales when available.

% apt install locales
# edit /etc/locale.gen to uncomment desired locales
% locale-gen

The default terminal emulator in Wayland/sway requires an UTF-8 locale to be set; make sure to select one if you want to take this route.

Configuring tools

If you plan on using a terminal, or applications other than the Symbolibre default, this is a good time to configure core utilities and install tools that are not in the base image.

You can for instance enable colors for ls in .bashrc:

alias ls='ls --color=auto --group-directories-first'
alias ll='ls -lh'

Or install another text editor such as vim (the default is nano, which is the most beginner-friendly):

% apt install vim
% echo "export EDITOR=vim" | tee -a $HOME/.bashrc
% echo "export VISUAL=vim" | tee -a $HOME/.bashrc

Installing a desktop environment

With X and i3

Warning

The X server seems to cope poorly with the modesetting driver used on the the Raspberry Pi (the VC4 KMS driver). Clients can be accelerated but applications that render with X (such as xterm) and the window compositor are very slow.

The first option is to install X with i3. The default configuration file is copied to its standard location in the user home.

% apt install xinit i3
# For safety, install a couple more fonts over xfonts-base
% apt install xfonts-unifont xfonts-75dpi
% mkdir -p $HOME/.config/i3
% cp /etc/i3/config $HOME/.config/i3/

i3 can be started from the console by running startx. The logs are stored in /var/log/Xorg*.log or $HOME/.local/share/xorg/Xorg*.log. The default terminal is xterm.

With Wayland and sway

Alternatively, Wayland can be installed with sway. Once again the configuration file is copied. The settings are very close to i3; the default terminal is a Wayland-native terminal called foot.

% apt install sway xwayland
% mkdir -p $HOME/.config/sway
% cp /etc/sway/config $HOME/.config/sway

sway can be started from the console by running sway. A log can be obtained with sway -d 2> sway.log. If you don’t have a mouse on the Pi Zero, you might want to change the sway exit shortcut to swaymsg exit instead of the default swaynag command that requires you to click on a confirm button to leave the desktop.

bindsym $mod+Shift+E exec swaymsg exit

foot doesn’t start if it’s not using an Unicode locale, so you should set one in $HOME/.bashrc. Additionally, sway overrides the keyboard layout so it should be specified before starting as well.

export LANG='en_US.UTF-8'
# Example for the French AZERTY keyboard
export XKB_DEFAULT_LAYOUT=fr
export XKB_DEFAULT_VARIANT=basic

Configuring graphics acceleration

The Raspberry Pi series come with a GPU of the VideoCore family, and the Pi Zero GPU in particular is based on VideoCore 4. The Linux open-source driver for VC4 is maintainted by Eric Anholt and integrated into MESA since 2014. It offers a mode-setting interface through Linux’s KMS.

The first step is to enable the VC4 module in the boot configuration and allocate enough memory to the GPU. The 512 MiB Pi memory is shared between CPU and GPU so anything that is specified as GPU memory is not available for applications.

In /boot/config.txt, load the device tree overlay that assigns the VC4 driver to the GPU and add some GPU memory.

dtoverlay=vc4-kms-d3d
gpu_mem=128

For user processes to be able to access the GPU (which is for instance needed by sway since Wayland compositors don’t run as root), symbolibre should be a member of the video group.

% usermod -a -G video symbolibre

The group change takes effect at login and the boot configuration at boot, so now is a good time to shut down and restart the Pi.

When you log in with this new setup, the vc4 driver should have been loaded automatically; lsmod | grep vc4 should show it along with its dependencies.

Both X and Wayland will automatically use this new driver to perform rendering. X will select the modesetting driver and enable acceleration:

  • For the server, Glamor will be enabled on the KMS device.

  • For clients, DRI2 will be enabled, letting applications perform GPU rendering without talking to the server.

However, as mentioned earlier, the Glamor half of that setup performs very poorly in our test setups. This makes window movement and resizing, as well as rendering in the server, very slow (even slower than with software rendering as provided by the fbdev driver). Applications like glxgears that use DRI2 run very smoothly but applications that render through the X server like xterm are extremely slow.

On Wayland, sway will auto-detect the GPU at /dev/dri/card0 (the dri here has nothing to do with the X server’s DRI2 technology and just represents the GPU) and use KMS with VC4 without any other configuration.

To test client rendering, you can install the mesa-utils package, which provides tools to check the configuration and performance of the display, such as glxinfo and glxgears.

% apt install mesa-utils

Native Wayland applications or X applications that support DRI through XWayland will use accelerated rendering. This is for instance the case with foot, but not with xterm, so not every program will run smoothly even with sway.

Installing libraries for the Symbolibre applications

We want to install the Qt framework with Qt Quick and a couple of QML modules. Some of these have GLES variants, but not all packages down the dependency tree support these alternatives, so we install the normal set.

First is the Qt framework, with Qt Quick, Qt Quick Controls 2, developer tools (mainly for translation support), and direct Wayland support. In addition, a couple of QML modules used by the Symbolibre applications.

% apt install qtbase5-dev qtdeclarative5-dev qtquickcontrols2-5-dev qttools5-dev qtwayland5
% apt install qml-module-qtquick2 qml-module-qtquick-window2 qml-module-qtquick-controls2 qml-module-qtquick-layouts qml-module-qt-labs-folderlistmodel

For the Symbolibre applications, we need building tools, a couple of libraries (graph rendering, syntax highlighting, Giac mainly), and some packages that Qt and Giac depend on but are not listed as such.

% apt install build-essential cmake
% apt install libgmp-dev libmpfi-dev libgsl-dev libntl-dev libfltk1.3-dev libutf8proc-dev
% apt install libqcustomplot-dev libgiac-dev libkf5syntaxhighlighting-dev libqtermwidget5-0-dev

Finally, there are interpreters for the languages supported by the IDE app.

% apt install python3
% apt install xcas

Building the Symbolibre applications

Download a copy of the release from the symbolibre repository. You can’t download Github’s automatic ZIP directly because it doesn’t have the submodule in the theme folder; you would need to download it separately from the symbolibre-theme repository.

% sudo apt install wget
% wget https://github.com/symbolibre/symbolibre/releases/download/v0.2/symbolibre-0.2.tar.gz
% tar -xzvf symbolibre-0.2.tar.gz && cd symbolibre-0.2

Configure the build in a build directory. CMake attemps (and fails) to read /proc/cpuinfo to determine the number of CPU cores, but it doesn’t prevent you from building in parallel.

We install in /usr/local which is not a search path for libraries by default, se we set the rpath of the executable to reference them (an alternative would be to add /usr/local/lib to the user’s LD_LIBRARY_PATH at login).

% mkdir build && cd build
% cmake .. -DSET_RPATH=ON

The build and install.

% make -j$(nproc)
% make install

The calculator’s main menu can be started with the symbolibre command. QML files are compiled at runtime and the results are cached, so startup is a bit faster after the first time.