-
Notifications
You must be signed in to change notification settings - Fork 16
Building Foxhound (with playwright integration)
Building Foxhound seems to be a significant hurdle for new users, especially with the essentially undocumented steps for integrating playwright. To fix this issue, we now provide a script that hopefully gets you started.
Building Firefox and Foxhound is not trivial and has quite a few edge cases, which might require manual intervention. For example, building Firefox requires a Rust version specific to the Firefox version you are trying to build. We try to ensure the build environment gets set up correctly via mach logic. Still, especially if you are building an older version of Firefox, this might not work as Mozilla aggressively purges old toolchain versions from their server. Consequently, you might need to install parts of the toolchain manually. See the Firefox documentation for the matching rust versions.
To build Foxhound as is, invoke bash.sh in the checked-out root folder.
-
-h: help
Prints the list of options with a brief explanation.
-
-p: Build with playwright integration
For a detailed explanation, see below.
-
-c: Don't clobber the build
By default the build script runs ./mach clobber, leading to a complete rebuild on each invocation. If you want to do an incremental build, you can avoid this by passing this flag.
-
-r: Reset Git repository
If you have a dirty Git repository, e.g., due to having the playwright patches applied from a previous build, you can reset all changes made to files known to Git with this flag. This effectively calls git reset --hard HEAD before any attempts to apply changes to the repository.
-
-b: Don't bootstrap the build environment
To build Firefox, mach can automatically download required toolchains for you via ./mach bootstrap. This greatly simplifies the build, as you do not need to install a matching clang version for example. The toolchains are downloaded from Mozilla servers. Recently, Mozilla began to rapidly purge old versions of the toolchains, so it is possible that this step fails. To still be able to build, you can skip this phase by passing -b, but you have to ensure the build environment is in shape to build Firefox manually.
-
-s: Skip preparation phase
In the preparation phase, this script tries to ensure the worktree contains everything to build Foxhound. This entails deleting stale playwright leftovers (i.e., the juggler directory), clobbering the build, running bootstrap, etc. This phase always has the side effect that previously built object files might get stale and require rebuilds, e.g., due to copying the juggler directory again. If you want to resume a build that crashed or failed due to a compilation error, running the preparation phase would greatly increase the build time without any added benefit. So, for incremental builds, provide -s to reduce build time.
To add playwright support, we first have to check out the playwright git repository and select the appropriate branch. The folder structure will look like this, assuming you have not renamed the Foxhound directory:
---
config:
look: handDrawn
theme: neutral
---
flowchart LR
A[parent] --> B[project-foxhound]
A --> C[playwright]
Consequently, if you have cloned Foxhound into /opt/project-foxhound, the build script will clone playwright into /opt/playwright.
If this directory already exists, the script will reuse the playwright checkout instead of cloning it again.
Building Foxhound with playwright integration requires us to apply changes to the code in this repository. Consequently, we must impose some constraints on the development workflow this script will support (see above). Most importantly, this requires you to take care when running the build script several times. For example, if you have built Foxhound with playwright support, running this script on the same branch will fail, as the patches are already applied, and applying them again will fail. One option to automate this is to pass the -r flag, which will reset all changes made to files known to Git before trying to apply the patches again. If you want to test code changes or want to resume the build (for example, after a compiler crash) and do not want to apply the playwright patches again, you can skip the preparation phase as a whole with s.
If you are trying to build Foxhound with playwright integration, we must enforce some constraints on the development workflow. These are:
-
Changes must be developed on a checkout that does not have playwright patches applied.
-
Any changes must be committed before applying the playwright patches.
- If you have a dirty repository (i.e., uncommitted changes) and apply the playwright patches, this can lead to situations where trying to commit only your changes requires somewhat advanced Git knowledge. Consequently, the build script checks for this and refuses to build Foxhound.