Project:Chromium/Packaging Electron apps

From Gentoo Wiki
Jump to:navigation Jump to:search

Packaging Electron apps on Gentoo is relatively straightforward.

A good portion of electron apps aren't particularly picky about the electron that they're built against: if there are no native modules in use, app.asar file can be installed directly from an upstream release and executed with a system electron binary.

Warning
YMMV, IANAL. The NodeJS (and Electron) ABIs move pretty quickly and although transpiled JS or CJS should run on any modern version of Node there is no guarantee of correct behaviour. Please don't blame me if Electron kicks your dog.
user $/usr/bin/electron-36 /usr/share/foo/app.asar
Tip
Gentoo provides electron as from-source and -bin packages. The -bin also includes appropriate node headers to build native modules.

TLDR

Upstream precompiled releases

It is acceptable to package electron applications directly from upstream releases:

  • Try to only install the app.asar and any icons.
    • app.asar will always(?) be found in the resources subdir
  • This should be installed into /usr/share/${P}
  • All of the other files are going to be part of the electron runtime and can be discarded.
  • Create a desktop file pointing to ${ELECTRON_VERSION} ${EPREFIX}/usr/share/${P}/app.asar

If it is not possible (or the build is straightforward), consider building the package from source

As a last resort, -bin packages may be installed (including their bundled electron) to /opt

Building from source

https://en.opensuse.org/openSUSE:Packaging_Electron https://wiki.archlinux.org/title/Electron_package_guidelines

There are tons of build systems, but almost all of them involve running some sort of node package manager and invoking a build script. Think npm, yarn, pnpm, etc. This all gets stuffed into a webpack typically via electron-builder using the project's preferred tool (esbuild is popular, and painful for distros!

Don't be afraid to call build steps directly, invoking the PM can be painful.

If possible try not to run a full build - bail as soon as the app.asar has been built. We can install that and there's no need to bundle our electron.

If the PM has to be invoked for some reason, it may be necessary to sed package.json to get the desired behaviour (like not trying to vendor an old version of itself...)

It's fine to use the bundled electron builder - it's just JS executed at runtime. 

./node_modules/.bin/electron-builder --dir \
		-c.electronDist="${ELECTRON_DIR}" \
		-c.electronVersion="${ELECTRON_VERSION}" || die "Failed to package electron asar"

Tools like esbuild include a native component and must be built. Ideally a system copy can be used.

Electron eclass

The electron eclass can be used in electron builds.

It provides several helper functions, including ...

It does ....

Ebuilds that use the electron eclass will automatically depend on electron and electron-bin

Ebuilds can set a minimum or maximum electron version before the inherit to influence dependency generation

The electron eclass will pick the latest electron that matches version requirements, with electron being preferred over electron-bin.

It will provide

${ELECTRON} ${ELECTRON_VERSION} ${ELECTRON_TYPE} ${ELECTRON_DIR}

Vendor tarballs

It's unreasonable to expect each and every node module (and version!) be packaged and slotted into Gentoo.

Instead, following the example of Rust and Golang, electron app ebuilds should include a vendor tarball containing node_modules.

Tip
There are helper scripts in proj/chromium-tools to assist with this process.

If generating vendor tarballs manually, ensure that no binaries are included - often binaries will be fetched (or compiled) as part of the npm install process as part of postinst scripts. There are environment variables that may be used to prevent this (some specific, some not), as well as package-manager-specific flags to avoid running build scripts after fetching. Despite this many dependencies will include native binaries in their npm distribution, and these will need to be identified and stripped.

Troubleshooting

Electron Builder

The DEBUG environment variable can be used to debug what electron-builder is doing:

user $DEBUG=electron-builder

The FPM_DEBUG environmen variable can be used to gather additional details about building Linux targets.

Retrieved from "https://wiki.gentoo.org/index.php?title=Project:Chromium/Packaging_Electron_apps&oldid=1400655"