Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/flathub-infra/flatpak-builder-lint

A linter for Flatpak manifests and build artifacts primarily developed for Flathub
https://github.com/flathub-infra/flatpak-builder-lint

flathub flatpak linter

Last synced: about 1 month ago
JSON representation

A linter for Flatpak manifests and build artifacts primarily developed for Flathub

Awesome Lists containing this project

README 

          
# flatpak-builder-lint



flatpak-builder-lint is a linter for Flatpak artifacts like Flatpak

manifests, Flatpak Builder build artifacts and repos. It is primarily

developed for Flathub, but can be useful for general use as well.



## Checks



There are four checks available right now - the `appstream` check, the

`manifest` check, the `builddir` check and the `repo` check. The manifest

and the repo checks are run on Flathub infrastructure.



- The `appstream` check expects path to a [Metainfo file](https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/#path-and-filename)

  as input. This is a wrapper for `appstreamcli validate` with some

  Flathub specific overrides.

- The `manifest` check expects path to a [Flatpak manifest](https://docs.flatpak.org/en/latest/manifests.html)

  as input.

- The `builddir` check expects path to a build directory generated by

  Flatpak Builder as input.

- The `repo` check expects path to an OSTree repository exported by

  Flatpak Builder as input.



The last two are created when [building the application](https://docs.flathub.org/docs/for-app-authors/submission#build-and-install)

with the proper arguments to Flatpak Builder.



Some checks may require network connectivity. Sentry integration is used

only if `SENTRY_DSN` environment variable is set.



## Exceptions



Errors can be overridden through exceptions.



Exceptions must be [submitted to Flathub](https://docs.flathub.org/docs/for-app-authors/linter#exceptions)

if the app is meant to be published on Flathub or already exists on

Flathub. These exceptions, once published, can be viewed by doing:



```sh

curl -s 'https://raw.githubusercontent.com/flathub-infra/flatpak-builder-lint/HEAD/flatpak_builder_lint/staticfiles/exceptions.json'|jq '.["my.app.id"]'

```



### Local exceptions



This option should be used sparingly as some errors should never be

ignored and it may hide errors that will fail on Flathub.



For ignoring errors locally (for example in CI outside Flathub),

the `--user-exceptions` argument can be used to point it to a local

JSON file containing exceptions:



```sh

flatpak-builder-lint --exceptions --user-exceptions exceptions.json {manifest,builddir,repo} path

```



The JSON file must be in the following format:



```json

{

    "com.foo.Bar.Devel": [

        "linter-error-1"

    ],

    "com.foo.Bar.Nightly": [

        "linter-error-2"

    ]

}

```



If it is passed only local exceptions loaded from the file, matching the

app ID will be used, otherwise it will use remote exceptions from

Flathub.



## Installation



The only supported ways to install and use are Flatpak and Docker.



### Flatpak



flatpak-builder-lint is part of the `org.flatpak.Builder` flatpak package

available on Flathub. [Set up Flathub][flatpak_setup] first, then install

`org.flatpak.Builder`:



```bash

flatpak install flathub -y org.flatpak.Builder

```



To run the manifest check:



```sh

flatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest com.foo.bar.json

```



To run the repo check:



```sh

flatpak run --command=flatpak-builder-lint org.flatpak.Builder repo repo

```



The Flatpak package tracks the git commit currently used on the Flathub

infrastructure.



### Docker



The latest build of flatpak-builder-linter can be used with Docker.



```bash

docker run --rm -it ghcr.io/flathub/flatpak-builder-lint:latest --help

```



To run the manifest check:



```sh

docker run -v $(pwd):/mnt --rm -it ghcr.io/flathub/flatpak-builder-lint:latest manifest /mnt/com.foo.bar.json

```



To run the repo check:



```sh

docker run -v $(pwd):/mnt --rm -it ghcr.io/flathub/flatpak-builder-lint:latest repo /mnt/repo

```



You may need to pass `:Z` if your distro is using SELinux like so

`-v $(pwd):/mnt:Z`.



### Local environment



Installing flatpak-builder-lint locally with [uv][uv] or pip is

not recommended unless for development purposes. It depends on patches

that are found in Flathub's fork of [appstream](https://github.com/flathub-infra/appstream/tree/flathub),

[flatpak](https://github.com/flathub-infra/flatpak/tree/flathub) and

[flatpak-builder](https://github.com/flathub-infra/flatpak-builder/tree/flathub).



## Contributing



### Dependencies



The following system dependencies must be installed:



- `libgirepository1.0-dev, gir1.2-ostree-1.0, gir1.2-appstream-1.0`

- `flatpak-builder` for validating flatpak-builder manifests

- `appstreamcli` from `org.flatpak.Builder` for validating MetaInfo files

```sh

#!/bin/sh



exec flatpak run --branch=stable --command=appstreamcli org.flatpak.Builder ${@}

```

- `desktop-file-validate` to validate desktop files

- `git` to check if a directory is a git repository



Debiab/Ubuntu:



```sh

sudo apt install git appstream flatpak-builder libgirepository1.0-dev gir1.2-ostree-1.0 gir1.2-appstream-1.0 libcairo2-dev desktop-file-utils

```



ArchLinux:



```sh

sudo pacman -S --needed git appstream flatpak-builder desktop-file-utils ostree glib2

```



Fedora:



```sh

sudo dnf install git appstream flatpak-builder desktop-file-utils ostree-libs glib2-devel cairo-devel

```



Clone the repo:



```bash

git clone https://github.com/flathub/flatpak-builder-lint.git && cd flatpak-builder-lint

```



Then the project can be run with:



```sh

uv run --all-groups --frozen -q flatpak-builder-lint --help

```



Dependencies can be added to removed with `uv add` and `uv remove` while

`uv lock` will regenerate the lockfile. `uv lock -P` can be used to

upgrade a specific package or `uv lock -U` to upgrade everything.



The following Python dependencies are installed and needed to run the

project: `jsonschema, requests, requests-cache, lxml, sentry-sdk,

ruamel.yaml, publicsuffixlist` and `PyGObject`. Additionally `setuptools`

is necessary to build the project. `dunamai` is used to generate a

version from the git commit, since no tags or releases are done, in

absence of which it will default to the version of the last tag made.



### Formatting and Linting



[Ruff](https://docs.astral.sh/ruff/installation/) is used to lint and

format code. [MyPy](https://mypy.readthedocs.io/en/stable/getting_started.html)

is used to check Python types.



A set of pre-commit hooks are provided to automate the formatting and

linting:



```sh

uv run --frozen -q pre-commit install

```



To uninstall:



```sh

uv run --frozen -q pre-commit uninstall

```



Or run individually:



```sh

uv run --frozen -q ruff format

```



```sh

uv run --frozen -q ruff check --fix --exit-non-zero-on-fix

```



```sh

uv run --frozen -q mypy .

```



### Tests



[Pytest](https://docs.pytest.org/en/stable/getting-started.html) is used

to run tests.



```sh

uv run --frozen -q pytest -vvv

```



An additional Flat manager test can be run when modifying code relying

on the flatmanager check. The test is meant to be run on CI and not

locally. If it is being run locally, it must be run from the root of the

git repository using



```sh

./tests/flatmanager.sh

```



To avoid cleanup run as:



```sh

NO_CLEAN_UP=1 ./tests/flatmanager.sh

```



Integration tests are best suited to be run in CI



```sh

uv run pytest -m integration -vvv

```



To write tests for manifest checks, recreate a minimal Flatpak builder

manifest with the cases to check against and put it in `tests/manifests`.

Then add the test using it (or modify the existing tests) in

`tests/test_manifest.py`.



Similarly to add a test for builddir check, recreate the `metadata`,

cataloge, metainfo, desktop files as needed and put them in a

subdirectory of `tests/builddir`. Then add the test in

`tests/test_builddir.py`. There are helper functions in

`tests/test_builddir.py` to emulate a flatpak-builder build directory

using the source files.



Please avoid adding binary files that aren't readable.



### Development environment



A development environment is also available as a docker container. To

use it to run tests or for linting execute the below from the root of the

repository:



```sh

./docker/build.sh

```



This gives an active shell inside the container with all the necessary

tools available and any changes made are available once the container

is exited. The same environment can also be used from the docker images

published to GitHub if rebuilding the latest isn't necessary:



```sh

docker run -it --rm --entrypoint= -v $(pwd):/mnt:Z -w /mnt ghcr.io/flathub-infra/flatpak-builder-lint:latest bash

```



## Usage



```

flatpak-builder-lint



A linter for Flatpak manifests and build artifacts primarily

developed for Flathub



positional arguments:

  {appstream,manifest,builddir,repo}

                        Type of artifact to lint



                          appstream expects a MetaInfo file

                          manifest  expects a flatpak-builder manifest

                          builddir  expects a flatpak-builder build directory

                          repo      expects an OSTree repo exported by flatpak-builder



  PATH                  Path to the artifact



options:

  -h, --help            Show this help message and exit

  --version             Show the version number and exit

  --exceptions          Skip errors added to exceptions. Exceptions must be submitted to Flathub

  --exceptions-repo     Repo key for remote exception lookups from Flathub. Omitting merges all repo keys; supplying a value merges '*' and that key.

  --user-exceptions     Path to a JSON file with exceptions

  --appid               Override the app ID with this app ID

  --cwd                 Override the path parameter with the current working directory

  --ref                 Override the primary ref detection with this ref

  --gha-format          Use GitHub Actions annotations in CI

  --janitor-exceptions  Enable reporting of stale exceptions to linter repository

  --debug               Enable debug logging



Please report any issues at https://github.com/flathub-infra/flatpak-builder-lint

```



[uv]: https://docs.astral.sh/uv/getting-started/installation/

[flatpak_setup]: https://flathub.org/setup



## Documentation



A list of errors and warnings and their explanations are available in the

[Flatpak builder lint page](https://docs.flathub.org/docs/for-app-authors/linter).