defining-binaries.rst (10928B)
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.