Electron¶

Devido à natureza do Electron, a criação de aplicativos Electron como Flatpaks requer algumas etapas extras em comparação com outros aplicativos. Felizmente, várias ferramentas e recursos estão disponíveis, o que facilita muito isso.

Este guia fornece informações sobre como a compilação de aplicativos Electron difere de outros aplicativos. Ele também inclui informações sobre as ferramentas para a compilação de aplicativos Electron e como usá-lo.

O guia percorre o arquivo de manifesto do aplicativo de amostra Electron de Flatpak. Antes de começar, é uma boa ideia dar uma olhada nisso, online ou baixando o aplicativo.

Compilando o aplicativo de amostra¶

Embora não seja estritamente necessário, convém tentar compilar e executar o aplicativo de amostra.

Para obter a configuração para a compilação, baixe ou clone o aplicativo de exemplo no GitHub e navegue até o diretório /flatpak no terminal. Você também deve instalar o aplicativo base Electron e a extensão de SDK Node.js:

$ flatpak install flathub org.electronjs.Electron2.BaseApp//23.08
$ flatpak install flathub org.freedesktop.Sdk.Extension.node18//23.08

Então, você pode executar a compilação:

$ flatpak-builder build org.flathub.electron-sample-app.yml --install --force-clean --user

Finalmente, o aplicativo pode ser executado com:

$ flatpak run org.flathub.electron-sample-app

Configuração básica¶

A primeira parte do manifesto do aplicativo de amostra especifica o ID do aplicativo. Ele também configura o runtime e o SDK:

id: org.flathub.electron-sample-app
runtime: org.freedesktop.Platform
runtime-version: '23.08'
sdk: org.freedesktop.Sdk

O runtime do Freedesktop é geralmente o melhor runtime para uso com aplicativos Electron, já que ele é o mais mínimo de todos e outras dependências serão específicas do próprio Electron.

O aplicativo base Electron¶

Em seguida, o manifesto especifica que o aplicativo base Electron deve ser usado, especificando as propriedades base e base-version no manifesto do aplicativo:

base: org.electronjs.Electron2.BaseApp
base-version: '23.08'

Os aplicativos base estão descritos em Dependências. Usar o aplicativo base Electron é muito mais rápido e mais conveniente do que compilar manualmente as dependências do Electron. Ele também tem a vantagem de reduzir a quantidade de duplicação nas máquinas dos usuários, pois significa que o Electron é salvo apenas uma vez no disco.

A extensão de SDK Node.js¶

Para criar aplicativos baseados em Electron, você precisa do Node.js disponível no momento da compilação. O Flathub fornece versões LTS do Node.js como extensões para o SDK, para que você possa instalar uma delas e adicioná-la no manifesto de seus aplicativos:

sdk-extensions:
  - org.freedesktop.Sdk.Extension.node18

Habilite a extensão adicionando-a a PATH:

build-options:
  append-path: /usr/lib/sdk/node18/bin

Observe que o nome da extensão (última parte da notação de DNS reverso, node18 neste exemplo) deve ser o mesmo em sdk-extensions e append-path.

Command¶

A propriedade command indica que um script chamado run.sh deve ser executado para executar o aplicativo. Isso será explicado em mais detalhes posteriormente.

command: run.sh

Permissões de sandbox¶

The standard guidelines on sandbox permissions apply to Electron applications. However, Electron does not use Wayland by default. So for display access, only X11 should be used as the default configuration. This will make Electron use Xwayland in a wayland session and nothing else is required.

The sample app also configures pulseaudio for sound and enables network access.

finish-args:
  - --share=ipc
  - --socket=x11
  - --socket=pulseaudio
  - --share=network

Nota

Native wayland support in electron is experimental and often unstable. It is advised to stick with the X11 and Xwayland configuration above as the default.

To enable experimental native Wayland support in Electron>=20, the --ozone-platform-hint=auto flag can be passed to the program. auto will choose Wayland when the seesion is wayland and Xwayland or X11 otherwise.

The recommended option is to leave it to the user. So --socket=x11 should be used in manifest and Wayland can be tested with:

flatpak run --socket=wayland org.flathub.electron-sample-app

To make native wayland the default for users --socket=fallback-x11 and --socket=wayland must be used in the manifest.

Client-side window decorations in native wayland can be enabled by passing --enable-features=WaylandWindowDecorations (Electron>=17).

Electron uses libnotify on Linux to provide desktop notifications. libnotify since 0.8.0 automatically uses the notification portal when inside a sandboxed environment and --talk-name=org.freedesktop.Notifications is not required.

org.electronjs.Electron2.BaseApp since branch/23.08 comes with libnotify>=0.8.0

Opções de compilação¶

Essas opções de compilação não são estritamente necessárias, mas podem ser úteis se algo der errado. env permite definir uma matriz de variáveis de ambiente; nesse caso, definimos NPM_CONFIG_LOGLEVEL para info, para que npm nos forneça mensagens de erro mais detalhadas.

build-options:
  cflags: -O2 -g
  cxxflags: -O2 -g
  env:
    NPM_CONFIG_LOGLEVEL: info

O módulo do aplicativo¶

A seção final do manifesto define como o módulo do aplicativo deve ser compilado. É aqui que algumas das lógicas adicionais para Electron e Node.js podem ser encontradas.

Por padrão, o flatpak-builder não permite que ferramentas de compilação acessem a rede. Isso significa que as ferramentas que dependem do download de fontes não funcionarão. Portanto, os pacotes Node.js devem ser baixados antes da execução da compilação. Definir a variável de ambiente electron_config_cache significa que elas serão encontradas quando se trata da compilação.

A próxima parte do manifesto descreve como o aplicativo deve ser criado. A opção buildsystem definida com simple é usada, o que permite que uma sequência de comandos seja especificada, que são usados para a compilação. O local do download e o hash do aplicativo também são especificados.

name: electron-sample-app
buildsystem: simple
build-options:
  env:
    XDG_CACHE_HOME: /run/build/electron-sample-app/flatpak-node/cache
    npm_config_cache: /run/build/electron-sample-app/flatpak-node/npm-cache
    npm_config_nodedir: /usr/lib/sdk/node18
    npm_config_offline: 'true'
subdir: main
sources:
  - type: archive
    url: https://github.com/flathub/electron-sample-app/archive/1.0.1.tar.gz
    sha256: a2feb3f1cf002a2e4e8900f718cc5c54db4ad174e48bfcfbddcd588c7b716d5b
    dest: main

Empacotando pacotes NPM¶

A próxima linha é como os módulos NPM são empacotados como parte de Flatpaks:

- generated-sources.json

Como até mesmo aplicativos simples do Node.js dependem de dezenas de pacotes, seria impraticável especificar todos eles como parte de um arquivo de manifesto. Um script em Python foi, portanto, desenvolvido para baixar pacotes Node.js com o NPM ou Yarn e inclui-los nas fontes do aplicativo.

O script Python requer um arquivo package-lock.json (ou yarn.lock). Este arquivo contém informações sobre os pacotes dos quais um aplicativo depende e pode ser gerado executando npm install --package-lock-only no diretório raiz de um aplicativo. O script é então executado da seguinte maneira:

$ flatpak-node-generator npm package-lock.json

Isso gera o manifesto JSON necessário para compilar os pacotes NPM/Yarn para o aplicativo, que são gerados em um arquivo chamado generated-sources.json. O conteúdo desse arquivo pode ser copiado para o manifesto do aplicativo, mas, como geralmente é muito longo, é melhor vinculá-lo a partir do manifesto principal, o que é feito adicionando generated-source.json como um linha na seção do manifesto, como visto acima.

Iniciando o aplicativo¶

O aplicativo Electron é executado através de um script simples. Isso pode receber qualquer nome, mas deve ser especificado na propriedade "command": do manifesto. Veja abaixo um exemplo de wrapper para iniciar um aplicativo:

- type: script
  dest-filename: run.sh
  commands:
    - zypak-wrapper.sh /app/main/electron-sample-app "$@"

Comandos de compilação¶

Por último, mas não menos importante, como a opção de compilação simples está sendo usada, uma lista de comandos de compilação deve ser fornecida. Como pode ser visto, npm é executado com a variável de ambiente npm_config_offline=true, instalando dependências de pacotes que já foram armazenados em cache. Estes são copiados para /app/main/. Finalmente, o script run.sh é instalado em /app/bin/ para que ele esteja em $PATH:

build-commands:
  # Install npm dependencies
  - npm install --offline
  # Build the app; in this example the `dist` script
  # in package.json runs electron-builder
  - |
    . ../flatpak-node/electron-builder-arch-args.sh
    npm run dist -- $ELECTRON_BUILDER_ARCH_ARGS  --linux --dir
  # Bundle app and dependencies
  - cp -a dist/linux*unpacked /app/main
  # Install app wrapper
  - install -Dm755 -t /app/bin/ ../run.sh

Note que se o aplicativo que você está tentando empacotar contiver um bloco build no package.json com instruções para Linux, isso pode fazer com que o electron-builder tente buscar binários adicionais em tempo de compilação (Mesmo se a opção –dir for usada). O exemplo a seguir mostra uma configuração que tentará baixar os binários do AppImage:

"build": {
  "linux": {
    "target": "AppImage",
  }
}

A maneira preferida de corrigir isso não é um patch, mas uma edição em tempo de construção usando jq. O comando a seguir substituirá "target": "AppImage" por "target": "dir":

jq '.build.linux.target="dir"' <<<$(<package.json) > package.json