Add support for more Linux distributions & packaging formats

[lamergameryt]

In the present state, the project is available as a package catering mainly to Arch Linux (pkgbuild), Debian (deb), and Red Hat (rpm) distributions. Furthermore, as evident from the blog post by @ashitaprasad at Medium, the packaging and distribution process is manual and cumbersome.

To solve this issue, there are a few steps we can take:

• Create a CI/CD pipeline (using GitHub actions?) for automating the creation of a deb, pkgbuild, and rpm distributable file.
• Check out Add an option to install from FlatHub #93 : Package the application as a Flatpak for a more streamlined installation across multiple distributions.
• Check out Add Linux build for NixOS #162 : Create a build for nixOS and add it to the nixpkgs repository.
• Also check out Feedback and Arch Linux Install Support #87 : We have a community contributed Arch Linux build, but the process steps are not documented.
• Package the application as a snap for distribution via the Snap Store.
• Package the application as an AppImage to make the application portable across distributions.

[lamergameryt]

@animator @ashitaprasad: Can you please add the Enhancement tag to this issue?

[animator]

@lamergameryt Instead of setting up a CI/CD pipeline right away, we want to first have clarity regarding the build process as you have read in the medium articles. So a good start will be to document the step by step build process for each distribution in this thread.

[lamergameryt]

@animator Sounds good; I'll document the build process for each of the above distributions as a separate comment in this issue. Starting with the step-by-step build process of a deb & rpm file, I'm using Pop!_OS 22.04 LTS x86_64 for building and testing the distributions.

Building a DEB Package

• Clone the GitHub repository with git clone --depth=1 https://github.com/foss42/apidash.git
• Install pre-requisites required for building: sudo apt-get install clang cmake git ninja-build pkg-config libgtk-3-dev liblzma-dev libstdc++-12-dev and sudo apt install rpm patchelf
• Install flutter_distributor: dart pub global activate flutter_distributor
• Create the necessary desktop files and directories required for building the project for Linux: flutter create --platforms=linux .
• Create the make_config.yaml for DEB releases:

mkdir -p ./linux/packaging/deb
mkdir -p ./linux/assets

# Enter the download link for the actual png file here.
wget -O ./linux/assets/apidash.png https://example.org/image.png

cat > ./linux/packaging/deb/make_config.yaml << EOF
display_name: API Dash
icon: linux/assets/apidash.png
package_name: apidash
summary: A beautiful, lightweight, open-source cross-platform API Client
group: Applications/Development Tools
vendor: Ashita Prasad
packager: Ashita Prasad
packagerEmail: [email protected]
license: ASL 2.0
url: https://github.com/foss42/apidash

maintainer:
  name: Ashita Prasad
  email: [email protected]

priority: optional
section: x11
dependencies:
  - mpv

essential: false
postuninstall_scripts:
  - echo "Sorry to see you go."

keywords:
  - API
  - API Client

generic_name: API Client
categories:
  - Development
  - Utility

startup_notify: true
EOF

• Build the DEB package using flutter_distrubution: flutter_distributor release --name=dev --jobs=release-dev-linux-deb

Building a RPM Package

Similarly, for building a RPM distributable file:

• Create the make_config.yaml for RPM releases:

mkdir -p ./linux/packaging/rpm
mkdir -p ./linux/assets

# Enter the download link for the actual png file here.
wget -O ./linux/assets/apidash.png https://example.org/image.png

cat > ./linux/packaging/rpm/make_config.yaml << EOF
display_name: API Dash
icon: linux/assets/apidash.png
summary: A beautiful, lightweight, open-source cross-platform API Client
group: Applications/Development Tools
vendor: Ashita Prasad
packager: Ashita Prasad
packagerEmail: [email protected]
license: ASL 2.0
url: https://github.com/foss42/apidash

maintainer:
  name: Ashita Prasad
  email: [email protected]

priority: optional
section: x11
dependencies:
  - mpv

essential: false
postuninstall_scripts:
  - echo "Sorry to see you go."

keywords:
  - API
  - API Client

generic_name: API Client
categories:
  - Development
  - Utility

startup_notify: true
EOF

• Build the RPM package using flutter_distributor: flutter_distributor release --name=dev --jobs=release-dev-linux-rpm

The above configuration works perfectly for creating DEB files. However, I'm encountering issues creating RPM files on my host machine.

warning: absolute symlink: /usr/bin/apidash -> /usr/share/apidash/apidash
I/O error : Permission denied
I/O error : Permission denied
Failed to write XML file; For permission problems, try rerunning as root

Despite this, the RPM file is successfully built and verified as OK with rpm -K apidash-0.3.0+3-linux.rpm. I tried rerunning as root, but I have to reinstall flutter_distributor as root. Hence, I'm still determining what needs to be done here. I am looking for your suggestions, @animator and @ashitaprasad.

[lamergameryt]

• Package the application as an AppImage to make the application portable across distributions.

I've added implementing this application as an AppImage package to the scope of this issue to make the application portable and run everywhere.

[Tanish2002]

@animator @ashitaprasad One easy way to distribute for linux is to just provide a tarball of the bundle generated by flutter build.

You can create this tarball using:

1. flutter build linux --release (add the --target-platform flag as needed)
2. cd into ./build/linux/x64/release/bundle
3. create tarball for the files inside this directory using: tar -czvf apidash_x64-linux.tar.gz * (Here x64 can be replaced with the corresponding target platform.)

This tarball will contain the binary, the assests, and the linked libs. Which a packager can easily use to package the app.

Extra Notes:

• Distro-specific packages (.deb, .rpm) are even more convenient for end-users, but they take more work to create.
• The tarball method gives packagers a simple way to get started and support many Linux users quickly.

I can provide some examples of repos distributing their project through tarballs.

[ashitaprasad]

@lamergameryt Why are you summarising the article for .deb and .rpm? That is sorted out and well documented by our team. What @animator said is to document the steps for build process for Linux platforms other than the ones we already have (.deb & .rpm).

[ashitaprasad]

@Tanish2002 When you are creating .deb & .rpm you can specify external dependencies.
How can you do the same for the tarball?

[Tanish2002]

@Tanish2002 When you are creating .deb & .rpm you can specify external dependencies. How can you do the same for the tarball?

@ashitaprasad

Dependencies in Apidash

• Dynamically Linked Libraries: When Flutter builds an app for Linux, all required libraries are placed in the ./libs folder which is inside the bundle folder. These will be included in the tarball.
• External dependencies: Currently, Apidash doesn't rely on external dependencies from what I've seen. Even if it does in the future, Tarballs are not supposed to be a package, (refer to the section below).

Tarball Purpose:

• The tarball is not a complete, self-contained package.
• It serves as a base to make packaging easier for maintainers.
• Maintainers need to place the binary and libraries in the correct system locations, create .desktop files and include any external dependencies.
• Tarballs eliminate the need for package maintainers to know how the flutter toolchain work and also the need for them to install it.

Tarball as a Tool for Package Maintainers:

• Maintainers can easily download the tarball using wget or curl.
• This approach simplifies packaging for both the maintainers and repository managers.

Caveats with Pre-built Binaries:

• Some distros (like OpenSUSE) don't allow pre-built binaries in packages However, most distros do permit this, making packaging much simpler.
• Though with distros that don't allow prebuilt binaries can simply build from source like we're currently doing for deb and rpm packages.

Ending Notes

• Tarball Advantage: Maintainers seeking a simpler packaging process can use the provided tarball. They don't need to understand the Flutter toolchain.
• Building from Source: Maintainers who must build from source (due to distro guidelines or preference) can still do so by cloning the repo and using the release tag.

[animator]

• External dependencies: Currently, Apidash doesn't rely on external dependencies from what I've seen. Even if it does in the future, Tarballs are not supposed to be a package, (refer to the section below).

Note: API Dash currently has mpv as external dependency.

[Tanish2002]

Didn't know that. What library depends on mpv?

[animator]

Didn't know that. What library depends on mpv?

just_audio_mpv

[animator]

We are converting this issue into a discussion.

[PratyushChauhan]

I saw that the issue regarding packaging apidash as a flatpak was closed #93 . Are we still working on that?

[PratyushChauhan]

@Tanish2002 cool, I was tinkering around with flutter and flatpaks to get it working.

[NotAProton]

is anyone actively working on flatpaks?

[ashitaprasad]

@NotAProton no one is currently working on Flatpaks

[NotAProton]

@ashitaprasad Here's my proposed CD pipeline.

• I did my best with outlining the MacOS part, I do not have a Mac to test on so it should probably be done by someone who does.
• The Windows workflow deviates from the medium article where the workflow does not install MSCV libs on the runner but packages the redist installer along with the app using innosetup.
• The Flathub workflow will be on separate repository owned by @flathub

[ashitaprasad]

@NotAProton CI/CD pipeline is just the automation part. First, you need to document all the steps/command/configs required for building the Flatpak.