build/docs/defining-binaries.rst

   1 .. _defining_binaries:
   2
   3 ======================================
   4 Defining Binaries for the Build System
   5 ======================================
   6
   7 One part of what the build system does is compile C/C++ and link the resulting
   8 objects to produce executables and/or libraries. This document describes the
   9 basics of defining what is going to be built and how. All the following
  10 describes constructs to use in moz.build files.
  11
  12
  13 Source files
  14 ============
  15
  16 Source files to be used in a given directory are registered in the ``SOURCES``
  17 and ``UNIFIED_SOURCES`` variables. ``UNIFIED_SOURCES`` have a special behavior
  18 in that they are aggregated by batches of 16, requiring, for example, that there
  19 are no conflicting variables in those source files.
  20
  21 ``SOURCES`` and ``UNIFIED_SOURCES`` are lists which must be appended to, and
  22 each append requires the given list to be alphanumerically ordered.
  23
  24 .. code-block:: python
  25
  26    UNIFIED_SOURCES += [
  27        'FirstSource.cpp',
  28        'SecondSource.cpp',
  29        'ThirdSource.cpp',
  30    ]
  31
  32    SOURCES += [
  33        'OtherSource.cpp',
  34    ]
  35
  36 ``SOURCES`` and ``UNIFIED_SOURCES`` can contain a mix of different file types,
  37 for C, C++, and Objective C.
  38
  39
  40 Static Libraries
  41 ================
  42
  43 To build a static library, other than defining the source files (see above), one
  44 just needs to define a library name with the ``Library`` template.
  45
  46 .. code-block:: python
  47
  48    Library('foo')
  49
  50 The library file name will be ``libfoo.a`` on UNIX systems and ``foo.lib`` on
  51 Windows.
  52
  53 If the static library needs to aggregate other static libraries, a list of
  54 ``Library`` names can be added to the ``USE_LIBS`` variable. Like ``SOURCES``, it
  55 requires the appended list to be alphanumerically ordered.
  56
  57 .. code-block:: python
  58
  59    USE_LIBS += ['bar', 'baz']
  60
  61 If there are multiple directories containing the same ``Library`` name, it is
  62 possible to disambiguate by prefixing with the path to the wanted one (relative
  63 or absolute):
  64
  65 .. code-block:: python
  66
  67    USE_LIBS += [
  68        '/path/from/topsrcdir/to/bar',
  69        '../relative/baz',
  70    ]
  71
  72 Note that the leaf name in those paths is the ``Library`` name, not an actual
  73 file name.
  74
  75 Note that currently, the build system may not create an actual library for
  76 static libraries. It is an implementation detail that shouldn't need to be
  77 worried about.
  78
  79 As a special rule, ``USE_LIBS`` is allowed to contain references to shared
  80 libraries. In such cases, programs and shared libraries linking this static
  81 library will inherit those shared library dependencies.
  82
  83
  84 Intermediate (Static) Libraries
  85 ===============================
  86
  87 In many cases in the tree, static libraries are built with the only purpose
  88 of being linked into another, bigger one (like libxul). Instead of adding all
  89 required libraries to ``USE_LIBS`` for the bigger one, it is possible to tell
  90 the build system that the library built in the current directory is meant to
  91 be linked to that bigger library, with the ``FINAL_LIBRARY`` variable.
  92
  93 .. code-block:: python
  94
  95    FINAL_LIBRARY = 'xul'
  96
  97 The ``FINAL_LIBRARY`` value must match a unique ``Library`` name somewhere
  98 in the tree.
  99
 100 As a special rule, those intermediate libraries don't need a ``Library`` name
 101 for themselves.
 102
 103
 104 Shared Libraries
 105 ================
 106
 107 Sometimes, we want shared libraries, a.k.a. dynamic libraries. Such libraries
 108 are defined similarly to static libraries, using the ``SharedLibrary`` template
 109 instead of ``Library``.
 110
 111 .. code-block:: python
 112
 113    SharedLibrary('foo')
 114
 115 When this template is used, no static library is built. See further below to
 116 build both types of libraries.
 117
 118 With a ``SharedLibrary`` name of ``foo``, the library file name will be
 119 ``libfoo.dylib`` on OSX, ``libfoo.so`` on ELF systems (Linux, etc.), and
 120 ``foo.dll`` on Windows. On Windows, there is also an import library named
 121 ``foo.lib``, used on the linker command line. ``libfoo.dylib`` and
 122 ``libfoo.so`` are considered the import library name for, resp. OSX and ELF
 123 systems.
 124
 125 On OSX, one may want to create a special kind of dynamic library: frameworks.
 126 This is done with the ``Framework`` template.
 127
 128 .. code-block:: python
 129
 130    Framework('foo')
 131
 132 With a ``Framework`` name of ``foo``, the framework file name will be ``foo``.
 133 This template however affects the behavior on all platforms, so it needs to
 134 be set only on OSX.
 135
 136
 137 Executables
 138 ===========
 139
 140 Executables, a.k.a. programs, are, in the simplest form, defined with the
 141 ``Program`` template.
 142
 143 .. code-block:: python
 144
 145    Program('foobar')
 146
 147 On UNIX systems, the executable file name will be ``foobar``, while on Windows,
 148 it will be ``foobar.exe``.
 149
 150 Like static and shared libraries, the build system can be instructed to link
 151 libraries to the executable with ``USE_LIBS``, listing various ``Library``
 152 names.
 153
 154 In some cases, we want to create an executable per source file in the current
 155 directory, in which case we can use the ``SimplePrograms`` template
 156
 157 .. code-block:: python
 158
 159    SimplePrograms([
 160        'FirstProgram',
 161        'SecondProgram',
 162    ])
 163
 164 Contrary to ``Program``, which requires corresponding ``SOURCES``, when using
 165 ``SimplePrograms``, the corresponding ``SOURCES`` are implied. If the
 166 corresponding ``sources`` have an extension different from ``.cpp``, it is
 167 possible to specify the proper extension:
 168
 169 .. code-block:: python
 170
 171    SimplePrograms([
 172        'ThirdProgram',
 173        'FourthProgram',
 174    ], ext='.c')
 175
 176 Please note this construct was added for compatibility with what already lives
 177 in the mozilla tree ; it is recommended not to add new simple programs with
 178 sources with a different extension than ``.cpp``.
 179
 180 Similar to ``SimplePrograms``, is the ``CppUnitTests`` template, which defines,
 181 with the same rules, C++ unit tests programs. Like ``SimplePrograms``, it takes
 182 an ``ext`` argument to specify the extension for the corresponding ``SOURCES``,
 183 if it's different from ``.cpp``.
 184
 185
 186 Linking with system libraries
 187 =============================
 188
 189 Programs and libraries usually need to link with system libraries, such as a
 190 widget toolkit, etc. Those required dependencies can be given with the
 191 ``OS_LIBS`` variable.
 192
 193 .. code-block:: python
 194
 195    OS_LIBS += [
 196        'foo',
 197        'bar',
 198    ]
 199
 200 This expands to ``foo.lib bar.lib`` when building with MSVC, and
 201 ``-lfoo -lbar`` otherwise.
 202
 203 For convenience with ``pkg-config``, ``OS_LIBS`` can also take linker flags
 204 such as ``-L/some/path`` and ``-llib``, such that it is possible to directly
 205 assign ``LIBS`` variables from ``CONFIG``, such as:
 206
 207 .. code-block:: python
 208
 209    OS_LIBS += CONFIG['MOZ_PANGO_LIBS']
 210
 211 (assuming ``CONFIG['MOZ_PANGO_LIBS']`` is a list, not a string)
 212
 213 Like ``USE_LIBS``, this variable applies to static and shared libraries, as
 214 well as programs.
 215
 216
 217 Libraries from third party build system
 218 =======================================
 219
 220 Some libraries in the tree are not built by the moz.build-governed build
 221 system, and there is no ``Library`` corresponding to them.
 222
 223 However, ``USE_LIBS`` allows to reference such libraries by giving a full
 224 path (like when disambiguating identical ``Library`` names). The same naming
 225 rules apply as other uses of ``USE_LIBS``, so only the library name without
 226 prefix and suffix shall be given.
 227
 228 .. code-block:: python
 229
 230    USE_LIBS += [
 231        '/path/from/topsrcdir/to/third-party/bar',
 232        '../relative/third-party/baz',
 233    ]
 234
 235 Note that ``/path/from/topsrcdir/to/third-party`` and
 236 ``../relative/third-party/baz`` must lead under a subconfigured directory (a
 237 directory with an AC_OUTPUT_SUBDIRS in configure.in), or ``security/nss``.
 238
 239
 240 Building both static and shared libraries
 241 =========================================
 242
 243 When both types of libraries are required, one needs to set both
 244 ``FORCE_SHARED_LIB`` and ``FORCE_STATIC_LIB`` boolean variables.
 245
 246 .. code-block:: python
 247
 248    FORCE_SHARED_LIB = True
 249    FORCE_STATIC_LIB = True
 250
 251 But because static libraries and Windows import libraries have the same file
 252 names, either the static or the shared library name needs to be different
 253 than the name given to the ``Library`` template.
 254
 255 The ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME`` variables can be used
 256 to change either the static or the shared library name.
 257
 258 .. code-block:: python
 259
 260   Library('foo')
 261   STATIC_LIBRARY_NAME = 'foo_s'
 262
 263 With the above, on Windows, ``foo_s.lib`` will be the static library,
 264 ``foo.dll`` the shared library, and ``foo.lib`` the import library.
 265
 266 In some cases, for convenience, it is possible to set both
 267 ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME``. For example:
 268
 269 .. code-block:: python
 270
 271   Library('mylib')
 272   STATIC_LIBRARY_NAME = 'mylib_s'
 273   SHARED_LIBRARY_NAME = CONFIG['SHARED_NAME']
 274
 275 This allows to use ``mylib`` in the ``USE_LIBS`` of another library or
 276 executable.
 277
 278 When referring to a ``Library`` name building both types of libraries in
 279 ``USE_LIBS``, the shared library is chosen to be linked. But sometimes,
 280 it is wanted to link the static version, in which case the ``Library`` name
 281 needs to be prefixed with ``static:`` in ``USE_LIBS``
 282
 283 ::
 284
 285    a/moz.build:
 286       Library('mylib')
 287       FORCE_SHARED_LIB = True
 288       FORCE_STATIC_LIB = True
 289       STATIC_LIBRARY_NAME = 'mylib_s'
 290    b/moz.build:
 291       Program('myprog')
 292       USE_LIBS += [
 293           'static:mylib',
 294       ]
 295
 296
 297 Miscellaneous
 298 =============
 299
 300 The ``SONAME`` variable declares a "shared object name" for the library. It
 301 defaults to the ``Library`` name or the ``SHARED_LIBRARY_NAME`` if set. When
 302 linking to a library with a ``SONAME``, the resulting library or program will
 303 have a dependency on the library with the name corresponding to the ``SONAME``
 304 instead of the ``Library`` name. This only impacts ELF systems.
 305
 306 ::
 307
 308    a/moz.build:
 309       Library('mylib')
 310    b/moz.build:
 311       Library('otherlib')
 312       SONAME = 'foo'
 313    c/moz.build:
 314       Program('myprog')
 315       USE_LIBS += [
 316           'mylib',
 317           'otherlib',
 318       ]
 319
 320 On e.g. Linux, the above ``myprog`` will have DT_NEEDED markers for
 321 ``libmylib.so`` and ``libfoo.so`` instead of ``libmylib.so`` and
 322 ``libotherlib.so`` if there weren't a ``SONAME``. This means the runtime
 323 requirement for ``myprog`` is ``libfoo.so`` instead of ``libotherlib.so``.
 324
 325
 326 Gecko-related binaries
 327 ======================
 328
 329 Some programs or libraries are totally independent of Gecko, and can use the
 330 above mentioned templates. Others are Gecko-related in some way, and may
 331 need XPCOM linkage, mozglue. These things are tedious. A set of additional
 332 templates exists to ease defining such programs and libraries. They are
 333 essentially the same as the above mentioned templates, prefixed with "Gecko":
 334
 335   - ``GeckoProgram``
 336   - ``GeckoSimplePrograms``
 337   - ``GeckoCppUnitTests``
 338   - ``GeckoSharedLibrary``
 339   - ``GeckoFramework``
 340
 341 All the Gecko-prefixed templates take the same arguments as their
 342 non-Gecko-prefixed counterparts, and can take a few more arguments
 343 for non-standard cases. See the definition of ``GeckoBinary`` in
 344 build/gecko_templates.mozbuild for more details, but most usecases
 345 should not require these additional arguments.