build/docs/build-overview.rst

   1 .. _build_overview:
   2
   3 =====================
   4 Build System Overview
   5 =====================
   6
   7 This document provides an overview on how the build system works. It is
   8 targeted at people wanting to learn about internals of the build system.
   9 It is not meant for persons who casually interact with the build system.
  10 That being said, knowledge empowers, so consider reading on.
  11
  12 The build system is composed of many different components working in
  13 harmony to build the source tree. We begin with a graphic overview.
  14
  15 .. graphviz::
  16
  17    digraph build_components {
  18       rankdir="LR";
  19       "configure" -> "config.status" -> "build backend" -> "build output"
  20    }
  21
  22 Phase 1: Configuration
  23 ======================
  24
  25 Phase 1 centers around the ``configure`` script, which is a bash shell script.
  26 The file is generated from a file called ``configure.in`` which is written in M4
  27 and processed using Autoconf 2.13 to create the final configure script.
  28 You don't have to worry about how you obtain a ``configure`` file: the build
  29 system does this for you.
  30
  31 The primary job of ``configure`` is to determine characteristics of the system
  32 and compiler, apply options passed into it, and validate everything looks OK to
  33 build. The primary output of the ``configure`` script is an executable file
  34 in the object directory called ``config.status``. ``configure`` also produces
  35 some additional files (like ``autoconf.mk``). However, the most important file
  36 in terms of architecture is ``config.status``.
  37
  38 The existence of a ``config.status`` file may be familiar to those who have worked
  39 with Autoconf before. However, Mozilla's ``config.status`` is different from almost
  40 any other ``config.status`` you've ever seen: it's written in Python! Instead of
  41 having our ``configure`` script produce a shell script, we have it generating
  42 Python.
  43
  44 Now is as good a time as any to mention that Python is prevalent in our build
  45 system. If we need to write code for the build system, we do it in Python.
  46 That's just how we roll. For more, see :ref:`python`.
  47
  48 ``config.status`` contains 2 parts: data structures representing the output of
  49 ``configure`` and a command-line interface for preparing/configuring/generating
  50 an appropriate build backend. (A build backend is merely a tool used to build
  51 the tree - like GNU Make or Tup). These data structures essentially describe
  52 the current state of the system and what the existing build configuration looks
  53 like. For example, it defines which compiler to use, how to invoke it, which
  54 application features are enabled, etc. You are encouraged to open up
  55 ``config.status`` to have a look for yourself!
  56
  57 Once we have emitted a ``config.status`` file, we pass into the realm of
  58 phase 2.
  59
  60 Phase 2: Build Backend Preparation and the Build Definition
  61 ===========================================================
  62
  63 Once ``configure`` has determined what the current build configuration is,
  64 we need to apply this to the source tree so we can actually build.
  65
  66 What essentially happens is the automatically-produced ``config.status`` Python
  67 script is executed as soon as ``configure`` has generated it. ``config.status``
  68 is charged with the task of tell a tool how to build the tree. To do this,
  69 ``config.status`` must first scan the build system definition.
  70
  71 The build system definition consists of various ``moz.build`` files in the tree.
  72 There is roughly one ``moz.build`` file per directory or per set of related directories.
  73 Each ``moz.build`` files defines how its part of the build config works. For
  74 example it says *I want these C++ files compiled* or *look for additional
  75 information in these directories.* config.status starts with the ``moz.build``
  76 file from the root directory and then descends into referenced ``moz.build``
  77 files by following ``DIRS`` variables or similar.
  78
  79 As the ``moz.build`` files are read, data structures describing the overall
  80 build system definition are emitted. These data structures are then fed into a
  81 build backend, which then performs actions, such as writing out files to
  82 be read by a build tool. e.g. a ``make`` backend will write a
  83 ``Makefile``.
  84
  85 When ``config.status`` runs, you'll see the following output::
  86
  87    Reticulating splines...
  88    Finished reading 1096 moz.build files into 1276 descriptors in 2.40s
  89    Backend executed in 2.39s
  90    2188 total backend files. 0 created; 1 updated; 2187 unchanged
  91    Total wall time: 5.03s; CPU time: 3.79s; Efficiency: 75%
  92
  93 What this is saying is that a total of *1096* ``moz.build`` files were read.
  94 Altogether, *1276* data structures describing the build configuration were
  95 derived from them.  It took *2.40s* wall time to just read these files and
  96 produce the data structures.  The *1276* data structures were fed into the
  97 build backend which then determined it had to manage *2188* files derived
  98 from those data structures. Most of them already existed and didn't need
  99 changed. However, *1* was updated as a result of the new configuration.
 100 The whole process took *5.03s*. Although, only *3.79s* was in
 101 CPU time. That likely means we spent roughly *25%* of the time waiting on
 102 I/O.
 103
 104 For more on how ``moz.build`` files work, see :ref:`mozbuild-files`.
 105
 106 Phase 3: Invokation of the Build Backend
 107 ========================================
 108
 109 When most people think of the build system, they think of phase 3. This is
 110 where we take all the code in the tree and produce Firefox or whatever
 111 application you are creating. Phase 3 effectively takes whatever was
 112 generated by phase 2 and runs it. Since the dawn of Mozilla, this has been
 113 make consuming Makefiles. However, with the transition to moz.build files,
 114 you may soon see non-Make build backends, such as Tup or Visual Studio.
 115
 116 When building the tree, most of the time is spent in phase 3. This is when
 117 header files are installed, C++ files are compiled, files are preprocessed, etc.