diff options
Diffstat (limited to 'docs/setup')
| -rw-r--r-- | docs/setup/building_with_debug_symbols.rst | 61 | ||||
| -rw-r--r-- | docs/setup/configuring_build_options.rst | 404 | ||||
| -rw-r--r-- | docs/setup/contributing_code.rst | 181 | ||||
| -rw-r--r-- | docs/setup/index.rst | 25 | ||||
| -rw-r--r-- | docs/setup/linux_32bit_build_on_64bit_OS.rst | 37 | ||||
| -rw-r--r-- | docs/setup/linux_build.rst | 151 | ||||
| -rw-r--r-- | docs/setup/macos_build.rst | 122 | ||||
| -rw-r--r-- | docs/setup/windows_build.rst | 181 |
8 files changed, 1162 insertions, 0 deletions
diff --git a/docs/setup/building_with_debug_symbols.rst b/docs/setup/building_with_debug_symbols.rst new file mode 100644 index 0000000000..316e04af31 --- /dev/null +++ b/docs/setup/building_with_debug_symbols.rst @@ -0,0 +1,61 @@ +Building with Debug Symbols +=========================== + ++--------------------------------------------------------------------+ +| This page is an import from MDN and the contents might be outdated | ++--------------------------------------------------------------------+ + +By default, a release build of Firefox will not generate debug symbols +suitable for debugging or post-processing into the +:ref:`breakpad <Crash reporting>` symbol format. Use the +following :ref:`mozconfig <Configuring Build Options>` settings +to do a build with symbols: + + + +Building Firefox with symbols +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There is a single configure option to enable building with symbols on +all platforms. This is enabled by default so unless you have explcitly +disabled it your build you should include symbols. + +:: + + ac_add_options --enable-debug-symbols + +This can optionally take an argument for the type of symbols that need +to be produced (like "-g3"). By default it uses "-g" on Linux and MacOS. +This value takes precedence over the flags set in ``MOZ_DEBUG_FLAGS`` + +Note that this will override the values provided for ``CFLAGS`` and +``CXXFLAGS``. + + +Breakpad symbol files +~~~~~~~~~~~~~~~~~~~~~ + +After the build is complete, run the following command to generate an +archive of :ref:`Breakpad <Crash reporting>` symbol files: + +.. code:: bash + + mach buildsymbols + +Treeherder uses an additional ``uploadsymbols`` target to upload +symbols to a socorro server. See +https://searchfox.org/mozilla-central/source/toolkit/crashreporter/tools/upload_symbols.py +for more information about the environment variables used by this +target. + + +``make package`` +~~~~~~~~~~~~~~~~ + +If you use ``make package`` to package your build, symbols will be +stripped. If you want to keep the symbols in the patches, you need to +add this to your mozconfig: + +.. code:: + + ac_add_options --disable-install-strip diff --git a/docs/setup/configuring_build_options.rst b/docs/setup/configuring_build_options.rst new file mode 100644 index 0000000000..fd57930022 --- /dev/null +++ b/docs/setup/configuring_build_options.rst @@ -0,0 +1,404 @@ +Configuring Build Options +========================= + ++--------------------------------------------------------------------+ +| This page is an import from MDN and the contents might be outdated | ++--------------------------------------------------------------------+ + +This document details how to configure Firefox builds. +Most of the time a ``mozconfig`` file is not required. The default +options are the most well-supported, so it is preferable to add as few +options as possible. Please read the following directions carefully +before building, and follow them in order. Skipping any step may cause +the build to fail, or the built software to be unusable. Build options, +including options not usable from the command-line, may appear in +"``confvars.sh``" files in the source tree. + + +Using a ``mozconfig`` configuration file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The choice of which Mozilla project to build and other configuration +options can be configured in a ``mozconfig`` file. (It is possible to +manually call ``configure`` with command-line options, but this is not +recommended). The ``mozconfig`` file should be in your source directory +(that is, ``/mozilla-central/mozconfig``). + +Create a blank ``mozconfig`` file: + +.. code:: bash + + echo "# My first mozilla config" > mozconfig + +If your mozconfig isn't in your source directory, you can also use the +``MOZCONFIG`` environment variable to specify the path to your +``mozconfig``. The path you specify **must** be an **absolute** path or +else ``client.mk`` will not find it. This is useful if you choose to +have multiple ``mozconfig`` files for different projects or +configurations (see below for a full example). Note that in the +``export`` example below the filename was not ``mozconfig``. Regardless +of the name of the actual file you use, we refer to this file as the +``mozconfig`` file in the examples below. + +Setting the ``mozconfig`` path: + +.. code:: bash + + export MOZCONFIG=$HOME/mozilla/mozconfig-firefox + +.. note:: + + Calling the file ``.mozconfig`` (with a leading dot) is also + supported, but this is not recommended because it may make the file + harder to find. This will also help when troubleshooting because + people will want to know which build options you have selected and + will assume that you have put them in your ``mozconfig`` file. + + +``mozconfig`` contains two types of options: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Options prefixed with ``mk_add_options`` are passed to + ``client.mk``. The most important of these is ``MOZ_OBJDIR``, which + controls where your project gets built (also known as the object + directory). +- Options prefixed with ``ac_add_options`` are passed to ``configure``, + and affect the build process. + + +Building with an objdir +~~~~~~~~~~~~~~~~~~~~~~~ + +This means that the source code and object files are not intermingled in +your directory system and you can build multiple projects (e.g., +Firefox and Thunderbird) from the same source tree. If you do not +specify a ``MOZ_OBJDIR``, it will be automatically set to +``@TOPSRCDIR@/obj-@CONFIG_GUESS@``. + +If you need to re-run ``configure``, the easiest way to do it is using +``./mach configure``; running ``configure`` manually is strongly +discouraged. + +Adding the following line to your ``mozconfig`` allows you to change the +objdir: + +.. code:: bash + + mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-@CONFIG_GUESS@ + +It is a good idea to have your objdir name start with ``obj`` so that +Mercurial ignores it. + +Sometimes it can be useful to build multiple versions of the source +(such as with and without diagnostic asserts). To avoid the time it +takes to do a full rebuild, you can create multiple ``mozconfig`` files +which specify different objdirs. For example, a ``mozconfig-dbg``: + +.. code:: bash + + mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-dbg + ac_add_options --enable-debug + +and a ``mozconfig-rel-opt``: + +.. code:: bash + + mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-rel-opt + ac_add_options --disable-debug + ac_add_options --enable-optimize + +allow for building both versions by specifying the configuration via +the ``MOZCONFIG`` environment variable: + +.. code:: bash + + $ env MOZCONFIG=/path/to/mozconfig-dbg ./mach build + $ env MOZCONFIG=/path/to/mozconfig-rel-opt ./mach build + +Don't forget to set the ``MOZCONFIG`` environment variable for the +``mach run`` command as well. + +Be aware that changing your ``mozconfig`` will require the configure +process to be rerun and therefore the build will take considerably +longer, so if you find yourself changing the same options regularly, it +may be worth having a separate ``mozconfig`` for each. The main downside +of this is that each objdir will take up a significant amount of space +on disk. + + +Parallel compilation +~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + **Note**: The build system automatically makes an intelligent guess + for how many CPU cores to use when building. The option below is + typically not needed. + +Most modern systems have multiple cores or CPUs, and they can be +optionally used concurrently to make the build faster. The ``-j`` flag +controls how many parallel builds will run concurrently. You will see +(diminishing) returns up to a value approximately 1.5× to 2.0× the +number of cores on your system. + +.. code:: bash + + mk_add_options MOZ_PARALLEL_BUILD=4 + +If your machine is overheating, you might want to try a lower value. + + +Choose a project +~~~~~~~~~~~~~~~~ + +The ``--enable-project=project`` flag is used to select a project to +build. Firefox is the default. + +Choose one of the following options to add to your ``mozconfig`` file: + +Browser (Firefox) + .. code:: + + ac_add_options --enable-project=browser + + .. note:: + + **Note**: This is the default + +Mail (Thunderbird) + .. code:: + + ac_add_options --enable-project=comm/mail + +Mozilla Suite (SeaMonkey) + .. code:: + + ac_add_options --enable-project=suite + +Calendar (Lightning Extension, uses Thunderbird) + .. code:: + + ac_add_options --enable-project=comm/mail + ac_add_options --enable-calendar + + +Selecting build options +~~~~~~~~~~~~~~~~~~~~~~~ + +The build options you choose depends on what project you are +building and what you will be using the build for. If you want to use +the build regularly, you will want a release build without extra +debugging information; if you are a developer who wants to hack the +source code, you probably want a non-optimized build with extra +debugging macros. + +There are many options recognized by the configure script which are +special-purpose options intended for embedders or other special +situations, and should not be used to build the full suite/XUL +projects. The full list of options can be obtained by running +``./mach configure -- --help``. + +.. warning:: + + Do not use a configure option unless you know what it does. + The default values are usually the right ones. Each additional option + you add to your ``mozconfig`` file reduces the chance that your build + will compile and run correctly. + +The following build options are very common: + +sccache +^^^^^^^ + +`SCCache <https://github.com/mozilla/sccache>`__ allows speeding up subsequent +C / C++ builds by caching compilation results. Unlike +`ccache <https://ccache.dev>`__, it also allows caching Rust artifacts, and +supports `distributed compilation +<https://github.com/mozilla/sccache/blob/master/docs/DistributedQuickstart.md>`__. + +In order to enable ``sccache`` for Firefox builds, you can use +``ac_add_options --with-ccache=sccache``. + +Optimization +^^^^^^^^^^^^ + +``ac_add_options --enable-optimize`` + Enables the default compiler optimization options + + .. note:: + + **Note**: This is enabled by default + +``ac_add_options --enable-optimize=-O2`` + Chooses particular compiler optimization options. In most cases, this + will not give the desired results, unless you know the Mozilla + codebase very well; note, however, that if you are building with the + Microsoft compilers, you probably **do** want this as ``-O1`` will + optimize for size, unlike GCC. +``ac_add_options --enable-debug`` + Enables assertions in C++ and JavaScript, plus other debug-only code. + This can significantly slow a build, but it is invaluable when + writing patches. **People developing patches (especially in C++) + should generally use this option.** +``ac_add_options --disable-optimize`` + Disables compiler optimization. This makes it much easier to step + through code in a debugger. +``ac_add_options --enable-release`` + Enables more conservative, release engineering-oriented options. This may + slow down builds. This also turns on full optimizations for Rust. Note this + is the default when building release/beta/esr. +``ac_add_options --enable-debug-js-modules`` + Enable only JavaScript assertions. This is useful when working + locally on JavaScript-powered components like the DevTools. This will + help catch any errors introduced into the JS code, with less of a + performance impact compared to the ``--enable-debug`` option. +``export RUSTC_OPT_LEVEL=2`` + Enable full optimizations for Rust code. + +You can make an optimized build with debugging symbols. See :ref:`Building +with Debug Symbols <Building with Debug Symbols>`. + +Extensions +^^^^^^^^^^ + +``ac_add_options --enable-extensions=default|all|ext1,ext2,-skipext3`` + There are many optional pieces of code that live in {{ + Source("extensions/") }}. Many of these extensions are now considered + an integral part of the browsing experience. There is a default list + of extensions for the suite, and each app-specific ``mozconfig`` + specifies a different default set. Some extensions are not compatible + with all apps, for example: + + - ``cookie`` is not compatible with thunderbird + - ``typeaheadfind`` is not compatible with any toolkit app (Firefox, + Thunderbird) + + Unless you know which extensions are compatible with which apps, do + not use the ``--enable-extensions`` option; the build system will + automatically select the proper default set of extensions. + +Tests +^^^^^ + +``ac_add_options --disable-tests`` + By default, many auxiliary test programs are built, which can + help debug and patch the mozilla source. Disabling these tests can + speed build time and reduce disk space considerably. Developers + should generally not use this option. + +Localization +^^^^^^^^^^^^ + +``mk_add_options MOZ_CO_LOCALES=ISOcode`` + TBD. +``ac_add_options --enable-ui-locale=ISOcode`` + TBD. +``ac_add_options --with-l10n-base=/path/to/base/dir`` + TBD. + +Other Options +^^^^^^^^^^^^^ + +``mk_add_options AUTOCLOBBER=1`` + If a clobber would be required before a build, this will cause mach + to clobber and continue with the build instead of asking the user to + manually clobber and exiting. + +``ac_add_options --enable-crashreporter`` + This enables the machinery that allows Firefox to write out a + `minidump <https://docs.microsoft.com/en-us/windows/desktop/Debug/minidump-files>`__ + files when crashing as well as the tools to process and submit crash + reports to Mozilla. After enabling the crash reporter in your local + build, you will need to run mach with the --enable-crash-reporter + (note the extra dash) to enable it at runtime, like so: + ``./mach run --enable-crash-reporter`` +``ac_add_options --enable-warnings-as-errors`` + This makes compiler warnings into errors which fail the build. This + can be useful since certain warnings coincide with reviewbot lints + which must be fixed before merging. + +.. _Example_.mozconfig_Files: + +Example ``mozconfig`` Files +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mozilla's official builds use mozconfig files from the appropriate +directory within each repository. + +.. warning:: + + These ``mozconfig`` files are taken from production builds + and are provided as examples only. It is recommended to use the default + build options, and only change the properties from the list above as + needed. The production builds aren't really appropriate for local + builds." + +- .. rubric:: Firefox, `Debugging Build (macOS + 64bits) <http://hg.mozilla.org/mozilla-central/file/tip/browser/config/mozconfigs/macosx64/debug>`__ + :name: Firefox.2C_Default_Release_Configuration + +Building multiple projects from the same source tree +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to build multiple projects from the same source tree, +as long as you `use a different objdir <#Building_with_an_Objdir>`__ for +each project. + +You need to create multiple ``mozconfig`` files. + +As an example, the following steps can be used to build Firefox and +Thunderbird. You should first create three ``mozconfig`` files. + +``mozconfig-common``: + +.. code:: + + # add common options here, such as making an optimized release build + mk_add_options MOZ_PARALLEL_BUILD=4 + ac_add_options --enable-optimize --disable-debug + +``mozconfig-firefox``: + +.. code:: + + # include the common mozconfig + . ./mozconfig-common + + # Build Firefox + mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-firefox + ac_add_options --enable-project=browser + +``mozconfig-thunderbird``: + +.. code:: + + # include the common mozconfig + . ./mozconfig-common + + # Build Thunderbird + mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-thunderbird + ac_add_options --enable-project=comm/mail + +To build Firefox, run the following commands: + +.. code:: + + export MOZCONFIG=/path/to/mozilla/mozconfig-firefox + ./mach build + +To build Thunderbird, run the following commands: + +.. code:: + + export MOZCONFIG=/path/to/mozilla/mozconfig-thunderbird + ./mach build + +Using mozconfigwrapper +^^^^^^^^^^^^^^^^^^^^^^ + +Mozconfigwrapper is similar to using multiple mozconfig files except +that it abstracts and hides them so you don't have to worry about where +they live or which ones you've created. It also saves you from having to +export the MOZCONFIG variable each time. For information on installing +and configuring mozconfigwrapper, see +https://github.com/ahal/mozconfigwrapper. diff --git a/docs/setup/contributing_code.rst b/docs/setup/contributing_code.rst new file mode 100644 index 0000000000..8b24dac87d --- /dev/null +++ b/docs/setup/contributing_code.rst @@ -0,0 +1,181 @@ +How To Contribute Code To Firefox +================================= + +The whole process can be a bit long, and it might take time to get things right. +If at any point you are stuck, please don't hesitate to ask at `https://chat.mozilla.org <https://chat.mozilla.org>`_ +in the `#introduction <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_ channel. + +We make changes to Firefox by writing patches, testing them and pushing them into "the tree", the +term we use for all the code in Mozilla-Central. Let's get started. + +Please see the :ref:`Firefox Contributors Quick Reference <Firefox Contributors' Quick Reference>` for simple check list. + +Finding something to work on +---------------------------- + +| Bugs listed as 'Assigned' are not usually a good place to start, + unless you're sure you have something worthy to contribute. Someone + else is already working on it! +| Even with no assignee, it is polite to check if someone has recently + commented that they're looking at fixing the issue. +| Once you have found something to work on, go ahead and comment! Let + the bug submitter, reviewer, and component owner know that you'd like + to work on the bug. You might receive some extra information, perhaps + also made the assignee. + +Find a bug we've identified as a good fit for new contributors. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +With more than a million bugs filed in Bugzilla, it can be hard to know +where to start, so we've created these bug categories to make getting +involved a little easier: + +- `Codetribute <https://codetribute.mozilla.org/>`_ - our site for + finding bugs that are mentored, some are good first bugs, some are + slightly harder. Your mentor will help guide you with the bug fix and + through the submission and landing process. +- `Good First Bugs <https://mzl.la/2yBg3zB>`_ + - are the best way to take your first steps into the Mozilla + ecosystem. They're all about small changes, sometimes as little as a + few lines, but they're a great way to learn about setting up your + development environment, navigating Bugzilla, and making + contributions to the Mozilla codebase. +- `Student Projects <https://bugzil.la/kw:student-project>`_ - are + larger projects, such as might be suitable for a university student + for credit. Of course, if you are not a student, feel free to fix one + of these bugs. We maintain two lists: one for projects `based on the + existing codebase <https://bugzil.la/kw:student-project>`_. + +Fix that one bug +~~~~~~~~~~~~~~~~ + +If there's one particular bug you'd like to fix about Firefox, Thunderbird, or +your other favorite Mozilla application, this can be a great place to +start. There are a number of ways to do this: + +- `Search bugzilla <https://bugzilla.mozilla.org/query.cgi>`_ for + relevant keywords. See pages on + `Bugzilla and Searching Bugzilla <https://bmo.readthedocs.io/en/latest/using/finding.html>`_ for further + help +- Learn the `bugzilla + component <https://bugzilla.mozilla.org/describecomponents.cgi>`_, + with which your pet bug is implemented, using the components list. + Browse this component on bugzilla for related bugs + +Fixing your bug +--------------- + +We leave this in your hands. Here are some further resources to help: + +- Check out + :ref:`Our Developer Guide and its parent document <Working on Firefox>` +- Our :ref:`reviewer checklist <Reviewer Checklist>` is very + useful, if you have a patch near completion, and seek a favorable + review +- Utilize our build tool :ref:`mach`, its linting, + static analysis, and other code checking features + +Getting your code reviewed +-------------------------- + +Once you fix the bug, you can advance to having your code reviewed. + +Mozilla uses +`Phabricator <https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html>`_ +for code review. + +Who is the right person to ask for a review? + +- If you have a mentored bug: ask your mentor. They will help, or can + easily find out. It might be them! +- Run ``{hg, git} blame`` on the file and look for the people who have touched + the functions you're working on. They too are good candidates. + Running ``{hg, git} log`` and looking for regular reviewers might be a + solution too. +- The bug itself may contain a clear indication of the best person to + ask for a review +- Are there related bugs on similar topics? The reviewer in those bugs + might be another good choice +- We have a :ref:`list of modules <Governance>`, which lists peers and + owners for the module. Some of these will be good reviewers. In a + worst case scenario, set the module owner as the reviewer, asking + them in the comments to pick someone more suitable + +Please select only one reviewer. + +Following up and responding +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you've asked for a review, a reviewer will often respond within a +day or two, reviewing the patch, or saying when they will be able to +review it, perhaps due to a backlog. If you don't hear back within this +time, naturally reach out to them: add a comment to the bug saying +'review ping?', check the "Need more information from" box, and add the +reviewer's name. If they don't respond within a day or two, you can ask +for help on Matrix in the +`#introduction:mozilla.org <https://riot.im/app/#/room/#introduction:mozilla.org>`_ +or +`#developers:mozilla.org <https://chat.mozilla.org/#/room/#developers:mozilla.org>`_ +channels. + +Don't hesitate to contact your mentor as well if this isn't moving. + +For most new contributors, and even for long-time Mozillians, the first +review of your patch will be "Requested Changes" (or an "r-" in +Bugzilla). This does not mean you've done bad work. There is more work +to do before the code can be merged into the tree. Your patch may need +some changes - perhaps minor, perhaps major - and your reviewer will +give you some guidance on what needs to be done next. + +This is an important process, so don't be discouraged! With our +long-lived codebase, and hundreds of millions of users, the care and +attention helping contributors bring good patches is the cornerstone of +the Mozilla project. Make any changes your reviewer seeks; if you're +unsure how, be sure to ask! Push your new patch up to Phabricator again and +ask for a further review from the same reviewer. If they accept your +changes, this means your patch can be landed into the tree! + +Getting code into Firefox +------------------------- + +Once your patch has been accepted, it is ready to go. Before it can be +merged into the tree, your patch will need to complete a successful run +through our :ref:`try server <Pushing to Try>`, +making sure there are no unexpected regressions. If you don't have try +server access already, your mentor, or the person who reviewed your +patch, will be able to help. + +Ask the reviewer to land the patch for you. +For more details, see :ref:`push_a_change` + + +Do it all again! +---------------- + +Thank you. You've fixed your very first bug, and the Open Web is +stronger for it. But don't stop now. + +Go back to step 3, as there is plenty more to do. Your mentor might +suggest a new bug for you to work on, or `find one that interests +you <http://www.whatcanidoformozilla.org/>`_. Now that you've got your +first bug fixed you should request level 1 access to the repository to +push to the try server and get automated feedback about your changes on +multiple platforms. After fixing a nontrivial number of bugs you should +request level 3 access so you can land your own code after it has been +reviewed. + +More information +---------------- + +We're in the process of improving information on this page for newcomers +to the project. We'll be integrating some information from these pages +soon, but until then you may find them interesting in their current +form: + +- `A guide to learning the Firefox + codebase <http://www.joshmatthews.net/blog/2010/03/getting-involve-with-mozilla/>`_ +- `A beginner's guide to SpiderMonkey, Mozilla's Javascript + engine <https://wiki.mozilla.org/JavaScript:New_to_SpiderMonkey>`_ +- `Mozilla platform development + cheatsheet <https://web.archive.org/web/20160813112326/http://www.codefirefox.com:80/cheatsheet>`_ + (archive.org) diff --git a/docs/setup/index.rst b/docs/setup/index.rst new file mode 100644 index 0000000000..eb0c68aa4e --- /dev/null +++ b/docs/setup/index.rst @@ -0,0 +1,25 @@ +Getting Set Up To Work On The Firefox Codebase +============================================== + +This page will help you get set up to build Firefox on your own machine. + +Don't hesitate to look at the :ref:`Firefox Contributors Quick Reference <Firefox Contributors' Quick Reference>` to read a quick tutorial. + +.. toctree:: + :caption: Thank you for contributing to Firefox + + /contributing/contributing_to_mozilla + +.. toctree:: + :caption: Setting Up Your Machine + :maxdepth: 1 + + windows_build + macos_build + linux_build + linux_32bit_build_on_64bit_OS + +.. toctree:: + :caption: Getting Ready To Contribute + + contributing_code diff --git a/docs/setup/linux_32bit_build_on_64bit_OS.rst b/docs/setup/linux_32bit_build_on_64bit_OS.rst new file mode 100644 index 0000000000..6e8656fc4a --- /dev/null +++ b/docs/setup/linux_32bit_build_on_64bit_OS.rst @@ -0,0 +1,37 @@ +Building Firefox 32-bit On Linux 64-bit +======================================= + +.. note:: + + Unless you really want to target older hardware, you probably + want to :ref:`Build Firefox 64-bit <Building Firefox On Linux>` + since it is better-supported. + +Before following these 32-bit-Firefox-specific instructions, follow +the :ref:`Building Firefox On Linux` instructions to ensure that +your machine can do a normal build. + +Instructions for Ubuntu 19.10 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These steps were verified to work as of June 2020. + +#. Run ``rustup target install i686-unknown-linux-gnu`` to install the + 32-bit Rust target. +#. Install 32-bit dependencies with the following command (this shouldn't try to + remove packages. If this is the case, those instructions won't work as-is): + + .. code:: + + sudo apt install gcc-multilib g++-multilib libdbus-glib-1-dev:i386 \ + libgtk2.0-dev:i386 libgtk-3-dev:i386 libpango1.0-dev:i386 libxt-dev:i386 \ + libx11-xcb-dev:i386 libpulse-dev:i386 libdrm-dev:i386 + +#. Then, create a ``mozconfig`` file in your Firefox code directory + (probably ``mozilla-unified``) that looks like the following example: + + .. code:: + + ac_add_options --target=i686 + +#. Run ``./mach build``. diff --git a/docs/setup/linux_build.rst b/docs/setup/linux_build.rst new file mode 100644 index 0000000000..8582a52be6 --- /dev/null +++ b/docs/setup/linux_build.rst @@ -0,0 +1,151 @@ +Building Firefox On Linux +========================= + +This document will help you get set up to build Firefox on your own +computer. Getting set up can take a while - we need to download a +lot of bytes! Even on a fast connection, this can take ten to fifteen +minutes of work, spread out over an hour or two. + +Requirements +------------ + +- **Memory:** 4GB RAM minimum, 8GB+ recommended. +- **Disk Space:** At least 30GB of free disk space. +- **Operating System:** A 64-bit installation of Linux. It is strongly advised + that you use a supported distribution; see :ref:`build_hosts`. We also + recommend that your system is fully up-to-date. + +.. note:: + + Some Linux distros are better-supported than others. Mozilla maintains + bootstrapping code for Ubuntu, but others are managed by the + community (thanks!). The more esoteric the distro you're using, + the more likely that you'll need to solve unexpected problems. + + +1. System preparation +--------------------- + +1.1 Install Python +~~~~~~~~~~~~~~~~~~ + +To build Firefox, it's necessary to have a Python of version 3.6 or later +installed. Python 2 is no longer required to build Firefox, although it is still +required for running some kinds of tests. Additionally, you will probably need +Python development files as well to install some pip packages. + +You should be able to install Python using your system package manager: + +- For Debian-based Linux (such as Ubuntu): ``sudo apt-get install curl python3 python3-pip`` +- For Fedora Linux: ``sudo dnf install python3 python3-pip`` + +If you need a version of Python that your package manager doesn't have (e.g.: +the provided Python 3 is too old, or you want Python 2 but it's not available), +then you can use `pyenv <https://github.com/pyenv/pyenv>`_, assuming that your +system is supported. + +1.2 Install Mercurial +~~~~~~~~~~~~~~~~~~~~~ + +Mozilla's source code is hosted in Mercurial repositories. You will +need Mercurial to download and update the code. + +Note that if you'd prefer to use the version of Mercurial that is +packaged by your distro, you can skip this section. However, keep in +mind that distro-packaged Mercurial may be outdated, and therefore +slower and less supported. + +.. code-block:: shell + + python3 -m pip install --user mercurial + +You can test that Mercurial is installed by running: + +.. code-block:: shell + + hg version + +.. note:: + + If your shell is showing ``command not found: hg``, then Python's packages aren't + being found in the ``$PATH``. You can resolve this by doing the following and + restarting your shell: + + .. code-block:: shell + + # If you're using zsh + echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.zshenv + + # If you're using bash + echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.bashrc + + # If you're using a different shell, follow its documentation to see + # how to configure your PATH. Ensure that `$(python3 -m site --user-base)/bin` + # is prepended. + +2. Bootstrap a copy of the Firefox source code +---------------------------------------------- + +Now that your system is ready, we can download the source code and have Firefox +automatically download the other dependencies it needs. The below command +will download a lot of data (years of Firefox history!) then guide you through +the interactive setup process. + +.. code-block:: shell + + curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O + python3 bootstrap.py + +.. note:: + + In general, the Firefox workflow works best with Mercurial. However, + if you'd prefer to use ``git``, you can grab the source code in + "git" form by running the bootstrap script with the ``vcs`` parameter: + + .. code-block:: shell + + python3 bootstrap.py --vcs=git + + This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood. + +Choosing a build type +~~~~~~~~~~~~~~~~~~~~~ + +If you aren't modifying the Firefox backend, then select one of the +:ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are +building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide`. + +3. Build +-------- + +Now that your system is bootstrapped, you should be able to build! + +.. code-block:: shell + + cd mozilla-unified + hg up -C central + ./mach build + ./mach run + +🎉 Congratulations! You've built your own home-grown Firefox! + +Now the fun starts +------------------ + +Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_, +say hello in the `Introduction channel +<https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to +start working on <https://codetribute.mozilla.org/>`_. +See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes, +send patches to Mozilla, update your source code locally, and more. + +Troubleshooting +--------------- + +Using a non-native file system (NTFS, network drive, etc) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In our experience building Firefox in these hybrid or otherwise complex environments +always ends in unexpected, often silent and always hard-to-diagnose failure. +Building Firefox in that environment is far more likely to reveal the flaws and +shortcomings of those systems than it is to produce a running web browser. diff --git a/docs/setup/macos_build.rst b/docs/setup/macos_build.rst new file mode 100644 index 0000000000..3d32b8aed0 --- /dev/null +++ b/docs/setup/macos_build.rst @@ -0,0 +1,122 @@ +Building Firefox On macOS +========================= + +This document will help you get set up to build Firefox on your own +computer. Getting set up can take a while - we need to download a +lot of bytes! Even on a fast connection, this can take ten to fifteen +minutes of work, spread out over an hour or two. + +Requirements +------------ + +- **Memory:** 4GB RAM minimum, 8GB+ recommended. +- **Disk Space:** At least 30GB of free disk space. +- **Operating System:** macOS - most recent or prior release. It is advisable + to upgrade to the latest “point” release. See :ref:`build_hosts` for more + information. + + +1. System preparation +--------------------- + +1.1. Install Brew +~~~~~~~~~~~~~~~~~ + +Mozilla's source tree requires a number of third-party tools. +You will need to install `Homebrew <https://brew.sh/>`__ so that we +can automatically fetch the tools we need. + +1.2. Install Xcode +~~~~~~~~~~~~~~~~~~ + +Install Xcode from the App Store. +Once done, finalize the installation in your terminal: + +.. code-block:: shell + + sudo xcode-select --switch /Applications/Xcode.app + sudo xcodebuild -license + +1.3 Install Mercurial +~~~~~~~~~~~~~~~~~~~~~ + +Mozilla's source code is hosted in Mercurial repositories. You will +need Mercurial to download and update the code. Additionally, we'll +put user-wide python package installations on the ``$PATH``, so that +both ``hg`` and ``moz-phab`` will be easily accessible: + +**NOTE** Pay special attention to the `==6.1.4`, as Mercurial >=6.2 is incompatible with several plugins + +.. code-block:: shell + + echo 'export PATH="'"$(python3 -m site --user-base)"'/bin:$PATH"' >> ~/.zshenv + python3 -m pip install --user mercurial==6.1.4 + +Now, restart your shell so that the ``PATH`` change took effect. +You can test that Mercurial is installed by running: + +.. code-block:: shell + + hg version + +.. note:: + + If you're using a shell other than ``zsh``, you'll need to manually add Python's + ``bin`` directory to your ``PATH``, as your shell probably won't pick up our + changes in ``~/.zshenv``. + +2. Bootstrap a copy of the Firefox source code +---------------------------------------------- + +Now that your system is ready, we can download the source code and have Firefox +automatically download the other dependencies it needs. The below command +will download a lot of data (years of Firefox history!) then guide you through +the interactive setup process. + +.. code-block:: shell + + curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O + python3 bootstrap.py + +.. note:: + + In general, the Firefox workflow works best with Mercurial. However, + if you'd prefer to use ``git``, you can grab the source code in + "git" form by running the bootstrap script with the ``vcs`` parameter: + + .. code-block:: shell + + python3 bootstrap.py --vcs=git + + This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood. + +Choosing a build type +~~~~~~~~~~~~~~~~~~~~~ + +If you aren't modifying the Firefox backend, then select one of the +:ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are +building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide`. + +3. Build +-------- + +Now that your system is bootstrapped, you should be able to build! + +.. code-block:: shell + + cd mozilla-unified + hg up -C central + ./mach build + ./mach run + +🎉 Congratulations! You've built your own home-grown Firefox! + +Now the fun starts +------------------ + +Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_, +say hello in the `Introduction channel +<https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to +start working on <https://codetribute.mozilla.org/>`_. +See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes, +send patches to Mozilla, update your source code locally, and more. diff --git a/docs/setup/windows_build.rst b/docs/setup/windows_build.rst new file mode 100644 index 0000000000..2e8da661e9 --- /dev/null +++ b/docs/setup/windows_build.rst @@ -0,0 +1,181 @@ +Building Firefox On Windows +=========================== + +This document will help you get set up to build Firefox on your own +computer. Getting set up can take a while - we need to download a +lot of bytes! Even on a fast connection, this can take ten to fifteen +minutes of work, spread out over an hour or two. + +If you'd prefer to build Firefox for Windows in a virtual machine, +you may be interested in the `Windows images provided by Microsoft +<https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/>`_. + +Requirements +------------ + +- **Memory:** 4GB RAM minimum, 8GB+ recommended. +- **Disk Space:** At least 40GB of free disk space. +- **Operating System:** Windows 10. It is advisable to have Windows Update be fully + up-to-date. See :ref:`build_hosts` for more information. + +1. Install MozillaBuild +----------------------- + +Install `MozillaBuild +<https://ftp.mozilla.org/pub/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`_. + +Accept the default installation directory. +Windows may prompt you to "reinstall with the correct settings", which you +should click to accept. + +When working with Firefox tooling, you'll need to do so from within the MozillaBuild +shell. You can start it by running ``C:\mozilla-build\start-shell.bat`` (you may want +to make a shortcut to this file so it's easier to start). + +.. note:: + + The MozillaBuild shell is a lot more like a Linux shell than the Windows ``cmd``. You can + learn more about it `here <https://wiki.mozilla.org/MozillaBuild>`_. + +2. Bootstrap a copy of the Firefox source code +---------------------------------------------- + +Now that your system is ready, we can download the source code and have Firefox +automatically download the other dependencies it needs. The below command +will download a lot of data (years of Firefox history!) then guide you through +the interactive setup process. + +.. code-block:: shell + + # Using the C:\mozilla-build\start-shell.bat shell from step 1: + cd c:/ + mkdir mozilla-source + cd mozilla-source + wget https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py + python3 bootstrap.py +.. note:: + + When running ``bootstrap.py`` there will be a `UAC (User Account Control) prompt <https://docs.microsoft.com/en-us/windows/security/identity-protection/user-account-control/how-user-account-control-works>`_ for PowerShell after + selecting the destination directory for the source code clone. This is + necessary to add the Microsoft Defender Antivirus exclusions automatically. You + should select ``Yes`` on the UAC prompt, otherwise you will need + to :ref:`follow some manual steps below <Ensure antivirus exclusions>`. + +.. note:: + + In general, the Firefox workflow works best with Mercurial. However, + if you'd prefer to use ``git``, you can grab the source code in + "git" form by running the bootstrap script with the ``vcs`` parameter: + + .. code-block:: shell + + python3 bootstrap.py --vcs=git + + This uses `Git Cinnabar <https://github.com/glandium/git-cinnabar/>`_ under the hood. + +Choosing a build type +~~~~~~~~~~~~~~~~~~~~~ + +If you aren't modifying the Firefox backend, then select one of the +:ref:`Artifact Mode <Understanding Artifact Builds>` options. If you are +building Firefox for Android, you should also see the :ref:`GeckoView Contributor Guide`. + +.. _Ensure antivirus exclusions: + +Ensure antivirus exclusions +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Microsoft Defender Antivirus and some third-party antivirus products +are known to significantly degrade build times and sometimes even cause failed +builds (due to a "missing file"). This is usually because we have tests for +well-known security bugs that have code samples that antivirus software identifies +as a threat, automatically quarantining/corrupting the files. + +To avoid this, add the following folders to your third-party antivirus exclusion list: + +- The ``C:\mozilla-build`` folder. +- The directory where the Firefox code is (probably ``C:\mozilla-source``). +- The ``%USERPROFILE%/.mozbuild`` directory (probably ``C:\Users\<user>\.mozbuild``). + +The ``bootstrap.py`` script attempts to add the above folders to the Microsoft +Defender Antivirus exclusion list automatically. You should check that they were +successfully added, but if they're missing you will need to `add the exclusions to +Microsoft Defender Antivirus manually +<https://support.microsoft.com/en-ca/help/4028485/windows-10-add-an-exclusion-to-windows-security>`_. + +.. note:: + + If you're already missing files (you'll see them listed in ``hg status``, you can have them + brought back by reverting your source tree: ``hg update -C``). + +3. Build +-------- + +Now that your system is bootstrapped, you should be able to build! + +.. code-block:: shell + + cd c:/mozilla-source/mozilla-unified + hg up -C central + ./mach build + ./mach run + +🎉 Congratulations! You've built your own home-grown Firefox! + +Now the fun starts +------------------ + +Time to start hacking! You should join us on `Matrix <https://chat.mozilla.org/>`_, +say hello in the `Introduction channel +<https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, and `find a bug to +start working on <https://codetribute.mozilla.org/>`_. +See the :ref:`Firefox Contributors' Quick Reference` to learn how to test your changes, +send patches to Mozilla, update your source code locally, and more. + +.. note:: + + If you'd like to interact with Mach from a different command line environment + than MozillaBuild, there's experimental support for it described + :ref:`over here <Using Mach on Windows Outside MozillaBuild>`. + +Troubleshooting +--------------- + +MozillaBuild out-of-date +~~~~~~~~~~~~~~~~~~~~~~~~ + +The build system expects that you're using the most-recent MozillaBuild release. +However, MozillaBuild doesn't auto-update. If you're running into local issues, +they may be resolved by `upgrading your MozillaBuild <https://wiki.mozilla.org/MozillaBuild>`_. + +Spaces in folder names +~~~~~~~~~~~~~~~~~~~~~~ + +**Firefox will not build** if the path to the installation +tool folders contains **spaces** or other breaking characters such as +pluses, quotation marks, or metacharacters. The Visual Studio tools and +SDKs are an exception - they may be installed in a directory which +contains spaces. It is strongly recommended that you accept the default +settings for all installation locations. + +Quotation marks in ``PATH`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Quotation marks (") aren't translated properly when passed to MozillaBuild +sub-shells. Since they're not usually necessary, you should ensure they're +not in your ``PATH`` environment variable. + +``PYTHON`` environment variable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If ``PYTHON`` is set, the build may fail with the error: "``The system +cannot find the file specified``." Ensure that you aren't having +a ``PYTHON`` environment variable set. + +Cygwin interference +~~~~~~~~~~~~~~~~~~~ + +If you happen to have Cygwin installed, its tools may erroneously be +used when building Firefox. Ensure that MozillaBuild directories (in +``C:\mozilla-build\``) are before Cygwin directories in the ``PATH`` +environment variable. |