From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- build/docs/snap.rst | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 build/docs/snap.rst (limited to 'build/docs/snap.rst') diff --git a/build/docs/snap.rst b/build/docs/snap.rst new file mode 100644 index 0000000000..6ff52da4e8 --- /dev/null +++ b/build/docs/snap.rst @@ -0,0 +1,132 @@ +.. _snap: + +====================== +Firefox Snap Packaging +====================== + +This page explains interactions between Firefox and Snap packaging format. + +Where is the upstream +===================== + +The code reference itself is mozilla-central, but the packaging is being worked +within the `Canonical's firefox-snap repository `_. + +This packaging includes a few more bits and dependencies, including compiler. +It will also re-download the mercurial repository: this is on purpose. + +Where to report bugs +==================== + +All bugs should be reported to Bugzilla's ``Third Party Packaging`` component, +and marked as blocking ``snap`` meta-bug. + +Build process +============= + +While there is an existing ``repackage`` `task +`_, +is currently is no up-to-date and it is not usable from ``mach`` (work is being +`tracked in `_ for this), +so unfortunately the only way to work right now is a full rebuild using +upstream tooling. + +The following steps should be enough, assuming you have properly setup: + + - ``snapcraft`` (see `quickstart doc `_) + - ``LXD`` (see `providers doc `_) + +While the documentation still refers to `Multipass`, the Firefox Snap and its +dependency had some requirements that made it better suited to use `LXD`. + +When performing the checkout, please keep in mind the branch mapping: + + - `edge` is our `nightly` + - `beta` is our `beta` + - `stable` is our `release` + - `esr` is our `esr` + +.. code-block:: shell + + $ git clone https://github.com/canonical/firefox-snap --branch BRANCH + $ snap run snapcraft + +You should end up after some time with two files: ``firefox-XXX.snap`` and +``firefox-XXX.debug``. The first one is the package you will want to ``snap +install`` while the second one holds your debugging symbols. + +You can then install the package: + +.. code-block:: shell + + $ sudo snap install --name firefox --dangerous ./path/to/firefox-XXX.snap + +If you want to have parallel installs, then you can change the `--name firefox` +to something else. This will be the name you use for ``snap run +installed-name``, e.g., ``--name firefox_nightly`` will require you to run +``snap run firefox_nightly``. + +`Snap` has a notion of plugs and slots, and some gets automatically connected +in various ways, including depending on the ``Snap Sore`` itself, and if you +manually install as ``firefox`` it should reuse them (but you might do bad +things with your profile). If you install using another name, then the ``Snap +Store`` automatic connection will not happen and this can result in a broken +state. Inspecting ``snap connections firefox`` using a store-installed snap +should get your an accurate list that you can replicate. + +What CI coverage +================ + +Currently, there are upstream-like builds on treeherder. They are scheduled as +a cron task daily and includes: + + - building opt/debug versions of the snap + - building them on all branches + - running a few selenium-based tests + +The build definitions `are based on docker `_. + +It should be noted that for the moment, all tasks needs to run under docker. +However, this setup is not working for `Snap` since it interacts with `SystemD` +which does not work under `Docker`. This is why the installation is handled by +`the install-snap script +`_ +rather than plain `sudo snap install`, and also why we need to run `snap` in +`destructive mode` (which is fine since we are within a docker container). This +does not apply to the tests case which relies on newly-available wayland +virtual machines. + +Outside the build oddities because of the setup, it should be noted that those +builds are as close as possible to upstream. This means: + + - the mozilla-central hash they run against is not matching the source code it + builds from, and one should inspect the build log to see the mercurial clone + step + - it builds using the clang build within the snap definition + +The tests are defined `within the docker subdirectory +`_. +They are using Selenium because this is what was used by pre-existing tests ran +on GitHub Actions from upstream. + +Their coverage is ensuring that we get a basic working browser out of builds. +It includes some tests that previously were manually ran by QA. + +How to hack on try +================== + +Build and test tasks can be explored via ``mach try fuzzy --full`` by searching +for ``'snap 'upstream``. There is a bit of hacking for try to make sure we +actually don't re-download the mercurial repo and directly reuse the clone +generated by `run-task`, handled in the `run.sh script +`_. + +So pushing to try is basically just: + +.. code-block:: shell + + $ mach try fuzzy --full -q "'snap 'upstream 'try" + +Because of the build process, a full opt build will take around 1h45-2h while a +debug build will be around 60 minutes, the difference coming from the use of +PGO on opt builds. -- cgit v1.2.3