snap.rst (6947B)
1 .. _snap: 2 3 ====================== 4 Firefox Snap Packaging 5 ====================== 6 7 This page explains interactions between Firefox and Snap packaging format. 8 9 Where is the upstream 10 ===================== 11 12 The code reference itself is mozilla-central, but the packaging is being worked 13 within the `Canonical's firefox-snap repository <https://github.com/canonical/firefox-snap/>`_. 14 15 This packaging includes a few more bits and dependencies, including compiler. 16 It will also re-download the mercurial repository: this is on purpose. 17 18 Where to report bugs 19 ==================== 20 21 All bugs should be reported to Bugzilla's ``Third Party Packaging`` component, 22 and marked as blocking ``snap`` meta-bug. 23 24 Full build process 25 ================== 26 27 There may be a few differences between a simple repack and a real full build of 28 the Snap, you can find mention of the repackage usage below. 29 30 The following steps should be enough, assuming you have properly setup: 31 32 - ``snapcraft`` (see `quickstart doc <https://snapcraft.io/docs/snapcraft-quickstart>`_) 33 - ``LXD`` (see `providers doc <https://snapcraft.io/docs/build-providers>`_) 34 35 While the documentation still refers to `Multipass`, the Firefox Snap and its 36 dependency had some requirements that made it better suited to use `LXD`. 37 38 When performing the checkout, please keep in mind the branch mapping: 39 40 - `edge` is our `nightly` 41 - `beta` is our `beta` 42 - `stable` is our `release` 43 - `esr` is our `esr` 44 45 .. code-block:: shell 46 47 $ git clone https://github.com/canonical/firefox-snap --branch BRANCH 48 $ snap run snapcraft 49 50 You should end up after some time with two files: ``firefox-XXX.snap`` and 51 ``firefox-XXX.debug``. The first one is the package you will want to ``snap 52 install`` while the second one holds your debugging symbols. 53 54 You can then install the package: 55 56 .. code-block:: shell 57 58 $ sudo snap install --name firefox --dangerous ./path/to/firefox-XXX.snap 59 60 If you want to have parallel installs, then you can change the `--name firefox` 61 to something else. This will be the name you use for ``snap run 62 installed-name``, e.g., ``--name firefox_nightly`` will require you to run 63 ``snap run firefox_nightly``. 64 65 `Snap` has a notion of plugs and slots, and some gets automatically connected 66 in various ways, including depending on the ``Snap Sore`` itself, and if you 67 manually install as ``firefox`` it should reuse them (but you might do bad 68 things with your profile). If you install using another name, then the ``Snap 69 Store`` automatic connection will not happen and this can result in a broken 70 state. Inspecting ``snap connections firefox`` using a store-installed snap 71 should get your an accurate list that you can replicate. 72 73 Cross-compilation 74 ================= 75 76 There is now support for cross-compilation for ``arm64``. 77 To produce cross-compiled version locally: 78 79 - follow the steps above for building, except you need to pass 80 ``--build-for=ARCH`` to ``snapcraft`` 81 - this needs ``snapcraft`` of at least v8.x 82 - make sure you uncomment the ``##CROSS-COMPILATION##`` lines due to Launchpad 83 limitations 84 85 Builds on Treeherder as well as Try pushes are also available using 86 cross-compilation. Tests on Treeherder will also be supported when ARM-based 87 workers will be available, confere `Bug 1855463 88 <https://bugzilla.mozilla.org/show_bug.cgi?id=1855463>`_. 89 90 What CI coverage 91 ================ 92 93 Currently, there are upstream-like builds on treeherder. They are scheduled as 94 a cron task daily and includes: 95 96 - building opt/debug versions of the snap 97 - building them on all branches 98 - running a few selenium-based tests 99 100 The build definitions `are based on docker <https://searchfox.org/mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8/taskcluster/docker/snap-coreXX-build/Dockerfile>`_. 101 102 It should be noted that for the moment, all tasks needs to run under docker. 103 However, this setup is not working for `Snap` since it interacts with `SystemD` 104 which does not work under `Docker`. This is why the installation is handled by 105 `the install-snap script 106 <https://searchfox.org/mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8/taskcluster/docker/snap-coreXX-build/install-snap.sh>`_ 107 rather than plain `sudo snap install`, and also why we need to run `snap` in 108 `destructive mode` (which is fine since we are within a docker container). This 109 does not apply to the tests case which relies on newly-available wayland 110 virtual machines. 111 112 Outside the build oddities because of the setup, it should be noted that those 113 builds are as close as possible to upstream. This means: 114 115 - the mozilla-central hash they run against is not matching the source code it 116 builds from, and one should inspect the build log to see the mercurial clone 117 step 118 - it builds using the clang build within the snap definition 119 120 The tests are defined `within the docker subdirectory 121 <https://searchfox.org/mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8/taskcluster/docker/snap-coreXX-build/snap-tests/tests.sh>`_. 122 They are using Selenium because this is what was used by pre-existing tests ran 123 on GitHub Actions from upstream. 124 125 Their coverage is ensuring that we get a basic working browser out of builds. 126 It includes some tests that previously were manually ran by QA. 127 128 How to hack on try 129 ================== 130 131 Build and test tasks can be explored via ``mach try fuzzy --full`` by searching 132 for ``'snap 'upstream``. There is a bit of hacking for try to make sure we 133 actually don't re-download the mercurial repo and directly reuse the clone 134 generated by `run-task`, handled in the `run.sh script 135 <https://searchfox.org/mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8/taskcluster/docker/snap-coreXX-build/run.sh#61-72>`_. 136 137 So pushing to try is basically just: 138 139 .. code-block:: shell 140 141 $ mach try fuzzy --full -q "'snap 'upstream 'local" 142 143 Because of the build process, a full opt build will take around 1h45-2h while a 144 debug build will be around 60 minutes, the difference coming from the use of 145 PGO on opt builds. 146 147 If you need to reuse a package from the Snap Store or from the latest 148 mozilla-central or a specific successful build, you can use ``USE_SNAP_FROM_STORE_OR_MC`` en 149 variable ; setting it to ``store`` will download from the Snap Store (warning: 150 no debug builds on the Snap Store, so whatever ``debug`` variants we have will 151 be an ``opt`` build in fact), and setting to a TaskCluster index value will 152 download from the index. Set it to ``latest`` if you want latest, or explore 153 the TaskCluster index for others. Any ``try`` will be pulled from latest 154 ``nightly`` while others will be fetched from their respective branches. 155 156 How to hack locally 157 =================== 158 159 After a successful build, you can also build a Snap by performing a repackaging 160 using the ``mach repackage snap`` tool. This requires a ``snapcraft`` working 161 installation relying on ``LXD``, which installation steps are 162 `documented upstream <https://snapcraft.io/docs/build-providers>`_.