diff options
Diffstat (limited to 'docs/contributing/directory_structure.rst')
| -rw-r--r-- | docs/contributing/directory_structure.rst | 565 |
1 files changed, 565 insertions, 0 deletions
diff --git a/docs/contributing/directory_structure.rst b/docs/contributing/directory_structure.rst new file mode 100644 index 0000000000..fd447278c2 --- /dev/null +++ b/docs/contributing/directory_structure.rst @@ -0,0 +1,565 @@ +Firefox Source Code Directory Structure +======================================= + +This article provides an overview of what the various directories contain. + +To simply take a look at the Firefox source code, you do not need to +download it. You can look at the source directly with your web browser +using Searchfox (start at https://searchfox.org/mozilla-central/source for +the complete firefox source code of branch HEAD). + +In order to modify the source, you have to acquire it either by +downloading a :ref:`snapshot <Mercurial Overview>` of the sources or +by checking out the current sources from +:ref:`the repository <Firefox Contributors' Quick Reference>`. + +This document describes the directory structure -- i.e., directories that +are used by at least some of the +Mozilla project's client products. There are other directories in the +other Mozilla repository, such as those for Web tools and those for the +Classic codebase. + +See the `more detailed overview of the pieces of Gecko <https://wiki.mozilla.org/Gecko:Overview>`__. + +.cargo +------ + +Configuration files for the `Cargo package +manager <https://crates.io/>`__. + +.vscode +------- + +Configuration files used by the `Visual Studio Code +IDE <https://code.visualstudio.com/>`__ when working in the +mozilla-central tree. + +accessible +---------- + +Files for accessibility (i.e., MSAA (Microsoft Active Accessibility), +ATK (Accessibility Toolkit, used by GTK) support files). See +`Accessibility <https://developer.mozilla.org/docs/Web/Accessibility>`__. + + +browser +------- + +Contains the front end code (in XUL, Javascript, XBL, and C++) for the +Firefox desktop browser. Many of these files started off as a copy of files in +`xpfe <#xpfe>`__. + +browser/extensions +------------------ + +Contains `PDF.js <https://mozilla.github.io/pdf.js/>`__ and +`WebCompat <https://github.com/mozilla/webcompat-addon>`__ built-in extensions. + +browser/themes +-------------- + +Contains images and CSS files to skin the browser for each OS (Linux, +Mac and Windows) + +build +----- + +Miscellaneous files used by the build process. See also `config <#config>`__. + +caps +---- + +Capability-based web page security management. It contains C++ interfaces +and code for determining the capabilities of content based on the +security settings or certificates (e.g., VeriSign). See `Component +Security <https://www.mozilla.org/projects/security/components/>`__ . + +chrome +------ + +:ref:`Chrome registry <Chrome Registration>` used with `toolkit <#toolkit>`__/. +These files were originally copies of files in `rdf/chrome/`. + +config +------ + +More files used by the build process, common includes for the makefiles, +etc. + + +devtools +-------- + +The Firefox Developer Tools server and client components. See :ref:`contributor <devtools-contributor-doc>` and :ref:`user <devtools-user-doc>` documentation. + + +docs +---- + +Contains the documentation configuration (`Sphinx <http://www.sphinx-doc.org/>`__ based), the index page +and the contribution pages. + + +docshell +-------- + +Implementation of the docshell, the main object managing things related +to a document window. Each frame has its own docshell. It contains +methods for loading URIs, managing URI content listeners, etc. It is the +outermost layer of the embedding API used to embed a Gecko browser into +an application. + +dom +--- + +- :ref:`IDL definitions <XPIDL>` of the interfaces defined by + the DOM specifications and Mozilla extensions to those interfaces + (implementations of these interfaces are primarily, but not + completely, in `content <#content>`__). +- The parts of the connection between JavaScript and the + implementations of DOM objects that are specific both to JavaScript + and to the DOM. +- Implementations of a few of the core "DOM Level 0" objects, such as + `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. + +editor +------ + +The editor directory contains XUL/Javascript for the embeddable editor +component, which is used for the HTML Editor("Composer"), for plain and +HTML mail composition, and for text fields and text areas throughout the +product. The editor is designed like a +"browser window with editing features": it adds some special classes for +editing text and managing transaction undo/redo, but reuses browser code +for nearly everything else. + +extensions +---------- + +Contains several extensions to mozilla, which can be enabled at +compile-time using the ``--enable-extensions`` configure argument. + +Note that some of these are now built specially and not using the +``--enable-extensions`` option. For example, disabling xmlextras is done +using ``--disable-xmlextras``. + + +extensions/auth +--------------- + +Implementation of the negotiate auth method for HTTP and other +protocols. Has code for SSPI, GSSAPI, etc. See `Integrated +Authentication <https://www.mozilla.org/projects/netlib/integrated-auth.html>`__. + + +extensions/pref +--------------- + +Preference-related extensions. + +extensions/spellcheck +--------------------- + +Spellchecker for mailnews and composer. + +extensions/universalchardet +--------------------------- + +Detects the character encoding of text. + +gfx +--- + +Contains interfaces that abstract the capabilities of platform specific +graphics toolkits, along with implementations on various platforms. +These interfaces provide methods for things like drawing images, text, +and basic shapes. It also contains basic data structures such as points +and rectangles used here and in other parts of Mozilla. + +gradle +------ + +Containing files related to a Java build system. + +hal +--- + +Contains platform specified functions (e.g. obtaining battery status, +sensor information, memory information, Android +alarms/vibrate/notifications/orientation, etc) + +image +----- + +Image rendering library. Contains decoders for the image formats Firefox +supports. + +intl +---- + +Internationalization and localization support. See +`L10n:NewProjects <https://wiki.mozilla.org/L10n:NewProjects>`__. + +intl/locale +----------- + +Code related to determination of locale information from the operating +environment. + +intl/lwbrk +---------- + +Code related to line breaking and word breaking. + +intl/strres +----------- + +Code related to string resources used for localization. + +intl/uconv +---------- + +Code that converts (both ways: encoders and decoders) between UTF-16 and +many other character encodings. + +intl/unicharutil +---------------- + +Code related to implementation of various algorithms for Unicode text, +such as case conversion. + +ipc +--- + +Container for implementations of IPC (Inter-Process Communication). + +js/src +------ + +The JavaScript engine, also known as +:ref:`SpiderMonkey <SpiderMonkey>`. +See also `JavaScript <https://developer.mozilla.org/docs/JavaScript>`__. + +js/xpconnect +------------ + +Support code for calling JavaScript code from C++ code and C++ code from +JavaScript code, using XPCOM interfaces. See +`XPConnect <https://developer.mozilla.org/docs/XPConnect>`__. + +layout +------ + +Code that implements a tree of rendering objects that describe the types +and locations of the objects that are displayed on the screen (such as +CSS boxes, tables, form controls, XUL boxes, etc.), and code that +manages operations over that rendering tree (such as creating and +destroying it, doing layout, painting, and event handling). See +`documentation <https://www.mozilla.org/newlayout/doc/>`__ and `other +information <https://www.mozilla.org/newlayout/>`__. + +layout/base +----------- + +Code that deals with the rendering tree. + +layout/forms +------------ + +Rendering tree objects for HTML form controls. + +layout/generic +-------------- + +The basic rendering object interface and the rendering tree objects for +basic CSS boxes. + +layout/mathml +------------- + +Rendering tree objects for `MathML <https://developer.mozilla.org/docs/Web/MathML>`__. + +layout/svg +---------- + +Rendering tree objects for `SVG <https://developer.mozilla.org/docs/Web/SVG>`__. + +layout/tables +------------- + +Rendering tree objects for CSS/HTML tables. + +layout/xul +---------- + +Additional rendering object interfaces for `XUL <https://developer.mozilla.org/docs/XUL>`__ and +the rendering tree objects for XUL boxes. + +media +----- + +Contains sources of used media libraries for example *libpng*. + +memory +------ + +Cross-platform wrappers for *memallocs* functions etc. + +mfbt +---- + +Implementations of classes like *WeakPtr*. Multi-platform *assertions* +etc. + +mobile +------ + +mobile/android +-------------- + +Firefox for Android and Geckoview + +modules +------- + +Compression/Archiving, math library, font (and font compression), +Preferences Library + +modules/libjar +-------------- + +Code to read zip files, used for reading the .jar files that contain the +files for the mozilla frontend. + +modules/libpref +--------------- + +Library for reading and writing preferences. + +modules/zlib +------------ + +Source code of zlib, used at least in the networking library for +compressed transfers. + +mozglue +------- + +Glue library containing various low-level functionality, including a +dynamic linker for Android, a DLL block list for Windows, etc. + +netwerk +------- + +:ref:`Networking library <Networking>`, also known as Necko. +Responsible for doing actual transfers from and to servers, as well as +for URI handling and related stuff. + +netwerk/cookie +-------------- + +Permissions backend for cookies, images, etc., as well as the user +interface to these permissions and other cookie features. + +nsprpub +------- + +Netscape Portable Runtime. Used as an abstraction layer to things like +threads, file I/O, and socket I/O. See :ref:`NSPR`. + +nsprpub/lib +----------- + +Mostly unused; might be used on Mac? + +other-licenses +-------------- + +Contains libraries that are not covered by the MPL but are used in some +Firefox code. + +parser +------ + +Group of structures and functions needed to parse files based on +XML/HTML. + +parser/expat +------------ + +Copy of the expat source code, which is the XML parser used by mozilla. + +parser/html +----------- + +The HTML parser (for everything except about:blank). + +parser/htmlparser +----------------- + +The legacy HTML parser that's still used for about:blank. Parts of it +are also used for managing the conversion of the network bytestream into +Unicode in the XML parsing case. + +parser/xml +---------- + +The code for integrating expat (from parser/expat) into Gecko. + +python +------ + +Cross module python code. + +python/mach +----------- + +The code for the :ref:`Mach` building tool. + +security +-------- + +Contains NSS and PSM, to support cryptographic functions in mozilla +(like S/MIME, SSL, etc). See :ref:`Network Security Services (NSS)` +and +`Personal Security Manager +(PSM) <https://www.mozilla.org/projects/security/pki/psm/>`__. + +services +-------- + +Firefox accounts and sync (history, preferences, tabs, bookmarks, +telemetry, startup time, which addons are installed, etc). See +`here <https://docs.services.mozilla.com/>`__. + +servo +----- + +`Servo <https://servo.org/>`__, the parallel browser engine project. + +startupcache +------------ + +XXX this needs a description. + +storage +------- + +`Storage <https://developer.mozilla.org/docs/Mozilla/Tech/XPCOM/Storage>`__: XPCOM wrapper for sqlite. Wants to +unify storage of all profile-related data. Supersedes mork. See also +`Unified Storage <https://wiki.mozilla.org/Mozilla2:Unified_Storage>`__. + +taskcluster +----------- + +Scripts and code to automatically build and test Mozilla trees for the +continuous integration and release process. + +testing +------- + +Common testing tools for mozilla codebase projects, test suite +definitions for automated test runs, tests that don't fit anywhere else, +and other fun stuff. + +third_party +----------- + +Vendored dependencies maintained outside of Mozilla. + +toolkit +------- + +The "new toolkit" used by Thunderbird, Firefox, etc. This contains +numerous front-end components shared between applications as well as +most of the XBL-implemented parts of the XUL language (most of which was +originally forked from versions in `xpfe/`). + +toolkit/mozapps/extensions/test/xpinstall +----------------------------------------- + +The installer, which contains code for installing Mozilla and for +installing XPIs/extensions. This directory also contains code needed to +build installer packages. See `XPInstall <https://developer.mozilla.org/docs/XPInstall>`__ and +the `XPInstall project +page <https://www.mozilla.org/projects/xpinstall/>`__. + +tools +----- + +Some tools which are optionally built during the mozilla build process. + +tools/lint +---------- + +The linter declarations and configurations. +See `linting documentation </code-quality/lint/>`_ + +uriloader +--------- + +uriloader/base +-------------- + +Content dispatch in Mozilla. Used to load uris and find an appropriate +content listener for the data. Also manages web progress notifications. +See `Document Loading: From Load Start to Finding a +Handler <https://www.mozilla.org/docs/docshell/uri-load-start.html>`__ +and `The Life Of An HTML HTTP +Request <https://www.mozilla.org/docs/url_load.html>`__. + + +uriloader/exthandler +-------------------- + +Used to handle content that Mozilla can't handle itself. Responsible for +showing the helper app dialog, and generally for finding information +about helper applications. + +uriloader/prefetch +------------------ + +Service to prefetch documents in order to have them cached for faster +loading. + +view +---- + +View manager. Contains cross-platform code used for painting, scrolling, +event handling, z-ordering, and opacity. Soon to become obsolete, +gradually. + +widget +------ + +A cross-platform API, with implementations on each platform, for dealing +with operating system/environment widgets, i.e., code related to +creation and handling of windows, popups, and other native widgets and +to converting the system's messages related to painting and events into +the messages used by other parts of Mozilla (e.g., `view/` and +`content/`, the latter of which converts many of the +messages to yet another API, the DOM event API). + +xpcom +----- + +`Cross-Platform Component Object Model </en-US/docs/XPCOM>`__. Also +contains data structures used by the rest of the mozilla code. See also +`XPCOM Project <https://www.mozilla.org/projects/xpcom/>`__. + +xpfe +---- + +XPFE (Cross Platform Front End) is the SeaMonkey frontend. It contains +the XUL files for the browser interface, common files used by the other +parts of the mozilla suite, and the XBL files for the parts of the XUL +language that are implemented in XBL. Much of this code has been copied +to `browser/` and `toolkit/` for use in +Firefox, Thunderbird, etc. + + +xpfe/components +--------------- + +Components used by the Mozilla frontend, as well as implementations of +interfaces that other parts of mozilla expect. |