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

mozilla

Compare Revisions

An introduction to hacking Mozilla

Change Revisions

Revision 169706:

Revision 169706 by Hendrik0 on

Revision 169707:

Revision 169707 by Hendrik0 on

Title:
An introduction to hacking Mozilla
An introduction to hacking Mozilla
Slug:
An_introduction_to_hacking_Mozilla
An_introduction_to_hacking_Mozilla
Tags:
"Developing Mozilla"
"Developing Mozilla"
Content:

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="http://www.mozilla.org/projects/xpcom/"> class="external" href="http://www.mozilla.org/projects/xpcom/">X
>>XPCOM</a> on mozilla.org. To get you started, one could say that>PCOM</a> on mozilla.org. 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="http://www.mozilla.org/projects/x>me is <a class="external" href="http://www.mozilla.org/projects/x
>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://www.xulplanet.com/">XULPlanet</a>).>="external" href="http://www.xulplanet.com/">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 www.mozilla.org web site. If you can’t find what you>ed on the www.mozilla.org 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