Skip to content

linux-packaging.md

Latest commit

 

History

History
165 lines (129 loc) · 4.85 KB

linux-packaging.md

File metadata and controls

165 lines (129 loc) · 4.85 KB
Raw

Linux Packaging

Status: stale legacy Electron packaging notes.

Cells now uses the NW.js runtime as the primary development, packaging, and release path. The Electron runtime and Electron Builder packaging are deprecated and are kept only behind explicit legacy-electron scripts. This document is retained as historical guidance for the old Linux package flow until NW.js Linux packaging is rebuilt.

Cells publishes Linux release artifacts for x64 and arm64:

  • Cells-<version>-linux-<arch>.AppImage
  • Cells-<version>-linux-<arch>.deb
  • Cells-<version>-linux-x86_64.rpm

The .deb is the recommended artifact for Ubuntu and Debian-based systems. The AppImage is the recommended upstream binary input for distro package repositories such as Nixpkgs and Gentoo overlays because it is self-contained and does not run package-manager maintainer scripts from another distro.

Build Locally

On Linux:

pnpm install --frozen-lockfile
pnpm release:legacy-electron:linux

pnpm release:legacy-electron:linux builds the deprecated Electron app, bundles Linux zellij and tmux binaries for x64 and arm64, and emits AppImage, deb, and x64 rpm artifacts in release/. This is not the active Cells runtime.

To build only the host architecture while developing packaging changes:

pnpm prepare:mcp-server
pnpm prepare:terminal-bundles
pnpm typecheck
pnpm build:legacy-electron
pnpm exec electron-builder --linux --publish never

Ubuntu

Users can install the release .deb directly:

sudo apt install ./Cells-<version>-linux-x64.deb

For an apt repository or PPA, publish the upstream .deb or rebuild it from a source checkout. A minimal source-package flow is:

git clone https://github.com/xrehpicx/cells.git cells_<version>
cd cells_<version>
git checkout v<version>
pnpm install --frozen-lockfile
pnpm release:legacy-electron:linux

The generated legacy Electron deb declares the runtime libraries that old package needs:

  • libgtk-3-0
  • libnotify4
  • libnss3
  • libxss1
  • libxtst6
  • xdg-utils
  • libatspi2.0-0
  • libuuid1
  • libsecret-1-0

Nix and NixOS

Use the Linux AppImage as the packaged binary input. This derivation is suitable for a Nixpkgs package or an overlay:

{ appimageTools
, fetchurl
, lib
}:

let
  version = "<version>";
  src = fetchurl {
    url = "https://github.com/xrehpicx/cells/releases/download/v${version}/Cells-${version}-linux-x64.AppImage";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };
  appimageContents = appimageTools.extractType2 { inherit src; pname = "cells"; inherit version; };
in
appimageTools.wrapType2 {
  pname = "cells";
  inherit version src;

  extraInstallCommands = ''
    install -Dm444 ${appimageContents}/cells.desktop $out/share/applications/cells.desktop
    install -Dm444 ${appimageContents}/cells.png $out/share/pixmaps/cells.png
    substituteInPlace $out/share/applications/cells.desktop \
      --replace-fail 'Exec=AppRun' 'Exec=cells'
  '';

  meta = {
    description = "Infinite desktop workspace for terminals, browsers, and agent workflows";
    homepage = "https://github.com/xrehpicx/cells";
    license = lib.licenses.asl20;
    platforms = [ "x86_64-linux" "aarch64-linux" ];
    mainProgram = "cells";
  };
}

For aarch64-linux, change the artifact name to Cells-${version}-linux-arm64.AppImage and update the hash.

Gentoo

Use the Linux AppImage in an overlay ebuild. This skeleton installs the prebuilt AppImage under /opt/cells and exposes /usr/bin/cells:

EAPI=8

DESCRIPTION="Infinite desktop workspace for terminals, browsers, and agent workflows"
HOMEPAGE="https://github.com/xrehpicx/cells"
SRC_URI="
  amd64? ( https://github.com/xrehpicx/cells/releases/download/v${PV}/Cells-${PV}-linux-x86_64.AppImage -> ${P}-amd64.AppImage )
  arm64? ( https://github.com/xrehpicx/cells/releases/download/v${PV}/Cells-${PV}-linux-arm64.AppImage -> ${P}-arm64.AppImage )
"

LICENSE="Apache-2.0"
SLOT="0"
KEYWORDS="~amd64 ~arm64"
IUSE=""

RDEPEND="
  dev-libs/nss
  gnome-base/librsvg
  sys-apps/dbus
  sys-fs/fuse:0
  x11-libs/gtk+:3
  x11-libs/libnotify
  x11-libs/libXtst
  x11-misc/xdg-utils
"

S="${WORKDIR}"

src_install() {
  local appdir="/opt/cells"
  local image
  use amd64 && image="${DISTDIR}/${P}-amd64.AppImage"
  use arm64 && image="${DISTDIR}/${P}-arm64.AppImage"
  exeinto "${appdir}"
  newexe "${image}" cells.AppImage
  dosym "${appdir}/cells.AppImage" /usr/bin/cells
}

After adding the ebuild to an overlay:

ebuild cells-<version>.ebuild manifest
emerge --ask cells

Maintainer Checklist

  1. Replace <version> with the release version without the leading v.
  2. Replace all placeholder hashes with hashes from the downloaded artifacts.
  3. Test launch on a clean VM for each target distro.
  4. Confirm terminal panes can start; this verifies the bundled tmux and zellij binaries are reachable.