Setting up the Symbolibre OS and applications¶
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
Getting privileged access¶
Graphical applications will run under the unprivileged
su should be sufficient to switch between users but it can be convenient to
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
sudo -iu symbolibre.
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
% 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).
If you plan on using any other locale than the default C/English, edit the list
/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.
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
alias ls='ls --color=auto --group-directories-first' alias ll='ls -lh'
Or install another text editor such as
vim (the default is
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¶
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
$HOME/.local/share/xorg/Xorg*.log. The default
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
% 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
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
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
$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.
/boot/config.txt, load the device tree overlay that assigns the VC4
driver to the GPU and add some GPU memory.
For user processes to be able to access the GPU (which is for instance needed
sway since Wayland compositors don’t run as root),
be a member of the
% 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
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
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
% 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
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
theme folder; you would need to download it separately from the
% 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.