MDN may have intermittent access issues April 18 13:00 - April 19 01:00 UTC. See for all notifications.


Compare Revisions

An introduction to hacking Mozilla

Change Revisions

Revision 169706:

Revision 169706 by Hendrik0 on

Revision 169707:

Revision 169707 by Hendrik0 on

An introduction to hacking Mozilla
An introduction to hacking Mozilla
"Developing Mozilla"
"Developing Mozilla"

Revision 169706
Revision 169707
n76      Note that JavaScript can not be compiled to be executed by n76      Note that JavaScript can not be compiled to be executed by 
>the operating system directly, we still use C/C++ for the back-en>the operating system directly: we still use C/C++ for the back-en
>d of the program, JavaScript runs inside Mozilla.>d of the program; JavaScript runs inside Mozilla.
n88      A primary requirement for Software developed in the Mozillan88      A primary requirement for software developed in the Mozilla
> project is that it must be cross-platform, i.e. it must not be r> project is that it must be cross-platform, i.e. it must not be r
>estricted to any particular operating system.>estricted to any particular operating system.
n115      In most simple C++ projects, this only means, you carefullyn115      In most simple C++ projects, this only means that you caref
> design your classes to use public/protected/private as appropria>ully design your classes to use public/protected/private as appro
>te, but all source code is still available everywhere. For instan>priate, but all source code is still available everywhere. For in
>ce, at any time, you can change any class’ component from private>stance, at any time, you can change any class component from priv
> to public, so it will be available at any other place in your pr>ate to public, so it will be available at any other place in your
>oject. This does not apply to Mozilla. It was decided that Mozill> project. This does not apply to Mozilla. It was decided that Moz
>a should be even more modular.>illa should be even more modular.
116    </p>
117    <p>116    </p>
118      The Mozilla source code is organized as separate components
>. While within one component, you have all the freedom as describ 
>ed in the previous paragraph for simple projects, you don’t have  
>the same level of flexibility between components. 
119    </p>117    <p>
118      The Mozilla source code is organized as separate components
 >. While within one component, you have all the freedom as describ
 >ed in the previous paragraph for simple projects. You don’t have 
 >the same level of flexibility between components.
120    <p>119    </p>
120    <p>
121      When components talk to each other, they only do so using w121      When components talk to each other, they only do so using w
>ell defined interfaces using the component object model (COM).>ell-defined interfaces using the component object model (COM).
n130      In a CORBA environment, life is more restrictive and difficn130      In a CORBA environment, life is more restrictive and diffic
>ult, because you have inter-process and inter-network communicati>ult, because you have inter-process and inter-network communicati
>on, something which Mozilla is not actively using. In a distribut>on&nbsp;–&nbsp;something which Mozilla is not actively using. In 
>ed CORBA environment, it is difficult to change the components of>a distributed CORBA environment, it is difficult to change the co
> an interface, because you are usually unable to replace all runn>mponents of an interface, because you are usually unable to repla
>ing systems at the same time. If you want to change something, yo>ce all running systems at the same time. If you want to change so
>u have to define a new version of an interface, but you might sti>mething, you have to define a new version of an interface, but yo
>ll be required to support the old one.>u might still be required to support the old one.
131    </p>
132    <p>131    </p>
132    <p>
133      As Mozilla is not a distributed application as of writing, 133      As Mozilla is not a distributed application as of writing, 
>it is currently possible to change most interfaces as the develop>it is currently possible to change most interfaces as the develop
>ment process requires it. But because the Mozilla browser runs em>ment process requires it. But because the Mozilla browser runs em
>bedded in some environments, those environments must be able to r>bedded in some environments, those environments must be able to r
>ely on a fixed interface, therefore interfaces can be frozen. Thi>ely on a fixed interface; therefore, interfaces can be frozen. Th
>s state is usually indicated in the interface definition. As Mozi>is state is usually indicated in the interface definition. As Moz
>lla stabilizes over time, or approaches the magical version numbe>illa stabilizes over time, or approaches the magical version numb
>r One-Dot-Zero, the ratio of frozen to not frozen interfaces is l>er One-Dot-Zero, the ratio of frozen to not frozen interfaces is 
>ikely to increase.>likely to increase.
n148      You should definitively read the introductory documents on n148      You should definitely read the introductory documents on <a
><a class="external" href=""> class="external" href="">X
>>XPCOM</a> on To get you started, one could say that>PCOM</a> on To get you started, one could say that X
> XPCOM is the engine that makes the COM concept work. This includ>PCOM is the engine that makes the COM concept work. This includes
>es playing the role of an object broker.> playing the role of an object broker.
n154      Even if your code stays completely within one component, ann154      Even if your code stays completely within one component, an
>d therefore using COM is not a strict requirement, it is used ver>d therefore using COM is not a strict requirement, it is very oft
>y often anyway. One reason is flexibility. Another one is to allo>en used anyway. One reason is flexibility. Another is to allow sh
>w sharing functionality with those portions of the Mozilla logic >aring functionality with those portions of the Mozilla logic that
>that are implemented using JavaScript. Mozilla provides a technol> are implemented using JavaScript. Mozilla provides a technology 
>ogy called XPConnect that enables communication between interpret>called XPConnect that enables communication between interpreted J
>ed JavaScript and compiled C++ at runtime.>avaScript and compiled C++ at runtime.
155    </p>
156    <p>155    </p>
156    <p>
157      Whenever you request an instance of a COM object at runtime157      Whenever you request an instance of a COM object at runtime
>, a class object will be created and you will be given an interfa>, a class object will be created and you will be given an interfa
>ce pointer. For several reasons it was decided that these instanc>ce pointer. For several reasons it was decided that these instanc
>es are reference counted. One reason is efficiency, for it making>es are reference counted. One reason is efficiency, since making 
> unnecessary copies of objects should be avoided. Another require>unnecessary copies of objects should be avoided. Another requirem
>ment is that data objects must be passed between threads, but all>ent is that when data objects must be passed between threads, eac
> keep a pointer to the same data object in memory. Finally, the s>h thread needs to keep a pointer to the same data object in memor
>ame data object might be referenced by multiple components, or st>y. Finally, the same data object might be referenced by multiple 
>ored in multiple lists.>components, or stored in multiple lists.
158    </p>
159    <p>158    </p>
159    <p>
160      As the lifetime of a reference is different, it is easiest 160      As the lifetime of each reference is different, it is easie
>to have each object maintain a reference count, to remember how o>st to have each object maintain a reference count, to remember ho
>ften it is currently referenced by something else. When you are g>w often it is currently referenced by something else. When you ar
>iven a reference to an object (be it from the XPCOM engine direct>e given a reference to an object (be it from the XPCOM engine dir
>ly or from a function call), you have to make sure that you care >ectly or from a function call), you have to make sure that you ca
>for reference counting. You must tell the object whether you want>re for reference counting. You must tell the object whether you w
> to keep a reference to it, or whether you are finished with it, >ant to keep a reference to it, or whether you are finished with i
>and remove the reference. That way, the object can decide on its >t, and remove the reference. That way, the object can decide on i
>own whether it is still needed. When its not needed anymore, it d>ts own whether it is still needed. When its not needed anymore, i
>eletes itself from memory.>t deletes itself from memory.
n166      There is the general rule, that you must clean up what you n166      There is a general rule that you must clean up what you all
>allocate. For instance, if you add a reference, you are strongly >ocate. For instance, if you add a reference, you are strongly enc
>encouraged to release the reference as soon as it is no longer ne>ouraged to release the reference as soon as it is no longer neede
>eded. If you don’t, you might cause problems such as memory leaks>d. If you don’t, you might cause problems such as memory leaks.
167    </p>
168    <p>167    </p>
169      In C++, this can be done by explicit method calls to method
>s of the nsISupports base class. But calling these methods is not 
> only easy to forget, but it also makes your code less readable.  
>Especially since many functions/methods have multiple exit points 
> (i.e. return statements). 
170    </p>168    <p>
169      In C++, this can be done by explicit method calls to method
 >s of the nsISupports base class. But calling these methods is not
 > only easy to forget, but it also makes your code less readable&n
 >bsp;–&nbsp;especially since many functions/methods have multiple 
 >exit points (i.e. return statements).
171    <p>170    </p>
171    <p>
172      You have to make sure that you release all your referenced 172      You have to make sure that you release all your referenced 
>objects in each of your exit points. To make this easier, and to >objects in each of your exit points. To make this easier, and to 
>not have to repeat many release calls, a general helper class has>not have to repeat many release calls, a general helper class has
> been provided for dealing with pointers to COM objects, whose na> been provided for dealing with pointers to COM objects, whose na
>me is <a class="external" href=">me is <a class="external" href="
>pcom/nsCOMPtr.html">nsCOMPtr</a>. This is something special to XP>pcom/nsCOMPtr.html">nsCOMPtr</a>. This is something special to XP
>COM and makes coding COM much easier. It simulates a pointer thro>COM and makes coding COM much easier. It simulates a pointer by o
>ugh overriding certain operators. Although there might be some ed>verriding certain operators. Although there might be some edge ca
>ge cases, the following general rule should be followed for nearl>ses, the following general rule should be followed for nearly all
>y all code: Whenever you’d expect to use a pointer variable “inte> code: Whenever you’d expect to use a pointer variable “interface
>rface*” to an object that implements an interface, use a local “n>*” to an object that implements an interface, use a local “nsCOMP
>sCOMPtr&lt;interface&gt;” variable instead. As soon as this point>tr&lt;interface&gt;” variable instead. As soon as this pointer go
>er goes “out of scope”, its destructor will automatically decreas>es “out of scope”, its destructor will automatically decrease the
>e the reference count, triggering destruction if possible.> reference count, triggering destruction if possible.
173    </p>
174    <p>173    </p>
174    <p>
175      In interpreted JavaScript this is easier to code, because o175      In interpreted JavaScript this is easier to code, because o
>f garbage collection. There is some magic that automatically rele>f garbage collection. There is some magic that automatically rele
>ases the references when possible. However, this magic requires t>ases the references when possible. However, this magic requires t
>hat you don’t introduce cycles. For example, if you have two obje>hat you don’t introduce cycles. For example, if you have two obje
>cts, and each contain a reference to each other, but nobody else >cts, and each contain a reference to the other, but nobody else k
>keeps a reference to them, this can not be detected, and those ob>eeps a reference to them, this can not be detected. Those objects
>jects will live in memory for the rest of program execution.> will live in memory for the rest of program execution.
n181      Code execution can fail at runtime. One programming mechanin181      Code execution can fail at runtime. One programming mechani
>sm to deal with failure is to use exceptions. While Mozilla uses >sm to deal with failure is to use exceptions. While Mozilla uses 
>Exceptions in its JavaScript code portions, it does not in C++. O>Exceptions in its JavaScript code portions, it does not in C++. O
>ne out of several reasons for this is exceptions haven’t always b>ne of several reasons for this is exceptions haven’t always been 
>een portable, so what was done in the past has stuck. Mozilla C++>portable, so what was done in the past has stuck. Mozilla C++ cod
> code uses return codes to simulate exceptions. That means, while>e uses return codes to simulate exceptions. That means that while
> in JavaScript you can use try-catch blocks, in C++ you should ch> you can use try-catch blocks in JavaScript, in C++ you should ch
>eck the return code whenever you call an interface method. That r>eck the return code whenever you call an interface method. That r
>eturn code is of type nsresult. For this reason, the logical retu>eturn code is of type nsresult. For this reason, the logical retu
>rn type, as defined in the IDL file, is mapped to an additional m>rn type, as defined in the IDL file, is mapped to an additional m
>ethod parameter in the C++ code.>ethod parameter in the C++ code.
182    </p>
183    <p>182    </p>
183    <p>
184      The nsresult type is intended to transport additional failu184      The nsresult type is intended to transport additional failu
>re reasons. Instead of simply reporting failure or success, an in>re reasons. Instead of simply reporting failure or success, an in
>teger type is used instead, to allow for defining a lot of differ>teger type is used instead, to allow for the definition of a lot 
>ent error codes.>of different error codes.
n196      While many application frameworks or class libraries deciden196      While many application frameworks or class libraries decide
>d to use just a single string class, the Mozilla developers have >d to use just a single string class, the Mozilla developers have 
>decided they need something more powerful. They have implemented >decided they need something more powerful. They have implemented 
>a hierarchy of several string classes, which allows the dynamic r>a hierarchy of several string classes, which allows the dynamic r
>untime behaviour to be optimized for different situations. Someti>untime behaviour to be optimized for different situations. Someti
>mes you just need to fixed size string, sometimes you need a larg>mes you just need a fixed size string; sometimes you need a large
>e string that grows over time. Therefore, for example, not only f> string that grows over time. Therefore, for example, not only fl
>lat strings, but also segmented string types are available.>at strings, but also segmented string types are available.
n202      The string types are template based, with the character typn202      The string types are template-based, with the character typ
>e as the variable type, to allow the same logic to be used with r>e as the variable type, to allow the same logic to be used with r
>egular and Unicode strings.>egular and Unicode strings.
n226      Mozilla developers have chosen to use an approach where then226      Mozilla developers have chosen to use an approach where the
> contents of the UI are designed in a logical matter. We don’t cu> contents of the UI are designed in a logical manner. We don’t cu
>rrently use an UI editor. We write a file with instructions how t>rrently use a UI editor. We write a file with instructions on how
>he UI should look. At runtime, the layout engine decides which fo> the UI should look. At runtime, the layout engine decides which 
>nts are available, and considers all the requests that have been >fonts are available, and considers all the requests that have bee
>defined in the UI description, and creates the actual UI dynamica>n defined in the UI description, and creates the actual UI dynami
>lly. This is similar to what the web browser does when displaying>cally. This is similar to what the web browser does when displayi
> web pages.>ng web pages.
227    </p>
228    <p>227    </p>
228    <p>
229      The web has gone from a mostly text-based system to a very 229      The web has gone from a mostly text-based system to a very 
>graphical rich environment that has user interfaces akin to many >graphically rich environment that has user interfaces akin to man
>programs. Therefore, it was only natural for a web browser to use>y programs. Therefore, it was only natural for a web browser to u
> web languages in order to define its user interface. It was deci>se web languages in order to define its user interface. It was de
>ded to use an XML based syntax to write the UI description, which>cided to use an XML based syntax to write the UI description, whi
> has been called XUL (extensible user-interface language). (A goo>ch has been called XUL (extensible user-interface language, prono
>d reference for XUL is available at <a class="external" href="htt>unced ‘zool’). (A good reference for XUL is available at <a class
>p://">XULPlanet</a>).>="external" href="">XULPlanet</a>).
230    </p>
231    <p>230    </p>
231    <p>
232      A XUL file describes what elements the UI consists of, and 232      A XUL file describes what elements the UI consists of, and 
>where elements appear. The XUL language defines attributes that a>where elements appear. The XUL language defines attributes that a
>llow the programmer to define the actions controls react to. To d>llow the programmer to define the user actions that controls will
>efine the dynamic behaviour of the application, one can define Ja> react to. To define the dynamic behaviour of the application, on
>vaScript functions that will be called when certain user interfac>e can define JavaScript functions that will be called when certai
>e events happen. Within those JavaScript functions, you can eithe>n user interface events happen. Within those JavaScript functions
>r do the required application behaviour directly, or call any oth>, you can either do the required application behaviour directly, 
>er application logic available by COM objects, including logic de>or call any other application logic available through COM objects
>fined in C++.>, including logic defined in C++.
233    </p>
234    <p>233    </p>
234    <p>
235      In addition to the logical representation of the UI, people235      In addition to the logical representation of the UI, people
> also prefer to have a pretty looking UI. To define the detailed > also prefer to have a pretty looking UI. To define the detailed 
>characteristics of the UI, one uses CSS files, that defines, for >characteristics of the UI, one uses CSS files, which define, for 
>example, which images will be used to display certain UI elements>example, which images will be used to display certain UI elements
>. This makes it flexible to define additional “looks” for the app>. This makes it flexible enough to define additional “looks” for 
>lication, which are referred to as “themes” or “skins”. Mozilla d>the application, which are referred to as “themes” or “skins”. Mo
>efines currently two themes, classic and modern, which are active>zilla defines currently two themes, classic and modern, which are
>ly maintained by the Mozilla developers. While there exist additi> actively maintained by the Mozilla developers. While there are a
>onal themes for Mozilla, they often exist only for certain versio>dditional themes, they often exist only for certain versions of M
>ns of Mozilla. It is a lot of work for a theme designer to stay i>ozilla. It is a lot of work for a theme designer to stay in sync 
>n sync with all the changes that happen to the UI each day.>with all the changes that happen to the UI each day.
n247      Most of the platform-specific code is contained in only a fn247      Most of the platform-specific code is contained in only a f
>ew places of the tree. The layer that sits between the operating >ew places of the tree. The layer that sits between the operating 
>system and the rest of the Mozilla code are the interfaces that a>system and the rest of the Mozilla code consists of the interface
>re implemented by this code. Only the platform-specific code pert>s that are implemented by this code. Only the platform-specific c
>aining to the platform in which the build is occurring is built.>ode pertaining to the platform in which the build is occurring is
 > built.
n253      Widgets in respect to the Mozilla project are OS-independenn253      Widgets, with respect to the Mozilla project, are OS-indepe
>t widgets drawn using platform-specific rendering techniques.>ndent widgets drawn using platform-specific rendering techniques.
254    </p>
255    <p>254    </p>
255    <p>
256      Within the tree, directories named public usually contain i256      Within the tree, directories named public usually contain
>nterface headers, and directories named src usually contain inter> interface headers, and directories named src usually contain i
>face implementations and non-interface headers.>nterface implementations and non-interface headers.
n268      Mozilla’s COM system relies on type libraries and an internn268      Mozilla’s COM system relies on type libraries and an intern
>al registry of available components and interfaces. During applic>al registry of available components and interfaces. During applic
>ation startup, a check is being made whether the registry is stil>ation startup, a check is being made whether the registry is stil
>l up to date. If changed libraries are detected, the registry is >l up to date. If changed libraries are detected, the registry is 
>updated. Each component is allowed to do initialization during th>updated. Each component is allowed to do initialization during th
>at registration phase. If changed libraries are detected, they ar>at registration phase. If changed libraries are detected, they ar
>e loaded and their initialization logic is executed. Besides chan>e loaded and their initialization logic is executed. Besides chan
>ged libraries, only those application components are loaded as th>ged libraries, other application components are loaded only as th
>ey become required.>ey become required.
n283      Mozilla was designed to separate code from human language. n283      Mozilla was designed to separate code from human language. 
>Whenever you need to use a text string that needs to be shown to >Whenever you need to use a text string that needs to be shown to 
>a user, you are not allowed to store that string directly in your>a user, you are not allowed to store that string directly in your
> JavaScript or C++ file. Instead you define an descriptive identi> JavaScript or C++ file. Instead you define a descriptive identif
>fier for your text, which is used in your C++ or JavaScript file.>ier for your text, which is used in your C++ or JavaScript file. 
> You use that identifier as a key and call members of the string >You use that identifier as a key and call members of the string b
>bundle interface to retrieve the actual text. The text itself is >undle interface to retrieve the actual text. The text itself is s
>stored in separate files, that only contain text. As Mozilla is m>tored in separate files, that only contain text. As Mozilla is mo
>odular, there are a lot of those files, each owned by a separate >dular, there are a lot of these files, each owned by a separate m
>module. With that separation, it is easy to have translators crea>odule. With that separation, it is easy to have translators creat
>te different language versions of those text files.>e different language versions of these text files.
n310      In order to achieve this, the Mozilla community has decidedn310      In order to achieve this, the Mozilla community has decided
> that all code has to be reviewed by other already known Mozilla > that all code has to be reviewed by other already known Mozilla 
>hackers. There are two levels of review. You should get a first r>hackers. There are two levels of review. You should get a first r
>eview (r=) from the owner of the code area your are changing. You>eview (r=) from the owner of the code area you are changing. You 
> are expected to make the corrections that are requested, or your>are expected to make the corrections that are requested, or your 
> code will not go in. If you have that first review, you need to >code will not go in. If you have that first review, you need to g
>get what is called super-review (sr=) in most cases. There are on>et what is called super-review (sr=) in most cases. There are onl
>ly a limited number of “Mozilla gurus” that have an accepted repu>y a limited number of “Mozilla gurus” that have an accepted reput
>tation for making good decisions on what code is good and what ne>ation for making good decisions on what code is good and what nee
>eds to be changed. Once you have both reviews, your code may be c>ds to be changed. Once you have both reviews, your code may be ch
>hecked in most of the time. There are other levels of review in c>ecked in most of the time. There are other levels of review in ce
>ertain instances, and that is described elsewhere.>rtain instances, and that is described elsewhere.
311    </p>
312    <p>311    </p>
313      Many people make changes to Mozilla. While everybody tries 312    <p>
>to make Mozilla better, every change has the risk of unforeseen s 
>ide effects. This range from application features that, as a resu 
>lt of a change, no longer work, to the simple problem, that Mozil 
>la source code does not even compile anymore. The latter is calle 
>d “the tree is broken, burning, or red”, where tree refers to the 
> CVS source repository. 
313      Many people make changes to Mozilla. While everybody tries 
 >to make Mozilla better, every change has the risk of unforeseen s
 >ide effects. These range from application features that, as a res
 >ult of the change, no longer work, to the problem that the Mozill
 >a source code simply does not compile anymore. The latter is call
 >ed “the tree is broken, burning, or red”, where tree refers to th
 >e CVS source repository.
t373      If you want to learn more about the mentioned programming tt373      If you want to learn more about the mentioned programming t
>echniques in general, I recommend searching the web for free docu>echniques in general, I recommend searching the web for free docu
>ments. Hopefully the mentioned terms in this document will guide >ments. Hopefully the mentioned terms in this document will guide 
>you. If you prefer to read books, I suggest to choose those books>you. If you prefer to read books, I suggest to choose those books
>, where the author tries to explain in general, and does not conc> in which the author tries to explain in general, and does not co
>entrate on some particular operating system.>ncentrate on some particular operating system.
374    </p>
375    <p>374    </p>
375    <p>
376      Most documentation regarding to Mozilla development is publ376      Most documentation regarding Mozilla development is publish
>ished on the web site. If you can’t find what you>ed on the web site. If you can’t find what you ar
> are looking for, try to use a search engine. Some popular search>e looking for, try to use a search engine. Some popular search en
> engines offer an advanced search option, where one can limit the>gines offer an advanced search option, where one can limit the se
> search to a specific web site.>arch to a specific web site.

Back to History