Espresso Linux

Using Espresso

What to know once Espresso boots. If it doesn't boot yet, start with the install guide.

Packages

bean update              # fetch the package index
bean upgrade             # upgrade everything
bean install mpv         # install with dependencies
bean remove mpv
bean autoremove          # remove dependencies nothing needs any more
bean search player       # search names and descriptions
bean info mpv            # version, size, dependencies
bean files mpv           # what it installed
bean owns /usr/bin/ffmpeg
bean verify              # check installed files against their checksums
bean list -e             # what you installed by name

-n shows what a command would do without doing it, and -y skips the confirmation. The configuration is /etc/bean.conf. Every bean update checks the index's signature against /etc/bean/espresso.pub, so a tampered mirror is refused.

Building your own packages

Packages are built from recipes in the bean repository, and you can build any of them, or your own, the same way:

bean install gcc make mercurial
hg clone https://hg.charliesmp.net/bean && cd bean
echo 'BEAN_UPLOAD=' >> ~/.config/bean-build.conf   # build locally, don't publish
tools/bean-build zlib
doas bean install ~/espresso-repo/zlib-*.bean

A recipe is a short shell file, recipes/<name>:

name=zlib
version=1.3.1-1
desc="Compression library"
url=https://zlib.net
license=Zlib
depends="uclibc-ng"
makedepends=""
source=https://zlib.net/zlib-1.3.1.tar.gz

build() {
    ./configure --prefix=/usr
    make -j"$JOBS"
    make DESTDIR="$STAGE" install
}

Each build runs in a fresh copy of the source. Its depends and makedepends are installed into a private $DEPS tree, and CPPFLAGS, LDFLAGS and PKG_CONFIG_PATH point there, so ./configure finds them. Turn off a project's auto-detection where it has it (--disable-autodetect, meson's -Dauto_features=disabled): otherwise it can pick up a library that happens to be installed on your machine but isn't in depends, and the package breaks on machines without it.

Boot and services

/init mounts the kernel filesystems, runs /etc/rc once, and keeps a login prompt on tty1-4 and ttyS0. There's no service manager: /etc/rc is a shell script, and anything long-running goes in it with &. Out of the box it starts hotplug, sets the sound volume, brings up wired networking with sdhcp and starts Wi-Fi if eiwd is installed. For SSH:

bean install dropbear
echo 'dropbear -R' >> /etc/rc

Devices

smdev creates device nodes with the right owners, and nldev runs it again whenever something is plugged in. Access goes by group:

GroupGives
audiosound cards: /dev/snd/*, /dev/dsp*, /dev/mixer*
wheelUSB devices (adb, fastboot), /dev/kvm, and root through doas

Graphics and input devices (/dev/dri, /dev/input) stay root-only: swc-launch opens them for the compositor. adduser puts new users in wheel, audio, video and input. Log out and back in after changing your groups.

Sound

There's no ALSA library and no sound server. Programs open the kernel's devices directly: tinyalsa for ALSA, or the kernel's OSS emulation (/dev/dsp) for programs like mpv. Each card is a number:

cat /proc/asound/cards           # e.g. 0 = HDMI, 1 = PCH (speakers, headphones)
tinymix -D 1 set 'Master Playback Volume' 60%
flacplay -D 1 song.flac

/etc/rc unmutes every card and sets its Master volume to 80% at boot; edit it to change that. Only one program can play at a time on a card, since nothing mixes streams. A kernel needs SND_HDA_INTEL (or your card's driver) and, for /dev/dsp, SND_OSSEMUL, SND_PCM_OSS and SND_MIXER_OSS. The shipped kernel configs have all of them.

Video and images

bean install mpv
mpv video.mkv
mpv ~/Pictures/*.png     # an image viewer too: > and < to move between them

mpv runs without a GPU, drawing into Wayland shared memory, and plays sound through OSS. Put this in ~/.config/mpv/mpv.conf, with your own card's /dev/dsp number:

vo=wlshm
ao=oss
audio-device=oss//dev/dsp1
image-display-duration=inf

It has no Lua, so there's no on-screen controller; the keyboard works as usual (space, arrows, q). ffmpeg converts and encodes with its built-in codecs. There's no H.264 encoder, so -c:v mpeg4 makes an MP4, or -c:v ffv1 keeps it lossless.

Screenshots and recording

Inside yawc:

swcsnap image shot.ppm && ppm2png shot.ppm shot.png
swcsnap record -r 30 -o - | zstd -o rec.raw.zst   # ^C to stop

swcsnap record writes raw BGRA frames and prints their size to stderr. Turn them into a video with:

zstd -dc rec.raw.zst | ffmpeg -f rawvideo -pix_fmt bgra -s 1920x1080 -r 30 \
    -i - -c:v mpeg4 -q:v 3 -pix_fmt yuv420p rec.mp4

Terminal and locale

/etc/profile sets LANG=en_US.UTF-8. Without a UTF-8 locale, tmux and some programs show _ in place of anything that isn't ASCII. To use British English, set it in ~/.profile:

export LANG=en_GB.UTF-8

uClibc-ng only has the en_US and en_GB locales. C.UTF-8 doesn't exist on it, and asking for it leaves programs in plain ASCII. To keep your shell history between logins, add this to ~/.profile:

export HISTFILE="$HOME/.mksh_history"
export HISTSIZE=5000

Where things are

PathWhat
/etc/rcboot-time setup: network, daemons, volume
/etc/profilelogin environment for everyone; yours goes in ~/.profile
/etc/bean.confrepositories and bean settings
/var/lib/iwd/Wi-Fi networks, one file each
/usr/share/espresso/the known-good kernel configs