Upload via GUI (7543 Dateien)

2026-10-22 06:58:16 +00:00
parent 68133f4d0f
commit 860c714301
50 changed files with 3039 additions and 0 deletions
@@ -0,0 +1,19 @@
+Copyright (c) 2016 Endless Mobile, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,210 @@
+# @malept/flatpak-bundler [![Version](https://img.shields.io/npm/v/@malept/flatpak-bundler.svg)](https://www.npmjs.com/package/@malept/flatpak-bundler) [![Build Status](https://github.com/malept/flatpak-bundler/workflows/CI/badge.svg)](https://github.com/malept/flatpak-bundler/actions?query=workflow%3ACI)
+Build [flatpaks](https://flatpak.org/) from Node.js.
+
+# Quick Start
+
+Install `@malept/flatpak-bundler`.
+```shell
+$ npm install @malept/flatpak-bundler
+```
+
+[Build a flatpak with a Node script](#hello-world).
+
+Install and run it!
+```shell
+$ flatpak install --user --bundle hello.flatpak
+$ flatpak run org.world.Hello
+Hello, world!
+```
+
+## Overview
+This modules allows building flatpaks programmatically from Node. It requires
+Node 10 or above and flatpak >= 0.6.13 to be installed on your system.
+
+Under the hood, this is just a wrapper for the [flatpak-builder](https://docs.flatpak.org/en/latest/flatpak-builder.html)
+tool with some extra sugar added.
+
+With `flatpak-builder`, you specify a runtime, sandbox permissions and software
+modules to build into your application, and build a flatpak from start to finish.
+This module provides a few additional features:
+
+ - Supports auto installing flatpak runtime and app dependencies
+ - Supports exporting directly to the a single file flatpak bundle
+ - Supports easy copying files and creating symlinks directly in `/app`
+
+The latter is particularly useful for [Electron](https://electronjs.org/) and
+[nw.js](http://nwjs.io/) style Node applications, which often create packages
+from prebuilt binaries and do not attempt to follow an autotools-like
+[build api](https://github.com/cgwalters/build-api).
+
+This module should make it easy to plug flatpak support into an Electron or nw.js
+app packaging phase.
+
+## Usage
+
+### translateArch(arch)
+
+Used to translate a Node-style arch (e.g., `x64`) into a Flatpak-compatible arch (e.g., `x86_64`).
+
+If the arch is unknown, it will pass through the input value.
+
+### bundle(manifest, buildOptions)
+
+Takes an [app manifest](#manifest) and a build options object. It returns a Promise.
+
+Both the manifest and options objects support both camelCase and dash-separated
+variants of any option.
+
+The promise is returned with a `finalBuildOptions` value. It contains the build
+options after default values have been applied. Useful to read out the
+`workingDir`, for example.
+
+#### Manifest
+
+This matches the format for [`flatpak-builder` app
+manifests](https://docs.flatpak.org/en/latest/manifests.html), with a few extra
+options added and camelCase variants supported.
+
+ - **id**: Required. The application id.
+ - **runtime**: Required. The runtime for your flatpak application.
+ - **sdk**: Required. The sdk for your flatpak application.
+ - **base**: An app to inherit from. Use the app as a "base" for `/app`
+   contents.
+ - **finishArgs**: The arguments to pass to `flatpak build-finish`. Use this to
+   add sandbox permissions. See the [Electron app example](#electron-app) for
+   some common app permissions.
+ - **modules**: If you need to build other software modules into you flatpak app
+   (anything not already in your runtime or base app), you can specify them
+   here.
+
+#### Build Options
+
+ - **bundlePath**: Output location for a single file version of the flatpak. If
+   non supplied, the single file flatpak will not be created.
+ - **arch**: The architecture for the flatpak bundle. x86_64, i386 or arm.
+ - **workingDir**: The working directory to call `flatpak-builder` from.
+   Defaults to a new tmp directory.
+ - **buildDir**: The directory to build the application in. Defaults to
+   `${workingDir}/build`
+ - **repoDir**: The directory for a flatpak repo, can be used to publish to an
+   existing repo. Defaults to `${workingDir}/repo`
+ - **cleanTmpdirs**: Cleanup any tmp directories created during the build on
+   process exit. Defaults to true. Set false for easier debugging.
+ - **autoInstallRuntime**: Install/update the runtime while building. Defaults
+   to true if runtimeFlatpakref is set in the manifest.
+ - **autoInstallSdk**: Install/update the sdk while building. Defaults
+   to true if sdkFlatpakref is set in the manifest.
+ - **autoInstallBase**: Install/update the base app while building. Defaults
+   to true if baseFlatpakref is set in the manifest.
+ - **gpgSign**: The gpg key to use to sign the flatpak repo and bundle file.
+ - **gpgHomedir**: The gpg homedir to use when signing.
+ - **subject**: The single line subject to use for the flatpak repo commit
+   message.
+ - **body**: The description to use for the flatpak repo commit message.
+ - **files**: Files to copy directly into the app. Should be a list of [source,
+   dest] tuples. Source should be a relative/absolute path to a file/directory
+   to copy into the flatpak, and dest should be the path inside the app install
+   prefix (e.g. `/share/applications/`)
+ - **symlinks**: Symlinks to create in the app files. Should be a list of
+   [target, location] symlink tuples. Target can be either a relative or
+   absolute path inside the app install prefix, and location should be a
+   absolute path inside the prefix to create the symlink at.
+ - **extraExports**: Files to export outside of the flatpak sandbox, in addition
+   to the application desktop file, icons and appstream. File basename *must*
+   be prefixed with the app id. Should not be needed for common use.
+ - **runtimeFlatpakref**: A pathname or url to a flatpakref file to use to auto
+   install the runtime.
+ - **sdkFlatpakref**: A pathname or url to a flatpakref file to use to auto
+   install the sdk.
+ - **baseFlatpakref**: A pathname or url to a flatpakref file to use to auto
+   install the base app.
+ - **bundleRepoUrl**: Repo url for the single file bundle. Installing the bundle
+   will automatically configure a remote for this URL.
+ - **extraFlatpakBuilderArgs**: List of extra arguments to pass to the
+   [flatpak-builder](https://docs.flatpak.org/en/latest/flatpak-builder-command-reference.html) command.
+ - **extraFlatpakBuildExportArgs**: List of extra arguments to pass to the
+   [flatpak build-export](https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak-build-export) command.
+ - **extraFlatpakBuildBundleArgs**: List of extra arguments to pass to the
+   [flatpak build-bundle](https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak-build-bundle) command.
+
+### Logging
+To turn on debugging output, set the DEBUG environment variable:
+
+```shell
+DEBUG=flatpak-bundler npm run my-flatpak-command
+```
+
+## Examples
+
+### Hello world
+
+```javascript
+const flatpakBundler = require('@malept/flatpak-bundler')
+const fs = require('fs-extra')
+
+// Write a hello world script to disk
+await fs.writeFile('hello',
+`#!/bin/bash
+echo "Hello, world!"`, { mode: 0o755 })
+
+// Make a flatpak with it!
+try {
+  await flatpakBundler.bundle({
+    id: 'org.world.Hello',
+    runtime: 'org.freedesktop.Platform',
+    runtimeVersion: '1.4',
+    sdk: 'org.freedesktop.Sdk',
+  }, {
+    bundlePath: 'hello.flatpak',
+    files: [
+      ['hello', '/bin/hello']
+    ],
+    runtimeFlatpakref: 'https://raw.githubusercontent.com/endlessm/flatpak-bundler/master/refs/freedesktop-runtime-1.4.flatpakref'
+  })
+  console.log('Flatpak built successfully')
+} catch (error) {
+    console.error('Error building flatpak', error)
+}
+```
+
+### Electron App
+
+```javascript
+const flatpakBundler = require('@malept/flatpak-bundler')
+
+try {
+  const finalBuildOptions = await flatpakBundler.bundle({ // Manifest
+    id: 'org.world.Hello',
+    base: 'io.atom.electron.BaseApp', // Electron base application
+    runtime: 'org.freedesktop.Platform', // Use the freedesktop runtime
+    runtimeVersion: '1.4',
+    sdk: 'org.freedesktop.Sdk',
+    finishArgs: [
+      '--share=ipc', '--socket=x11', // Allow app to show windows with X11
+      '--socket=pulseaudio', // Allow audio output
+      '--filesystem=home', // Allow access to users home directory
+      '--share=network', // Allow network access
+      '--device=dri' // Allow OpenGL rendering
+    ],
+    renameDesktopFile: 'hello.desktop', // Rename the desktop file to agree with the app ID so flatpak will export it
+    renameIcon: 'hello' // Rename the icon to agree with the app ID so flatpak will export it
+  }, { // Build options
+    arch: 'x86_64',
+    baseFlatpakref: 'https://s3-us-west-2.amazonaws.com/electron-flatpak.endlessm.com/electron-base-app-master.flatpakref', // So we can auto install the runtime
+    bundlePath: 'dist/hello_x86_64.flatpak',
+    files: [
+      [ 'static/linux', '/share/' ], // Desktop file and icons
+      [ packagedFileDir, '/share/bar' ] // Application binaries and assets
+    ],
+    gpgSign: '1234ABCD', // GPG key to sign with
+    runtimeFlatpakref: 'https://raw.githubusercontent.com/endlessm/flatpak-bundler/master/refs/freedesktop-runtime-1.4.flatpakref',
+    symlinks: [
+      [ '/share/bar/Bar', '/bin/Bar' ] // Create a symlink in /bin to to app executable
+    ]
+  })
+  console.log('Flatpak built successfully.')
+  console.log(`Build dir and repo in ${finalBuildOptions.workingDir}`)
+} catch (error) {
+  console.error('Error building flatpak', error)
+}
+```
@@ -0,0 +1,318 @@
+'use strict'
+
+const _ = require('lodash')
+const childProcess = require('child_process')
+const fs = require('fs-extra')
+const path = require('path')
+const { promisify } = require('util')
+const tmp = require('tmp-promise')
+
+const pkg = require('./package.json')
+const logger = require('debug')(pkg.name)
+
+const exec = promisify(childProcess.exec)
+
+function kebabify (object) {
+  return _.cloneDeepWith(object, (value) => {
+    if (!value || typeof value !== 'object') return value
+
+    return Object.keys(value).reduce((newValue, key) => {
+      newValue[_.kebabCase(key)] = value[key]
+      return newValue
+    }, {})
+  })
+}
+
+function translateArch (arch) {
+  if (arch === 'ia32') return 'i386'
+  if (arch === 'x64') return 'x86_64'
+  if (arch === 'amd64') return 'x86_64'
+  if (arch === 'armv7l') return 'arm'
+  return arch
+}
+
+function getOptionsWithDefaults (options, manifest) {
+  const defaults = {
+    'build-dir': path.join(options['working-dir'], 'build'),
+    'repo-dir': path.join(options['working-dir'], 'repo'),
+    'manifest-path': path.join(options['working-dir'], 'manifest.json'),
+    'extra-flatpak-builder-args': [],
+    'extra-flatpak-build-bundle-args': [],
+    'extra-flatpak-build-export-args': [],
+    'clean-tmpdirs': true,
+    'auto-install-runtime': typeof options['runtime-flatpakref'] !== 'undefined',
+    'auto-install-sdk': typeof options['sdk-flatpakref'] !== 'undefined',
+    'auto-install-base': typeof options['base-flatpakref'] !== 'undefined'
+  }
+  options = _.defaults({}, options, defaults)
+  options['working-dir'] = path.resolve(options['working-dir'])
+  options['build-dir'] = path.resolve(options['build-dir'])
+  options['repo-dir'] = path.resolve(options['repo-dir'])
+  options['manifest-path'] = path.resolve(options['manifest-path'])
+  if (options['bundle-path']) options['bundle-path'] = path.resolve(options['bundle-path'])
+  return options
+}
+
+async function spawnWithLogging (options, command, args, allowFail) {
+  return new Promise((resolve, reject) => {
+    logger(`$ ${command} ${args.join(' ')}`)
+    const child = childProcess.spawn(command, args, { cwd: options['working-dir'] })
+    child.stdout.on('data', (data) => {
+      logger(`1> ${data}`)
+    })
+    child.stderr.on('data', (data) => {
+      logger(`2> ${data}`)
+    })
+    child.on('error', (error) => {
+      reject(error)
+    })
+    child.on('close', (code) => {
+      if (!allowFail && code !== 0) {
+        reject(new Error(`${command} failed with status code ${code}`))
+      }
+      resolve(code === 0)
+    })
+  })
+}
+
+function addCommandLineOption (args, name, value) {
+  if (!value) return
+
+  args.push(`--${name}`)
+  if (value !== true) args.push(value)
+}
+
+async function checkInstalled (id, options, version, checkUser) {
+  const args = ['info']
+  addCommandLineOption(args, 'show-commit', true)
+  addCommandLineOption(args, checkUser ? 'user' : 'system', true)
+  args.push([id, options.arch, version].join('/'))
+  return spawnWithLogging(options, 'flatpak', args, true)
+}
+
+let _flatpakBuilderVersion
+
+/**
+ * Get the flatpak-builder version in a comparable form (Array of Numbers).
+ */
+async function flatpakBuilderVersion () {
+  if (!_flatpakBuilderVersion) {
+    const versionString = _.last((await exec('flatpak-builder --version')).toString().split(' '))
+    _flatpakBuilderVersion = versionString.split('.').map(part => parseInt(part, 10))
+  }
+
+  return _flatpakBuilderVersion
+}
+
+async function addAssumeYesArg (args) {
+  if ((await flatpakBuilderVersion()) >= [0, 9, 9]) {
+    logger('flatpak-builder is new enough, adding --assumeyes')
+    addCommandLineOption(args, 'assumeyes', true)
+  }
+}
+
+async function ensureRef (options, manifest, type, version) {
+  const flatpakref = options[`${type}-flatpakref`]
+  const id = manifest[type]
+  if (!options[`auto-install-${type}`]) {
+    return
+  }
+  logger(`Ensuring ${type} is up to date`)
+
+  logger(`Checking for install of ${id}`)
+  const [userInstall, systemInstall] = await Promise.all([
+    checkInstalled(id, options, version, true),
+    checkInstalled(id, options, version, false)
+  ])
+  if (!userInstall && !systemInstall) {
+    logger(`No install of ${id} found, trying to install from ${flatpakref}`)
+    if (!flatpakref) {
+      throw new Error(`Cannot install ${id} without flatpakref`)
+    }
+    const args = ['install']
+    addCommandLineOption(args, 'user', true)
+    addCommandLineOption(args, 'no-deps', true)
+    addCommandLineOption(args, 'arch', options.arch)
+    await addAssumeYesArg(args)
+    if (flatpakref.startsWith('app/') || flatpakref.startsWith('runtime/')) {
+      args.push(flatpakref)
+    } else {
+      addCommandLineOption(args, 'from', flatpakref)
+    }
+    return spawnWithLogging(options, 'flatpak', args)
+  }
+
+  logger(`Found install of ${id}, trying to update`)
+  const args = ['update']
+  addCommandLineOption(args, 'user', userInstall)
+  addCommandLineOption(args, 'no-deps', true)
+  addCommandLineOption(args, 'arch', options.arch)
+  await addAssumeYesArg(args)
+  args.push(id)
+  if (version) {
+    args.push(version)
+  }
+  return spawnWithLogging(options, 'flatpak', args)
+}
+
+async function ensureRuntime (options, manifest) {
+  return ensureRef(options, manifest, 'runtime', manifest['runtime-version'])
+}
+
+async function ensureSdk (options, manifest) {
+  return ensureRef(options, manifest, 'sdk', manifest['runtime-version'])
+}
+
+async function ensureBase (options, manifest) {
+  return ensureRef(options, manifest, 'base', manifest['base-version'])
+}
+
+async function ensureWorkingDir (options) {
+  if (!options['working-dir']) {
+    const dir = await tmp.dir({ prefix: 'flatpak-bundler', unsafeCleanup: options['clean-tmpdirs'] })
+    options['working-dir'] = dir.path
+  } else {
+    return fs.ensureDir(options['working-dir'])
+  }
+}
+
+async function writeJsonFile (options, manifest) {
+  return fs.writeJson(options['manifest-path'], manifest, { space: '  ' })
+}
+
+async function copyFiles (options, manifest) {
+  if (!options.files) {
+    return
+  }
+
+  return Promise.all(options.files.map(async sourceDest => {
+    const source = path.resolve(sourceDest[0])
+    const dest = path.join(options['build-dir'], 'files', sourceDest[1])
+    let dir = dest
+    if (!dir.endsWith(path.sep)) {
+      dir = path.dirname(dir)
+    }
+
+    logger(`Copying ${source} to ${dest}`)
+    await fs.ensureDir(dir)
+    await fs.copy(source, dest)
+  }))
+}
+
+async function createSymlinks (options, manifest) {
+  if (!options.symlinks) {
+    return
+  }
+
+  return Promise.all(options.symlinks.map(async ([targetPath, location]) => {
+    const target = path.join('/app', targetPath)
+    const dest = path.join(options['build-dir'], 'files', location)
+
+    logger(`Symlinking ${target} at ${dest}`)
+    await fs.ensureDir(path.dirname(dest))
+    await fs.symlink(target, dest)
+  }))
+}
+
+async function copyExports (options, manifest) {
+  if (!options['extra-exports']) {
+    return
+  }
+
+  return Promise.all(options['extra-exports'].map(async source => {
+    const dest = path.join(options['build-dir'], 'export', source)
+    const dir = path.dirname(dest)
+    source = path.join(options['build-dir'], 'files', source)
+
+    logger(`Exporting ${source} to ${dest}`)
+    await fs.ensureDir(dir)
+    await fs.copy(source, dest)
+  }))
+}
+
+async function flatpakBuilder (options, manifest, finish) {
+  const args = []
+  addCommandLineOption(args, 'arch', options.arch)
+  addCommandLineOption(args, 'force-clean', true)
+  // If we are not compiling anything, allow building without the platform and sdk
+  // installed. Allows automated builds on a minimal environment, for example.
+  if (!manifest.modules || manifest.modules.length === 0) {
+    addCommandLineOption(args, 'allow-missing-runtimes', true)
+  }
+  if (!finish) {
+    addCommandLineOption(args, 'build-only', true)
+  } else {
+    addCommandLineOption(args, 'finish-only', true)
+  }
+  await addAssumeYesArg(args)
+  args.push.apply(args, options['extra-flatpak-builder-args'])
+
+  args.push(options['build-dir'])
+  args.push(options['manifest-path'])
+  return spawnWithLogging(options, 'flatpak-builder', args)
+}
+
+async function flatpakBuildExport (options, manifest) {
+  const args = ['build-export']
+  addCommandLineOption(args, 'arch', options.arch)
+  addCommandLineOption(args, 'gpg-sign', options['gpg-sign'])
+  addCommandLineOption(args, 'gpg-homedir', options['gpg-homedir'])
+  addCommandLineOption(args, 'subject', options.subject)
+  addCommandLineOption(args, 'body', options.body)
+  if (options['build-runtime']) addCommandLineOption(args, 'runtime', true)
+  args.push.apply(args, options['extra-flatpak-build-export-args'])
+
+  args.push(options['repo-dir'])
+  args.push(options['build-dir'])
+  if (manifest.branch) args.push(manifest.branch)
+  return spawnWithLogging(options, 'flatpak', args)
+}
+
+async function flatpakBuildBundle (options, manifest) {
+  if (!options['bundle-path']) {
+    return
+  }
+
+  const args = ['build-bundle']
+  addCommandLineOption(args, 'arch', options.arch)
+  addCommandLineOption(args, 'gpg-keys', options['gpg-keys'])
+  addCommandLineOption(args, 'gpg-homedir', options['gpg-homedir'])
+  addCommandLineOption(args, 'repo-url', options['bundle-repo-url'])
+  if (options['build-runtime']) addCommandLineOption(args, 'runtime', true)
+  args.push.apply(args, options['extra-flatpak-build-bundle-args'])
+
+  args.push(options['repo-dir'])
+  args.push(options['bundle-path'])
+  args.push(manifest.id)
+  if (manifest.branch) args.push(manifest.branch)
+
+  await fs.ensureDir(path.dirname(options['bundle-path']))
+  return spawnWithLogging(options, 'flatpak', args)
+}
+
+exports.bundle = async function (manifest, options) {
+  manifest = kebabify(manifest)
+  options = kebabify(options)
+  if (manifest['app-id']) manifest.id = manifest['app-id']
+
+  await ensureWorkingDir(options)
+  options = getOptionsWithDefaults(options, manifest)
+  options.arch = translateArch(options.arch)
+
+  logger(`Using manifest...\n${JSON.stringify(manifest, null, '  ')}`)
+  logger(`Using options...\n${JSON.stringify(options, null, '  ')}`)
+  await ensureRuntime(options, manifest)
+  await ensureSdk(options, manifest)
+  await ensureBase(options, manifest)
+  await writeJsonFile(options, manifest)
+  await flatpakBuilder(options, manifest, false)
+  await copyFiles(options, manifest)
+  await createSymlinks(options, manifest)
+  await flatpakBuilder(options, manifest, true)
+  await copyExports(options, manifest)
+  await flatpakBuildExport(options, manifest)
+  await flatpakBuildBundle(options, manifest)
+  return options
+}
+
+exports.translateArch = translateArch
@@ -0,0 +1,46 @@
+{
+  "name": "@malept/flatpak-bundler",
+  "version": "0.4.0",
+  "description": "A small utility for packing files in a flatpak.",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/malept/flatpak-bundler.git"
+  },
+  "keywords": [
+    "flatpak"
+  ],
+  "author": "Matt Watson <mattdangerw@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/malept/flatpak-bundler/issues"
+  },
+  "files": [],
+  "homepage": "https://github.com/malept/flatpak-bundler#readme",
+  "engines": {
+    "node": ">= 10.0.0"
+  },
+  "dependencies": {
+    "debug": "^4.1.1",
+    "fs-extra": "^9.0.0",
+    "lodash": "^4.17.15",
+    "tmp-promise": "^3.0.2"
+  },
+  "devDependencies": {
+    "husky": "^4.2.5",
+    "lint-staged": "^10.2.9",
+    "mocha": "^7.0.0",
+    "standard": "^14.0.0"
+  },
+  "scripts": {
+    "lint": "standard",
+    "mocha": "mocha",
+    "test": "standard && mocha"
+  },
+  "husky": {
+    "pre-commit": "lint-staged"
+  },
+  "lint-staged": {
+    "*.js": "standard --fix"
+  }
+}