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