.. _flatpak:

=========================
IceCat Flatpak Packaging
=========================

This page explains interactions between IceCat and Flatpak packaging format.

Where is the upstream
=====================

The code reference itself is mozilla-central and the repackaging is under `the mach repackage flatpak command <https://searchfox.org/mozilla-central/source/python/mozbuild/mozbuild/repackaging/flatpak.py>`_.

Where to report bugs
====================

All bugs should be reported to Bugzilla in the appropriate component depending on the bug and marked as blocking the ``flatpak`` meta-bug.

Build process
=============

Perform a build and then run ``mach repackage flatpak``, e.g.:

.. code-block:: shell

   $ mach repackage flatpak \
                    --input target.tar.xz \
                    --name org.gnu.icecat \
                    --arch aarch64 \
                    --version 137.0a1 \
                    --product icecat \
                    --release-type nightly \
                    --flatpak-branch nightly \
                    --template-dir browser/installer/linux/app/flatpak \
                    --langpack-pattern $PWD/langpacks/*.xpi \
                    --output test.flatpak.tar.xz,

Where ``target.tar.xz`` can be a downloaded artifact from try build or built from a local build. You will also want to download `some langpack <https://ftp.mozilla.org/pub/icecat/nightly/latest-mozilla-central-l10n/linux-x86_64/xpi/>`_.

How to hack on try
==================

Pushing to try is basically just:

.. code-block:: shell

    $ mach try fuzzy --full -q "'repackage 'flatpak !shippable"`

This will produce a repackage flatpak task at the end that generates a ``target.flatpak.tar.xz``.

Installing the try build
========================

Download and extract the previously generated ``target.flatpak.tar.xz`` and it will produce a ``./repo`` directory that you can directly use with flatpak:

.. code-block:: shell

    $ flatpak --user --no-gpg-verify remote-add icecat-try ./repo/

This should add you a user-level icecat-try flatpak remote, you can verify with (``flathub`` remote may be a user or a system level remote):

 .. code-block:: shell

    $ flatpak remotes
    Name        Options
    icecat-try user
    flathub     user

Then you can install your local build:

 .. code-block:: shell

    $ flatpak install icecat-try icecat
    Looking for matches…
    Found ref ‘app/org.gnu.icecat/x86_64/nightly’ in remote ‘icecat-try’ (user).
    Use this ref? [Y/n]: y

    org.gnu.icecat permissions:
        ipc          network                cups                  fallback-x11            pcsc                         pulseaudio       wayland       x11       devices
        devel        file access [1]        dbus access [2]       bus ownership [3]       system dbus access [4]

        [1] /run/.heim_org.h5l.kcm-socket, xdg-download, xdg-run/speech-dispatcher:ro
        [2] org.a11y.Bus, org.freedesktop.FileManager1, org.gtk.vfs.*
        [3] org.gnu.icecat.*, org.gnu.icecat_beta.*, org.mpris.MediaPlayer2.icecat.*
        [4] org.freedesktop.NetworkManager


            ID                                              Branch                 Op            Remote                 Download
     1. [✓] org.freedesktop.Platform.GL.default             24.08                  u             flathub                 67,3 Mo / 156,6 Mo
     2. [✓] org.freedesktop.Platform.GL.default             24.08extra             u             flathub                  3,9 Mo / 156,6 Mo
     3. [✓] org.freedesktop.Platform.Locale                 24.08                  u             flathub                282,1 Ko / 380,3 Mo
     4. [✓] org.freedesktop.Platform                        24.08                  u             flathub                 25,4 Mo / 264,4 Mo
     5. [✓] org.gnu.icecat.Locale                      nightly                i             icecat-try              1,0 Ko / 1,6 Mo
     6. [✓] org.gnu.icecat                             nightly                i             icecat-try              1,0 Ko / 111,5 Mo

    Changes complete.

And after that you can just run ``flatpak run org.gnu.icecat//nightly``.