native-packages 0.11.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CONTRIBUTING.md +1 -1
- data/README.md +2 -1
- data/docs/_guides/building-packages.md +5 -0
- data/docs/_guides/getting-started.md +2 -2
- data/docs/_guides/github-actions.md +4 -4
- data/docs/_guides/hosted-repositories.md +170 -0
- data/docs/_guides/native-recipes.md +1 -1
- data/docs/_guides/publishing.md +19 -0
- data/docs/_guides/release-signing.md +3 -3
- data/docs/_guides/windows-signing.md +1 -1
- data/docs/_reference/commands.md +4 -3
- data/docs/_reference/configuration.md +7 -3
- data/docs/_reference/platforms.md +122 -5
- data/docs/_reference/troubleshooting.md +2 -2
- data/docs/index.md +1 -1
- data/docs/releasing.md +2 -2
- data/examples/native-packages-all-formats.yaml +1 -1
- data/examples/native-packages-linux-distribution.yaml +76 -0
- data/examples/native-packages.yaml +1 -1
- data/lib/native_packages/appimage.rb +4 -66
- data/lib/native_packages/apt_repository.rb +190 -0
- data/lib/native_packages/build.rb +39 -2
- data/lib/native_packages/configuration.rb +27 -2
- data/lib/native_packages/dnf_repository.rb +131 -0
- data/lib/native_packages/flatpak.rb +171 -0
- data/lib/native_packages/flatpak_repository.rb +63 -0
- data/lib/native_packages/hosted_repository.rb +73 -0
- data/lib/native_packages/inspection.rb +3 -2
- data/lib/native_packages/macos_signing.rb +20 -2
- data/lib/native_packages/openpgp.rb +114 -0
- data/lib/native_packages/snap.rb +166 -0
- data/lib/native_packages/staging.rb +74 -0
- data/lib/native_packages/support.rb +1 -1
- metadata +11 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b0bd80674a1e85d0ea267ea482d110043051ad942fbb8e0b618b3acaf3cb16eb
|
|
4
|
+
data.tar.gz: 05c74949fd067cf2b8b81adf7ac8a148a16c2620c5b9fdf4dea0af78f02457c6
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 8d8301d54fa95ee34b3c80ab34657b44cd1e2a09d751039d97e437115537ae5224bc4a42f936becd4cb5e6c42e4594f54af4adc925d6b5a4e74c07693bc5e3ea
|
|
7
|
+
data.tar.gz: 64d8dfa8a953385b61f4a12377fdf810b497571c28f859ab11615995f2093193e128650735a304771f2235a5f287a06aeb0c6e3790ed2232715d351fbce25a2c
|
data/CONTRIBUTING.md
CHANGED
|
@@ -18,7 +18,7 @@ To check the packaged gem and standalone command:
|
|
|
18
18
|
|
|
19
19
|
```sh
|
|
20
20
|
gem build native-packages.gemspec
|
|
21
|
-
ruby test/gem_install.rb native-packages-0.
|
|
21
|
+
ruby test/gem_install.rb native-packages-0.12.0.gem
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
See [Releasing the gem](docs/releasing.md) for publication and
|
data/README.md
CHANGED
|
@@ -50,7 +50,7 @@ record. Local builds work without a GitHub release or credentials.
|
|
|
50
50
|
|
|
51
51
|
| Platform | Outputs |
|
|
52
52
|
| --- | --- |
|
|
53
|
-
| Linux | DEB, RPM, AppImage, Arch Linux packages, Alpine APK, IPK, and source RPM |
|
|
53
|
+
| Linux | DEB, RPM, AppImage, Flatpak bundles, snaps, Arch Linux packages, Alpine APK, IPK, and source RPM |
|
|
54
54
|
| macOS | DMG, using your packaging script; optional Apple signing and notarization |
|
|
55
55
|
| Windows | MSIX, or MSI and Inno Setup installers using your packaging script; optional Azure Artifact Signing |
|
|
56
56
|
|
|
@@ -69,6 +69,7 @@ Start with [getting started](docs/_guides/getting-started.md).
|
|
|
69
69
|
- [Apple signing and notarization](docs/_guides/apple-notarization.md) — prepare macOS downloads for distribution.
|
|
70
70
|
- [Windows code signing](docs/_guides/windows-signing.md): sign Windows executables and installers with Azure Artifact Signing.
|
|
71
71
|
- [Release signatures and attestations](docs/_guides/release-signing.md): authorize updater downloads and identify their build workflow.
|
|
72
|
+
- [Hosted package repositories](docs/_guides/hosted-repositories.md): publish signed repositories that users update through their package manager.
|
|
72
73
|
- [AUR, Homebrew, and other repositories](docs/_guides/distribution-recipes.md) — generate and publish recipes.
|
|
73
74
|
- [Omarchy packages](docs/_guides/omarchy.md): write a first Omarchy recipe that Omarchy's bot then keeps updated.
|
|
74
75
|
|
|
@@ -130,6 +130,11 @@ Add `appimage` to a Linux target's formats for a single file that runs without
|
|
|
130
130
|
installation. It needs one desktop entry and its icon among the contents; see
|
|
131
131
|
[AppImage](../_reference/platforms.md#appimage).
|
|
132
132
|
|
|
133
|
+
Add `flatpak` for a Flatpak bundle of the same files, with a top-level
|
|
134
|
+
`flatpak` section naming the app ID, runtime and sandbox permissions; see
|
|
135
|
+
[Flatpak](../_reference/platforms.md#flatpak). Add `snap` for a snap, with a
|
|
136
|
+
top-level `snap` section; see [Snap](../_reference/platforms.md#snap).
|
|
137
|
+
|
|
133
138
|
Use a separate musl or static build for Alpine. Changing `formats` alone
|
|
134
139
|
does not change which systems a binary can run on.
|
|
135
140
|
|
|
@@ -17,7 +17,7 @@ own compiled executable, or build the tiny example below.
|
|
|
17
17
|
You need Ruby 3.2 or later. Install the version used by these guides:
|
|
18
18
|
|
|
19
19
|
```sh
|
|
20
|
-
gem install native-packages --version 0.
|
|
20
|
+
gem install native-packages --version 0.12.0
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
For Linux packages, install **nFPM 2.47.0**, the helper native-packages uses to
|
|
@@ -79,7 +79,7 @@ Open the generated `native-packages.yaml` and replace its contents with:
|
|
|
79
79
|
```yaml
|
|
80
80
|
schema: 1
|
|
81
81
|
tool:
|
|
82
|
-
version: '0.
|
|
82
|
+
version: '0.12.0'
|
|
83
83
|
nfpm: '2.47.0'
|
|
84
84
|
|
|
85
85
|
nfpm:
|
|
@@ -24,7 +24,7 @@ packaging:
|
|
|
24
24
|
needs: release
|
|
25
25
|
permissions:
|
|
26
26
|
contents: write
|
|
27
|
-
uses: crmne/native-packages/.github/workflows/package.yml@v0.
|
|
27
|
+
uses: crmne/native-packages/.github/workflows/package.yml@v0.12.0
|
|
28
28
|
with:
|
|
29
29
|
version: ${{ github.ref_name }}
|
|
30
30
|
publish: true
|
|
@@ -39,7 +39,7 @@ The configuration must include `release.repository` and a `release_asset`
|
|
|
39
39
|
for each selected target. See [Publishing a release](publishing.md).
|
|
40
40
|
|
|
41
41
|
Use the same native-packages release for the workflow and `tool.version`.
|
|
42
|
-
For an immutable workflow reference, replace `v0.
|
|
42
|
+
For an immutable workflow reference, replace `v0.12.0` with that release's
|
|
43
43
|
full commit SHA.
|
|
44
44
|
|
|
45
45
|
## Build without publishing
|
|
@@ -57,7 +57,7 @@ permissions:
|
|
|
57
57
|
contents: read
|
|
58
58
|
jobs:
|
|
59
59
|
packaging:
|
|
60
|
-
uses: crmne/native-packages/.github/workflows/package.yml@v0.
|
|
60
|
+
uses: crmne/native-packages/.github/workflows/package.yml@v0.12.0
|
|
61
61
|
```
|
|
62
62
|
|
|
63
63
|
Validation does not compile the app or check that future release inputs exist.
|
|
@@ -72,7 +72,7 @@ packaging:
|
|
|
72
72
|
needs: build
|
|
73
73
|
permissions:
|
|
74
74
|
contents: write
|
|
75
|
-
uses: crmne/native-packages/.github/workflows/package.yml@v0.
|
|
75
|
+
uses: crmne/native-packages/.github/workflows/package.yml@v0.12.0
|
|
76
76
|
with:
|
|
77
77
|
version: '1.2.3'
|
|
78
78
|
source-artifact: linux-binaries
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Hosted package repositories
|
|
3
|
+
description: Publish signed APT, DNF and Flatpak repositories that users add once and update with their package manager.
|
|
4
|
+
nav_order: 13
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Hosted package repositories
|
|
8
|
+
|
|
9
|
+
A package attached to a GitHub release is installed once and then forgotten.
|
|
10
|
+
Users who add your repository instead get every update through their own
|
|
11
|
+
package manager. native-packages writes these repositories as static files
|
|
12
|
+
into a directory you choose, such as a checkout of a GitHub Pages site, and
|
|
13
|
+
signs them with your OpenPGP key. It only writes files: your release job
|
|
14
|
+
commits and pushes the directory afterwards, as it would any website change.
|
|
15
|
+
|
|
16
|
+
## 1. Make a signing key
|
|
17
|
+
|
|
18
|
+
Use a key for this repository alone, without an expiry date you might miss,
|
|
19
|
+
and keep its secret half out of every repository:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
gpg --quick-gen-key 'Hello packages <packages@example.org>' ed25519 sign never
|
|
23
|
+
gpg --list-keys --with-colons packages@example.org | awk -F: '/^fpr/ { print $10; exit }'
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The second command prints the key's full fingerprint, which goes into the
|
|
27
|
+
configuration. Locally, native-packages signs with the key your GnuPG agent
|
|
28
|
+
already holds. In CI, export the secret key and store it as a secret:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
gpg --armor --export-secret-keys FINGERPRINT
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Pass it to the publish step as `NATIVE_PACKAGES_GPG_KEY`, and the key's
|
|
35
|
+
passphrase, if it has one, as `NATIVE_PACKAGES_GPG_PASSPHRASE`.
|
|
36
|
+
native-packages removes both from its environment before running any other
|
|
37
|
+
program, imports the key into a temporary keyring that it deletes
|
|
38
|
+
afterwards, and checks every signature against the configured fingerprint
|
|
39
|
+
before writing it.
|
|
40
|
+
|
|
41
|
+
## 2. Configure the repositories
|
|
42
|
+
|
|
43
|
+
```yaml
|
|
44
|
+
apt:
|
|
45
|
+
directory: ../hello-site/apt
|
|
46
|
+
url: https://example.org/apt
|
|
47
|
+
signing_key: 0123456789ABCDEF0123456789ABCDEF01234567
|
|
48
|
+
keep: 3
|
|
49
|
+
dnf:
|
|
50
|
+
directory: ../hello-site/rpm
|
|
51
|
+
url: https://example.org/rpm
|
|
52
|
+
signing_key: 0123456789ABCDEF0123456789ABCDEF01234567
|
|
53
|
+
flatpak:
|
|
54
|
+
# The app's id, runtime, command and permissions, as for any Flatpak.
|
|
55
|
+
repository:
|
|
56
|
+
directory: ../hello-site/flatpak
|
|
57
|
+
url: https://example.org/flatpak
|
|
58
|
+
title: Hello
|
|
59
|
+
signing_key: 0123456789ABCDEF0123456789ABCDEF01234567
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
| Field | Purpose |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| `directory` | Required. Where the repository is written, relative to the configuration file. |
|
|
65
|
+
| `url` | Required. The `https://` URL at which that directory is served. |
|
|
66
|
+
| `signing_key` | Required. The signing key's full fingerprint. |
|
|
67
|
+
| `keep` | APT and DNF only. How many versions of each package and architecture to keep. Defaults to `3`. |
|
|
68
|
+
| `suite`, `component` | APT only. Default to `stable` and `main`. |
|
|
69
|
+
| `title`, `homepage` | Flatpak only. The repository's name in software centers (defaults to the package name) and an `https://` homepage. |
|
|
70
|
+
|
|
71
|
+
## 3. Publish
|
|
72
|
+
|
|
73
|
+
Build as usual, then publish the build to the repositories:
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
native-packages build --version 1.2.3
|
|
77
|
+
native-packages publish --from dist/packages/1.2.3 --to github,apt,dnf,flatpak
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Each publication adds the build's packages to what the directory already
|
|
81
|
+
holds, removes versions beyond `keep`, and rewrites and signs the indexes. A
|
|
82
|
+
file that is already published can only be published again unchanged. Then
|
|
83
|
+
commit and push the directory.
|
|
84
|
+
|
|
85
|
+
## APT
|
|
86
|
+
|
|
87
|
+
`publish --to apt` copies each `.deb` into `pool/main/h/hello/` and writes
|
|
88
|
+
`dists/stable/` with `Packages` and `Packages.gz` for every architecture,
|
|
89
|
+
`Release`, a clearsigned `InRelease` and a detached `Release.gpg`. These are
|
|
90
|
+
written by native-packages itself, so no Debian tools are needed. Beside them
|
|
91
|
+
go the public key as `hello.gpg` and a `hello.sources` file. Users install
|
|
92
|
+
with:
|
|
93
|
+
|
|
94
|
+
```sh
|
|
95
|
+
sudo install -d -m 0755 /etc/apt/keyrings
|
|
96
|
+
sudo curl -fsSLo /etc/apt/keyrings/hello.gpg https://example.org/apt/hello.gpg
|
|
97
|
+
sudo curl -fsSLo /etc/apt/sources.list.d/hello.sources https://example.org/apt/hello.sources
|
|
98
|
+
sudo apt update && sudo apt install hello
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The `.sources` file trusts this key for this repository alone. Use it on
|
|
102
|
+
apt 1.1 and later (Debian 9, Ubuntu 16.04 and newer).
|
|
103
|
+
|
|
104
|
+
## DNF
|
|
105
|
+
|
|
106
|
+
`publish --to dnf` copies each `.rpm` into `packages/`, runs `createrepo_c`
|
|
107
|
+
to write `repodata/`, and signs `repodata/repomd.xml` as
|
|
108
|
+
`repodata/repomd.xml.asc`. Beside them go the public key as `hello.asc` and
|
|
109
|
+
a `hello.repo` file. Users install with:
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
sudo curl -fsSLo /etc/yum.repos.d/hello.repo https://example.org/rpm/hello.repo
|
|
113
|
+
sudo dnf install hello
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
dnf asks once whether to trust the key, then checks the metadata's signature
|
|
117
|
+
on every update (`repo_gpgcheck=1`). The packages themselves are signed only
|
|
118
|
+
if you sign them, with nFPM's `rpm.signature`; `hello.repo` turns on
|
|
119
|
+
`gpgcheck` when every published RPM carries a signature. The same file works
|
|
120
|
+
for Zypper (`zypper addrepo https://example.org/rpm/hello.repo`). Install
|
|
121
|
+
`createrepo_c` (in the `createrepo-c` package on Debian and Ubuntu) on the
|
|
122
|
+
machine that publishes.
|
|
123
|
+
|
|
124
|
+
## Flatpak
|
|
125
|
+
|
|
126
|
+
`publish --to flatpak` imports each Flatpak bundle into an OSTree
|
|
127
|
+
repository in the directory, signing its commits, then updates the
|
|
128
|
+
repository's summary and static deltas with `flatpak build-update-repo`.
|
|
129
|
+
Each bundle's commit stands alone, without the previous version as its
|
|
130
|
+
parent, so the repository serves each app's newest commit and prunes the
|
|
131
|
+
rest; users cannot roll back to an older version through it. Beside it go
|
|
132
|
+
`hello.flatpakrepo`, for adding the repository, and `ID.flatpakref`, for
|
|
133
|
+
installing the app, both carrying the public key. Users install with:
|
|
134
|
+
|
|
135
|
+
```sh
|
|
136
|
+
flatpak install --user https://example.org/flatpak/org.example.Hello.flatpakref
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
and get updates from `flatpak update`. If `flatpak.runtime_repo` is set, a
|
|
140
|
+
missing runtime comes from there. Publishing needs `flatpak` and `ostree`.
|
|
141
|
+
|
|
142
|
+
This is your own repository, not Flathub. native-packages does not write or
|
|
143
|
+
submit Flathub manifests, because Flathub does not accept AI-assisted
|
|
144
|
+
manifests or submissions.
|
|
145
|
+
|
|
146
|
+
## GitHub Pages
|
|
147
|
+
|
|
148
|
+
Serve the site from a branch or folder, and add an empty `.nojekyll` file
|
|
149
|
+
at its root so GitHub publishes the repository's files as they are. A
|
|
150
|
+
release job can check out the site beside the app:
|
|
151
|
+
|
|
152
|
+
```yaml
|
|
153
|
+
- uses: actions/checkout@v7
|
|
154
|
+
with:
|
|
155
|
+
repository: example/hello-site
|
|
156
|
+
path: hello-site
|
|
157
|
+
token: ${{ secrets.SITE_TOKEN }}
|
|
158
|
+
- run: native-packages publish --from dist/native-packages --to apt,dnf,flatpak
|
|
159
|
+
env:
|
|
160
|
+
NATIVE_PACKAGES_GPG_KEY: ${{ secrets.PACKAGES_GPG_KEY }}
|
|
161
|
+
- run: |
|
|
162
|
+
cd hello-site
|
|
163
|
+
git add -A
|
|
164
|
+
git commit -m "Publish hello $VERSION"
|
|
165
|
+
git push
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
With directories such as `hello-site/apt` in the configuration, the
|
|
169
|
+
repositories land in that checkout. GitHub Pages serves sites of up to 1 GB, so keep `keep` low
|
|
170
|
+
for large packages.
|
data/docs/_guides/publishing.md
CHANGED
|
@@ -115,6 +115,25 @@ To combine builds from several jobs, follow
|
|
|
115
115
|
[Building across platforms](multi-platform.md). Builds with deferred recipes
|
|
116
116
|
must be finalized before publication.
|
|
117
117
|
|
|
118
|
+
## Upload snaps to the Snap Store
|
|
119
|
+
|
|
120
|
+
Register the snap's name in the Snap Store, set `snap.store.channels`, and
|
|
121
|
+
export a login for the release job:
|
|
122
|
+
|
|
123
|
+
```sh
|
|
124
|
+
snapcraft export-login --snaps hello --acls package_upload,package_release credentials.txt
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Store that file's contents as a secret and pass it to the publish step as
|
|
128
|
+
`SNAPCRAFT_STORE_CREDENTIALS`. With `snapcraft` installed:
|
|
129
|
+
|
|
130
|
+
```sh
|
|
131
|
+
native-packages publish --from dist/packages/1.2.3 --to snapcraft
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Each snap in the build is uploaded and released to the configured channels.
|
|
135
|
+
See [Snap](../_reference/platforms.md#snap).
|
|
136
|
+
|
|
118
137
|
## Update distribution recipes
|
|
119
138
|
|
|
120
139
|
For AUR, Homebrew, or another downstream repository, first configure its
|
|
@@ -67,7 +67,7 @@ Package publication's separate `packaging-checksums.txt` is also unchanged.
|
|
|
67
67
|
|
|
68
68
|
## Attest in the application's build job
|
|
69
69
|
|
|
70
|
-
The examples use `v0.
|
|
70
|
+
The examples use `v0.12.0` for readability. For release workflows, replace it
|
|
71
71
|
with that release's reviewed full commit SHA, not a mutable branch.
|
|
72
72
|
After producing the final package, before uploading it, add this step to the
|
|
73
73
|
job that built it:
|
|
@@ -79,7 +79,7 @@ permissions:
|
|
|
79
79
|
attestations: write
|
|
80
80
|
steps:
|
|
81
81
|
# Existing checkout, build, platform signing and packaging steps go here.
|
|
82
|
-
- uses: crmne/native-packages/.github/actions/attest@v0.
|
|
82
|
+
- uses: crmne/native-packages/.github/actions/attest@v0.12.0
|
|
83
83
|
with:
|
|
84
84
|
subject-path: dist/*.tar.gz
|
|
85
85
|
```
|
|
@@ -108,7 +108,7 @@ and install Ruby 3.2 or later with Ed25519-capable OpenSSL before the signing
|
|
|
108
108
|
step. Then call:
|
|
109
109
|
|
|
110
110
|
```yaml
|
|
111
|
-
- uses: crmne/native-packages/.github/actions/sign-release@v0.
|
|
111
|
+
- uses: crmne/native-packages/.github/actions/sign-release@v0.12.0
|
|
112
112
|
with:
|
|
113
113
|
directory: dist/release
|
|
114
114
|
public-key: assets/update-public-key.hex
|
|
@@ -150,7 +150,7 @@ jobs:
|
|
|
150
150
|
- uses: ruby/setup-ruby@v1
|
|
151
151
|
with:
|
|
152
152
|
ruby-version: '4.0'
|
|
153
|
-
- run: gem install native-packages --version 0.
|
|
153
|
+
- run: gem install native-packages --version 0.12.0 --no-document
|
|
154
154
|
- run: cargo build --locked --release --target x86_64-pc-windows-msvc
|
|
155
155
|
- name: Sign in to Azure for code signing
|
|
156
156
|
if: vars.AZURE_SIGNING_PROFILE != ''
|
data/docs/_reference/commands.md
CHANGED
|
@@ -97,8 +97,9 @@ native-packages publish --from dist/linux --to github --target linux-amd64
|
|
|
97
97
|
```
|
|
98
98
|
|
|
99
99
|
`--from` selects the build directory; `--to` lists destinations separated by
|
|
100
|
-
commas. `github` uploads release assets
|
|
101
|
-
|
|
100
|
+
commas. `github` uploads release assets, `snapcraft` uploads snaps to the
|
|
101
|
+
Snap Store, and `apt`, `dnf` and `flatpak` write the signed repositories configured under
|
|
102
|
+
`apt`, `dnf` and `flatpak.repository`. Other names select entries or groups in `repositories`.
|
|
102
103
|
|
|
103
104
|
The build must be complete and its recorded files unmodified. Repeated
|
|
104
105
|
`--target` options require exactly those targets, with all their formats.
|
|
@@ -221,7 +222,7 @@ If several gem versions are installed, RubyGems lets you select the one required
|
|
|
221
222
|
by the configuration:
|
|
222
223
|
|
|
223
224
|
```sh
|
|
224
|
-
native-packages _0.
|
|
225
|
+
native-packages _0.12.0_ build --version 1.2.3
|
|
225
226
|
```
|
|
226
227
|
|
|
227
228
|
Bundler also works if you prefer to manage the gem in a Gemfile.
|
|
@@ -28,7 +28,7 @@ expressions. Use the replacement values listed below.
|
|
|
28
28
|
| Field | Purpose |
|
|
29
29
|
| --- | --- |
|
|
30
30
|
| `schema` | Required. Set to `1`. |
|
|
31
|
-
| `tool.version` | Required. Exact native-packages version, such as `'0.
|
|
31
|
+
| `tool.version` | Required. Exact native-packages version, such as `'0.12.0'`. |
|
|
32
32
|
| `tool.nfpm` | Required. Set to `'2.47.0'`, including in native-only configurations. |
|
|
33
33
|
| `nfpm` | Shared package metadata and installed-file mappings, or a relative YAML filename. Requires `name`. |
|
|
34
34
|
| `targets` | Required. Named build targets; use `{}` for recipe-only projects. |
|
|
@@ -41,6 +41,10 @@ expressions. Use the replacement values listed below.
|
|
|
41
41
|
| `version_file` | Cargo manifest checked by `check-version`. |
|
|
42
42
|
| `version_section` | Cargo section to check; defaults to `package`. |
|
|
43
43
|
| `windows` | Optional. `windows.signing` turns on [Windows code signing](#windows-signing). |
|
|
44
|
+
| `flatpak` | Required by `flatpak` targets: the app ID, runtime, command and permissions. See [Flatpak](platforms.md#flatpak). |
|
|
45
|
+
| `snap` | Required by `snap` targets: the base, confinement and apps, and the Snap Store channels. See [Snap](platforms.md#snap). |
|
|
46
|
+
| `apt` | Optional signed APT repository for `publish --to apt`. See [Hosted package repositories](../_guides/hosted-repositories.md). |
|
|
47
|
+
| `dnf` | Optional signed DNF repository for `publish --to dnf`. See [Hosted package repositories](../_guides/hosted-repositories.md). |
|
|
44
48
|
|
|
45
49
|
Quote tool versions so they remain strings. A version mismatch reports the
|
|
46
50
|
command needed to install and select the configured gem.
|
|
@@ -99,8 +103,8 @@ letters, digits, and hyphens, starting with a letter or digit.
|
|
|
99
103
|
| `native` | Required for DMG, MSI and Inno. Contains `command` and `output`. |
|
|
100
104
|
| `appimage` | Optional for AppImage targets: `update_information`, embedded with a `.zsync` file beside the AppImage. See [AppImage](platforms.md#update-information). |
|
|
101
105
|
|
|
102
|
-
Formats are `deb`, `rpm`, `archlinux`, `apk`, `ipk`, `appimage`, `
|
|
103
|
-
`msix`, `dmg`, `msi`, and `inno`. See [Supported platforms](platforms.md) for their requirements.
|
|
106
|
+
Formats are `deb`, `rpm`, `archlinux`, `apk`, `ipk`, `appimage`, `flatpak`,
|
|
107
|
+
`snap`, `srpm`, `msix`, `dmg`, `msi`, and `inno`. See [Supported platforms](platforms.md) for their requirements.
|
|
104
108
|
|
|
105
109
|
Windows targets select only `[msix]`, `[msi]` or `[inno]`; macOS targets select `[dmg]`.
|
|
106
110
|
DMG, MSI and Inno each require a separate binary target. SRPM requires a separate
|
|
@@ -14,12 +14,14 @@ libraries.
|
|
|
14
14
|
|
|
15
15
|
| Format | Target | What you supply | Packaging tools |
|
|
16
16
|
| --- | --- | --- | --- |
|
|
17
|
-
| `deb` | Linux | Compatible Linux files and package metadata. | nFPM, `readelf` for binaries. |
|
|
18
|
-
| `rpm` | Linux | Compatible Linux files and RPM-specific dependencies. | nFPM, `readelf` for binaries. |
|
|
17
|
+
| `deb` | Linux | Compatible Linux files and package metadata. | nFPM, `readelf` for binaries; `gpg` for a hosted APT repository. |
|
|
18
|
+
| `rpm` | Linux | Compatible Linux files and RPM-specific dependencies. | nFPM, `readelf` for binaries; `createrepo_c` and `gpg` for a hosted DNF repository. |
|
|
19
19
|
| `archlinux` | Linux | Arch-compatible files and explicit dependencies. | nFPM, `readelf` for binaries. |
|
|
20
20
|
| `apk` | Linux | Suitable Alpine files, usually musl or static binaries, and dependencies. | nFPM, `readelf` for binaries. |
|
|
21
21
|
| `ipk` | Linux | Files for the device/distribution baseline, dependencies, and an `abi` label. | nFPM, `readelf` for binaries. |
|
|
22
22
|
| `appimage` | Linux | The same files as the DEB/RPM, including one desktop entry and its icon. | `mksquashfs` (squashfs-tools), `curl`, `readelf`; `zsyncmake` (zsync) with update information. |
|
|
23
|
+
| `flatpak` | Linux | The same files as the DEB/RPM, under `/usr`, and a top-level `flatpak` section. | `flatpak`, `readelf`; `ostree` and `gpg` to publish a repository. |
|
|
24
|
+
| `snap` | Linux | The same files as the DEB/RPM and a top-level `snap` section. | `mksquashfs` (squashfs-tools), `readelf`; `snapcraft` to upload to the Snap Store. |
|
|
23
25
|
| `srpm` | Linux source target | RPM spec and source files. | nFPM; native RPM tooling for rebuild tests. |
|
|
24
26
|
| `msix` | Windows | Windows binaries, identity, application assets, and capabilities. | nFPM; Windows tools for signing and installation tests. |
|
|
25
27
|
| `dmg` | macOS | Complete app and a DMG script. | macOS, `lipo`, and your script's tools, such as `hdiutil`. |
|
|
@@ -123,6 +125,120 @@ pattern. An `after_package` hook must leave the AppImage as it is, or the
|
|
|
123
125
|
Running an AppImage needs FUSE on the user's system, or
|
|
124
126
|
`./App.AppImage --appimage-extract-and-run`.
|
|
125
127
|
|
|
128
|
+
## Flatpak
|
|
129
|
+
|
|
130
|
+
Add `flatpak` to a Linux binary target's `formats` (`amd64` or `arm64`) and
|
|
131
|
+
describe the app once, at the top level:
|
|
132
|
+
|
|
133
|
+
```yaml
|
|
134
|
+
flatpak:
|
|
135
|
+
id: org.example.Hello
|
|
136
|
+
runtime: org.freedesktop.Platform
|
|
137
|
+
runtime_version: '24.08'
|
|
138
|
+
sdk: org.freedesktop.Sdk
|
|
139
|
+
command: hello
|
|
140
|
+
metainfo: packaging/org.example.Hello.metainfo.xml
|
|
141
|
+
runtime_repo: https://dl.flathub.org/repo/flathub.flatpakrepo
|
|
142
|
+
finish_args:
|
|
143
|
+
- --socket=wayland
|
|
144
|
+
- --socket=fallback-x11
|
|
145
|
+
- --share=ipc
|
|
146
|
+
- --share=network
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
| Field | Purpose |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| `id` | Required. The reverse-DNS application ID. |
|
|
152
|
+
| `runtime`, `runtime_version` | Required. The runtime the app runs on, such as `org.freedesktop.Platform` `24.08`. |
|
|
153
|
+
| `sdk` | Optional. Recorded for `flatpak run --devel`; nothing is built with it. |
|
|
154
|
+
| `command` | Required. A program in `/usr/bin` (which becomes `/app/bin`), or an absolute `/app` path. |
|
|
155
|
+
| `finish_args` | The app's sandbox permissions, as `flatpak build-finish` options. |
|
|
156
|
+
| `metainfo` | Optional AppStream file, installed as `ID.metainfo.xml`. It must declare `<id>ID</id>`. |
|
|
157
|
+
| `branch` | Defaults to `stable`. |
|
|
158
|
+
| `runtime_repo` | Optional `.flatpakrepo` URL from which `flatpak install` fetches a missing runtime. |
|
|
159
|
+
| `repository` | Optional [self-hosted Flatpak repository](../_guides/hosted-repositories.md#flatpak) for `publish --to flatpak`. |
|
|
160
|
+
|
|
161
|
+
The bundle holds the same `contents` as the other formats, with `/usr`
|
|
162
|
+
becoming `/app`; a file installed anywhere else fails the build. A contents
|
|
163
|
+
entry with `packager: flatpak` is included only in the Flatpak. Flatpak
|
|
164
|
+
exports only files named after the app ID, so the package's one desktop entry
|
|
165
|
+
becomes `ID.desktop`, its `Icon` becomes the ID, and the icon files it names
|
|
166
|
+
are renamed to match.
|
|
167
|
+
|
|
168
|
+
The output is `NAME-VERSION-ARCH.flatpak` (`x86_64` or `aarch64`), a
|
|
169
|
+
single-file bundle users install with `flatpak install --user FILE`. The app
|
|
170
|
+
is already built, so native-packages writes the metadata and runs
|
|
171
|
+
`flatpak build-finish`, `build-export` and `build-bundle` on the staged
|
|
172
|
+
files. No flatpak-builder, SDK or network is needed, and nothing is compiled
|
|
173
|
+
in the sandbox. Runtimes installed on the build host are hidden from
|
|
174
|
+
`build-finish`, so they cannot add permissions. The same inputs and
|
|
175
|
+
`SOURCE_DATE_EPOCH` give the same OSTree commit, which `build.json` records;
|
|
176
|
+
the bundle file around it also records when it was written, so its hash
|
|
177
|
+
changes between builds.
|
|
178
|
+
|
|
179
|
+
**Libraries come from the runtime.** The binary must run against the
|
|
180
|
+
runtime's libraries, or the package must install the others under `/usr/lib`.
|
|
181
|
+
Test the app in the sandbox with the permissions you declared.
|
|
182
|
+
|
|
183
|
+
native-packages does not write Flathub manifests or submit apps to Flathub,
|
|
184
|
+
because Flathub does not accept AI-assisted manifests or submissions. Write
|
|
185
|
+
and submit a Flathub manifest yourself if you want to publish there.
|
|
186
|
+
|
|
187
|
+
## Snap
|
|
188
|
+
|
|
189
|
+
Add `snap` to a Linux binary target's `formats` and describe the snap once,
|
|
190
|
+
at the top level. The fields follow `snap.yaml`:
|
|
191
|
+
|
|
192
|
+
```yaml
|
|
193
|
+
snap:
|
|
194
|
+
base: core24
|
|
195
|
+
confinement: strict
|
|
196
|
+
grade: stable
|
|
197
|
+
icon: /usr/share/icons/hicolor/scalable/apps/hello.svg
|
|
198
|
+
apps:
|
|
199
|
+
hello:
|
|
200
|
+
command: usr/bin/hello
|
|
201
|
+
desktop: usr/share/applications/hello.desktop
|
|
202
|
+
plugs: [wayland, x11, opengl, network, audio-playback]
|
|
203
|
+
store:
|
|
204
|
+
channels: [stable]
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
| Field | Purpose |
|
|
208
|
+
| --- | --- |
|
|
209
|
+
| `name` | Defaults to `nfpm.name`. 2 to 40 lowercase letters, digits and hyphens. |
|
|
210
|
+
| `base` | Required, such as `core24`. |
|
|
211
|
+
| `confinement` | `strict` (default), `classic` or `devmode`. |
|
|
212
|
+
| `grade` | `stable` (default) or `devel`. |
|
|
213
|
+
| `summary`, `description`, `license`, `title` | Default to the first line of `nfpm.description`, the description and `nfpm.license`. The summary has at most 78 characters. |
|
|
214
|
+
| `apps` | Required. Each app's `command` is a path inside the snap, such as `usr/bin/hello`, and may also set `plugs`, `slots`, `environment`, `daemon` and the other `snap.yaml` app fields. |
|
|
215
|
+
| `apps.APP.desktop` | Optional desktop entry the package installs. It is copied to `meta/gui/APP.desktop`, launching the app. |
|
|
216
|
+
| `icon` | Optional `.png` or `.svg` the package installs; it becomes `meta/gui/icon` and the desktop entries' `Icon`. |
|
|
217
|
+
| `plugs`, `slots`, `layout`, `environment` | Optional top-level `snap.yaml` sections, passed through. |
|
|
218
|
+
| `store.channels` | Channels for `publish --to snapcraft`, such as `stable` or `latest/edge`. |
|
|
219
|
+
|
|
220
|
+
The package's `contents` become the snap's root (`/usr/bin/hello` is
|
|
221
|
+
`$SNAP/usr/bin/hello`), beside a generated `meta/snap.yaml`. A contents entry
|
|
222
|
+
with `packager: snap` is included only in the snap. The output is
|
|
223
|
+
`NAME_VERSION_ARCH.snap` with Snap's architecture names (`amd64`, `arm64`,
|
|
224
|
+
`armhf`, `ppc64el`, `s390x`, `riscv64`). It is an xz SquashFS image owned by
|
|
225
|
+
root, packed with mksquashfs as `snap pack` packs a prime directory. No
|
|
226
|
+
snapcraft, LXD or network is involved, and the same inputs and
|
|
227
|
+
`SOURCE_DATE_EPOCH` give the same bytes.
|
|
228
|
+
|
|
229
|
+
**Libraries come from the base snap or the package.** A strictly confined
|
|
230
|
+
snap does not see the host's libraries, and no snapcraft extension (such as
|
|
231
|
+
`gnome` or `kde-neon`) is applied, so a dynamically linked desktop app needs
|
|
232
|
+
its libraries among the contents and an `environment` that points at them.
|
|
233
|
+
Static binaries need nothing more. Install the snap with
|
|
234
|
+
`snap install --dangerous FILE` and test it under its confinement before
|
|
235
|
+
uploading.
|
|
236
|
+
|
|
237
|
+
`publish --to snapcraft` uploads each snap in the build with
|
|
238
|
+
`snapcraft upload --release=CHANNELS`. The Snap Store login comes from
|
|
239
|
+
`SNAPCRAFT_STORE_CREDENTIALS` (from `snapcraft export-login`), never the
|
|
240
|
+
configuration, and the snap's name must already be registered.
|
|
241
|
+
|
|
126
242
|
## MSIX
|
|
127
243
|
|
|
128
244
|
MSIX targets use `platform: windows`, `formats: [msix]`, and PE binaries with
|
|
@@ -163,9 +279,10 @@ An Arch package file and an AUR recipe are separate outputs: the former can
|
|
|
163
279
|
be installed directly; the latter tells Arch tooling how to obtain and package
|
|
164
280
|
your app.
|
|
165
281
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
282
|
+
native-packages can also write signed APT, DNF and Flatpak repositories from
|
|
283
|
+
your DEB, RPM and Flatpak packages, served as static files; see
|
|
284
|
+
[Hosted package repositories](../_guides/hosted-repositories.md). There is no
|
|
285
|
+
NSIS adapter. Keep that workflow in your app's release process if you need it.
|
|
169
286
|
|
|
170
287
|
## What validation establishes
|
|
171
288
|
|
|
@@ -23,8 +23,8 @@ working on with `doctor --target ID` and `build --target ID --dry-run`.
|
|
|
23
23
|
Install and select the version named in the error:
|
|
24
24
|
|
|
25
25
|
```sh
|
|
26
|
-
gem install native-packages --version 0.
|
|
27
|
-
native-packages _0.
|
|
26
|
+
gem install native-packages --version 0.12.0
|
|
27
|
+
native-packages _0.12.0_ doctor
|
|
28
28
|
```
|
|
29
29
|
|
|
30
30
|
`tool.version` is an exact match. In CI, use the matching released reusable
|
data/docs/index.md
CHANGED
|
@@ -25,7 +25,7 @@ features:
|
|
|
25
25
|
details: Describe your app's files, package metadata, and build targets in a single YAML file.
|
|
26
26
|
- icon: 🐧
|
|
27
27
|
title: Linux packages
|
|
28
|
-
details: Create DEB, RPM, AppImage, Arch, Alpine, and IPK packages from your compatible Linux builds.
|
|
28
|
+
details: Create DEB, RPM, AppImage, Flatpak, Snap, Arch, Alpine, and IPK packages from your compatible Linux builds.
|
|
29
29
|
- icon: 🖥️
|
|
30
30
|
title: Native installers
|
|
31
31
|
details: Connect your macOS DMG script and your Windows MSI or Inno Setup script, or package Windows apps as MSIX.
|
data/docs/releasing.md
CHANGED
|
@@ -23,7 +23,7 @@ Update the gemspec, `NativePackages::VERSION`, example/version references and ch
|
|
|
23
23
|
Create a GitHub release for that commit:
|
|
24
24
|
|
|
25
25
|
```sh
|
|
26
|
-
gh release create v0.
|
|
26
|
+
gh release create v0.12.0 --target main --title 'native-packages 0.12.0' --notes-file release-notes.md
|
|
27
27
|
```
|
|
28
28
|
|
|
29
29
|
Adding `--draft` permits review before publication and does not trigger the publisher. The tag must match the exact gem version and point to a commit on `main`. Set `--prerelease` only for a prerelease gem version.
|
|
@@ -36,7 +36,7 @@ If the workflow itself needs a correction, fix it on `main` and dispatch the
|
|
|
36
36
|
corrected release workflow against the existing published tag:
|
|
37
37
|
|
|
38
38
|
```sh
|
|
39
|
-
gh workflow run release.yml --ref main -f tag=v0.
|
|
39
|
+
gh workflow run release.yml --ref main -f tag=v0.12.0
|
|
40
40
|
```
|
|
41
41
|
|
|
42
42
|
Validation resolves the original tag to an exact commit, requires it to be on
|