Sylvestre Ledru
df0583fb15
Convert build/docs/*.rst (top-level and mozbuild/) to MyST-flavored
Markdown.
- Keep build/docs/mozbuild-symbols.rst as RST. The mozbuildsymbols
custom directive emits nodes that confuse autosectionlabel when
wrapped in a MyST eval-rst block.
- Keep build/docs/supported-configurations.rst as RST so that
docs/contributing/build/supported.md can continue to use the MyST
{include} directive on the original source.
- Refresh allowed-warnings globs to match the .md filenames for
code-quality, contributing, crash-reporting, gtest, jsloader, js,
overview, setup, and js/build.
Differential Revision: https://phabricator.services.mozilla.com/D304226
150 lines
6.4 KiB
Markdown
150 lines
6.4 KiB
Markdown
(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](https://github.com/canonical/firefox-snap/).
|
|
|
|
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.
|
|
|
|
## Full build process
|
|
|
|
There may be a few differences between a simple repack and a real full build of
|
|
the Snap, you can find mention of the repackage usage below.
|
|
|
|
The following steps should be enough, assuming you have properly setup:
|
|
|
|
- `snapcraft` (see [quickstart doc](https://snapcraft.io/docs/snapcraft-quickstart))
|
|
- `LXD` (see [providers doc](https://snapcraft.io/docs/build-providers))
|
|
|
|
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`
|
|
|
|
```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:
|
|
|
|
```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.
|
|
|
|
## Cross-compilation
|
|
|
|
There is now support for cross-compilation for `arm64`.
|
|
To produce cross-compiled version locally:
|
|
|
|
- follow the steps above for building, except you need to pass
|
|
`--build-for=ARCH` to `snapcraft`
|
|
- this needs `snapcraft` of at least v8.x
|
|
- make sure you uncomment the `##CROSS-COMPILATION##` lines due to Launchpad
|
|
limitations
|
|
|
|
Builds on Treeherder as well as Try pushes are also available using
|
|
cross-compilation. Tests on Treeherder will also be supported when ARM-based
|
|
workers will be available, confere [Bug 1855463](https://bugzilla.mozilla.org/show_bug.cgi?id=1855463).
|
|
|
|
## 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 {searchfox}`are based on docker <mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8:taskcluster/docker/snap-coreXX-build/Dockerfile>`.
|
|
|
|
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
|
|
{searchfox}`the install-snap script <mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8:taskcluster/docker/snap-coreXX-build/install-snap.sh>`
|
|
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 {searchfox}`within the docker subdirectory <mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8:taskcluster/docker/snap-coreXX-build/snap-tests/tests.sh>`.
|
|
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 {searchfox}`run.sh script <mozilla-central/rev/3c72de9280ec57dc55c24886c6334d9e340500e8:taskcluster/docker/snap-coreXX-build/run.sh#61-72>`.
|
|
|
|
So pushing to try is basically just:
|
|
|
|
```shell
|
|
mach try fuzzy --full -q "'snap 'upstream 'local"
|
|
```
|
|
|
|
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.
|
|
|
|
If you need to reuse a package from the Snap Store or from the latest
|
|
mozilla-central or a specific successful build, you can use `USE_SNAP_FROM_STORE_OR_MC` en
|
|
variable ; setting it to `store` will download from the Snap Store (warning:
|
|
no debug builds on the Snap Store, so whatever `debug` variants we have will
|
|
be an `opt` build in fact), and setting to a TaskCluster index value will
|
|
download from the index. Set it to `latest` if you want latest, or explore
|
|
the TaskCluster index for others. Any `try` will be pulled from latest
|
|
`nightly` while others will be fetched from their respective branches.
|
|
|
|
## How to hack locally
|
|
|
|
After a successful build, you can also build a Snap by performing a repackaging
|
|
using the `mach repackage snap` tool. This requires a `snapcraft` working
|
|
installation relying on `LXD`, which installation steps are
|
|
[documented upstream](https://snapcraft.io/docs/build-providers).
|