Portable Mode

Portable Mode

Emutastic supports a fully portable install — useful for USB sticks, sync folders (Syncthing / Nextcloud), running multiple isolated profiles from the same binary, or just keeping everything self-contained instead of scattering data across ~/.local/share and ~/.config.

The portable install is truly portable: take the entire app folder to a USB stick, plug it into any Linux box, and it runs as-is. Mount points don't matter (/media/usb on one machine, /run/media/you/STICK on another); ROMs you import auto-copy onto the USB so they travel with you; cores download into the data folder so a different machine doesn't need to redownload anything.

Enable

Either trigger works (both are opt-in):

1. Marker file — drop a zero-byte file named portable.txt into the same folder as the Emutastic binary, then launch.
2. CLI flag — launch with --portable on the command line: ./Emutastic --portable. Useful for a desktop shortcut or a launcher script when you don't want to leave a marker file in the install folder.

That's it. Both the config file and the data root get redirected to a PortableData/ subfolder beside the binary. ~/.local/share/Emutastic and ~/.config/Emutastic are never touched, and the first-run "choose data folder" prompt is skipped.

What lives where

Everything Emutastic needs at runtime lives inside the install folder:

Emutastic            (the binary)
*.so                 (.NET runtime + dependencies, ships with the build)
portable.txt         (empty marker — opt-in only)
PortableData/
    config.json       (everything that would normally live in ~/.config/Emutastic)
    library.db
    Cores/            (libretro core .so files — downloaded here in portable mode)
    Native/           (user-downloaded native helpers, e.g. ffmpeg)
    DATs/             (Redump/No-Intro DATs for CHD identification)
    Roms/             (ROMs auto-copied here on import in portable mode)
    System/           (BIOS files)
    Saves/            (battery saves, RetroArch-style <rom>.srm)
    Save States/
    Screenshots/
    Recordings/
    Snaps/
    Artwork/
    BoxArt3D/
    ss2d/
    Themes/
    Cheats/
    CheatsDatabase/
    CoreOptions/
    RomPatches/
    ExtractedRoms/    (archive imports get extracted here)
    Logs/
    Overlays/

Moving between machines

Move (or copy) the entire Emutastic folder to your USB stick, then plug into a different Linux box and run the Emutastic binary from the USB. No setup, no config changes — your library, saves, cores, and ROMs come along automatically.

How mount-point independence works: filesystem paths under PortableData/ are stored in the database as relative paths (e.g. Roms/NES/zelda.smc) instead of absolute paths. The binary resolves them against its own location at runtime, so /media/usb/Emutastic/PortableData/Roms/NES/zelda.smc on machine A becomes /run/media/you/STICK/Emutastic/PortableData/Roms/NES/zelda.smc on machine B with no DB changes needed. (AppPaths.ToStoragePath / FromStoragePath do the relativizing.)

ROM import behaviour

In portable mode, every ROM you import gets automatically copied into PortableData/Roms/<Console>/, regardless of how Preferences → Library is configured and regardless of where the source file lives. The CopyToLibrary setting and LibraryPath setting are ignored — portable mode wins, because a ROM outside the portable folder defeats the whole point. The source can be on the USB, a fixed internal drive, a network share, anywhere readable at import time; the copy lands in PortableData and the database stores a relative path. Archive imports continue to extract into PortableData/ExtractedRoms/<Console>/ as before.

If the copy fails (permission denied, disk full), the import is skipped with a visible warning rather than silently importing the unportable source path. Retry after fixing the underlying problem.

Note on disk usage: this means a ROM that already lives on the USB stick (e.g. at /media/usb/my-rom-collection/) gets duplicated into PortableData/Roms/ rather than referenced in place. That keeps the rule simple — "everything Emutastic uses lives inside PortableData/" — at the cost of some duplicated bytes on the USB. A future release may add same-volume relative-path support so on-USB collections aren't duplicated; for now, the guarantee is that nothing the app touches escapes PortableData/.

Important — enable portable mode BEFORE importing ROMs. ROMs imported while running in normal mode stay at their original location, and the database stores the absolute path to wherever you grabbed them from. Switching to portable mode afterwards does NOT reach back to copy those ROMs into PortableData. If you've already been using Emutastic in normal mode and want to go portable, the cleanest path is: enable portable mode first (drop portable.txt, launch once), then re-import your ROM folder. The portable launch will copy each ROM into PortableData and the library will travel with the USB from there on.

Disable

Delete portable.txt. The next launch reads ~/.local/share/Emutastic like a normal install.

Your PortableData/ folder is left untouched on disk — Emutastic just stops looking at it. If you want to switch back to portable later, drop the marker back in and your data is right there. To reclaim the space, delete the folder manually.

Caveats

• Marker location is strict — portable.txt must sit in the same directory as the Emutastic binary, not inside a subfolder.
• Folder must be writable — running from a read-only location (read-only mount, locked network share) silently falls back to ~/.local/share/Emutastic mode. Note that a .deb install puts the binary under a read-only system path (e.g. /usr/lib/emutastic), so portable mode is meant for the self-contained tarball build, not the packaged install.
• No single-instance lock — unlike the Windows app, the Linux port doesn't hold a global single-instance mutex, so a portable copy and an installed copy can run side by side. They use independent data roots; just don't point two running instances at the same PortableData/ folder.
• Dev workflow unaffected — there's no portable.txt in the source tree, so debug/release builds default to the standard ~/.local/share/Emutastic (or your configured custom data folder).