diff options
Diffstat (limited to 'docs/setup/macos_build.rst')
| -rw-r--r-- | docs/setup/macos_build.rst | 477 |
1 files changed, 477 insertions, 0 deletions
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. |