← Feature notes · Status · Architecture · Open work
A self-contained orientation for starting the Linux port from a Linux machine. Assumes you've worked on (or read about) the macOS side recently: if not, read docs/ARCHITECTURE.md first; the prime directive and crate boundaries described there apply unchanged on Linux. The Windows port handoff is the sister document and shares the same structure: much of the cross-platform discipline there applies verbatim, so skim it too.
This doc covers:
- What Ferail is, in one minute.
- The current state of the Linux port (scaffold landed: a lot already comes for free).
- Workspace map: where every kind of work lives.
- The
platform_shellindirection, and the one change that makes the app compile on Linux at all. - macOS assumptions in
ferail-gpuithat need cfg-gating for Linux. - The Linux shell surface, each function mapped to the freedesktop / D-Bus / XDG mechanism you'll likely reach for.
- What "Linux" even means here, and where you can do the work (native Linux, WSL2 on Windows, or a Mac).
- Day-one steps on a Linux machine.
- Working on Linux without breaking Mac/Windows.
- References.
- 1. What Ferail is
- 2. State of the Linux port
- 3. Workspace map
- 4. The
platform_shellindirection - and the one change that unblocks Linux - 5. macOS assumptions in
ferail-gpuithat need cfg-gating for Linux - 6. The Linux shell surface
- 7. What "Linux" means here, and where to do the work
- 8. Day-one steps on a Linux machine
- 9. Working on Linux without breaking Mac/Windows
- 10. References
A fast file manager written in Rust, originally for macOS, built on Zed's GPUI plus longbridge/gpui-component for higher-level primitives (sidebar, title bar, settings, virtualized table, context menu). The macOS app ships virtualized file listings, magic-first format detection, Finder tags, Quick Look previews, an async disk-usage window, multi-window + tabs, favorites with persistence, drag-and-drop, and a command catalogue surfaced through keyboard, menu, and Cmd+K palette. A Windows port is in progress (windows-port.md).
GPUI itself runs on Linux: Zed ships a Linux build on the same backend, over both Wayland and X11, with a Vulkan renderer. So the rendering and windowing foundation already exists at the rev we pin; the work is the platform shell (the OS integration layer), not the graphics.
The prime directive from ARCHITECTURE.md: the UI must never stop. Rendering, hover, hit-testing, scroll, resize, keyboard, text input, and modal drawing are read-only and non-blocking. Anything blocking (filesystem, SQLite, AppKit/Win32/D-Bus shell calls, magic, previews) runs off the UI thread and reports back through GPUI's entity-update boundaries. This applies on Linux just as strictly, and D-Bus round-trips (portals, udisks2) are exactly the kind of latency that must never touch the hot path.
There is no Linux predecessor to port from (unlike Windows, which has a private predecessor checkout). The reference is the macOS shell crate's shape plus the freedesktop specifications.
The compile scaffold has landed, plus a first batch of real shell impls.
ferail-shell-linux exists, the
#[cfg(target_os = "linux")] pub use ferail_shell_linux as platform_shell
arm is wired, and the crate is in the workspace, so the surface the Linux
build needs is in place. The deterministic, verifiable functions are now
implemented for real (real arm under cfg(target_os = "linux"), no-op twin
under cfg(not)):
- Pure
std/ process-based:duplicate_path,make_alias,make_alias_in,open_url,reveal_in_finder(D-BusFileManager1→xdg-openfallback),open_terminal(emulator detection chain),system_is_dark(gsettings v1),open_with_app(gio launch/ exec). compress_paths:.zipvia thezipcrate, lifted verbatim from the (platform-neutral) win32 impl. Because it's not target-gated, its tests run on any host (cargo test -p ferail-shell-linuxpasses on macOS).prevent_idle_sleep: RAIISleepBlockerowning asystemd-inhibit --what=idlechild; dropping it releases the lock.- File-type icons (
ferail_fs_native::fetch_icon_rgba, not a shell fn): shared-mime-info MIME detection (xdg-mime) → freedesktop icon-theme lookup (freedesktop-icons, GTK theme via gsettings, hicolor cascade) → PNG/SVG rasterization (image/resvg, straight RGBA). Cached per-kind one level up inIconCache, never on the render path. Verified in WSL2 by dumping real theme glyphs to PNG (examples/icon_dump.rs) + a smoke test.
Deliberately still stubbed: these need a running Linux desktop to get right, not just to compile (so they're the first things to do on a Linux box, not blind from a Mac):
- File clipboard on X11. Wayland desktops with data-control support use
native
text/uri-listandx-special/gnome-copied-filesoffers, with Copy/Move metadata. Requests run on a worker and do not resolve symbolic links. Pure URI lists are treated as Copy; remote URIs are rejected. Desktops without data-control support are not covered by this implementation. : done. Rides the shared freedesktop thumbnail cache (fetch_quick_look_thumbnail$XDG_CACHE_HOME/thumbnails/{normal,large,x-large,xx-large}/ <md5(file-uri)>.png), regenerating withgdk-pixbuf-thumbnaileron a miss or stale entry (source newer than the cached PNG). The MD5 keying is locked to the freedesktop spec vector by a unit test, so we hit the same cache Nautilus writes. v1 covers gdk-pixbuf-loadable formats (images); video/PDF thumbnails need their own thumbnailers (totem/evince) or the Tumbler D-Bus dispatcher: a follow-up. Verified in WSL2: generated a real 256×256 thumbnail and it populated the shared cache (examples/thumb_dump.rs).- Theme / volume / power observers: async D-Bus signal subscriptions
(
ashpd/zbus) bridged into the sync callback API; signal match rules and the runtime-thread bridge need live testing. eject_volume/eject_device: implemented viaudisksctl unmount+power-off(plainumountfallback for udisks-less setups).eject_deviceis Finder's "Eject All": unmount every partition of a disk, then power the drive down once its last filesystem is gone. The partition→disk grouping key (VolumeInfo::device_id, e.g.sdb1→sdb) is resolved through sysfs inferail-fs-native::list_volumes;volume_busy_processes(the failed-eject holder list) scans/proc/<pid>/{fd,cwd}likelsof. Still needs live testing on a real removable device.- trash,
open_with_candidates, video: freedesktop-trash / MIME-association parsing / GStreamer respectively.
Packaging (2026-08-08), .deb builds, installs, and runs on Ubuntu 24.04:
Validated end to end in an arm64 QEMU VM (Ubuntu 24.04 server): cargo deb -p ferail-gpui produces ferail_<ver>_arm64.deb; it installs via apt;
ferail doctor and the magic CLI work; the GUI launches under Xvfb with a
1180×760 window whose WM_CLASS is ("ferail", "ferail"): the desktop-file
association string. Findings worth keeping:
c_charportability: the first arm64 build failed becausestat_info.rsspelledgetpwuid_r/getgrgid_rbuffers as[i8; …];c_charisu8on aarch64 Linux. Never writei8for a C string buffer.- Fat-LTO links are memory-hungry: the two
lto = true, codegen-units = 1binaries linking in parallel OOM-killed an 8 GB VM. 16 GB +-j2(or just more RAM) builds fine. - dlopen'd deps are invisible to
$auto: dpkg-shlibdeps only lists linked libs, solibvulkan1/libwayland-client0/libwayland-cursor0are spelled out independsby hand (gpui dlopens them), withmesa-vulkan-driversas Recommends. - Weston's headless backend crashes gpui (no
wl_seat; gpui unwraps it inwayland/client.rs). Use Xvfb + the X11 backend for headless smoke tests, but window captures under Xvfb come back black (no DRI3, Vulkan presents outside X's readable surface), so pixel-level verification still waits on therender_to_imageTODO or a real desktop session.
Interactive testing + first performance fix (2026-08-19):
The same VM now boots with a virtio-gpu into a QEMU Cocoa window
(~/VMs/ferail-ubuntu/vm.sh start-gui), runs weston on it with the DRM
backend + pixman renderer (vm.sh desktop; needs seatd and the user in
video/render/input), and launches the release binary in that session
(vm.sh ferail). Vulkan is llvmpipe: fully software, fine for testing,
not for judging frame rate. Weston's screenshooter refuses un-authorized
clients, so grab pictures from the host side or add --debug to weston.
First thing it showed: the app was unusable: seconds per frame, 100% on
the UI thread while idle. perf on the main thread put 78% of the time in
libgcc _Unwind_Find_FDE:
.SystemUIFontdoes not resolve on Linux. gpui's cosmic-text system maps the virtual name to "IBM Plex Sans" (what Zed bundles; Ferail does not). A stock system misses, andresolve_fontwalks the fallback stack (.ZedMono,.ZedSans, Helvetica, Segoe UI, Ubuntu, Adwaita Sans, Cantarell, Noto Sans, …) until DejaVu Sans answers. gpui caches the miss but re-wraps it in a freshanyhow!on every cache hit: nine error allocations per text run per frame.text::install_platform_font_familiesnow resolves a real installed family once at startup (and a real mono family; the generic"monospace"name is equally unknown to gpui's matcher, so Linux code previews were proportional).RUST_BACKTRACE=1makesanyhowcapture backtraces.obs::initdefaults it on for panic reports;Backtrace::capture()(anyhow's constructor path) honours it unlessRUST_LIB_BACKTRACEsays otherwise. So every one of those per-frame misses walked the stack, and on Linux that walk is a linear FDE search over a ~100 MB binary.obs::initnow also defaultsRUST_LIB_BACKTRACE=0; panics are unaffected (the hook usesforce_capture). This was costing something on macOS too, just cheaply enough to hide.
Original scaffold notes (2026-08-04):
- Desktop identity:
crates/ferail-gpui/resources/linux/ferail.desktop(freedesktop desktop entry) + every window now setsWindowOptions::app_id = "ferail"throughferail_gpui::base_window_options()(lib.rs): the string compositors match against the.desktopbasename and hicolor icon name.set_app_idis a no-op on macOS/Windows, so it's set unconditionally. New windows should close theirWindowOptionsliteral with..crate::base_window_options(), not..Default::default(). - Debian packaging:
[package.metadata.deb]incrates/ferail-gpui/Cargo.toml(cargo-deb): shipsusr/bin/ferail, the desktop entry, andresources/ferail.pngas the 512×512 hicolor icon;depends = "$auto", with the runtime tools the shell layer execs (xdg-utils, udisks2, gdk-pixbuf-thumbnailer, gio, shared-mime-info) as Recommends. Needs a Debian-family host to actually runcargo deb -p ferail-gpui(dpkg-shlibdeps resolves$autothere) and to validate install/launch; build on the oldest Ubuntu LTS you want to support : the .deb inherits the build host's glibc floor. - Known gap:
Exec=ferailhas no%F/%Ufield code: the binary treats a bare positional argument as an unknown subcommand (main.rs::handle_cli_subcommand), so "Open folder with Ferail" /MimeType=inode/directory;must wait until a directory argument is accepted.
Verify Linux code from any host.
cargo checkdoesn't link, so the real arms type-check (and the Linux-gated unit tests compile) on a Mac/Windows box:cargo check --target x86_64-unknown-linux-gnu -p ferail-shell-linux --tests(afterrustup target add x86_64-unknown-linux-gnu). This catches API/typing mistakes long before you reach a Linux machine, but it does not run the code or exercise D-Bus/xdg-open; that still needs a real Linux session (§7).
Beyond the shell crate, the architecture means a surprising amount already works or compiles:
Already free / cross-platform (no Linux-specific code needed):
ferail-core,ferail-disk-usage,ferail-design: zero platform deps; compile and behave identically.ferail-meta: SQLite viarusqlitewith thebundledfeature compiles from source with any C compiler; works on Linux out of the box (you just needcc/gcc).ferail-fs-native: already compiles on Linux. Several functions have acfg(not(any(target_os = "macos", windows)))catch-all arm giving generic Unix behavior (e.g.entry_is_hidden→ dot-prefix).std::fsenumeration, the magic-detection table, the disk-usage scanner, and the cross-platformfile_opscopy/move engine are all platform-neutral.- Path handling:
/is the native separator, so the Windows-specific separator/long-path headaches simply don't exist here. - Keybindings: gpui maps the
"cmd-X"bind string to Ctrl on Linux (Zed convention), same as Windows: the catalogue'sShortcut::primaryshould land as Ctrl automatically.
Not yet done: your work ahead (rough priority order):
- Make it compile. Scaffold done: the
platform_shellLinux arm and a stubferail-shell-linuxexist (§4). Two unguarded directferail_shell_mac::call sites still bypass the alias and will fail the Linux build until routed throughplatform_shellor cfg-gated:entry_info.rsset_hidden_extension(≈L480) andtoggle_tag(≈L488). (search.rs'sspotlight_availableis alreadycfg(target_os = "macos")- guarded: fine.) - Make it run. Confirm GPUI's Linux backend renders the shell under your session (Wayland or X11). You need working Vulkan drivers: this is the most common first-run failure on Linux.
- Fill in real shell implementations (§6): clipboard, trash, reveal, open-with, dark-mode, volume enumeration. Each is small and isolated.
- Conditionalize macOS assumptions in
ferail-gpuithat compile but behave wrong on Linux (§5). - Add Linux-native UX: freedesktop Trash,
user.xdg.origin.urlas the "where did this download come from" provenance signal,.desktop-based Open With, XDG thumbnail cache reuse.
The multi-window + tabs spec (ferail-windows-instances-tabs-spec.md) is OS-agnostic: it'll work on Linux once the platform layer is caught up.
crates/
├── ferail-core Domain types, command catalogue, NodeId/FileEntry,
│ NodeStore. Zero platform deps.
├── ferail-design Shared visual constants. `TextTokens` is now the
│ live type scale (see ARCHITECTURE Typography).
├── ferail-disk-usage Pure disk-usage model + treemap layout. No I/O.
├── ferail-fs-native std::fs backend + icons, magic detection,
│ disk-usage scanner, xattr. Already has generic
│ cfg(not(any(macos, windows))) arms: specialize
│ them to cfg(target_os = "linux") for real impls.
├── ferail-meta SQLite-backed metadata store. rusqlite bundled.
├── ferail-shell-mac macOS platform shell: AppKit/Cocoa/NSWorkspace.
├── ferail-shell-win32 Windows platform shell: Win32 via `windows` 0.58.
│ (Smaller, newer crate: the best scaffold to copy.)
├── ferail-shell-linux ⟵ DOES NOT EXIST YET. You create this. Freedesktop
│ / D-Bus / XDG integration. Your home base.
└── ferail-gpui The app. Views, actions, tasks, sidebar, file
list, preview, tabs, multi-window. All platform
coupling goes through `platform_shell::*`.
Where to put new Linux code:
| Kind of work | Crate | File pattern |
|---|---|---|
| Native shell API (clipboard, trash, dark-mode, reveal, open-with) | ferail-shell-linux (new) |
New src/<topic>.rs, re-exported via lib.rs |
| Filesystem (icons, volumes, trash, provenance xattr) | ferail-fs-native |
Specialize the cfg(not(any(target_os = "macos", windows))) arm, or add a cfg(target_os = "linux") arm next to it |
| UI / view tree changes | ferail-gpui |
Same file you'd touch on Mac; gate platform diffs with cfg, or call into platform_shell |
| Domain logic | ferail-core |
Stays platform-agnostic; if you reach for cfg here, reconsider |
| SQLite schema for Linux-specific state | ferail-meta |
New table or extended one |
gpui never calls ferail_shell_mac:: or ferail_shell_win32:: directly (or
shouldn't: see the two stragglers in §2 and §5). It calls
crate::platform_shell::X. The alias is in
crates/ferail-gpui/src/lib.rs and
now has all three arms (the Linux one landed with the stub scaffold):
#[cfg(target_os = "macos")]
pub use ferail_shell_mac as platform_shell;
#[cfg(windows)]
pub use ferail_shell_win32 as platform_shell;
#[cfg(target_os = "linux")]
pub use ferail_shell_linux as platform_shell;This was step one of the port and it's done. For the record, the wiring is:
crates/ferail-shell-linux: the new crate. Every function gpui reaches through the alias is present as a no-op / empty stub, with the canonical macOS signature.lib.rs's module doc is the authoritative surface inventory; §6 below maps each entry to its real Linux mechanism.crates/ferail-gpui/Cargo.toml:[target.'cfg(target_os = "linux")'.dependencies] ferail-shell-linuxso the dep is pulled only on Linux (mirroring the mac/win32 target stanzas).- Root
Cargo.toml: added tomembersand[workspace.dependencies].
The crate is plain stubs, not yet cfg-split: because no body does real work,
a single set of bodies compiles on every host. When you write the first real
impl, put it behind #[cfg(target_os = "linux")] and keep a
#[cfg(not(target_os = "linux"))] no-op twin so the crate still compiles on
Mac/Windows as a workspace member (the pattern win32/mac already use).
The shell-crate pattern (mirror it in shell-linux): every function has a
real arm under cfg(target_os = "linux") and a no-op arm under
cfg(not(target_os = "linux")). The no-op arm exists purely so the crate
compiles on Mac/Windows as a workspace member: it's never reached through the
alias, because cargo only links the matching shell crate per target. Shared
types (OpenWithCandidate, SetIconResult, …) are declared unconditionally
with identical shape in all shell crates so they round-trip through the alias.
Adding any new shell surface now means touching three crates (mac, win32, linux), real-or-stub in each, so the alias keeps compiling on every target.
Cases where the code compiles for Linux (the stubs cover the call surface) but
the behavior is wrong. Each needs a #[cfg] arm or a small redesign. Several
overlap with the Windows port: where the desired behavior is the same, gate on
cfg(not(target_os = "macos")) so Linux and Windows share an arm; where they
differ, be explicit with cfg(target_os = "linux").
| Site | macOS behavior | Linux behavior wanted |
|---|---|---|
main.rs run_gui |
Stays resident with zero windows (Finder model). | Quit when the last window closes. Re-add the on_window_closed → cx.quit() handler (shared with Windows under cfg(not(target_os = "macos"))). |
| main.rs menu install | install_app_menu(cx) installs an NSApp menu bar. |
No global menu bar on Linux. Use an in-window title-bar hamburger (same call as Windows): drop the global menu. (Unity/appmenu exists but isn't worth targeting for v1.) |
| main.rs titlebar options | Reserves the macOS traffic-light area on the left. | Linux uses client-side decorations with min/max/close on the right (GNOME, KDE). Need a CSD-appropriate title-bar layout: check what gpui-component already offers, and respect the compositor's preference where possible. |
| Action labels "Reveal in Finder" / "Move to Trash" (ferail-core/src/commands.rs) | Finder / Trash literal. | "Move to Trash" is fine (freedesktop calls it Trash). "Reveal in Finder" → "Open Containing Folder" / "Show in Files". Swap by cfg in the catalogue or a localized lookup. |
| Spacebar → Quick Look | Pops the Quick Look panel. | No Quick Look on Linux. Spacebar should pop the in-app preview pane (already wired) or no-op. (GNOME's sushi is an optional shell-out, not a dependency.) |
| Sidebar Volumes | ferail-fs-native::list_volumes() reads /Volumes / mount. |
A cached UDisks2 filesystem list includes unmounted devices and labels. Activation mounts on a worker, with authorization handled by UDisks/Polkit. Existing mounted-volume discovery remains available when UDisks is unavailable. |
Trash (MoveToTrash) |
NSFileManager trash via shell-mac. | freedesktop Trash spec: $XDG_DATA_HOME/Trash/{files,info} plus per-volume .Trash-<uid> with .trashinfo records. The trash crate implements this; sits in ferail-fs-native next to the existing trash arms. |
| Quarantine indicator (red shield) | com.apple.quarantine xattr (ferail-fs-native/src/xattr_info.rs). |
No exact equivalent. The closest is the freedesktop download-provenance xattr user.xdg.origin.url (+ user.xdg.referrer.url) that browsers set. Add a Linux arm to fetch_quarantine_info; relabel the UI as "downloaded from" provenance. |
| Finder tags (color chips) | com.apple.metadata:_kMDItemUserTags. |
No portable Linux tag system. Drop for v1 (recommended) or back via ferail-meta SQLite as private tags (no file-manager interop). |
| Path separators in display strings | / (already native). |
/ is native on Linux too: easier than Windows. Still double-check no display string assumes a macOS-only convention. |
--screenshot headless harness |
macOS render_to_image + icon install in screenshot::run. |
Verify gpui's Linux backend supports render_to_image at our pinned rev. If not, you'll need an on-screen capture path like the Windows capture_window_rgba route. The icon-install call already routes through platform_shell::set_app_icon_from_png_bytes (make it a no-op on Linux: see §6). |
ferail-shell-linux must mirror the public pub fn surface of
ferail-shell-mac (and -win32). Below is each function mapped to the Linux
mechanism. Strong recommendation: lean on the
ashpd crate for XDG Desktop Portals
(appearance/dark-mode, open-uri, file-chooser) and
zbus for raw D-Bus (udisks2, FileManager1),
both async, both the idiomatic Rust path. Run portal/D-Bus calls off the UI
thread (prime directive).
| Function | Linux approach |
|---|---|
clipboard_copy_file_urls / clipboard_read_file_urls |
Clipboard with a text/uri-list target carrying file:// URIs. GNOME apps additionally use the x-special/gnome-copied-files target (copy\nfile:///path\n…) and KDE its own, write/read the common text/uri-list first, add the GNOME target for Nautilus interop. Wayland: smithay-clipboard or wl-clipboard shell-out; X11: raw selections or xclip. (Plain text copy_to_clipboard can use arboard, but it doesn't do custom MIME targets well, file-URLs need lower-level access.) |
start_volume_observer |
UDisks2 object/property signals through zbus on a worker. The callback is Send; it only queues a device-cache refresh. |
| (text-naming prompt, no Linux work needed) | Already solved cross-platform: the shared open_text_prompt gpui modal in ferail-gpui handles rename + new-folder on every platform, and the native prompt_for_text shell stub was deleted (2026-06-20). Nothing to port here. |
| Function | Linux approach |
|---|---|
show_alert(title, body) |
A gpui modal (preferred, cross-platform), or zenity --info shell-out for a quick stub. |
copy_to_clipboard(text) |
arboard (handles Wayland + X11). |
open_url(url) |
xdg-open <url>, or portal org.freedesktop.portal.OpenURI via ashpd. |
reveal_in_finder(path) |
D-Bus org.freedesktop.FileManager1.ShowItems (works with Nautilus/Dolphin/Nemo/Files), fallback xdg-open <parent dir>. |
open_terminal(dir) / open_terminal_with(dir, spec) |
No standard. Detection chain: $TERMINAL, then x-terminal-emulator (Debian alternatives), then probe known emulators (gnome-terminal, konsole, kgx, alacritty, xterm). The _with form honours the Settings → Files → Terminal prefs (custom program/params, {dir} expansion); admin mode appends the emulator's exec tokens (ferail_core::terminal::exec_prefix_for) + sudo -s for a root shell in the window. |
duplicate_path(src) |
Pure std::fs (lift the Windows impl almost verbatim; just use a Linux-ish copy-name convention, e.g. <stem> (copy).<ext>). |
make_alias(target) |
std::os::unix::fs::symlink: trivial. (A .desktop launcher is the heavier alternative; a symlink is the right default.) |
compress_paths(targets) |
The zip crate, already cross-platform; reuse the shared logic. |
open_with_candidates(path) / open_with_app |
Resolve MIME via xdg-mime query filetype (or GIO), then enumerate handler .desktop files from the MIME associations (mimeapps.list + applications/). The gio CLI (gio open, gio mime) is the pragmatic shortcut; the proper path parses desktop entries (consider a freedesktop/xdg crate). |
fetch_quick_look_thumbnail(path) |
Reuse the freedesktop thumbnail cache first: check $XDG_CACHE_HOME/thumbnails/{normal,large}/<md5(canonical file:// URI)>.png. On miss, generate (gdk-pixbuf for images, ffmpeg for video) or ask the org.freedesktop.thumbnails.Thumbnailer1 (Tumbler) D-Bus service. Images-only via gdk-pixbuf is a fine v1. |
show_quick_look(paths) |
No Quick Look. Route to the in-app preview pane, or gio open / GNOME sushi as an optional shell-out. |
read_canonical_tags / toggle_tag / clear_tags |
No portable native tags. Back via ferail-meta SQLite (private), or drop for v1. |
system_is_dark() |
Portal org.freedesktop.portal.Settings.ReadOne("org.freedesktop.appearance", "color-scheme") (1 = prefer-dark) via ashpd::desktop::settings. Fallback: gsettings get org.gnome.desktop.interface color-scheme. |
start_system_theme_observer(cb) |
Subscribe to the portal SettingChanged signal for org.freedesktop.appearance / color-scheme (ashpd exposes a stream); fire the callback off-thread. |
set_app_icon_from_png_bytes |
No-op. On Linux app identity/icon comes from a .desktop file + the Wayland app_id / X11 WM_CLASS, not a runtime swap. Shipped: resources/linux/ferail.desktop + the hicolor icon are installed by the cargo-deb assets, and every window sets app_id = "ferail" via ferail_gpui::base_window_options() (see §2). |
set_app_user_model_id(id) |
No-op (Windows taskbar concept). The Wayland app_id plays the grouping role; ensure gpui sets it to match the .desktop file's basename. |
app_bundle_path() |
The running executable's path, for Diagnostics and Reveal. |
video_overlay_show / set_frame / remove |
GStreamer (gstreamer crate) or libmpv child surface floated over the viewer stage rect. Viewer-feature-sized; defer. See VIEWER.md. |
install_app_menu, register_command_callback, set_tab_count, set_command_state, set_about_options / show_about_panel |
NSApp main-menu paradigm, no Linux global menu. Title-bar hamburger covers about/settings; make these no-ops for v1. |
begin_drag, show_context_menu, install_services_anchor,
set_services_selection, show_share_picker, apply_native_chrome take a
&winit::window::Window and aren't called through platform_shell (gpui
doesn't hand out winit handles). Drag-out-to-file-manager and a share action
will grow fresh functions when needed: drag-and-drop via the Wayland/X11 DND
protocols (gpui may already mediate this), and "share" via the portal
org.freedesktop.portal.OpenURI / email handler. Don't try to recycle these
macOS signatures.
Two questions that come up before you've even cloned the repo: which Linux do I target? and do I even need a Linux machine to start?
Unlike macOS (one Finder, one NSWorkspace) or Windows (one Win32 shell), there is no single "Linux shell" to port to, but the flip side is you don't pick a distribution at the source level either. The binary targets the Linux kernel ABI + glibc (or musl), and everything in §6 targets freedesktop.org standards, not a distro:
- The display server: Wayland vs X11: is abstracted by GPUI (it supports both). You don't choose; you support both.
- The desktop environment: GNOME vs KDE vs others: is what actually
varies, and you abstract it via D-Bus portals (
org.freedesktop.portal.*) and freedesktop specs (Trash, MIME-apps, thumbnails, icon theme). That's the whole point of §6: write to the spec, not to GNOME or KDE specifically. - A distribution (Ubuntu, Fedora, Arch, …) only matters as a dev/test/CI
target, which box you run and screenshot on, which
-devpackages and Vulkan drivers you install (§8). It is not a source-level fork. Pick Ubuntu LTS or Fedora as the primary test target because they're what the Vulkan drivers andgpuideps are best exercised against; nothing in the code branches on it.
So: target freedesktop, test on a couple of mainstream distros, support
both display servers. There is no cfg(distro = …).
A large fraction of the port is host-agnostic Rust that compiles on any machine. Three realistic dev hosts, in rough order of how much of the loop they cover:
| Host | Build / cargo check / cargo test |
Write shell-linux + fs-native arms | Run the GPU UI + screenshot |
|---|---|---|---|
| Native Linux (or a Linux VM) | ✅ | ✅ | ✅ (needs working Vulkan, §8) |
| WSL2 on Windows | ✅ genuine Linux kernel | ✅ | --screenshot but not smooth interactive use |
| macOS (this repo's home) | ferail-gpui to Linux (Apple→Linux cross with the gpui native/Vulkan deps is impractical) |
✅ | ❌, no Linux runtime; use a VM/remote box |
What "the workspace-member check" means on a Mac: ferail-shell-linux and
the cfg(target_os = "linux") arms in ferail-fs-native are plain Rust with
no Linux-only deps, so they compile as workspace members on macOS
(cargo check -p ferail-shell-linux is green today). That lets you write and
type-check the entire stub surface and much of the real shell logic from the
Mac. What you cannot do from the Mac is build ferail-gpui for
target_os = "linux" (its GPUI/Vulkan/Wayland deps don't cross-compile from
Darwin) or run anything, so the moment you need to see pixels or exercise a
real portal call, move to a Linux host.
Recommended split if you're starting from a Windows or Mac box:
- Do the mechanical, type-checkable work anywhere: flesh out
ferail-shell-linux, addfs-nativeLinux arms, keepcargo check -p ferail-shell-linuxgreen. - Stand up one real Linux environment for the run/screenshot loop: a
WSL2 instance (easiest if you're on Windows;
vulkaninfoto see whether Dozen gives you a GPU, else set lavapipe for screenshots) or a Linux VM / cloud box (best for smooth interactive testing). Push early so CI on the other platforms stays honest (§9).
Naming caveat: CLAUDE.md's porting rule "WSL features are not macOS v1 features" is about WSL as a feature to support in the old Ferail-Win32 (browsing
\\wsl$paths), not about using WSL2 as a build host for this port. The two are unrelated; don't conflate them.
Assumes a recent distro with a working graphical session. GPUI needs a Vulkan driver: this is the single most common first-run blocker.
# 1. Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable
# 2. System build deps - Debian/Ubuntu
sudo apt install -y build-essential pkg-config cmake \
libwayland-dev libxkbcommon-dev libxkbcommon-x11-dev \
xorg-dev libxcb1-dev \
libvulkan1 mesa-vulkan-drivers vulkan-tools \
libssl-dev libzstd-dev libdbus-1-dev
# (rusqlite `bundled` compiles SQLite from source - build-essential covers it.)
# Fedora equivalents: gcc gcc-c++ make cmake pkgconf-pkg-config
# wayland-devel libxkbcommon-devel libxkbcommon-x11-devel
# libX11-devel libxcb-devel vulkan-loader mesa-vulkan-drivers
# vulkan-tools openssl-devel libzstd-devel dbus-devel
# Authoritative list drifts with the gpui rev - cross-check Zed's
# script/linux in the zed-industries/zed repo we pin.
# 3. Confirm Vulkan actually works (blank window / crash on launch == this)
vulkaninfo | head -n 20 # should print a device, not an error
# 4. Clone and build
git clone <your-ferail-remote> Ferail && cd Ferail
cargo check --workspace --all-targets # expect a platform_shell error first: see §4What'll fail first, in rough order:
platform_shellis undefined on Linux. Compile error inferail-gpui. This is expected: fix it via §4 (createferail-shell-linux, or the temporary win32-stub alias to see pixels) before anything else.- No Vulkan device → blank window or panic on launch. Install
mesa-vulkan-drivers(or vendor drivers); verify withvulkaninfo. In a VM, ensure 3D acceleration / a software Vulkan (lavapipe) is available. - Wayland vs X11 quirks. gpui supports both; if one session misbehaves, force the other to isolate the issue (e.g. run under an X11 session, or set the relevant backend env var) and file what you find.
- gpui-component visual oddities. Title-bar height, CSD button placement, sidebar borders: tested primarily on macOS. Screenshot and triage by element.
- Stay-resident-at-zero-windows is wrong on Linux. Closing the last window leaves the process running invisibly: first behavioral bug to fix (§5 row 1).
- Sidebar Volumes empty/wrong, Trash a no-op. Until you write the Linux
list_volumesarm and trash impl (§5, §6).
Verification commands:
cargo check --workspace --all-targets # sanity at any point
cargo run --bin ferail-gpui # run the shell
cargo run --bin ferail-gpui -- --screenshot screenshots/linux-baseline.png
cargo test --workspaceConvention reminders:
- Screenshots go in the repo
screenshots/folder, not/tmp. - Never run broad formatters (
cargo fmt --all); the repo often has work-in-progress local changes. - New native code in
ferail-shell-linux; new filesystem code ascfg(target_os = "linux")arms inferail-fs-native. Don't put D-Bus/XDG calls inferail-gpuidirectly: go throughplatform_shell.
There are now three platforms. macOS is the established one and Windows is mid-port; your job from Linux is to add the Linux side without regressing the two you can't see.
You can't cross-compile to macOS from Linux (Apple toolchain is Apple-hardware-only), and cross-compiling to Windows MSVC from Linux is fiddly. So CI or a teammate's machine is the gate for Mac/Windows correctness. Push early; treat those signals as load-bearing.
Every new platform_shell::X surface now needs all three shell crates. Add
the real arm under cfg(target_os = "linux") in ferail-shell-linux, and a
matching signature (real-or-stub) in ferail-shell-mac and
ferail-shell-win32. The alias only resolves when every shell crate exposes
the symbol.
Mind the cfg traps: they're sharper with three platforms:
cfg(unix)catches both macOS and Linux: never use it for a macOS-only or Linux-only branch. Usecfg(target_os = "macos")/cfg(target_os = "linux").cfg(not(windows))catches macOS and Linux. Good when Linux and Mac want identical behavior; wrong when they differ.cfg(not(target_os = "macos"))catches Windows and Linux: handy for the "everything that isn't the Finder model" cases (e.g. quit-on-last-window).- When you cfg-gate behavior in
ferail-gpui, write every arm you affect so you're forced to think about the other platforms.
ferail-fs-native already has Linux arms via cfg(not(any(target_os = "macos", windows))). When you add real Linux behavior, decide: specialize
that catch-all to cfg(target_os = "linux") (if the generic fallback no longer
fits) or add a cfg(target_os = "linux") arm beside it. Don't silently change
the catch-all's behavior for other Unixes you haven't tested.
The command catalogue is shared and platform-agnostic.
crates/ferail-core/src/commands.rs defines actions and shortcuts for all
platforms. Gate the handler, not the catalogue entry, for a Linux-only action.
Shortcut::primary("X") maps to Cmd on Mac and Ctrl on Windows/Linux: verify a
chord doesn't collide with a compositor/WM global on your DE.
Things you can safely change from Linux without Mac/Windows risk:
ferail-shell-linux, cfg(target_os = "linux") arms anywhere, anything in
ferail-core / ferail-disk-usage / ferail-design (no platform code by
design), and gpui code where you've added matching arms for the other targets.
Within the repo:
- docs/ARCHITECTURE.md: crate boundaries, data model, work-scheduling rules. Apply unchanged on Linux.
- windows-port.md: the sister port doc; the cross-platform
discipline and
platform_shellmechanics are shared. - CLAUDE.md, operating manual for AI / human edits.
- TODO.md: open work backlog; Linux items will accrue here.
Freedesktop specs (the authoritative behavior reference):
- Trash spec: how
Move-to-Trash must behave (
Trash/files,Trash/info, per-volume.Trash-<uid>). - Thumbnail managing spec:
the
~/.cache/thumbnailscache layout and naming to reuse. - Desktop entry spec
and MIME apps / associations,
for Open With and the app's own
.desktopfile. - Icon theme spec, per-MIME icon lookup.
- Base directory spec (XDG): where config/cache/data live.
D-Bus / portals / volumes:
- XDG Desktop Portals:
Settings(appearance/dark-mode),OpenURI,FileChooser. ashpd: idiomatic Rust portals client. Start here for dark-mode + open-uri.zbus: raw D-Bus, for udisks2 andFileManager1.- udisks2: drive/volume enumeration and add/remove signals.
org.freedesktop.FileManager1: theShowItemsinterface every major file manager implements (for "reveal").
Useful Rust crates: ashpd (portals), zbus (D-Bus), trash (freedesktop
trash), arboard (plain-text clipboard), xattr (already used on macOS: reuse
for provenance), and a desktop-entry/xdg-mime parser for Open With.
GPUI on Linux:
- Zed's gpui platform backends: the X11/Wayland code gpui uses. When in doubt about windowing/DND behavior, read here.
- Zed's
script/linux(same repo): the canonical list of system build dependencies for the rev we pin; cross-check it when the apt list above drifts.