Running LikeOS

1. Overview

LikeOS is a 64-bit operating system written from scratch: its own kernel, C library, dynamic linker and core utilities, with bash, OpenSSH, an X.Org desktop, GTK3 applications, the WebKit-based luakit web browser and the Claws Mail client ported on top. The current development line is 0.2.7-HEAD on the dev branch.

Everything is built from source on a build host by the top-level Makefile, including the third-party ports under ports/. The result is a single file, build/likeos-ext4.img, which is a complete bootable GPT disk:

Partition 1

A small FAT EFI System Partition (64 MB by default) that holds only the UEFI bootloader, /EFI/BOOT/BOOTX64.EFI.

Partition 2

The ext4 root filesystem with the kernel (/boot/kernel.elf) and the whole userland. The bootloader reads the kernel straight out of ext4.

That image is written to a USB stick, and LikeOS runs from the stick — on real hardware, or in VMware or VirtualBox with the stick passed through to the virtual machine. UEFI boot is required; there is no legacy BIOS boot path.

The short version, for the impatient:

$ git clone https://github.com/kctherootkey/LikeOS-64 LikeOS
$ cd LikeOS
$ git checkout dev
$ sudo apt-get update
$ sudo make deps
$ make
$ lsblk
$ make usb-write USB_DEVICE=/dev/sdX

The rest of this page explains each of those steps in detail, together with the build options, the ways to boot, and what to do once LikeOS is running.

2. Requirements

Building LikeOS means cross-compiling a full desktop stack, including WebKitGTK, Mesa, LLVM and GCC's C++ runtime. The kernel alone builds in minutes; the ports are what make the first build long and large.

Build host

An x86-64 machine running Ubuntu. Building has been tested with Ubuntu 24.04.3 LTS (Noble Numbat). Ubuntu is currently required; other distributions are likely to need work on the dependency list and on the host tools the ports drive.

Privileges

An account with sudo: installing the dependencies and writing the USB stick both need it. The build itself runs as your normal user (the root filesystem image is populated under fakeroot).

Disk space

Plan for at least 40 GB free. A fully built tree occupies roughly 26 GB: the unpacked and built X.Org/GTK3 ports account for about 19 GB of it, build/ (objects, the cross-compiled sysroot and the image) for about 5 GB.

Memory

8 GB of RAM is the practical minimum; the port was developed on an 8-core machine with 7.9 GB. More is better: the WebKitGTK build sizes its parallelism from your RAM (about 3 GB per compile job, then halved to leave headroom), LLVM allows about 1.5 GB per job, and the final link of libWebKit.so is the high-water mark of the whole build. Some swap space is a sensible safety net.

CPU time

The first full build takes several hours. WebKitGTK alone is, in the words of its build script, the one package whose build “owns the machine for hours”; LLVM, GCC's libstdc++, Mesa, GStreamer and FFmpeg add to that. Later builds are incremental: every port package leaves a stamp, so a re-run continues where it left off and only rebuilds what changed.

Internet access

Needed to clone the repository (its git history is roughly three quarters of a gigabyte, because most third-party source tarballs are checked in), to install the Ubuntu packages, and for the ports' fetch.sh scripts, which download any source tarball not in the repository (LLVM and the Noto Sans fonts, for example) and verify every archive against a recorded SHA-256 checksum.

USB stick

The image is sized automatically to its contents (currently about 1.8 GB). Use a stick of at least 4 GB; 8 GB or more is recommended, because writing it grows the root filesystem to fill the whole stick, and that space is what you have for your files once LikeOS is running. A USB 3 stick makes a noticeable difference, since the entire system — X server, libraries, fonts — is read from it. The stick is completely erased.

Target machine

An x86-64 PC with UEFI firmware (required). LikeOS has been tested successfully on the Lenovo ThinkPad P50 and the Dell Pro 16 Plus notebooks. Alternatively, a virtual machine in VMware or VirtualBox; QEMU works too, through legacy targets.

3. Getting the source

The source lives on GitHub. Clone it (into a directory called LikeOS here) and switch to the dev branch, which is where development happens:

1. Install git if the build host does not have it yet:

   $ sudo apt-get install git

2. Clone the repository:

   $ git clone https://github.com/kctherootkey/LikeOS-64 LikeOS

3. Enter it and check out the development branch:

   $ cd LikeOS
   $ git checkout dev

All commands on the rest of this page are run from the top of this directory. Later, git pull on the dev branch followed by make brings your build up to date; only what changed is rebuilt.

4. Installing the build dependencies

The repository's deps target installs everything the build needs. Run it exactly like this:

$ sudo apt-get update
$ sudo make deps

What it takes care of, so you know what to expect:

Kernel and image tools

gcc, nasm, GNU-EFI (for the bootloader), mtools, dosfstools, e2fsprogs, fakeroot, gdisk/parted, and QEMU with the OVMF UEFI firmware.

Port build tooling

meson, ninja, cmake, libtool, gperf, xsltproc, bison, flex, xfonts-utils, shared-mime-info, gettext, the DocBook stylesheets, zstd (for the Intel graphics firmware) and ruby (JavaScriptCore's code generators).

Mesa's Intel driver

LLVM and clang with libclc and the SPIR-V tools, preferring version 18 and falling back to 15. Without them Mesa is built without its Intel (iris) driver.

A new enough g++

The terminal emulator (VTE) needs g++ 12.1 or newer. If the default compiler is older, a versioned g++-12 or later is installed beside it and used automatically for the target's C++ code.

A new enough meson

GLib needs meson 1.4.0 or newer, and Ubuntu 24.04 ships 1.3.2. A current meson is then installed into a Python virtual environment inside the port (ports/xorg/.hosttools), not system-wide — nothing outside the source tree is changed.

If make deps stops with “python3 -m venv failed”, install the venv module and run it again:

$ sudo apt-get install python3-venv
$ sudo make deps

5. Building LikeOS

One command builds everything — bootloader, kernel, C library, every program and port, the X.Org and GTK3 stacks, and finally the bootable image:

$ make

make and make all are the same thing. Because the first build runs for hours, it is worth keeping a log and running it somewhere that survives a closed terminal (inside tmux, for example):

$ make 2>&1 | tee build.log

What happens, in order.

1. The UEFI bootloader (build/bootloader.efi) and the kernel (build/kernel.elf) are compiled.
2. The C library, the dynamic linker (ld-likeos.so), PAM and crypt libraries and the user programs are built into build/.
3. The smaller ports are built: ncurses, bash, nano, tmux, libevent, zlib, nghttp2, OpenSSL, curl, OpenSSH, netcat and gdb.
4. The X.Org port (make ports-xorg) fetches and verifies its source tarballs, unpacks them, and cross-compiles its packages in dependency order into the shared sysroot build/xorg-sysroot.
5. The GTK3 port (make ports-gtk3) does the same for its larger manifest: GLib, GTK 3.24, Cairo, Pango, HarfBuzz, GCC's libstdc++, LLVM and Mesa, GStreamer and FFmpeg, libva and the Intel media drivers, WebKitGTK, luakit, PCManFM, Claws Mail, Mousepad, xfce4-terminal and the rest. When Mesa and libdrm have arrived in the sysroot, the X server is rebuilt once more with glamor, the modesetting driver and GLX.
6. Everything is staged into an ext4 root tree, turned into a filesystem with mkfs.ext4 -d under fakeroot, and combined with the EFI System Partition into build/likeos-ext4.img.

If the build is interrupted, simply run make again: each port package records a stamp when it finishes, and WebKitGTK in particular continues an interrupted compile instead of starting over.

Make targets. make help prints the complete list. The ones you are likely to use:

Build variables. Pass them on the make command line, for example make SCREEN_SIZE=medium. They can be combined.

Examples:

$ make SCREEN_SIZE=medium
$ make MAX_SCREEN_SIZE=1920x1080
$ make LIKEOS_VERSION=0.2.7
$ make CRASH_VERBOSE=1
$ make DEBUG=1

Rebuilding a single port package. The X.Org and GTK3 ports are driven by build.sh scripts that can also be run on their own. Given package names, they rebuild just those; -f ignores the stamps and builds from scratch. Afterwards, run make to put the result into the image:

$ ports/xorg/build.sh libX11 libXext
$ ports/xorg/gtk3/build.sh claws-mail
$ ports/xorg/gtk3/build.sh -f webkitgtk
$ make

Package names are the ones in ports/xorg/packages.list and ports/xorg/gtk3/packages.list. Each package's build output goes to ports/xorg/.logs/<package>.log or ports/xorg/gtk3/.logs/<package>.log. The smaller ports have their own targets, such as make ports-bash, make ports-openssh or make ports-curl.

To return a port to its checked-in state, ports/xorg/clean.sh and ports/xorg/gtk3/clean.sh remove the unpacked trees, stamps and logs (the GTK3 one leaves the shared sysroot alone); the next make rebuilds them.

$ systemd-run --user --scope -p MemoryHigh=4000M -p MemoryMax=5000M ports/xorg/gtk3/build.sh webkitgtk

6. Writing the USB stick

1. Plug in the USB stick and find its device name. It is the disk that appears when you plug it in, with the size of your stick:

   $ lsblk -d -o NAME,SIZE,MODEL,TRAN

2. Write the image, replacing /dev/sdX with your stick:

   $ make usb-write USB_DEVICE=/dev/sdX

   If the image is not current, it is built first. If you leave out USB_DEVICE, the target refuses and lists the available disks instead.
3. The target prints “WARNING: This will completely erase /dev/sdX…” and waits. Press Enter to continue, or Ctrl+C to cancel.
4. It unmounts any mounted partitions of the stick, writes the image with dd (bs=4M, synchronised), and then grows the ext4 root partition and filesystem to fill the whole stick (sgdisk, e2fsck, resize2fs), so the running system has the stick's full capacity.
5. When it reports “UEFI bootable USB drive created successfully”, the stick is ready. Eject it before unplugging.

Writing an image from a previous build is just as quick: usb-write only rebuilds when something changed, and an edited configuration file under res/ counts as a change.

$ sudo e2fsck -fy /dev/sdX2
$ sudo resize2fs /dev/sdX2

7. Booting LikeOS

The supported way to run LikeOS is from a written stick: on real hardware, or in VMware or VirtualBox with the stick attached to the virtual machine. The QEMU targets still work and are handy for a quick look at the console.

Real hardware (UEFI USB boot). Tested successfully on the Lenovo ThinkPad P50 and the Dell Pro 16 Plus.

1. In the firmware setup, make sure the machine boots in UEFI mode and that Secure Boot is disabled — the LikeOS bootloader is not signed.
2. Plug in the stick and switch the machine on. Open the firmware's one-time boot menu (on ThinkPad and Dell notebooks usually F12) and choose the USB stick's UEFI entry.
3. The bootloader sets the screen mode, loads /boot/kernel.elf from the stick's ext4 partition and starts the kernel. After the boot messages you get a login prompt on the console.

LikeOS reads and writes only the stick: its storage drivers are USB mass storage over xHCI (AHCI and NVMe are planned), so the machine's internal disks are left untouched. Networking is wired Ethernet with the Intel e1000/e1000e/igb, eepro100, AMD PCnet32, NE2000, Realtek RTL8139, DEC Tulip and VMware vmxnet3 drivers; the kernel requests an address over DHCP while it boots.

VMware. VMware boots the stick over its USB 3.1 controller, with X and the desktop fully working.

1. Create a virtual machine for a 64-bit guest without a virtual hard disk; LikeOS lives on the stick.
2. Set the firmware type to UEFI, and the USB controller's compatibility to USB 3.1.
3. Under Display, decide on Accelerate 3D graphics: with it on, X and GL clients (the web browser included) render on the virtual GPU; with it off, LikeOS renders in software. Both work.
4. For networking, the e1000, e1000e and vmxnet3 adapter types all have drivers.
5. Plug in the stick, connect it to the virtual machine (VMware's removable-devices menu), and power the VM on, choosing the USB device in the firmware's boot manager if it does not boot from it on its own.

VirtualBox. VirtualBox works with its xHCI (USB 3) controller and the VMSVGA graphics adapter.

1. Create a 64-bit virtual machine without a hard disk, and enable EFI in its system settings.
2. Under Display, choose the VMSVGA graphics controller. Enabling 3D acceleration lets X and GL clients use the virtual GPU, as on VMware.
3. Under USB, select the USB 3.0 (xHCI) controller and add a device filter for your stick, so it is attached to the virtual machine.
4. Choose an Intel PRO/1000 (e1000) or PCnet network adapter, then start the machine with the stick plugged in.

QEMU (legacy targets). These boot the image file (or a written stick) directly. They use OVMF as the UEFI firmware, an xHCI USB controller and an e1000 network card with user-mode networking. Under QEMU, LikeOS draws on the UEFI framebuffer: there is no VMware SVGA support there, so the desktop runs without GPU acceleration.

$ make qemu
$ make qemu-usb
$ make qemu-realusb USB_DEVICE=/dev/sdX

make qemu boots build/likeos-ext4.img as a USB stick. make qemu-usb does the same through sudo, so that ping to outside hosts works. make qemu-realusb boots a stick written by usb-write, which is the way to check that the stick really boots; it is console only — do not run startx under it, because every disk read goes to physical USB hardware through an emulated controller and X is far too slow that way. The QEMU targets give the guest 1024 MB by default; raise it with QEMU_MEM=2G, and add SERIAL=1 to see the kernel log on your terminal.

To run X from a real stick under QEMU, drive it through virt-manager with KVM. This configuration is known to work:

1. Create a new virtual machine in virt-manager and select manual installation.
2. Choose Debian 13 as the operating system.
3. Give it 2048 MB of RAM and, for example, 4 CPUs.
4. Tick Customize configuration before install.
5. Under Overview, set the firmware to UEFI with OVMF_CODE_4M.fd.
6. For the NIC, select Bridge and enter your bridge device (for example virbr0).
7. Select e1000e as the NIC model first, then change the model to e1000 in the XML.
8. Set Video to VGA.
9. Boot the machine, connect the USB stick to it, and type exit at the UEFI prompt. LikeOS then boots from the stick.

Graphics: chosen automatically at run time. Nothing has to be configured for the graphics. When you start X, its start-up scripts (xserverrc and xinitrc) ask the display driver what it is and what it can do, using drminfo, and pick the configuration to match. The X server and the GL clients always make the same choice:

Older Intel generations and the newest Xe2+ parts are recognised and left to the firmware framebuffer, which is the software path in the last row.

8. First steps after boot

1. Log in as root. At the console login prompt:

   login: root
   password: toor

2. Change the root password straight away:

   # passwd

3. Create an ordinary account. LikeOS is multi-user and file permissions are enforced, so you do not want to be root all the time. The desktop is meant to be used from an ordinary account: adduser asks for the new password, creates the home directory under /home and copies the desktop launchers into it from /etc/skel. Replace alice with the name you want:

   # adduser alice

4. Log out and log in as the new user:

   # exit

5. Start the graphical desktop:

   $ startx

   Any user can run startx: the X server is installed setuid root and gives root up as soon as it has opened the display and input devices, so no group membership is needed. The GTK applications expect to be run this way rather than as root — Claws Mail, for example, keeps its mailboxes and account settings in your home directory.

The desktop. X starts with the ctwm window manager, the PCManFM desktop (wallpaper and icons) and the LikeOS taskbar:

Desktop icons

Launchers from your ~/Desktop: Files (PCManFM), Terminal (xfce4-terminal), Xterm, Luakit Web Browser, Mail (Claws Mail), Text Editor (Mousepad), XNEdit, Calculator (galculator), X Calculator and Hexchat IRC Client. Double-click one to start it.

Taskbar

A Windows 11-style bar across the bottom of the screen: the load and memory monitor on the left; the LikeOS start button and one button per open window in the middle (click to switch to or minimise a window, right-click for Close); the four workspace buttons and the clock with the date on the right.

Start menu

The LikeOS button opens Programs, built from the launchers on your desktop, plus Restart ctwm and Exit ctwm.

Keyboard menus

All three mouse buttons over the desktop belong to PCManFM, so the window manager's menus are on the keyboard. Alt+F1 opens the root menu — Xterm, Explorer, Editor, Xnedit, Mail, Luakit Web Browser, Calculator, Restart ctwm and Exit session. Alt+F2 opens the window operations menu (move, resize, raise, lower, occupy workspaces, close, kill).

Starting programs. Use the desktop icons, the start menu or Alt+F1, or type the command in a terminal:

$ luakit &
$ claws-mail &
$ xfce4-terminal &
$ pcmanfm &
$ mousepad &

luakit is the web browser, built on WebKitGTK. Claws Mail reads and sends mail over IMAP, POP3 and SMTP with TLS, with spell checking; set up your mail account in it the first time you start it. The Terminal (xfce4-terminal) and Xterm give you a shell inside the desktop. The X keyboard layout is US.

Before you start the browser or mail client, you can check the network from a terminal — the kernel configures wired Ethernet over DHCP while it boots:

$ ifconfig
$ ping -c 3 example.com

Leaving the desktop. Choose Exit ctwm in the start menu or Exit session in the Alt+F1 menu; you return to the console.

Shutting down and rebooting. These need root. From the console as root:

# poweroff
# reboot
# shutdown -h now
# shutdown -r now

From an ordinary account, become root first with su, or run a single command as root:

$ su -c poweroff

shutdown also accepts a delay (+m minutes, or a time as hh:mm); without one it waits a minute. halt stops the machine without powering it off.

9. Troubleshooting

The build stops at GLib with “Meson version is 1.3.2 but project requires >= 1.4.0”. Run sudo make deps again: it installs a current meson into the port's own environment. The GTK3 target checks for this before it starts and tells you so.

A port package fails to build. Look at its log in ports/xorg/.logs/ or ports/xorg/gtk3/.logs/; the last lines usually name the problem. After fixing it, make continues from that package.

The WebKitGTK build dies with “ninja: build stopped”, or the build host swaps heavily. That is usually memory. Run it with fewer jobs (one is always safe), and see the memory-capping tip in Building:

$ LIKEOS_WEBKIT_JOBS=1 make

The build says the X server or the GTK3 stack is missing although the stamps say it was built. The sysroot was removed under the stamps. Rebuild that port as the error message suggests:

$ ports/xorg/clean.sh && make

The machine does not boot from the stick. Check that the firmware boots in UEFI mode (there is no legacy BIOS path), that Secure Boot is off, and that you picked the stick's UEFI entry in the boot menu. In a virtual machine, check that the firmware is set to UEFI/EFI and that the stick is actually attached to the VM.

Screen resolution. The resolution is chosen at build time. A default build prefers 1920×1200 and falls back to 1920×1080, 1280×800, 1280×768 and 1024×768; SCREEN_SIZE=medium prefers 1280×800. A virtual machine, though, advertises the modes its emulated adapter can scan out, not the ones the host's panel can show: on a 1920×1080 notebook VirtualBox, VMware and QEMU all offer 1920×1200, a default build takes it, and the host then has to shrink the guest's screen, which makes full-screen mode awkward. Put a ceiling on the list to say what the display really is, and write the stick again:

$ make MAX_SCREEN_SIZE=1920x1080
$ make usb-write USB_DEVICE=/dev/sdX

The ceiling need not be in the list: with MAX_SCREEN_SIZE=1600x900 a default build settles on 1280×800. On a VMware-family adapter the SVGA driver also asks the hypervisor for the resolution it recommends (the host's own screen) and uses it when it fits; a ceiling bounds that as well, so leave MAX_SCREEN_SIZE unset when the guest should simply match the host's display. Below 1024×768 nothing in the list is selectable, and the firmware's own default is kept.

Which graphics path am I on? drminfo opens the graphics device nodes and reports the display driver, its outputs and what it can do; drminfo --driver prints just the driver's name. The device nodes belong to root, so run it as root (for example su -c drminfo). The X server writes its log to /var/log/Xorg.0.log, which names the configuration file it was started with.

Logs and crash reports. dmesg shows the kernel log. For more detail, rebuild with one of these and write the stick again:

CRASH_VERBOSE=1

Detailed kernel and userspace crash reports (registers, decoded fault, page-table walk) in an otherwise normal build.

DEBUG=1

A full debug build with symbols and kernel memory poisoning.

SERIAL=1

Mirror the kernel log to the first serial port (COM1). Under the QEMU targets it appears in your terminal.

USB_SERIAL=1

On real hardware, mirror the kernel log to a USB CDC ACM serial device.

I915_DEBUG=1

Detailed log from the Intel graphics driver.

Reporting problems. Please report bugs and build failures on GitHub at github.com/kctherootkey/LikeOS-64, or write to the author, Nikolaos Rangos, at niko@systemtrap.com. Say which machine or virtual machine you used (and, for a VM, whether 3D acceleration was on), which commit you built, and include the crash report, the relevant lines of dmesg, or the failing port's log.