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 | 440 | ||||
| -rw-r--r-- | docs/setup/contributing_code.rst | 199 | ||||
| -rw-r--r-- | docs/setup/getting_set_up.rst | 65 | ||||
| -rw-r--r-- | docs/setup/index.rst | 21 | ||||
| -rw-r--r-- | docs/setup/linux_32bit_build_on_64bit_OS.rst | 78 | ||||
| -rw-r--r-- | docs/setup/linux_build.rst | 282 | ||||
| -rw-r--r-- | docs/setup/macos_build.rst | 477 | ||||
| -rw-r--r-- | docs/setup/windows_build.rst | 476 |
9 files changed, 2099 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..b870632ad4 --- /dev/null +++ b/docs/setup/configuring_build_options.rst @@ -0,0 +1,440 @@ +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 application 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 applications 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 application 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 applications (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_MAKE_FLAGS="-j4" + +If your machine is overheating, you might want to try a lower value, +e.g. ``-j1``. + + +Choose an application +~~~~~~~~~~~~~~~~~~~~~ + +The ``--enable-application=application`` flag is used to select an +application 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-application=browser + + .. note:: + + **Note**: This is the default + +Mail (Thunderbird) + .. code:: + + ac_add_options --enable-application=comm/mail + +Mozilla Suite (SeaMonkey) + .. code:: + + ac_add_options --enable-application=suite + +Calendar (Lightning Extension, uses Thunderbird) + .. code:: + + ac_add_options --enable-application=comm/mail + ac_add_options --enable-calendar + + +Selecting build options +~~~~~~~~~~~~~~~~~~~~~~~ + +The build options you choose depends on what application 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 +applications. The full list of options can be obtained by running +``./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 applications 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 applications from the same source tree +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to build multiple applications from the same source tree, +as long as you `use a different objdir <#Building_with_an_Objdir>`__ for +each application. + +You can either create multiple ``mozconfig`` files, or alternatively, +use the ``MOZ_BUILD_PROJECTS`` make option. + +Using ``MOZ_BUILD_PROJECTS`` in a single ``mozconfig`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To use ``MOZ_BUILD_PROJECTS``, you must specify a ``MOZ_OBJDIR`` and a +``MOZ_BUILD_PROJECTS`` make option, containing space separated names. +Each name can be an arbitrary directory name. For each name, a +subdirectory is created under the toplevel objdir. You then need to use +the ``ac_add_app_options`` with the specified names to enable different +applications in each object directory. + +For example: + +.. code:: + + ac_add_options --disable-optimize --enable-debug + mk_add_options MOZ_OBJDIR=/mozilla/src/obj-@CONFIG_GUESS@ + mk_add_options MOZ_BUILD_PROJECTS="browser mail" + ac_add_app_options browser --enable-application=browser + ac_add_app_options mail --enable-application=comm/mail + +If you want to build only one project using this ``mozconfig``, use the +following command line: + +.. code:: + + MOZ_CURRENT_PROJECT=browser ./mach build + +This will build only the browser. + +Using multiple mozconfig files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Alternatively, you may want to create separate ``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_MAKE_FLAGS="-j4" + 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-application=browser + +``mozconfig-thunderbird``: + +.. code:: + + # include the common mozconfig + . ./mozconfig-common + + # Build Thunderbird + mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-thunderbird + ac_add_options --enable-application=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..91a1264e0d --- /dev/null +++ b/docs/setup/contributing_code.rst @@ -0,0 +1,199 @@ +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. +- Visit `firefox-dev.tools <http://firefox-dev.tools>`_ - we list + Firefox Developer Tools bugs for new contributors. +- `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 <https://developer.mozilla.org/docs/Mozilla/Bugzilla>`_ and `Searching + Bugzilla <https://developer.mozilla.org/docs/Mozilla/QA/Searching_Bugzilla>`_ 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 + `https://developer.mozilla.org/docs/Developer_Guide <https://developer.mozilla.org/docs/Developer_Guide>`_ + and its parent document, + https://developer.mozilla.org/docs/Mozilla +- 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 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 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 an out of date `list of + modules <https://wiki.mozilla.org/Modules>`_, 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, or contact `Mike +Hoye <mailto:mhoye@mozilla.com?subject=Code%20Review%20Request%20&body=URL%3A%20%20%5Bplease%20paste%20a%20link%20to%20your%20patch%20here.%5D>`_ +directly. + +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 `try +server <https://wiki.mozilla.org/ReleaseEngineering/TryServer>`_, +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. + +Once you have a **green** try server run, mark that your patch is ready +to commit by + +#. opening the Phabricator page for your patch +#. clicking the 'Edit Revision' link in the sidebar on the right +#. then into the 'Tags' field and +#. typing 'Check-In Needed' to get the tag added. + +A friendly Mozillian, with commit access, will be along shortly to push +your patch to the repository, and update the bug as required. If your +patch passes all Mozilla's automated testing, it will soon be merged +into the main branch, and become a part of the Nightly build. + +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/getting_set_up.rst b/docs/setup/getting_set_up.rst new file mode 100644 index 0000000000..63482148aa --- /dev/null +++ b/docs/setup/getting_set_up.rst @@ -0,0 +1,65 @@ +Welcome to the Firefox codebase! +-------------------------------- + +This page is here to help you get from "I want to build Firefox" +to "I'm building my own Firefox" to "I can contribute to Firefox". +So if you'd like to help Mozilla build the best web browser in the +world, you're in the right place. + +.. rubric:: Need help? + :name: Need_help + +The Mozilla community prides itself on being an open, accessible, and +friendly community for new participants. If you have any difficulties +getting involved or finding answers to your questions, please `come and +ask your questions in our +chatroom <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_, +where we can help you get started. + +We know even before you start contributing that getting set up to work +on Firefox and finding a bug that's a good fit for your skills can be a +challenge, and we're always looking for ways to improve this process: making +Mozilla more open, accessible, and easier to participate with. If you're +having any trouble following this documentation, or hit a barrier you +can't get around, please join us in the the Introduction room on Matrix +or contact Mike Hoye directly at mhoye@mozilla.com. + +What skills do I need? +---------------------- + +Mozilla is a large project and we are thrilled to have contributors with +very diverse skills: + +- If you know **C++,** **Rust,** **JavaScript,** **HTML** or **CSS**, + you can contribute to the core layers of Firefox and many other Mozilla + projects. +- If you know **Rust**, you can also contribute to the Rust programming + language itself, and `Servo <https://servo.org/>`_, the web browser engine + designed for parallelism and safety. +- If you know **Java**, you can contribute to Firefox on Android, + `Firefox Focus for + Android <https://github.com/mozilla-mobile/focus-android>`_ . +- If you know **Kotlin**, you can contribute to `Firefox + Preview <https://github.com/mozilla-mobile/fenix>`_ (code name: + "Fenix"). +- If you know **Swift**, you can contribute to `Firefox for + iOS <https://github.com/mozilla-mobile/firefox-ios>`_ and `Firefox + Focus for iOS <https://github.com/mozilla-mobile/focus-ios>`_ +- If you know **Python**, you can contribute to our web services, + including Firefox Sync and Firefox Accounts +- If you know **Make**, **shell**, **Perl**, or **Python**, you can + contribute to our build systems, release engineering, and automation +- If you know **C**, you can contribute to NSS, Opus, and Daala +- There are even many ways to contribute to the Mozilla mission without + programming. If getting involved in design, support, translation, + testing, or other types of contributions sparks your interest please + see the `Volunteer Opportunities + wiki <https://contribute.mozilla.org>`_ or the `Mozilla + community <https://mozilla.community/>`_ site. + +Perhaps you do not know programming yet, but you want to start learning? +There are `plenty of +resources <https://developer.mozilla.org/learn>`_ available on +the MDN Web Docs! + +Read on for information about how to set up your machine to build Firefox. diff --git a/docs/setup/index.rst b/docs/setup/index.rst new file mode 100644 index 0000000000..332ac8d001 --- /dev/null +++ b/docs/setup/index.rst @@ -0,0 +1,21 @@ +Getting Set Up To Work On The Firefox Codebase +============================================== + +This page will help you get set up to build Firefox on your own machine. + +.. toctree:: + :caption: Thank you for contributing to Firefox + + getting_set_up + +.. toctree:: + :caption: Setting Up Your Machine + + windows_build + macos_build + linux_build + +.. 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..fb6682672e --- /dev/null +++ b/docs/setup/linux_32bit_build_on_64bit_OS.rst @@ -0,0 +1,78 @@ +Building Firefox 32-bit On Linux 64-bit +======================================= + +Instructions for Fedora 20 and 19 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First ensure that your compiler toolchain and Gecko build dependencies +are installed. + +.. code:: + + sudo yum install \ + ccache cmake gcc gcc-c++ glibc-devel.i686 \ + libstdc++-devel libstdc++-devel.i686 \ + gtk2-devel.i686 gtk+-devel.i686 gtk+extra-devel.i686 \ + glib-devel.i686 glib2-devel.i686 \ + dbus-devel.i686 dbus-glib-devel.i686 \ + alsa-lib-devel.i686 yasm-devel.i686 \ + libxml2-devel.i686 zlib-devel.i686 \ + freetype-devel.i686 \ + atk-devel.i686 pango-devel.i686 fontconfig-devel.i686 \ + cairo-devel.i686 gdk-pixbuf2-devel.i686 \ + libX11-devel.i686 libXt-devel.i686 libXext-devel.i686 \ + libXrender-devel.i686 libXau-devel.i686 libxcb-devel.i686 \ + pulseaudio-libs-devel.i686 harfbuzz-devel.i686 \ + mesa-libGL-devel.i686 libXxf86vm-devel.i686 \ + libXfixes-devel.i686 libdrm-devel-2.4.49-2.fc19.i686 \ + mesa-libEGL-devel libXdamage-devel.i686 libXcomposite-devel.i686 + +Then you need to use a .mozconfig that looks like the following example. + +.. code:: + + # Flags set for targeting x86. + export CROSS_COMPILE=1 + export PKG_CONFIG_PATH=/usr/lib/pkgconfig + + CC="ccache gcc -m32" + CXX="ccache g++ -m32" + AR=ar + ac_add_options --target=i686-pc-linux + + # Normal build flags. These make a debug browser build. + ac_add_options --enable-application=browser + mk_add_options MOZ_MAKE_FLAGS="-s -j6" + mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../ff-dbg + + ac_add_options --enable-debug + ac_add_options --disable-optimize + +Instructions for Ubuntu 19.10 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These steps were verified to work as of June 2020 + +#. Install mercurial or git and :ref:`fetch a copy <Mercurial Bundles>` of ``mozilla-central``. +#. Run ``./mach bootstrap`` to install some dependencies. Note that this + will install some amd64 packages that are not needed to build 32-bit + Firefox. +#. 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 + +5. Create a file called ``mozconfig`` in the top-level directory of you + ``mozilla-central`` checkout, containing at least the following: + + .. code:: + + ac_add_options --target=i686 + +6. Run ``./mach build``. diff --git a/docs/setup/linux_build.rst b/docs/setup/linux_build.rst new file mode 100644 index 0000000000..321db0a96a --- /dev/null +++ b/docs/setup/linux_build.rst @@ -0,0 +1,282 @@ +Building Firefox On Linux +========================= + +They aren’t complicated, but there are a few prerequisites to building Firefox on Linux. You need: + +#. A 64-bit installation of Linux. You can check by opening a terminal window; if ``uname -m`` returns ``x86_64`` you can proceed. +#. Next, you’ll need Python 3.6 or later installed. You can check with ``python3 --version`` to see if you have it already. If not, see `Installing Python <#installingpython>`_. You'll also need to install Mercurial and can do so with ``pip3 install Mercurial``. +#. Finally, a reasonably fast internet connection and 30GB of free disk space. + +Getting Started +--------------- + +Getting set up on Linux is fast and easy. + +If you don’t have one yet, create a "``src``" directory for +yourself under your home directory: + +.. code-block:: shell + + mkdir src && cd src + +Next `download the bootstrap.py +script <https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py>`_ +and save it in the ``src/`` directory created above. + +.. warning:: + + Building Firefox in Linux on top of a non-native file system - + for example, on a mounted NTFS partition - is explicitly not + supported. While a build environment like this may succeed it + may also fail while claiming to have succeeded, which can be + quite difficult to diagnose and fix. + +And finally, in your terminal from above start the bootstrapper +like this: + +.. code-block:: shell + + python3 bootstrap.py + +... and follow the prompts. This will use mercurial to checkout +the source code. If you prefer to work with ``git``, use this command +instead (make sure you have ``git`` installed): + +.. code-block:: shell + + python3 bootstrap.py --vcs=git + +Let’s Build Firefox +------------------- + +You’re ready; now we can tie it all together. In your terminal: + +.. code-block:: shell + + cd mozilla-unified # ... or the name of the repo you chose in the above step + +If you are not working on the C/C++ files you can also opt for +:ref:`Artifact Builds <Understanding Artifact Builds>` +which are much faster. To enable artifact build set up a +:ref:`mozconfig <Configuring Build Options>` +file with the following options: + +.. code-block:: shell + + # Automatically download and use compiled C++ components: + # This option will disable C/C++ compilation + ac_add_options --enable-artifact-builds + + # Write build artifacts to (not mandatory): + mk_add_options MOZ_OBJDIR=./objdir-frontend + +If you plan to walk through code with a debugger, set up a +:ref:`.mozconfig <Configuring Build Options>` +file with the following options: + +.. code-block:: shell + + ac_add_options --disable-optimize + ac_add_options --enable-debug + + +Older clang versions (especially clang 6) `from LTS linux +distributions sometimes miscompile +Firefox <https://bugzilla.mozilla.org/show_bug.cgi?id=1594686>`_, +resulting in startup crashes when starting the resulting build. +If this happens, you can force the use of the ``clang`` version +that ``./mach bootstrap`` downloaded by adding the following to +your ``.mozconfig``: + +.. code-block:: shell + + export CC=path/to/home/.mozbuild/clang/bin/clang + export CXX=path/to/home/.mozbuild/clang/bin/clang++ + +And finally, run the build command: + +.. code-block:: shell + + ./mach build + +If you encounter any error related to LLVM/Clang on Ubuntu or +Debian, download the latest version of LLVM and Clang and then +re-run ``./mach build``. + +And you’re on your way, building your own copy of Firefox from +source. Don’t be discouraged if this takes a while; this takes +some time on even the fastest modern machines, and as much as two +hours or more on older hardware. When the +``--enable-artifact-builds`` option is used, builds usually finish +within a few minutes. + +Now the fun starts +------------------ + +You have the code, you’ve compiled Firefox. Fire it up with +``./mach run`` and you’re ready to start hacking. The next steps +are up to you: join us on `Matrix <https://chat.mozilla.org/>`_ +in the `Introduction <https://chat.mozilla.org/#/room/#introduction:mozilla.org>`_ +channel, and find `a bug to start working on. <https://codetribute.mozilla.org/>`_ + + +General considerations +---------------------- + +#. 4GB RAM with an additional 4GB of available swap space is the bare minimum, and more RAM is always better - having 8GB or more will dramatically improve build time. +#. A 64-bit x86 CPU and a 64-bit OS. As of early 2015 it is no longer possible to do a full build of Firefox from source on most 32-bit systems; a 64-bit OS is required. ":ref:`Artifact Builds <Understanding Artifact Builds>`" may be possible, but are not a supported configuration. On Linux you can determine this by typing "``uname -a``" in a terminal. It is possible to build a 32-bit Firefox on a 64-bit system, see :ref:`Building Firefox 32-bit on Linux 64-bit <Building Firefox 32-bit On Linux 64-bit>`. +#. A recent version of Clang is required to build Firefox. You can learn more about the features we use and their :ref:`compiler support <Using C++ in Mozilla code>`. +#. If you are on a Fedora machine then simply install the following prerequisites from the terminal window: + +.. code-block:: shell + + sudo dnf install @development-tools @c-development gtk2-devel gtk3-devel libXt-devel GConf2-devel dbus-glib-devel yasm-devel alsa-lib-devel pulseaudio-libs-devel + + +.. _installingpython: + +Installing 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 some development tasks, like testing and pushing to ``try``. + +Often, you can install both Python 2 and 3 with your system package manager. +Make sure your system is up to date! However, users on older Linux distributions +might find they are unable to install a recent enough Python 3, while users on +newer Linux distributions may find that they can no longer install Python 2.7. +`pyenv <https://github.com/pyenv/pyenv>`_ is an easy way to install arbitrary +Python versions if you fall into either of these categories. Your system package +manager may or may not provide ``pyenv``, but the ``pyenv`` GitHub repository +provides detailed `manual installation instructions +<https://github.com/pyenv/pyenv#installation>`_ in any case. + +Once you have ``pyenv`` configured properly and ``pyenv``'s ``shims`` directory +at the front of your ``$PATH``, you can easily install any version of Python +and configure your project to use them. For example, at the root of your +checkout, do the following: + +.. code-block:: shell + + pyenv install 2.7.17 + pyenv install 3.7.8 + pyenv local 3.7.8 2.7.17 + + +Requirements for Debian / Ubuntu users +-------------------------------------- + +You need a number of different packages: + +.. code-block:: shell + + # the rust compiler + aptitude install rustc + + # the rust package manager + aptitude install cargo + + # the headers of important libs + aptitude install libgtk-2-dev + aptitude install libgtk-3-dev + aptitude install libgconf2-dev + aptitude install libdbus-glib-1-dev + aptitude install libpulse-dev + + # rust dependencies + cargo install cbindgen + + # an assembler for compiling webm + aptitude install yasm + + # Python 3 dependencies. This will work on Ubuntu 18.04LTS and later or + # Debian buster and later. For earlier releases of Ubuntu or Debian, you + # may prefer to use pyenv. + aptitude install python3 python3-dev python3-pip python3-setuptools + + # Python 2 dependencies. This will work on Ubuntu versions prior to 20.04 LTS + # and Debian versions prior to bullseye. For later releases of Ubuntu or + # Debian, you may prefer to use pyenv. + aptitude install python python-dev python-pip python-setuptools + + +One-Line Bootstrapping +---------------------- + +Our system bootstrapping script can automatically install the required +dependencies. You can download and run it by copying this line and +pasting it into a terminal window: + +.. code-block:: shell + + wget -q https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -O bootstrap.py && python3 bootstrap.py + +.. note:: + + Note: piping bootstrap.py to stdin of a python process will cause + interactive prompts in the bootstrap script to fail, causing the + bootstrap process to fail. You must run Python against a local file. + +If the above command fails, the reason is often because some Linux +distributions ship with an outdated list of root certificates. In this +case, you should upgrade your Linux distribution or use your browser to +download the file. That ensures that you will get it from the right +source. +If you get an error from this process, consider `filing a +bug <https://bugzilla.mozilla.org/enter_bug.cgi?product=Core&component=Build%20Config>`_ +saying that the bootstrapper didn't work and `contact Mike +Hoye <mailto:mhoye@mozilla.com>` directly for help. Please include the +error message and some details about your operating system. + +If you have already checked out the source code via Mercurial or Git you +can also use :ref:`mach` with the bootstrap command: + +.. code-block:: shell + + ./mach bootstrap + + + +Common Bootstrapper Failures +---------------------------- + +.. code-block:: shell + + wget: command not found + +You may not have wget (or curl) installed. In that case, you can either +install it via your package manager: + +On Debian-based distros like Ubuntu: + +.. code-block:: shell + + sudo apt install wget + +On Fedora-based distros: + +.. code-block:: shell + + sudo dnf install wget + +or you can just `download +bootstrap.py <https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py>`_ +using your browser and then run it with this command: + +.. code-block:: shell + + python3 bootstrap.py + +In some cases people who've customized their command prompt to include +emoji or other non-text symbols have found that bootstrap.py fails with +a ``UnicodeDecodeError``. We have a bug filed for that but in the +meantime if you run into this problem you'll need to change your prompt +back to something boring. + + +More info +--------- + +The above bootstrap script supports popular Linux distributions. If it +doesn't work for you, see :ref:`Linux build prerequisites <Building Firefox On Linux>` for more. diff --git a/docs/setup/macos_build.rst b/docs/setup/macos_build.rst new file mode 100644 index 0000000000..098f2b9f5b --- /dev/null +++ b/docs/setup/macos_build.rst @@ -0,0 +1,477 @@ +Building Firefox On macOS +========================= + +This document will help you get set up to build Firefox on your own +computer. Getting set up won't be difficult, but it 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. + +The details are further down this page, but this quick-start guide +should get you up and running: + +.. rubric:: Quick start (Try this first!) + :name: Quick_start_Try_this_first! + +.. rubric:: Prerequisites + :name: Prerequisites + +You will need: + +- an Apple ID to download and install Apple-distributed developer tools + mentioned below +- from 5 minutes to 1 hour to download and install Xcode, which is + large +- download and install a local copy of specific macOS SDK version + +You will need administrator permissions on your machine to install these +prerequisites. (You can verify that you have these permissions in System +Preferences -> Users & Groups.) + +See :ref:`1.1 Install Xcode and Xcode command line tools <xcode>` and :ref:`1.2 +Get the local macOS SDK <macossdk>` for more information on how to +install these prerequisites. + +.. rubric:: Getting the source + :name: Getting_the_source + :class: heading-tertiary + +Firstly you need to prepare a directory and get the bootstrap script +that will do the rest: + +.. code-block:: shell + + # the bootstrap script needs this directory, but you can choose a different target directory for the Mozilla code later + cd ~ && mkdir -p src && cd src + + # download the bootstrap script + curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -o bootstrap.py + +If you don't have Python 3.6 or later or Mercurial installed, see :ref:`2.1a Install +dependencies via Homebrew <#install-via-homebrew>` for more information on how +to do so. Then in your terminal from above start the bootstrapper like this: + +.. code-block:: shell + + python3 bootstrap.py + +... and follow the prompts. This will use mercurial to checkout the +source code. If you prefer to work with git, use this command instead: + +.. code-block:: shell + + python3 bootstrap.py --vcs=git + +If you don't have `Homebrew <https://brew.sh/>`_ or +`Ports <https://www.macports.org/>`__ installed - software package +managers that will let us install some programs we'll need - you'll be +asked to pick one. Either will work, but most Mozilla developers use +Homebrew. + +If you don't let the ``bootstrap.py`` script clone the source for you +make sure you do it manually afterward before moving onto the next step. + +.. rubric:: Build Firefox! + :name: Build_Firefox! + :class: heading-tertiary highlight-spanned + +Now we tie it all together. + +In your terminal window, ``cd`` to your Mozilla source directory chosen +before and type: + +.. code-block:: shell + + # create a minimal build options file + echo "ac_add_options --with-macos-sdk=$HOME/SDK-archive/MacOSX10.12.sdk" >> mozconfig + + ./mach bootstrap + + ./mach build + +The ``./mach bootstrap`` step is a catch-all for any dependencies not +covered in this documentation. If you are working on Firefox frontends +or building Firefox without any changes, select :ref:`Artifact Builds +<Understanding Artifact Builds>` in +the first question in ``./mach bootstrap``. Artifact builds will +complete more quickly! Artifact builds are unsuitable for those working +on C++ code. + +You’re on your way. Don’t be discouraged if this takes a while; it takes +some time even on the fastest modern machines and as much as two hours +or more on older hardware. Firefox is pretty big, because the Web is +big. + +.. rubric:: Now the Fun Starts + :name: Now_the_Fun_Starts + :class: heading-tertiary + +You have the code, you’ve compiled Firefox. Fire it up with +``./mach run`` and you’re ready to start hacking. + +Build steps (details) +--------------------- + +Building on macOS is divided into the following steps: + +#. Install Apple-distributed developer tools - Xcode, Xcode cli tools + and macOS SDK locally +#. Install supplementary build tools +#. Obtain a copy of the Mozilla source code +#. Configure the Mozilla source tree to suit your needs +#. Build Firefox + + +.. _xcode: + +1.1 Install Xcode and Xcode command line tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You first need to install Xcode, for which you have two options but both +require you to sign in with an Apple ID: + +- From Apple Developer Download page - `direct + link <https://developer.apple.com/download/release/>`__. Install the + latest **release** (non-beta) version of Xcode, open ``Xcode.xip``, + and then **before** **running the extracted Xcode.app, move it from + the download folder to /Applications**. (Running it from another + location may screw up various build paths, homebrew builds, etc. Fix + by running ``sudo xcode-select -switch /Applications/Xcode.app`` ) +- From the Mac App Store - `direct + link <https://apps.apple.com/us/app/xcode>`__. + +Open /Applications/Xcode.app and let it do its initial first run and +setup stuff. + +Install the Xcode command line tools by +running ``xcode-select --install`` in your terminal. + +.. _macossdk: + +1.2 Get the local macOS SDK +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Firefox currently requires a local copy of macOS 10.12 SDK to build (all +your other apps will still use your more recent version of this SDK, +most probably matching your macOS version). + +There are various issues when building the Mozilla source code with +other SDKs and that's why we recommend this specific version. + +To get the 10.12 SDK, first download Xcode 8.2 from the `More +Downloads for Apple +Developers <https://developer.apple.com/download/more/>`__ page. Once +downloaded, mount the .dmg file. Then in the Terminal run the following: + +.. code-block:: shell + + mkdir -p $HOME/SDK-archive + cp -a /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk $HOME/SDK-archive/MacOSX10.12.sdk + +2. Install supplementary build tools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mozilla's source tree requires a number of third-party tools and +applications to build it. You will need to install these before you can +build anything. + +You have the choice of how to install all these components. You can use +a package manager like Homebrew or Ports. Or, you can obtain, compile, +and install them individually. For simplicity and to save your time, +using a package manager is recommended. The following sections describe +how to install the packages using existing package managers. Choose +whatever package manager you prefer. + +.. _install-via-homebrew: + +2.1a Install dependencies via Homebrew +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`Homebrew <http://brew.sh/>`__ is "the missing package manager for +macOS." It provides a simple command-line interface to install packages, +typically by compiling them from source. + +The first step is to install Homebrew. See https://brew.sh/ + +Once you have Homebrew installed, you'll need to run the following: + +.. code-block:: shell + + brew install yasm mercurial gawk ccache python + +Python 2 is never necessary solely to build Firefox, but it is still required +for some development tasks (including testing and pushing to ``try``). If your +system does not already have a Python 2 installed, you can use ``brew`` to +install one: + +.. code-block:: shell + + brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/86a44a0a552c673a05f11018459c9f5faae3becc/Formula/python@2.rb + +2.1b Install Dependencies via MacPorts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +MacPorts is a package manager for macOS. If you are running Homebrew, +you can ignore this section. + +To install MacPorts, go to their `install +page <http://www.macports.org/install.php>`_, download the .dmg for +your platform, and install it. If you already have MacPorts installed, +ensure it is up to date by running: + +.. code:: + + sudo port selfupdate + sudo port sync + +The first of these commands will ask for your root password. + +Common errors include: + +- ``sudo`` doesn't accept a blank password: create a password for your + account in System Preferences. +- ``port`` command not found: add it to your path (see the + troubleshooting section below). + +Use MacPorts to install the packages needed for building Firefox: + +.. code:: + + sudo port install libidl yasm python27 py27-gnureadline + +You'll then see lots of output as MacPorts builds and installs these +packages and their dependencies -- it takes a while, so go grab a cup of +coffee. + +**Note:** By default, this will install Python 2.7, which in turn will +pull in all of the X11 libraries, which may take a while to build. You +don't need any of those to build Firefox; you may want to consider +adding +no\_tkinter to the install line to build a python without +support for the X11 UI packages. This should result in a much faster +install. + +**Note:** With older versions of Xcode (eg 6.4) you may need to use +MacPorts to get the proper version of clang, such as clang-3.6 or later. +See bugs in Core, Build Config referring to clang. + +2.2 Install Mercurial +~~~~~~~~~~~~~~~~~~~~~ + +Mozilla's source code is hosted in Mercurial repositories. You use +Mercurial to interact with these repositories. There are many ways to +install Mercurial on macOS: + +1. Install `official builds from + Selenic <http://mercurial.selenic.com/>`_ + +2. Install via Homebrew: + +.. code-block:: shell + + brew install mercurial + +3. Install via MacPorts: + +.. code-block:: shell + + sudo port install mercurial + +4. Install via Pip: + +.. code-block:: shell + + easy_install pip && pip install mercurial + +Once you have installed Mercurial, test it by running: + +.. code-block:: shell + + hg version + +If this works, congratulations! You'll want to configure your Mercurial +settings to match other developers. See :ref:`Getting Mozilla Source Code +Using Mercurial <Mercurial Overview>`. + +If this fails with the error "``ValueError: unknown locale: UTF-8``", +then see the +`workarounds <http://www.selenic.com/mercurial/wiki/index.cgi/UnixInstall#head-1c10f216d5b9ccdcb2613ea37d407eb45f22a394>`_ +on the Mercurial wiki's Unix Install page. + +When trying to clone a repository you may get an HTTP 500 error +(internal server error). This seems to be due to something that Mac +Mercurial sends to the server (it's been observed both with MacPort and +selenic.com Mercurial binaries). Try restarting your shell, your +computer, or reinstall Mercurial (in that order), then report back here +what worked, please. + +3. Obtain a copy of the Mozilla source code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You may want to read :ref:`Getting Mozilla Source Code +Using Mercurial <Mercurial Overview>` for the +complete instructions. + +If you are interested in Firefox development only then run the following +command, which will create a new directory, ``mozilla-central``, in the +current one with the contents of the remote repository. + +Below command will take many minutes to run, as it will be copying a +couple hundred megabytes of data over the internet. + +.. code:: + + hg clone https://hg.mozilla.org/mozilla-central/ + cd mozilla-central + +(If you are building Firefox for Android, you should now return to the +`Android build instructions <https://wiki.mozilla.org/Mobile/Fennec/Android#Mac_OS_X>`_.) + +4. Configure the build options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In your checked out source tree create a new file, ``mozconfig``, which +will contain your build options. For more on this file, see :ref:`Configuring Build Options`. + +To get started quickly, create the file with the following contents: + +.. code:: + + # Define where build files should go. This places them in the directory + # "obj-ff-dbg" under the current source directory + mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-dbg + + # Enable debug builds + ac_add_options --enable-debug + + # Use the local copy of specific version of macOS SDK compatible with Mozilla source code + ac_add_options --with-macos-sdk=$HOME/SDK-archive/MacOSX10.12.sdk + +Firefox no longer builds with gcc 4.8 or earlier, but the build system +should automatically select clang if it is available in the PATH. If +that is not the case, you need to set CC and CXX. For instance, if you +installed Clang 9 via Homebrew, then you need to have this in your +``mozconfig``: + +.. code:: + + CC=clang-9 + CXX=clang++-9 + +5. Build +~~~~~~~~ + +Once you have your ``mozconfig`` file in place, you should be able to +build! + +.. code-block:: shell + + ./mach build + +If the build step works, you should be able to find the built +application inside ``obj-ff-dbg/dist/``. If building the browser with +``--enable-debug``, the name of the application is ``NightlyDebug.app``. +To launch the application, try running the following: + +.. code-block:: shell + + ./mach run + +**Note:** The compiled application may also be named after the branch +you're building; for example, if you changed these instructions to fetch +the ``mozilla-1.9.2`` branch, the application will be named +``Namoroka.app`` or ``NamorokaDebug.app``. + +Hardware requirements +--------------------- + +There are no specific hardware requirements, provided that the hardware +accommodates all of the `software <#Software_Requirements>`_ required +to build Firefox. Firefox can take a long time to build, so more CPU, +more RAM and lots of fast disk space are always recommended. + +- **Processor:** Intel CPUs are required. Building for PowerPC chips is + not supported. +- **Memory:** 2GB RAM minimum, 8GB recommended. +- **Disk Space:** At least 30GB of free disk space. + +Software requirements +--------------------- + +- **Operating System:** macOS 10.12 or later. It is advisable to + upgrade to the latest “point” release by running Software Update, + found in the Apple menu. You will need administrative privileges to + set up your development environment +- **Development Environment:** Xcode. You can obtain this from the App + Store. +- **Package Management:** Either Homebrew or + `MacPorts <http://www.macports.org/>`_. + +These options are specific to Mozilla builds for macOS. For a more +general overview of build options and the ``mozconfig`` file, see +:ref:`Configuring Build Options`. + +- **Compiler:** Firefox releases are no longer built with gcc-4.8 or + earlier. A recent copy of clang is needed. + + - There are some options on where to get clang: + + - Newer versions of Xcode. + - Following the instructions in the `clang + website <http://clang.llvm.org/get_started.html>`__ for + information on how to get it. + - Using some of the package managers (see above). + + - Once clang is installed, make sure it is on the PATH and configure + should use it. + +The following options, specified with ``ac_add_options``, are lines that +are intended to be added to your ``mozconfig`` file. + +- **macOS SDK:** This selects the version of the system headers and + libraries to build against, ensuring that the product you build will + be able to run on older systems with less complete APIs available. + Selecting an SDK with this option overrides the default headers and + libraries in ``/usr/include``, ``/usr/lib``, and ``/System/Library``. + + .. code-block:: shell + + ac_add_options --with-macos-sdk=/path/to/SDK + + Official trunk builds use `MacOSX10.12.sdk`. Check + `build/macosx/universal/mozconfig.common <https://searchfox.org/mozilla-central/source/build/macosx/cross-mozconfig.common>`__ + for the SDK version used for official builds of any particular source + release. + + Applications built against a particular SDK will usually run on + earlier versions of macOS as long as they are careful not to use + features or frameworks only available on later versions. Note that + some frameworks (notably AppKit) behave differently at runtime + depending on which SDK was used at build time. This may be the source + of bugs that only appear on certain platforms or in certain builds. + +For macOS builds, defines are set up as follows: + +- ``XP_MACOSX`` is defined +- ``XP_UNIX`` is defined +- ``XP_MAC`` is **not** defined. ``XP_MAC`` is obsolete and has been + removed from the source tree (see {{ Bug(281889) }}). It was used for + CFM (non-Mach-O) builds for the classic (pre-X) Mac OS. + +This requires care when writing code for Unix platforms that exclude +Mac: + +.. code-block:: shell + + #if defined(XP_UNIX) && !defined(XP_MACOSX) + +Troubleshooting +--------------- + +- **If configure (or generally building with clang) fails with + ``fatal error: 'stdio.h' file not found``:** Make sure the Xcode + command line tools are installed by running. + ``xcode-select --install``. +- **For inexplicable errors in the configure phase:** Review all + modifications of your PATH in .bash\_profile, .bash\_rc or whatever + configuration file you're using for your chosen shell. Removing all + modifications and then re-adding them one-by-one can narrow down + problems. diff --git a/docs/setup/windows_build.rst b/docs/setup/windows_build.rst new file mode 100644 index 0000000000..945d38c349 --- /dev/null +++ b/docs/setup/windows_build.rst @@ -0,0 +1,476 @@ +Building Firefox On Windows +=========================== + +Thank you for helping us build the world's best browser on the world's +most popular OS. This document will help you get set up to build and +hack on your own version of Firefox on your local machine. + +Getting set up won't be difficult, but it 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. + +The details are further down this page, but this quick start guide +should get you up and running: + +Getting ready +------------- + +To build Firefox on Windows, you need a 64-bit version of Windows 7 or +later and about 40 GB of free space on your hard drive. You can make +sure your version of Windows is 64-bit on Windows 7 by right-clicking on +“Computer” in your “Start” menu, clicking “Properties” and then +“System”. On Windows 8.1 and Windows 10, right-clicking the “Windows” +menu button and choosing “System” will show you the same information. +You can alternatively press the “Windows” and “Pause Break” buttons +simultaneously on your keyboard on any version of Windows. + +Next, we want to start on a solid foundation: make sure you’re up to +date with Windows Update and then we’ll get moving. + +.. note:: + + Microsoft is providing some Windows images with Visual Studio and code + https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/ + + +Visual Studio 2019 +~~~~~~~~~~~~~~~~~~ + + +.. note:: + + As of `bug + 1483835 <https://bugzilla.mozilla.org/show_bug.cgi?id=1483835>`_, local + Windows builds `use clang-cl by + default <https://groups.google.com/d/topic/mozilla.dev.platform/MdbLAcvHC0Y/discussion>`_ + as compiler. Visual Studio is still necessary for build tools, headers, + and SDK. + +.. note:: + + Automation builds still use Visual Studio 2017, so there may be some + divergence until we upgrade. `Bug + 1581930 <https://bugzilla.mozilla.org/show_bug.cgi?id=1581930>`_ tracks + various issues building with 2019. Please file your issue there and + downgrade in the interim if you encounter build failures. + +`Download and install the Community +edition <https://visualstudio.microsoft.com/downloads/>`_ of Visual +Studio 2019. Professional and Enterprise are also supported if you have +either of those editions. + +.. note:: + + When installing, the following workloads must be checked: + + - "Desktop development with C++" (under the Windows group) + - "Game development with C++" (under the Mobile & Gaming group) + + In addition, go to the Individual Components tab and make sure the + following components are selected under the "SDKs, libraries, and + frameworks" group: + + - "Windows 10 SDK" (at least version **10.0.17134.0**) + - "C++ ATL for v142 build tools (x86 and x64)" (also select ARM64 + if you'll be building for ARM64) + +Make sure you run Visual Studio once after installing, so it finishes +any first-run tasks and associates the installation with your account. + +If you already have Visual Studio 2019 installed, you can get to the +installer via its menu "Tools" → "Get Tools and Features". + +Other Required Tools +~~~~~~~~~~~~~~~~~~~~ + +MozillaBuild +^^^^^^^^^^^^ + +Finally, download the `MozillaBuild +Package <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`__ +from Mozilla. Accept the default settings, in particular the default +installation directory: ``c:\mozilla-build\``. On some versions of +Windows an error dialog will give you the option to ‘reinstall with the +correct settings’ - you should agree and proceed. + +Once this is done, creating a shortcut to +``c:\mozilla-build\start-shell.bat`` on your desktop will make your life +easier. + +Getting the source +~~~~~~~~~~~~~~~~~~ + +This is the last big step. Double-clicking **start-shell.bat** in +``c:\mozilla-build`` (or the shortcut you’ve created above) will open a +terminal window. + +Start by creating a "mozilla-source" directory off of ``C:\`` and cd +into it like so + +.. code-block:: shell + + cd c:/ + + mkdir mozilla-source + + cd mozilla-source + +Next, you can get the Firefox source code with Mercurial. There is a +wiki page on how to :ref:`get the source using +Mercurial <Mercurial Overview>` +but, in summary, if your network connection is good enough to download +1+ GB without interuption and you want the main development repository, +then you can just use: + +.. code-block:: shell + + curl https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py -o bootstrap.py + + python3 bootstrap.py + +... and follow the prompts. This will use mercurial to checkout the +source code. If you prefer to work with git, use this command instead (you'll +have to have `Git for Windows <https://git-scm.com/download/win>`_ installed): + +.. code-block:: shell + + python3 bootstrap.py --vcs=git + +While you’re waiting for that process to finish, take a look at `our +Mercurial +documentation <http://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/index.html>`_. +It explains how we use version control at Mozilla to manage our code and +land changes to our source tree. + +Build Firefox! +~~~~~~~~~~~~~~ + +Now we tie it all together. In your terminal window, ``cd`` to your +source directory as before and type + +.. code-block:: shell + + cd mozilla-unified # ... or the name of the repo you chose earlier + + ./mach bootstrap + + ./mach build + +The ``./mach bootstrap`` step is a catch-all for any dependencies not +covered in this documentation. Note that, bootstrap works **only with +the Mercurial repo of the source**, not with source tar balls, nor the +github mirror. If you are working on Firefox or Firefox for Android +frontends or building Firefox without any changes, select :ref:`Artifact Builds +<Understanding Artifact Builds>` in +the first question in ``./mach bootstrap``. Artifact builds will +complete more quickly! Artifact builds are unsuitable for those working +on C++ or Rust code. + +You’re on your way. Don’t be discouraged if this takes a while; it takes +some time even on the fastest modern machines and as much as two hours +or more on older hardware. Firefox is pretty big, because the Web is +big. + + +You're ready +~~~~~~~~~~~~ + +When mach build completes, you'll have your own version of Firefox built +from the source code on your hard drive, ready to run. You can run it +with + +.. code-block:: shell + + ./mach run + +Now you have your own home-built version of Firefox. + +If you saw an error here, look further down in this document for the +"Troubleshooting" section - some antivirus software quarantine some of +our tests, so you need to create exceptions for the "mozilla-source" and +"mozilla-build" directories. Don't turn your antivirus off! Just add the +exceptions. + + +Details and troubleshooting +--------------------------- + +Hardware and software requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Firefox build process is both I/O and CPU-intensive, and can take a +long time to build even on modern hardware. The minimum and recommended +hardware requirements for Mozilla development are: + +- At least 4 GB of RAM. 8 GB or more is recommended, and more is always + better. +- 35 GB free disk space. This amount of disk space accommodates Visual + Studio 2019 Community Edition, the required SDKs, the MozillaBuild + package, the Mercurial source repository and enough free disk space + to compile. A solid-state hard disk is recommended as the Firefox + build process is I/O-intensive. +- A 64-bit version of Windows 7 (Service Pack 1) or later. You can + still build 32-bit Firefox on a 64-bit Windows installation. + +Overview +~~~~~~~~ + +The Mozilla build process requires many tools that are not pre-installed +on most Windows systems. In addition to Visual Studio, install +MozillaBuild - a software bundle that includes the required versions of +bash, GNU make, Mercurial, and much more. + +Firefox 61+ require Visual Studio 2017 Update 6 or newer to build. + +Firefox 48 to 60 build with Visual Studio 2015. Visual Studio 2017 also +works for building Firefox 58 or newer. + +Firefox 37 through to 47 build with Visual Studio 2013 (VC12) and +possibly Visual Studio 2015 (although Visual Studio 2015 may not build +every revision). + +Earlier versions of Firefox build with older versions of Visual Studio. + +Installing the build prerequisites +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Complete each of these steps otherwise, you may not be able to build +successfully. There are notes on these software requirements below. + +#. Make sure your system is up-to-date through Windows Update. +#. Install `Visual Studio Community + 2019 <https://www.visualstudio.com/downloads/>`_ (free). + Alternatively, you can also use a paid version of Visual Studio. Some + additional components may be required to build Firefox, as noted in + the "Visual Studio 2019" section above. Earlier versions of Visual + Studio are not supported; the Firefox codebase relies on C++ features + that are not supported in earlier releases. +#. Optionally, in addition to VS2019, you may want to install `Visual + C++ 2008 Express <http://go.microsoft.com/?linkid=7729279>`_ (free) + to compile some Python extensions used in the build system as Python + 2.7.x for Windows is built with that compiler by default. Note, if + you want to use "mach resource-usage", "mach doctor", "mach + android-emulator", or run talos tests locally, you should install it + for building psutil. +#. Download and install the + `MozillaBuild <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`__ + package, containing additional build tools. If you have Cygwin + installed, read the note in the tips section. If you see a Windows + error dialog giving you the option to re-install with the 'correct + settings', after the MozillaBuild's installer exits, choose the + option and after that all should be well. More information about + MozillaBuild and links to newer versions are available at + https://wiki.mozilla.org/MozillaBuild. + +Troubleshooting +~~~~~~~~~~~~~~~ + +In some circumstances, the following problems can arise: + +Antivirus performance +^^^^^^^^^^^^^^^^^^^^^ + +- Windows Defender and some scanning antivirus products are known to + have a major impact on build times. For example, if you have cloned + ``mozilla-unified`` successfully but ``./mach build`` fails, reporting + a missing file, you are likely experiencing this problem. Our + regression tests, for well-known security bugs, can include code + samples that some antivirus software will identify as a threat, and + will either quarantine or otherwise corrupt the files involved. To + resolve this you will need to add your source and object directories + (the ``mozilla-source`` and ``mozilla-build`` + directories) to the + `exclusion list in Windows Defender <https://support.microsoft.com/en-ca/help/4028485/windows-10-add-an-exclusion-to-windows-security>`_ + or your antivirus software. If you are missing files, revert your source + tree with the ``hg update -C`` command. Once this is done your next + ``./mach build`` should complete successfully. + +Installing Visual Studio in a different language than the system can cause issues +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- For example, having Visual Studio in French when the system is in + English causes the build to spew a lot of include errors and finishes + with a link error. + +.. note:: + + **Note:** **Mozilla 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. + +MozillaBuild package +~~~~~~~~~~~~~~~~~~~~ + +The MozillaBuild package contains other software prerequisites necessary +for building Mozilla, including the MSYS build environment, +`Mercurial <https://www.mercurial-scm.org/>`_, CVS, Python, YASM, NSIS, and UPX, +as well as optional but useful tools such as wget and emacs. + +`Download the current MozillaBuild +package. <https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe>`_ + +By default, the package installs to ``c:\mozilla-build`` and it is +recommended to use the default path. Don't use a path that contains +spaces. The installer does not modify the Windows registry. Note that +some binaries may require `Visual C++ Redistributable +package <https://www.microsoft.com/downloads/en/details.aspx?FamilyID=a5c84275-3b97-4ab7-a40d-3802b2af5fc2&displaylang=en>`_ to +run. + +.. note:: + + **MozillaBuild command prompt expectation setting:** Note that the + "UNIX-like" environment provided by MozillaBuild is only really useful + for building and committing to the Mozilla source. Most command line + tools you would expect in a modern Linux distribution are not present, + and those tools that are provided can be as much as a decade or so old + (especially those provided by MSYS). It's the old tools in particular + that can cause problems since they often don't behave as expected, are + buggy, or don't support command line arguments that have been taken for + granted for years. For example, copying a source tree using + ``cp -rf src1 src2`` does not work correctly because of an old version + of cp (it gives "cp: will not create hard link" errors for some files). + In short, MozillaBuild supports essential developer interactions with + the Mozilla code, but beyond that don't be surprised if it trips you up + in all sorts of exciting and unexpected ways. + +Opening a MozillaBuild command prompt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After the prerequisites are installed, launch +the ``start-shell.bat`` batch file using the Windows command +prompt in the directory to which you installed MozillaBuild +(``c:\mozilla-build`` by default). This will launch an MSYS/BASH command +prompt properly configured to build Firefox. All further commands should +be executed in this command prompt window. (Note that this is not the +same as what you get with the Windows CMD.EXE shell.) + +.. note:: + + Note: This is not the same as what you get with the Windows CMD.EXE + shell. + +Create a directory for the source +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Note:** You won't be able to build the Firefox source code if it's +under a directory with spaces in the path such as "Documents and +Settings". You can pick any other location, such as a new directory +c:/mozilla-source or c:/thunderbird-src. The build command prompt also +tolerates "c:\\" and "/c/", but the former gives confusion in the +Windows command prompt, and the latter is misinterpreted by some tools +(at least MOZ\_OBJDIR). The "C:/" syntax helps draw attention that the +**MozillaBuild** command prompt is assumed from here on out since it +provides configured environment and tools. + + +It's a sensible idea to create a new shallow directory, like +"c:/mozilla-source" dedicated solely to the +code: + +.. code-block:: shell + + cd c:/; mkdir mozilla-source; cd mozilla-source + +Keeping in mind the diagnostic hints below should you have issues. You +are now ready to get the Firefox source and build. + +Command prompt tips and caveats +------------------------------- + +- To paste into this window, you must right-click on the window's title + bar, move your cursor to the “Edit” menu, and click “Paste”. You can + also set “Quick Edit Mode” in the “Properties” menu and right-click + the window to paste your selection. +- If you have Cygwin installed, make sure that the MozillaBuild + directories come before any Cygwin directories in the search path + enhanced by ``start-shell-msvc2015.bat`` (use ``echo $PATH`` to see + your search path). +- In the MSYS / BASH shell started by ``start-shell-msvc2015.bat``, + UNIX-style forward slashes (/) are used as path separators instead of + the Windows-style backward slashes (\\). So if you want to change to + the directory ``c:\mydir``, in the MSYS shell to improve clarity, you + would use ``cd /c/mydir ``though both ``c:\mydir`` and ``c:/mydir`` + are supported. +- The MSYS root directory is located in ``/c/mozilla-build/msys`` if + you used the default installation directory. It's a good idea not to + build anything under this directory. Instead use something like + ``/c/mydir``. + +Common problems, hints, and restrictions +---------------------------------------- + +- :ref:`Debugging Firefox on Windows FAQ <Debugging On Windows>`: + Tips on how to debug Mozilla on Windows. +- Your installed MozillaBuild may be too old. The build system may + assume you have new features and bugfixes that are only present in + newer versions of MozillaBuild. Instructions for how to update + MozillaBuild `can be found + here <https://wiki.mozilla.org/MozillaBuild>`_. +- If the bootstrapping script ``bootstrap.py`` fails, you can also try running + ``hg clone https://hg.mozilla.org/mozilla-unified`` followed by + ``cd mozilla-unified; ./mach bootstrap`` yourself. +- The build may fail if your machine is configured with the wrong + architecture. If you want to build 64-bit Firefox, add the two lines + below to your mozconfig file: + +.. code-block:: shell + + ac_add_options --target=x86_64-pc-mingw32 + ac_add_options --host=x86_64-pc-mingw32 + +- The build may fail if your ``PATH`` environment variable contains + quotation marks("). Quotes are not properly translated when passed + down to MozillaBuild sub-shells and they are usually not needed so + they can be removed. +- The build may fail if you have a ``PYTHON`` environment variable set. + It displays an error almost immediately that says + "``The system cannot find the file specified``." Typing + "``unset PYTHON``" before running the Mozilla build tools in the same + command shell should fix this. Make sure that ``PYTHON`` is unset, + rather than set to an empty value. +- The build may fail if you have Cygwin installed. Make sure that the + MozillaBuild directories (``/c/mozilla-build`` and subdirectories) + come before any Cygwin directories in your PATH environment variable. + If this does not help, remove the Cygwin directories from PATH, or + try building on a clean PC with no Cygwin. +- Building with versions of NSIS other than the version that comes with + the latest supported version of MozillaBuild is not supported and + will likely fail. +- If you intend to distribute your build to others, set + ``WIN32_REDIST_DIR=$VCINSTALLDIR\redist\x86\Microsoft.VC141.CRT`` in + your mozconfig to get the Microsoft CRT DLLs packaged along with the + application. Note the exact .CRT file may depend on your Visual + Studio version. +- The Microsoft Antimalware service can interfere with compilation, + often manifesting as an error related to ``conftest.exe`` during + build. To remedy this, add at your object directory at least to the + exclusion settings. +- Errors like "second C linkage of overloaded function + '\_interlockedbittestandset' not allowed", are encountered when + intrin.h and windows.h are included together. Use a *#define* to + redefine one instance of the function's name. +- Parallel builds (``-jN``) do not work with GNU makes on Windows. You + should use the ``mozmake`` command included with current versions of + MozillaBuild. Building with the ``mach`` command will always use the + best available make command. +- If you encounter a build failure like "ERROR: Cannot find + makecab.exe", try applying the patch from `bug + 1383578 <https://bugzilla.mozilla.org/show_bug.cgi?id=1383578>`_, + i.e. change: ``SET PATH="%PATH%;!LLVMDIR!\bin"`` to + ``SET "PATH=%PATH%;!LLVMDIR!\bin"``. +- If you encounter a build failure with + ``LINK: fatal error LNK1181: cannot open input file ..\..\..\..\..\security\nss3.lib``, + it may be related to your clone of ``mozilla-unified`` being located + in the Users folder (possibly encrypted). Try moving it outside of + the Users folder. The docs recommend + ``C:\mozilla-source\mozilla-unified`` which should work. +- If you encounter a build failure with + ``ERROR: GetShortPathName returned a long path name.``.You need + create a 8dot3name short name for the path which has space.For + example : fsutil file setshortname "C:\\Program Files (x86)" + PROGRA~2. If you got "access denied", try to restart your computer + to safe mode and try again. + |