No one fights alone. A guide to your first Firefox patch on Linux.

Have you ever hit an annoying Firefox bug and want to fix it? You’re right here. Firefox is a great open source project with many volunteer contributors, large community and any patches and help is very welcome.

This post aims to help you with your first patch to Firefox and become an active Firefox contributor.

Get and build Firefox sources

First of all you need to get Firefox sources and build themon Linux. Ubuntu is a natural choice of many but I use Fedora as it’s Wayland leading distro and I’m also Red Hat employee. It doesn’t matter much because Firefox installs its own build environment.

Firefox development happens on nightly which is the latest up-to-date sources and all changes goes there. For start you need mercurial package installed.

Download latest Firefox sources to src directory by mercurial:

hg clone http://hg.mozilla.org/mozilla-central/ src

A finished Firefox build may need ~ 40GB of free space so don’t be surprised. It’s quite a beast 😀

Create .mozconfig file in src directory to set build conditions. Correct values are selected automatically so you don’t need to care much about it now. You can use mine generic one for optimized builds:

. $topsrcdir/browser/config/mozconfig

mk_add_options BUILD_OFFICIAL=1
mk_add_options MOZILLA_OFFICIAL=1
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/objdir
mk_add_options AUTOCLOBBER=1

ac_add_options --disable-debug
ac_add_options --enable-optimize

And one for debug / non-optimized builds. That’s suitable for debugging:

. $topsrcdir/browser/config/mozconfig

mk_add_options BUILD_OFFICIAL=1
mk_add_options MOZILLA_OFFICIAL=1
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/objdir
mk_add_options AUTOCLOBBER=1

ac_add_options --enable-debug
ac_add_options --disable-optimize

Then you go to create a build environment and download build tools for it. Run bootstrap and select Firefox for Desktop there:

./mach bootstrap

That downloads all requested tools from Mozilla and put them to ~/.mozbuild directory. It also configures Mercurial to work with Firefox sources. If you decide to quit or you want free disk space, just delete .mozbuild and src dirs.

You should be ready to build Firefox from sources now:

./mach build

When build is finished a new firefox build is in src/objdir/dist/bin directory and you can run it there.

Firefox hacking

Mozilla provides powerful tool Searchfox where Firefox sources may be browsed and investigated. From Linux/Gtk perspective some interesting code parts are:

• widget/gtk – there’s Firefox/Linux/Gtk integration point here named toolkit and almost all Linux related code is located here. Corresponding Bugzilla component is Core :: Widget/Gtk where most of Linux bugs are filed.
• widget/gtk/nsWindow.cpp – every Firefox window (main browser window, popups, tooltips etc.) have its nsWindow object. It creates GtkWindow for browser, handles Gtk signals and so on. Look at nsWindow::Create() for instance.
• widget/gtk/DMABufSurface.cpp – implements dmabuf based surfaces. It’s used for various Linux/HW operations like video playback and WebGL rendering.
• toolkit/xre – Firefox startup code. Set’s up GdkDisplay, wayland/x11 connections and remote startup code.
• dom/media/platforms/ffmpeg – ffmpeg video playback implementation, VA-API related code.
• gfx/thebes/gfxPlatformGtk.cpp – Set’s up gfx environment on LinuxGtk. Initilizes and configures WebRender, VA-API, DMABuf and related features and enable/disable them according to actual hardware.
• gfx/gl – EGL/GLX related code, contains OpenGL setup for Linux (and other systems).

You can use there hints as starting points for further investigation.

Mercurial mini-howto

Mercurial is a VCS used by Mozilla. I’ve never been good at it and both Git and Mercurial are still a mystery to me. But don’t worry, you need only a small subset of Mercurial commands to hack Firefox and submit your patches.

Show all changes in your sources:

hg diff

Revert all your changes:

hg revert --all

Or revert specified files:

hg revert file1 file2 ...

Commit your changes:

hg commit -m "commit message"

This is the most important Mercurial command you use. It saves your changes locally and you can submit them to Mozilla for review later.

Mercurial commits all changes by default but you can ask to commit selected files only:

hg commit -m "commit message" file1 file2 ...

After commit the change gets a revision number. You can print that by Mozilla hg wip helper:

hg wip

And you show complete patch (message and changes) by:

hg log -v --patch -r revision_number

Now let’s look at commit message. It’s important part of the commit and has following format for Firefox project:

Bug XXXXX - What changed r?reviewer_name

Look at Bug 1818517 and D172914 patch. They’re a good example how the commit message looks like:

Bug 1818517 - Ignore crossing-due-to-grab-start r?stransky

Bug field tells Mozilla tools where to attach your patch while r? field selects who is going to check and ack the change. You always need to specify these two entries.

Without bugzilla number and reviewer name the patch can’t be uploaded or will hang unnoticed there.

The patch reviewer is a key person for your contribution. He/she may direct you how to improve the patch, ack it and eventually check it into project. Sorrect reviewer selection may be tricky and could discourage new contributors.

If you create a new patch for Linux you can always select me (r?stransky). Reviewers for other parts of Firefox are listed here.

Submit your patch for review

So we have a patch committed to your local repository and want to upload it to Mozilla for review. First you need to create account in Bugzilla (bug tracking system) and Phabricator (patch tracking) and install moz-phab tool to submit your patches.

Let’s say we have Bugzilla/Phabricator installed and moz-phab is working. It’s time to submit your first patch. Make sure you enabled Mozilla mercurial extensions in mach bootstrap command above. If not please run it again and enable it.

hg wip command lists patches/revisions in nice format and you can select what to submit:

To submit our patch for Bug 1818517 use moz-phab tool with patch revision numbers:

moz-phab submit d67996f50ead d67996f50ead

and you have your first patch uploaded.

More useful Mercurial commands

Update your sources to the latest ones:

hg pull
hg up central

Switch sources to any revision/branch from history. Use hg wip to get revision number and use hg up to switch:

hg up d67996f50ead

Rebase tool allows you to re-arrange patches across branches, make patch stream linear or rebase your patches to latest trunk. It rebases single patch or more changesets.

In case of collision a merge tool is called. I personally use Meld tool as vimdiff is difficult to use for me. Use hg rebase –help to get complete options list. I usually use:

hg rebase -s source_revision -d dest_revision -k

histedit is a great tool for commit management:

hg histedit

It allows you to re-arrange, merge and drop individual patches and change commit messages or show individual patches.

Where to start?

Wanna help with the project and fix bugs reported by other people? Cool! Bugzilla is your friend there are trackers related to Linux/Gtk here:

• All Wayland related bugs
• Wayland/popup bugs
• Wayland bugs related to Sway/WLRoots
• Firefox bugs related to KDE and Wayland/KDE bugs
• Clipboard bugs
• Bugs in Gtk theming (wrong colors and so on).
• Drag&Drop bugs
• Bugs related to Gtk titlebar rendering
• Firefox/Flatpak bugs

And that’s all! Don’t hesitate to join Mozilla Matrix chat, have fun and become member of Firefox developer community. If you’re blocked on any step listed here, drop me a note or ask on Mozilla chat.