docs/contributing/directory_structure.rst

   1 Firefox Source Code Directory Structure
   2 =======================================
   3
   4 This article provides an overview of what the various directories contain.
   5
   6 To simply take a look at the Firefox source code, you do not need to
   7 download it. You can look at the source directly with your web browser
   8 using Searchfox (start at https://searchfox.org/mozilla-central/source for
   9 the complete firefox source code of branch HEAD).
  10
  11 In order to modify the source, you have to acquire it either by
  12 downloading a :ref:`snapshot <Mercurial Overview>` of the sources or
  13 by checking out the current sources from
  14 :ref:`the repository <Firefox Contributors' Quick Reference>`.
  15
  16 This document describes the directory structure -- i.e., directories that
  17 are used by at least some of the
  18 Mozilla project's client products. There are other directories in the
  19 other Mozilla repository, such as those for Web tools and those for the
  20 Classic codebase.
  21
  22 See the `more detailed overview of the pieces of Gecko <https://wiki.mozilla.org/Gecko:Overview>`__.
  23
  24 .cargo
  25 ------
  26
  27 Configuration files for the `Cargo package
  28 manager <https://crates.io/>`__.
  29
  30 .vscode
  31 -------
  32
  33 Configuration files used by the `Visual Studio Code
  34 IDE <https://code.visualstudio.com/>`__ when working in the
  35 mozilla-central tree.
  36
  37 accessible
  38 ----------
  39
  40 Files for accessibility (i.e., MSAA (Microsoft Active Accessibility),
  41 ATK (Accessibility Toolkit, used by GTK) support files). See
  42 `Accessibility <https://developer.mozilla.org/docs/Web/Accessibility>`__.
  43
  44
  45 browser
  46 -------
  47
  48 Contains the front end code (in XUL, Javascript, XBL, and C++) for the
  49 Firefox desktop browser. Many of these files started off as a copy of files in
  50 `xpfe <#xpfe>`__.
  51
  52 browser/extensions
  53 ------------------
  54
  55 Contains `PDF.js <https://mozilla.github.io/pdf.js/>`__ and
  56 `WebCompat <https://github.com/mozilla/webcompat-addon>`__ built-in extensions.
  57
  58 browser/themes
  59 --------------
  60
  61 Contains images and CSS files to skin the browser for each OS (Linux,
  62 Mac and Windows)
  63
  64 build
  65 -----
  66
  67 Miscellaneous files used by the build process. See also `config <#config>`__.
  68
  69 caps
  70 ----
  71
  72 Capability-based web page security management. It contains C++ interfaces
  73 and code for determining the capabilities of content based on the
  74 security settings or certificates (e.g., VeriSign). See `Component
  75 Security <https://www.mozilla.org/projects/security/components/>`__ .
  76
  77 chrome
  78 ------
  79
  80 :ref:`Chrome registry <Chrome Registration>` used with `toolkit <#toolkit>`__/.
  81 These files were originally copies of files in `rdf/chrome/`.
  82
  83 config
  84 ------
  85
  86 More files used by the build process, common includes for the makefiles,
  87 etc.
  88
  89
  90 devtools
  91 --------
  92
  93 The Firefox Developer Tools server and client components. See :ref:`contributor <devtools-contributor-doc>` and :ref:`user <devtools-user-doc>` documentation.
  94
  95
  96 docs
  97 ----
  98
  99 Contains the documentation configuration (`Sphinx <http://www.sphinx-doc.org/>`__ based), the index page
 100 and the contribution pages.
 101
 102
 103 docshell
 104 --------
 105
 106 Implementation of the docshell, the main object managing things related
 107 to a document window. Each frame has its own docshell. It contains
 108 methods for loading URIs, managing URI content listeners, etc. It is the
 109 outermost layer of the embedding API used to embed a Gecko browser into
 110 an application.
 111
 112 dom
 113 ---
 114
 115 -  :ref:`IDL definitions <XPIDL>` of the interfaces defined by
 116    the DOM specifications and Mozilla extensions to those interfaces
 117    (implementations of these interfaces are primarily, but not
 118    completely, in `content <#content>`__).
 119 -  The parts of the connection between JavaScript and the
 120    implementations of DOM objects that are specific both to JavaScript
 121    and to the DOM.
 122 -  Implementations of a few of the core "DOM Level 0" objects, such as
 123    `window <https://developer.mozilla.org/docs/Web/API/Window>`__ , `window.navigator <https://developer.mozilla.org/docs/Web/API/Window/navigator>`__, `window.location <https://developer.mozilla.org/docs/Web/API/Window/location>`__, etc.
 124
 125 editor
 126 ------
 127
 128 The editor directory contains XUL/Javascript for the embeddable editor
 129 component, which is used for the HTML Editor("Composer"), for plain and
 130 HTML mail composition, and for text fields and text areas throughout the
 131 product. The editor is designed like a
 132 "browser window with editing features": it adds some special classes for
 133 editing text and managing transaction undo/redo, but reuses browser code
 134 for nearly everything else.
 135
 136 extensions
 137 ----------
 138
 139 Contains several extensions to mozilla, which can be enabled at
 140 compile-time using the ``--enable-extensions`` configure argument.
 141
 142 Note that some of these are now built specially and not using the
 143 ``--enable-extensions`` option. For example, disabling xmlextras is done
 144 using ``--disable-xmlextras``.
 145
 146
 147 extensions/auth
 148 ---------------
 149
 150 Implementation of the negotiate auth method for HTTP and other
 151 protocols. Has code for SSPI, GSSAPI, etc. See `Integrated
 152 Authentication <https://www.mozilla.org/projects/netlib/integrated-auth.html>`__.
 153
 154
 155 extensions/pref
 156 ---------------
 157
 158 Preference-related extensions.
 159
 160 extensions/spellcheck
 161 ---------------------
 162
 163 Spellchecker for mailnews and composer.
 164
 165 extensions/universalchardet
 166 ---------------------------
 167
 168 Detects the character encoding of text.
 169
 170 gfx
 171 ---
 172
 173 Contains interfaces that abstract the capabilities of platform specific
 174 graphics toolkits, along with implementations on various platforms.
 175 These interfaces provide methods for things like drawing images, text,
 176 and basic shapes. It also contains basic data structures such as points
 177 and rectangles used here and in other parts of Mozilla.
 178
 179 gradle
 180 ------
 181
 182 Containing files related to a Java build system.
 183
 184 hal
 185 ---
 186
 187 Contains platform specified functions (e.g. obtaining battery status,
 188 sensor information, memory information, Android
 189 alarms/vibrate/notifications/orientation, etc)
 190
 191 image
 192 -----
 193
 194 Image rendering library. Contains decoders for the image formats Firefox
 195 supports.
 196
 197 intl
 198 ----
 199
 200 Internationalization and localization support. See
 201 `L10n:NewProjects <https://wiki.mozilla.org/L10n:NewProjects>`__.
 202
 203 intl/locale
 204 -----------
 205
 206 Code related to determination of locale information from the operating
 207 environment.
 208
 209 intl/lwbrk
 210 ----------
 211
 212 Code related to line breaking and word breaking.
 213
 214 intl/strres
 215 -----------
 216
 217 Code related to string resources used for localization.
 218
 219 intl/uconv
 220 ----------
 221
 222 Code that converts (both ways: encoders and decoders) between UTF-16 and
 223 many other character encodings.
 224
 225 intl/unicharutil
 226 ----------------
 227
 228 Code related to implementation of various algorithms for Unicode text,
 229 such as case conversion.
 230
 231 ipc
 232 ---
 233
 234 Container for implementations of IPC (Inter-Process Communication).
 235
 236 js/src
 237 ------
 238
 239 The JavaScript engine, also known as
 240 :ref:`SpiderMonkey <SpiderMonkey>`.
 241 See also `JavaScript <https://developer.mozilla.org/docs/JavaScript>`__.
 242
 243 js/xpconnect
 244 ------------
 245
 246 Support code for calling JavaScript code from C++ code and C++ code from
 247 JavaScript code, using XPCOM interfaces. See
 248 `XPConnect <https://developer.mozilla.org/docs/XPConnect>`__.
 249
 250 layout
 251 ------
 252
 253 Code that implements a tree of rendering objects that describe the types
 254 and locations of the objects that are displayed on the screen (such as
 255 CSS boxes, tables, form controls, XUL boxes, etc.), and code that
 256 manages operations over that rendering tree (such as creating and
 257 destroying it, doing layout, painting, and event handling). See
 258 `documentation <https://www.mozilla.org/newlayout/doc/>`__ and `other
 259 information <https://www.mozilla.org/newlayout/>`__.
 260
 261 layout/base
 262 -----------
 263
 264 Code that deals with the rendering tree.
 265
 266 layout/forms
 267 ------------
 268
 269 Rendering tree objects for HTML form controls.
 270
 271 layout/generic
 272 --------------
 273
 274 The basic rendering object interface and the rendering tree objects for
 275 basic CSS boxes.
 276
 277 layout/mathml
 278 -------------
 279
 280 Rendering tree objects for `MathML <https://developer.mozilla.org/docs/Web/MathML>`__.
 281
 282 layout/svg
 283 ----------
 284
 285 Rendering tree objects for `SVG <https://developer.mozilla.org/docs/Web/SVG>`__.
 286
 287 layout/tables
 288 -------------
 289
 290 Rendering tree objects for CSS/HTML tables.
 291
 292 layout/xul
 293 ----------
 294
 295 Additional rendering object interfaces for `XUL <https://developer.mozilla.org/docs/XUL>`__ and
 296 the rendering tree objects for XUL boxes.
 297
 298 media
 299 -----
 300
 301 Contains sources of used media libraries for example *libpng*.
 302
 303 memory
 304 ------
 305
 306 Cross-platform wrappers for *memallocs* functions etc.
 307
 308 mfbt
 309 ----
 310
 311 Implementations of classes like *WeakPtr*. Multi-platform *assertions*
 312 etc.
 313
 314 mobile
 315 ------
 316
 317 mobile/android
 318 --------------
 319
 320 Firefox for Android and Geckoview
 321
 322 modules
 323 -------
 324
 325 Compression/Archiving, math library, font (and font compression),
 326 Preferences Library
 327
 328 modules/libjar
 329 --------------
 330
 331 Code to read zip files, used for reading the .jar files that contain the
 332 files for the mozilla frontend.
 333
 334 modules/libpref
 335 ---------------
 336
 337 Library for reading and writing preferences.
 338
 339 modules/zlib
 340 ------------
 341
 342 Source code of zlib, used at least in the networking library for
 343 compressed transfers.
 344
 345 mozglue
 346 -------
 347
 348 Glue library containing various low-level functionality, including a
 349 dynamic linker for Android, a DLL block list for Windows, etc.
 350
 351 netwerk
 352 -------
 353
 354 :ref:`Networking library <Networking>`, also known as Necko.
 355 Responsible for doing actual transfers from and to servers, as well as
 356 for URI handling and related stuff.
 357
 358 netwerk/cookie
 359 --------------
 360
 361 Permissions backend for cookies, images, etc., as well as the user
 362 interface to these permissions and other cookie features.
 363
 364 nsprpub
 365 -------
 366
 367 Netscape Portable Runtime. Used as an abstraction layer to things like
 368 threads, file I/O, and socket I/O. See :ref:`NSPR`.
 369
 370 nsprpub/lib
 371 -----------
 372
 373 Mostly unused; might be used on Mac?
 374
 375 other-licenses
 376 --------------
 377
 378 Contains libraries that are not covered by the MPL but are used in some
 379 Firefox code.
 380
 381 parser
 382 ------
 383
 384 Group of structures and functions needed to parse files based on
 385 XML/HTML.
 386
 387 parser/expat
 388 ------------
 389
 390 Copy of the expat source code, which is the XML parser used by mozilla.
 391
 392 parser/html
 393 -----------
 394
 395 The HTML parser (for everything except about:blank).
 396
 397 parser/htmlparser
 398 -----------------
 399
 400 The legacy HTML parser that's still used for about:blank. Parts of it
 401 are also used for managing the conversion of the network bytestream into
 402 Unicode in the XML parsing case.
 403
 404 parser/xml
 405 ----------
 406
 407 The code for integrating expat (from parser/expat) into Gecko.
 408
 409 python
 410 ------
 411
 412 Cross module python code.
 413
 414 python/mach
 415 -----------
 416
 417 The code for the :ref:`Mach` building tool.
 418
 419 security
 420 --------
 421
 422 Contains NSS and PSM, to support cryptographic functions in mozilla
 423 (like S/MIME, SSL, etc). See :ref:`Network Security Services (NSS)`
 424 and
 425 `Personal Security Manager
 426 (PSM) <https://www.mozilla.org/projects/security/pki/psm/>`__.
 427
 428 services
 429 --------
 430
 431 Firefox accounts and sync (history, preferences, tabs, bookmarks,
 432 telemetry, startup time, which addons are installed, etc). See
 433 `here <https://docs.services.mozilla.com/>`__.
 434
 435 servo
 436 -----
 437
 438 `Servo <https://servo.org/>`__, the parallel browser engine project.
 439
 440 startupcache
 441 ------------
 442
 443 XXX this needs a description.
 444
 445 storage
 446 -------
 447
 448 `Storage <https://developer.mozilla.org/docs/Mozilla/Tech/XPCOM/Storage>`__: XPCOM wrapper for sqlite. Wants to
 449 unify storage of all profile-related data. Supersedes mork. See also
 450 `Unified Storage <https://wiki.mozilla.org/Mozilla2:Unified_Storage>`__.
 451
 452 taskcluster
 453 -----------
 454
 455 Scripts and code to automatically build and test Mozilla trees for the
 456 continuous integration and release process.
 457
 458 testing
 459 -------
 460
 461 Common testing tools for mozilla codebase projects, test suite
 462 definitions for automated test runs, tests that don't fit anywhere else,
 463 and other fun stuff.
 464
 465 third_party
 466 -----------
 467
 468 Vendored dependencies maintained outside of Mozilla.
 469
 470 toolkit
 471 -------
 472
 473 The "new toolkit" used by Thunderbird, Firefox, etc. This contains
 474 numerous front-end components shared between applications as well as
 475 most of the XBL-implemented parts of the XUL language (most of which was
 476 originally forked from versions in `xpfe/`).
 477
 478 toolkit/mozapps/extensions/test/xpinstall
 479 -----------------------------------------
 480
 481 The installer, which contains code for installing Mozilla and for
 482 installing XPIs/extensions. This directory also contains code needed to
 483 build installer packages. See `XPInstall <https://developer.mozilla.org/docs/XPInstall>`__ and
 484 the `XPInstall project
 485 page <https://www.mozilla.org/projects/xpinstall/>`__.
 486
 487 tools
 488 -----
 489
 490 Some tools which are optionally built during the mozilla build process.
 491
 492 tools/lint
 493 ----------
 494
 495 The linter declarations and configurations.
 496 See `linting documentation </code-quality/lint/>`_
 497
 498 uriloader
 499 ---------
 500
 501 uriloader/base
 502 --------------
 503
 504 Content dispatch in Mozilla. Used to load uris and find an appropriate
 505 content listener for the data. Also manages web progress notifications.
 506 See `Document Loading: From Load Start to Finding a
 507 Handler <https://www.mozilla.org/docs/docshell/uri-load-start.html>`__
 508 and `The Life Of An HTML HTTP
 509 Request <https://www.mozilla.org/docs/url_load.html>`__.
 510
 511
 512 uriloader/exthandler
 513 --------------------
 514
 515 Used to handle content that Mozilla can't handle itself. Responsible for
 516 showing the helper app dialog, and generally for finding information
 517 about helper applications.
 518
 519 uriloader/prefetch
 520 ------------------
 521
 522 Service to prefetch documents in order to have them cached for faster
 523 loading.
 524
 525 view
 526 ----
 527
 528 View manager. Contains cross-platform code used for painting, scrolling,
 529 event handling, z-ordering, and opacity. Soon to become obsolete,
 530 gradually.
 531
 532 widget
 533 ------
 534
 535 A cross-platform API, with implementations on each platform, for dealing
 536 with operating system/environment widgets, i.e., code related to
 537 creation and handling of windows, popups, and other native widgets and
 538 to converting the system's messages related to painting and events into
 539 the messages used by other parts of Mozilla (e.g., `view/` and
 540 `content/`, the latter of which converts many of the
 541 messages to yet another API, the DOM event API).
 542
 543 xpcom
 544 -----
 545
 546 `Cross-Platform Component Object Model </en-US/docs/XPCOM>`__. Also
 547 contains data structures used by the rest of the mozilla code. See also
 548 `XPCOM Project <https://www.mozilla.org/projects/xpcom/>`__.
 549
 550 xpfe
 551 ----
 552
 553 XPFE (Cross Platform Front End) is the SeaMonkey frontend. It contains
 554 the XUL files for the browser interface, common files used by the other
 555 parts of the mozilla suite, and the XBL files for the parts of the XUL
 556 language that are implemented in XBL. Much of this code has been copied
 557 to `browser/` and `toolkit/` for use in
 558 Firefox, Thunderbird, etc.
 559
 560
 561 xpfe/components
 562 ---------------
 563
 564 Components used by the Mozilla frontend, as well as implementations of
 565 interfaces that other parts of mozilla expect.