Skip to content

Latest commit

 

History

History
312 lines (231 loc) · 11.6 KB

GETTING_STARTED.md

File metadata and controls

312 lines (231 loc) · 11.6 KB

Getting Started

Zero to a running Ferail. This guide assumes nothing is installed yet. If you already build Rust projects, skip to Build & run.

Where Ferail runs today. macOS is the primary, daily-driver platform. Windows builds and runs natively with broad parity (verified on-device). Linux builds and runs but is an early port. See the Current status table for the honest breakdown: this guide flags the per-platform steps as you go.

Just want to run it? macOS, Windows and Linux have prebuilt downloads on the Releases page: see Download. This guide is for building from source.

Ferail is not published to crates.io, so build it from this workspace rather than using cargo install. GPUI and gpui-component come from crates.io, with a Git patch for the GPUI platform crate. The committed Cargo.lock pins the dependency versions.


1. Install the prerequisites

Rust (all platforms)

Install Rust via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then restart your shell (or source "$HOME/.cargo/env"). You don't need to pick a version: the repo's rust-toolchain.toml pins the stable channel (with clippy + rustfmt), and rustup installs/selects it automatically the first time you build inside the repo. Ferail needs a recent stable toolchain (GPUI uses Rust edition 2024).

You also need git to clone the repo and to fetch the git dependencies.

Platform build tools

  • macOS: install the Xcode Command Line Tools (the C linker + system SDKs):

    xcode-select --install

    That's all the system tooling a default build needs.

  • Windows: install the MSVC toolchain: Visual Studio Build Tools with the "Desktop development with C++" workload (or full Visual Studio), then the x86_64-pc-windows-msvc Rust target (rustup's default on Windows). See docs/features/windows-port.md for the current state of the Windows port.

  • Linux: you need a C toolchain, pkg-config, cmake, and working Vulkan drivers (the single most common first-run blocker). On Ubuntu/Debian:

    sudo apt install -y build-essential pkg-config cmake \
      libwayland-dev libxkbcommon-dev libxcb1-dev \
      libvulkan1 mesa-vulkan-drivers vulkan-tools \
      libssl-dev libzstd-dev libdbus-1-dev
    vulkaninfo | head -n 20   # should print a device, not an error

    Fedora equivalents and the full Linux story (including WSL2) are in docs/features/linux-port.md.

For PDF thumbnails and previews on Linux, install Poppler’s pdftoppm (poppler-utils on Debian/Ubuntu, poppler on Arch). Ferail renders the first page; PDF documents are recognized by their contents, not their extension.

Optional: libmpv (for the any-format video player)

The built-in viewer plays mp4 / m4v / mov out of the box. The optional mpv backend (any container, plus live grading and the transparent chroma-key windows) loads a user-installed libmpv at runtime: Ferail never bundles it. Install it only if you want that path:

# macOS
brew install mpv

Release downloads (the DMG, the Windows ZIP, the .deb) already compile the mpv provider in: install libmpv and select mpv under Settings → Plugins, no rebuild needed. The .deb recommends libmpv2, so apt normally installs it alongside. When you build from source, the provider is off by default; add --features mpv (see step 7).


2. Get the code

git clone https://github.com/jonx/Ferail.git
cd Ferail

3. Build & run

cargo run --bin ferail-gpui

The first build clones gpui / gpui-component from git and compiles a large dependency tree: expect several minutes and a lot of crates. This is normal and happens once; later builds are incremental and fast.

A window opens onto your home folder. You're running Ferail.

macOS note: folder access. Run loosely like this, Ferail inherits your terminal's privacy identity, so reads of protected folders (Desktop / Documents / Downloads / removable / network) show an in-app "Access required" screen instead of the normal system prompt. To get the real "…would like to access…" prompts, run the signed app bundle: see step 5 and its permissions notes.


4. Verify your setup

cargo test --workspace                       # the test suite should pass
cargo run --bin ferail-gpui -- --doctor    # health check: config, storage, deps

--doctor prints a storage/environment report and exits: handy if the GUI won't start, and the same report the in-app Settings → Diagnostics page shows. (Sharing a report? The Diagnostics page redacts file names and paths by default, so it's safe to send.)


5. macOS: the signed .app bundle

For the real per-folder access prompts (and a normal app you can launch from Finder), build a bundle:

scripts/bundle-mac.sh && open target/Ferail.app

This ad-hoc-signs the app by default. For grants that persist across rebuilds, sign with a real identity:

CODESIGN_IDENTITY="Developer ID Application: …" scripts/bundle-mac.sh

macOS permissions

macOS gates the protected folders (Desktop, Documents, Downloads, removable volumes, network volumes, cloud providers) behind its privacy system (TCC). The "Ferail would like to access files in your Documents folder" prompt only appears when all of these hold:

  1. the path is in one of those promptable categories (arbitrary folders are never promptable: they need Full Disk Access);
  2. Ferail runs as a code-signed .app bundle with a stable identity;
  3. that bundle's Info.plist declares the matching NS*UsageDescription string (packaging/macos/Info.plist).

Caveats:

  • Stale grants from terminal runs. Earlier cargo run sessions attribute grants/denials to Terminal, not Ferail. If the bundle doesn't prompt, clear the stale state:

    tccutil reset SystemPolicyRemovableVolumes me.jkn.ferail
    tccutil reset SystemPolicyDocumentsFolder  me.jkn.ferail
  • Ad-hoc signing doesn't persist. The default ad-hoc signature changes every build, so macOS treats each build as a new app and re-prompts. Sign with a real identity (above) for grants that stick.

  • After a denial, macOS never re-prompts. Once you click "Don't Allow", the only recourse is the in-app "Open Full Disk Access settings" link (also the path for arbitrary, non-promptable folders).


6. Windows: a distributable build

cargo run is all you need for development: unlike macOS, Windows gates no folders behind a signed-bundle identity, so there is no permissions reason to package. Packaging is purely for handing the app to someone else:

./scripts/package-win.ps1

That builds release binaries, stages them with the licence files, and writes target/package/Ferail-<version>-win-x64.zip:

Ferail/
├── Ferail.exe          the app
├── cli/ferail.exe      the `ferail magic` / `ferail du` CLI
└── licenses/           MIT, Apache-2.0, third-party notices

The CLI sits in cli/ rather than beside the app on purpose: Windows paths are case-insensitive, so ferail.exe next to Ferail.exe is one file and the second one written silently wins. The script asserts the two staged binaries are distinct so that cannot regress.

Install Inno Setup (winget install JRSoftware.InnoSetup) and it also emits a …-setup.exe installer with a Start Menu entry and an uninstaller.

Signing

macOS has notarization; Windows has Authenticode + SmartScreen reputation. An unsigned build works perfectly, but anyone who downloads one meets a "Windows protected your PC" interstitial, and reputation accrues to the certificate over time, so a public release wants signing from the first release, not the third:

./scripts/package-win.ps1 -SignCert C:\certs\ferail.pfx -SignPassword ...
# or, for a cert already in the user's store, pass its SHA1 thumbprint:
./scripts/package-win.ps1 -SignCert 9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B

$env:FERAIL_SIGN_CERT / $env:FERAIL_SIGN_PASSWORD work too, which is the shape CI wants. Both the payload and the installer get signed, and the script prints a Get-AuthenticodeSignature summary at the end. signtool.exe comes from the Windows SDK; the script finds it without a Developer Prompt.


7. Optional: enable the mpv video backend

With libmpv installed (step 1):

cargo run --bin ferail-gpui --features mpv

(Release downloads and the packaging scripts already build with this feature; the flag matters for cargo run/cargo build from source, where it is off by default.)

Then open Settings → Plugins, set the video player to mpv, and (if it isn't auto-found) point it at your libmpv. Now the viewer plays virtually any container and unlocks live grading + the chroma-keyed transparent video windows.


8. Command-line tools

Ferail ships a few non-GUI utilities:

cargo run --bin ferail -- magic <path>...                    # identify file types by content
cargo run --bin ferail -- du [--top N] [--packages] <path>   # disk-usage summary
cargo run --bin ferail-gpui -- --doctor                      # health check
cargo run --bin ferail-gpui -- --reset-db <scope>            # reset local metadata

Troubleshooting

  • First build takes forever. Expected: it's compiling gpui and the git dependency tree from source the first time. Incremental builds afterward are quick. Don't delete Cargo.lock; it pins the reproducible set.
  • macOS: folders show "Access required." You're running the loose binary, which can't prompt. Build and run the bundle (step 5).
  • Linux: blank window or a panic on launch. Almost always missing/broken Vulkan. Install mesa-vulkan-drivers (or vendor drivers) and confirm with vulkaninfo; in a VM, enable 3D acceleration or a software Vulkan (lavapipe). See docs/features/linux-port.md → Day-one steps.
  • mpv video doesn't play. Confirm libmpv is installed and that Settings → Plugins has mpv selected with a valid library path (source builds also need --features mpv; release downloads have it). --doctor reports whether libmpv was found.

Where to go next

  • README.md: overview, features, and platform status.
  • docs/ARCHITECTURE.md: how the code is organized and the one rule that shapes it (the UI must never stop).
  • CONTRIBUTING.md: the contribution workflow (AI PRs welcome) and the pre-PR checklist.
  • CLAUDE.md: the operating manual if you're driving an AI agent.
  • TODO.md: what's unfinished and where to help.