Compare Revisions

An introduction to hacking Mozilla

Revision 169704:

Revision 169704 by Sheppy on

Revision 169706:

Revision 169706 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 169704
Revision 169706
nn7    <p>
8      If you find errors in this document, or if you want to cont
 >ribute updated or additional sections, please contact <a class="e
 >xternal" href="mailto:kaie@kuix.de">Kai Engert</a>.
9    </p>
10    <h3 name="What_is_Mozilla.3F">
11      What is Mozilla?
12    </h3>
13    <p>
14      Mozilla is an open source project and organization to devel
 >op a cross-platform Internet client software. Since it is open so
 >urce, the source code is available to everyone&nbsp;–&nbsp;althou
 >gh you have to follow the <a class="external" href="http://www.mo
 >zilla.org/MPL/">licenses</a> as defined in the respective source 
 >files (a mixture of MPL, NPL, GPL, LGPL).
15    </p>
16    <p>
17      mozilla.org is the name of an organization that provides an
 > infrastructure to help developers in the project. <a class="exte
 >rnal" href="http://www.mozilla.org/">mozilla.org</a> is also the 
 >address of the central web site for the Mozilla project.
18    </p>
19    <h3 name="Motivation">
20      Motivation
21    </h3>
22    <p>
23      Mozilla is one of the largest open source software projects
 >. The Mozilla codebase has millions of lines of code. Therefore, 
 >getting started in this huge project isn’t easy. The intention of
 > this document is to give an overview about what you should be aw
 >are of in order to hack Mozilla. It tries to build a bridge betwe
 >en the many different technologies used in the Mozilla project.
24    </p>
25    <p>
26      When I started to look into Mozilla, I wished a document li
 >ke this existed.&nbsp;:)
27    </p>
28    <h3 name="Audience">
29      Audience
30    </h3>
31    <p>
32      This document is primarily written for developers who want 
 >to be able to work on any part of Mozilla. You should have a good
 > understanding of Object Oriented Programming, and especially you
 > should be experienced with C/C++, as it is the main programming 
 >language used in the project.
33    </p>
34    <p>
35      However, if you intend to work only on a subset of the code
 >, say only the JavaScript and XUL UI code, this document should s
 >till be helpful.
36    </p>
37    <h3 name="Scope_of_this_document">
38      Scope of this document
39    </h3>
40    <p>
41      This document will try to answer the following questions:
42    </p>
7    <ol>43    <ul>
8      <li>REDIRECT <a href="en/An_introduction_To_hacking_Mozilla44      <li>How is the source code organized?
>">An introduction To hacking Mozilla</a> 
tt46      <li>Which technologies are used?
47      </li>
48      <li>Where do I start?
49      </li>
50      <li>How do the components work together?
51      </li>
52      <li>Which tools exist and how can they help me?
53      </li>
54      <li>What rules do I need to follow in order to contribute?
55      </li>
10    </ol>56    </ul>
57    <h3 name="What_does_Netscape_have_to_do_with_this.3F">
58      What does Netscape have to do with this?
59    </h3>
60    <p>
61      From my personal point of view, in the beginning of Mozilla
 > there was Netscape. At some point Netscape, the company, decided
 > to give away those portions of the source code that they owned a
 >nd that were free of others’ copyright.
62    </p>
63    <p>
64      This wasn’t the complete product, therefore the Mozilla pro
 >ject has had to write a lot of new code. In addition, many portio
 >ns were rewritten. Some other components were kept and extended. 
 >That’s one reason why, in this document and when discussing the M
 >ozilla project, you will hear the term Netscape.
65    </p>
66    <h3 name="C.2B.2B_and_JavaScript">
67      C++ and JavaScript
68    </h3>
69    <p>
70      As it is widely used in Mozilla, it makes sense to explain 
 >how JavaScript and C++ relate to each other in the Mozilla source
 > code. C++ is a compiled language, while JavaScript is an interpr
 >eted language. JavaScript is most commonly known as a technology 
 >used to implement web sites. However, the developers of Mozilla d
 >ecided that the Mozilla source code itself should consist of a mi
 >xture of both languages.
71    </p>
72    <p>
73      When you start the application, the C/C++ components start 
 >first. But in an early stage, a technology called XPConnect gets 
 >initialized that enables the use of interpreted JavaScript at run
 >time. In fact, a Mozilla browser distribution consists of both co
 >mpiled C++ and uncompiled JS files.
74    </p>
75    <p>
76      Note that JavaScript can not be compiled to be executed by 
 >the operating system directly, we still use C/C++ for the back-en
 >d of the program, JavaScript runs inside Mozilla.
77    </p>
78    <p>
79      Also note, when surfing web pages which use JavaScript, tha
 >t JavaScript code is executed within a sand box, and does not hav
 >e access to Mozilla’s internal objects. Only those objects that a
 >re exposed by DOM (Document Object Model) are accessible.
80    </p>
81    <p>
82      Whenever JS is mentioned in this document, it is meant as a
 > technology to contribute to internal Mozilla functionality. Java
 >Script is mostly used in those areas of the source code that care
 > for user interface events. Most of the following document will e
 >xplain the C++ aspect of the application.
83    </p>
84    <h3 name="NSPR.C2.A0.E2.80.93.C2.A0Netscape_portable_runtime"
 >>
85      NSPR&nbsp;–&nbsp;Netscape portable runtime
86    </h3>
87    <p>
88      A primary requirement for Software developed in the Mozilla
 > project is that it must be cross-platform, i.e. it must not be r
 >estricted to any particular operating system.
89    </p>
90    <p>
91      While C++ is intended to be a portable programming language
 >, this portability aspect applies only to general program logic a
 >nd data structures. If you want to write software for a particula
 >r operating system, you need to use functionality that is specifi
 >c to that system. Often, you want the same functionality on all s
 >ystems, but in order to do it, you have to write specific softwar
 >e for each platform.
92    </p>
93    <p>
94      The intention of <a class="external" href="http://www.mozil
 >la.org/projects/nspr/">NSPR</a> is to provide a layer between the
 > OS and the Mozilla source code, to allow for simpler coding in o
 >ther areas of the Mozilla source code. When you are tempted to us
 >e a C library function, you should check first whether NSPR offer
 >s a cross-platform implementation.
95    </p>
96    <h3 name="Threads">
97      Threads
98    </h3>
99    <p>
100      Mozilla is a multithreaded application. You should understa
 >nd what that means before you try to code Mozilla.
101    </p>
102    <p>
103      NSPR provides an operating system independent facility to p
 >rogram with multiple threads. For example, all network data trans
 >fer happens on a separate thread, to make sure the user interface
 > stays responsive while data is being transferred.
104    </p>
105    <p>
106      One requirement for C++ code you write is that it is safe f
 >or multiple threads.
107    </p>
108    <h3 name="Object_oriented_programming_&amp;_Modularity">
109      Object oriented programming &amp; Modularity
110    </h3>
111    <p>
112      Mozilla C++ source code is intended to follow the rules of 
 >OOP, that includes building modular components, where access to i
 >nternal data (variables) is only allowed/possible using the publi
 >c interfaces of your classes.
113    </p>
114    <p>
115      In most simple C++ projects, this only means, you carefully
 > design your classes to use public/protected/private as appropria
 >te, but all source code is still available everywhere. For instan
 >ce, at any time, you can change any class’ component from private
 > to public, so it will be available at any other place in your pr
 >oject. This does not apply to Mozilla. It was decided that Mozill
 >a should be even more modular.
116    </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.
119    </p>
120    <p>
121      When components talk to each other, they only do so using w
 >ell defined interfaces using the component object model (COM).
122    </p>
123    <h3 name="Interfaces">
124      Interfaces
125    </h3>
126    <p>
127      The concept of interfaces is something that is used in the 
 >CORBA technology, for example. Both CORBA and Mozilla use a simil
 >ar language to describe interfaces, which is XPIDL (IDL means Int
 >erface Definition Language).
128    </p>
129    <p>
130      In a CORBA environment, life is more restrictive and diffic
 >ult, because you have inter-process and inter-network communicati
 >on, something which Mozilla is not actively using. In a distribut
 >ed CORBA environment, it is difficult to change the components of
 > an interface, because you are usually unable to replace all runn
 >ing systems at the same time. If you want to change something, yo
 >u have to define a new version of an interface, but you might sti
 >ll be required to support the old one.
131    </p>
132    <p>
133      As Mozilla is not a distributed application as of writing, 
 >it is currently possible to change most interfaces as the develop
 >ment process requires it. But because the Mozilla browser runs em
 >bedded in some environments, those environments must be able to r
 >ely on a fixed interface, therefore interfaces can be frozen. Thi
 >s state is usually indicated in the interface definition. As Mozi
 >lla stabilizes over time, or approaches the magical version numbe
 >r One-Dot-Zero, the ratio of frozen to not frozen interfaces is l
 >ikely to increase.
134    </p>
135    <p>
136      One step of building Mozilla is automatically translating t
 >he interface definition files into C/C++ header files. That’s the
 > job of Mozilla’s own IDL compiler, xpidl.
137    </p>
138    <p>
139      Besides of the methods and data members, interfaces have ad
 >ditional attributes. They have a UUID, a number to uniquely ident
 >ify an interface. Interfaces can have the scriptable attribute, w
 >hich means they will be accessible from the JavaScript code. A sc
 >riptable interface is restricted to only use data types for param
 >eters that are valid within the JavaScript runtime.
140    </p>
141    <h3 name="XPCOM_.2F_nsISupports_.2F_nsCOMPtr">
142      XPCOM / nsISupports / nsCOMPtr
143    </h3>
144    <p>
145      XPCOM is Mozilla’s own implementation of COM&nbsp;–&nbsp;th
 >e component object model. The XP in front means it is cross-platf
 >orm (do not confuse this with XP as it appears in product names f
 >or a certain operating system manufacturer). The fact that it is 
 >cross-platform makes XPCOM more versatile than any other form of 
 >COM.
146    </p>
147    <p>
148      You should definitively read the introductory documents on 
 ><a class="external" href="http://www.mozilla.org/projects/xpcom/"
 >>XPCOM</a> on mozilla.org. To get you started, one could say that
 > XPCOM is the engine that makes the COM concept work. This includ
 >es playing the role of an object broker.
149    </p>
150    <p>
151      Typically, an interface describes an object that can be use
 >d to get a job done. If you have a job to do, you need to request
 > an implementation that provides the interface. That implementati
 >on can reside within another component. To decide which particula
 >r implementation you want, you are using a contract ID, which is 
 >a text based identifier. The contract ID is a contract on the beh
 >aviour of the implementation, accessible using the well defined i
 >nterface. The XPCOM runtime system knows which class implements w
 >hich contract ID, and which component provides it.
152    </p>
153    <p>
154      Even if your code stays completely within one component, an
 >d therefore using COM is not a strict requirement, it is used ver
 >y often anyway. One reason is flexibility. Another one is to allo
 >w sharing functionality with those portions of the Mozilla logic 
 >that are implemented using JavaScript. Mozilla provides a technol
 >ogy called XPConnect that enables communication between interpret
 >ed JavaScript and compiled C++ at runtime.
155    </p>
156    <p>
157      Whenever you request an instance of a COM object at runtime
 >, a class object will be created and you will be given an interfa
 >ce pointer. For several reasons it was decided that these instanc
 >es are reference counted. One reason is efficiency, for it making
 > unnecessary copies of objects should be avoided. Another require
 >ment is that data objects must be passed between threads, but all
 > keep a pointer to the same data object in memory. Finally, the s
 >ame data object might be referenced by multiple components, or st
 >ored in multiple lists.
158    </p>
159    <p>
160      As the lifetime of a reference is different, it is easiest 
 >to have each object maintain a reference count, to remember how o
 >ften it is currently referenced by something else. When you are g
 >iven a reference to an object (be it from the XPCOM engine direct
 >ly or from a function call), you have to make sure that you care 
 >for reference counting. You must tell the object whether you want
 > to keep a reference to it, or whether you are finished with it, 
 >and remove the reference. That way, the object can decide on its 
 >own whether it is still needed. When its not needed anymore, it d
 >eletes itself from memory.
161    </p>
162    <p>
163      In order to implement this generic functionality, all class
 >es in Mozilla that implement any interface share the common base 
 >class nsISupports, which implements the reference counter and aut
 >omatic destruction functionality. A similar base class exists in 
 >every implementation of COM.
164    </p>
165    <p>
166      There is the general rule, that you must clean up what you 
 >allocate. For instance, if you add a reference, you are strongly 
 >encouraged to release the reference as soon as it is no longer ne
 >eded. If you don’t, you might cause problems such as memory leaks
 >.
167    </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. 
 >Especially since many functions/methods have multiple exit points
 > (i.e. return statements).
170    </p>
171    <p>
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 
 >not have to repeat many release calls, a general helper class has
 > been provided for dealing with pointers to COM objects, whose na
 >me is <a class="external" href="http://www.mozilla.org/projects/x
 >pcom/nsCOMPtr.html">nsCOMPtr</a>. This is something special to XP
 >COM and makes coding COM much easier. It simulates a pointer thro
 >ugh overriding certain operators. Although there might be some ed
 >ge cases, the following general rule should be followed for nearl
 >y all code: Whenever you’d expect to use a pointer variable “inte
 >rface*” to an object that implements an interface, use a local “n
 >sCOMPtr&lt;interface&gt;” variable instead. As soon as this point
 >er goes “out of scope”, its destructor will automatically decreas
 >e the reference count, triggering destruction if possible.
173    </p>
174    <p>
175      In interpreted JavaScript this is easier to code, because o
 >f garbage collection. There is some magic that automatically rele
 >ases the references when possible. However, this magic requires t
 >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 
 >keeps a reference to them, this can not be detected, and those ob
 >jects will live in memory for the rest of program execution.
176    </p>
177    <h3 name="Exceptions_.2F_nsresult">
178      Exceptions / nsresult
179    </h3>
180    <p>
181      Code execution can fail at runtime. One programming mechani
 >sm to deal with failure is to use exceptions. While Mozilla uses 
 >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
 >een portable, so what was done in the past has stuck. Mozilla C++
 > code uses return codes to simulate exceptions. That means, while
 > in JavaScript you can use try-catch blocks, in C++ you should ch
 >eck the return code whenever you call an interface method. That r
 >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
 >ethod parameter in the C++ code.
182    </p>
183    <p>
184      The nsresult type is intended to transport additional failu
 >re reasons. Instead of simply reporting failure or success, an in
 >teger type is used instead, to allow for defining a lot of differ
 >ent error codes.
185    </p>
186    <p>
187      There are some general result codes, like NS_OK, which is u
 >sed to indicate that everything went well and program flow can co
 >ntinue, or NS_ERROR_FAILURE, which is used if something went wron
 >g, but no more details need to be provided as of yet.
188    </p>
189    <p>
190      In addition to that, each component can request its own ran
 >ge of integers to define error codes that will not overlap with t
 >hose failure codes used in other areas of an application. Look at
 > mozilla/xpcom/base/nsError.h for more information.
191    </p>
192    <h3 name="Strings_in_C.2B.2B">
193      Strings in C++
194    </h3>
195    <p>
196      While many application frameworks or class libraries decide
 >d to use just a single string class, the Mozilla developers have 
 >decided they need something more powerful. They have implemented 
 >a hierarchy of several string classes, which allows the dynamic r
 >untime behaviour to be optimized for different situations. Someti
 >mes you just need to fixed size string, sometimes you need a larg
 >e string that grows over time. Therefore, for example, not only f
 >lat strings, but also segmented string types are available.
197    </p>
198    <p>
199      An additional requirement is that Mozilla has to be fully m
 >ulti-language. All strings that deal with information shown to a 
 >user are therefore using multi-byte Unicode character strings.
200    </p>
201    <p>
202      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
 >egular and Unicode strings.
203    </p>
204    <p>
205      While that approach of having many string classes means a l
 >ot of flexibility, the drawback is that learning Mozilla’s string
 > classes is not trivial.
206    </p>
207    <h3 name="Graphical_User_Interface_.2F_XUL">
208      Graphical User Interface / XUL
209    </h3>
210    <p>
211      Most operating systems define their own way to develop grap
 >hical user interfaces, and they are mostly different.
212    </p>
213    <p>
214      For a cross-platform application like Mozilla it is crucial
 > to have a set of technologies that hide the operating system dep
 >endent logic from the application logic.
215    </p>
216    <p>
217      In the past a lot of C/C++ libraries have been coded that w
 >ere cross-platform. To my knowledge, none of them are used in Moz
 >illa, yet we have created our own graphics system.
218    </p>
219    <p>
220      When defining the layout of a GUI (graphical user interface
 >), you can choose to go with either of two possibilities. You cou
 >ld define the absolute positions of each UI (user interface) elem
 >ent that you want to appear. This approach actually has been chos
 >en by a lot of GUI libraries. But it has some drawbacks&nbsp;–&nb
 >sp;you are not very flexible when the layout changes when adding 
 >more elements, because you have to rearrange all elements to new 
 >positions. You also have to do that graphically, to get immediate
 > feedback which elements overlap, etc. But still, the UI might no
 >t look as intended when a different font with different metrics h
 >as to be used&nbsp;–&nbsp;this can make a UI unusable.
221    </p>
222    <p>
223      Mozilla developers wanted to have something very flexible. 
 >As Mozilla is cross-platform, it has to be very flexible with reg
 >ards to fonts.
224    </p>
225    <p>
226      Mozilla developers have chosen to use an approach where the
 > contents of the UI are designed in a logical matter. We don’t cu
 >rrently use an UI editor. We write a file with instructions how t
 >he UI should look. At runtime, the layout engine decides which fo
 >nts are available, and considers all the requests that have been 
 >defined in the UI description, and creates the actual UI dynamica
 >lly. This is similar to what the web browser does when displaying
 > web pages.
227    </p>
228    <p>
229      The web has gone from a mostly text-based system to a very 
 >graphical rich environment that has user interfaces akin to many 
 >programs. Therefore, it was only natural for a web browser to use
 > web languages in order to define its user interface. It was deci
 >ded to use an XML based syntax to write the UI description, which
 > has been called XUL (extensible user-interface language). (A goo
 >d reference for XUL is available at <a class="external" href="htt
 >p://www.xulplanet.com/">XULPlanet</a>).
230    </p>
231    <p>
232      A XUL file describes what elements the UI consists of, and 
 >where elements appear. The XUL language defines attributes that a
 >llow the programmer to define the actions controls react to. To d
 >efine the dynamic behaviour of the application, one can define Ja
 >vaScript functions that will be called when certain user interfac
 >e events happen. Within those JavaScript functions, you can eithe
 >r do the required application behaviour directly, or call any oth
 >er application logic available by COM objects, including logic de
 >fined in C++.
233    </p>
234    <p>
235      In addition to the logical representation of the UI, people
 > also prefer to have a pretty looking UI. To define the detailed 
 >characteristics of the UI, one uses CSS files, that defines, for 
 >example, which images will be used to display certain UI elements
 >. This makes it flexible to define additional “looks” for the app
 >lication, which are referred to as “themes” or “skins”. Mozilla d
 >efines currently two themes, classic and modern, which are active
 >ly maintained by the Mozilla developers. While there exist additi
 >onal themes for Mozilla, they often exist only for certain versio
 >ns of Mozilla. It is a lot of work for a theme designer to stay i
 >n sync with all the changes that happen to the UI each day.
236    </p>
237    <h3 name="Build_System_and_Tree">
238      Build System and Tree
239    </h3>
240    <p>
241      Nowadays Mozilla is mostly used as a group of many shared l
 >ibraries, loaded dynamically at runtime as needed. The COM system
 > allows for a development environment, where you often need to re
 >-compile only a subset of the application when you make changes t
 >o areas of the source code base. This is a very convenient develo
 >pment environment, but it means a slowdown at runtime. On the oth
 >er hand, it is possible to create an executable where Mozilla’s i
 >nternal components are mostly linked statically. Due to the size 
 >of the application, this link step takes a lot of time, and makes
 > most sense when preparing a package for distribution.
242    </p>
243    <p>
244      Each component contains its own directory in the root direc
 >tory of Mozilla. It might also contain subcomponents within it ca
 >lled modules. There are make files throughout the tree which tell
 > Mozilla how to build.
245    </p>
246    <p>
247      Most of the platform-specific code is contained in only a f
 >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
 >re implemented by this code. Only the platform-specific code pert
 >aining to the platform in which the build is occurring is built.
248    </p>
249    <p>
250      Operating system messages are gathered by the platform-spec
 >ific code and then sent to the platform-independent code in the s
 >ame way.
251    </p>
252    <p>
253      Widgets in respect to the Mozilla project are OS-independen
 >t widgets drawn using platform-specific rendering techniques.
254    </p>
255    <p>
256      Within the tree, directories named public usually contain i
 >nterface headers, and directories named src usually contain inter
 >face implementations and non-interface headers.
257    </p>
258    <p>
259      Building this program can be daunting for someone not used 
 >to a project this large. It can take from 20 minutes on a powerfu
 >l workstation to a couple hours on an older PC. First, you have t
 >o get the source, then build it using the rules contained in http
 >://www.mozilla.org/build/. While it’s building, it will move all 
 >the header files to the dist/include directory so that you don’t 
 >have to specify the directory of each header. It will also copy a
 >ll the XUL, graphics, and JavaScript files (collectively called t
 >he chrome) to the chrome directory (a child of the directory cont
 >aining the Mozilla binary). They are mapped to chrome:// URLs as 
 >defined in a file called jar.mn. In release versions of Mozilla, 
 >the chrome directory will only contain .jar files.
260    </p>
261    <p>
262      Building Mozilla is only part of the process. If you want t
 >o develop, you will have to maintain the tree using a program cal
 >led <a class="external" href="http://www.cvshome.org/">CVS</a>. W
 >hen the build fails, you have to solve conflicts that occur when 
 >a merge between a file in your tree and one in the repository fai
 >ls. Also, when you hack the tree, you have to build parts of the 
 >trees you modified. Occasionally, you will have to rebuild the en
 >tire tree using a process called depending, so that dependencies 
 >between source files can be determined. Also, you will occasional
 >ly have to rebuild the tree. Most likely, while you are doing thi
 >s, you will be maintaining your own changes to the tree and tryin
 >g to keep it in sync with others’ changes.
263    </p>
264    <h3 name="Application_Startup">
265      Application Startup
266    </h3>
267    <p>
268      Mozilla’s COM system relies on type libraries and an intern
 >al registry of available components and interfaces. During applic
 >ation startup, a check is being made whether the registry is stil
 >l up to date. If changed libraries are detected, the registry is 
 >updated. Each component is allowed to do initialization during th
 >at registration phase. If changed libraries are detected, they ar
 >e loaded and their initialization logic is executed. Besides chan
 >ged libraries, only those application components are loaded as th
 >ey become required.
269    </p>
270    <h3 name="Internal_Notification_System">
271      Internal Notification System
272    </h3>
273    <p>
274      This section describes an engine that is available inside M
 >ozilla. Most of the time you don’t need it, but if you are requir
 >ed to react to certain events, knowing this system might be helpf
 >ul. The idea of OOP is, you only do your own job. However, it oft
 >en happens that component A needs to react when another component
 > triggers an action in B. But component B should not know the det
 >ails of what needed to happen, because its better to keep parts o
 >f the code separate. What is required here is: If other component
 >s need to react to B’s actions, B should be extended to send out 
 >notifications when its actions are triggered. In addition, B keep
 >s a dynamic list at runtime, where it remembers who wants to be n
 >otified. At runtime, when A becomes initialized, A informs B that
 > it wants to become a member of the notification list.
275    </p>
276    <p>
277      To make this more generic, it has been decided to use a cen
 >tral observer service. When component B triggers an action, it ju
 >st notifies the observer service, specifying a descriptive name o
 >f the event. Components like A subscribe to the observer service 
 >giving the names of events they would like to observe. Using that
 > principle, only the observer service has to deal with lists of c
 >omponents watching for events. When the observer receives notific
 >ation for an event, it passes that notification on to all listeni
 >ng components for that event. Look at nsIObserver for more inform
 >ation.
278    </p>
279    <h3 name="Localization">
280      Localization
281    </h3>
282    <p>
283      Mozilla was designed to separate code from human language. 
 >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
 > JavaScript or C++ file. Instead you define an descriptive identi
 >fier 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 
 >bundle interface to retrieve the actual text. The text itself is 
 >stored in separate files, that only contain text. As Mozilla is m
 >odular, there are a lot of those files, each owned by a separate 
 >module. With that separation, it is easy to have translators crea
 >te different language versions of those text files.
284    </p>
285    <p>
286      When defining the UI, there are two kinds of strings. Some 
 >strings are known at the time the application is compiled and pac
 >kaged, like labels for input fields, or the text that appears wit
 >hin the help system. Other text is assembled dynamically at runti
 >me.
287    </p>
288    <p>
289      Whenever you define text that does not need to be accessed 
 >at runtime, you define it in DTD files. You can refer to that tex
 >t directly in XUL files.
290    </p>
291    <p>
292      If you need to work with text at runtime, for example if yo
 >ur text contains a placeholder for a user name that needs to be f
 >illed at runtime, you define your text in properties files.
293    </p>
294    <h3 name="Coding_and_Review_Rules">
295      Coding and Review Rules
296    </h3>
297    <p>
298      You are free to download Mozilla, change the code, and work
 > with a version that contains your own changes.
299    </p>
300    <p>
301      However, one idea behind open source as used in Mozilla is 
 >the following: You received the source for free, and if you make 
 >changes, you should consider giving something back to the communi
 >ty. By doing so, you become a contributor.
302    </p>
303    <p>
304      But the Mozilla community has decided that it can’t accept 
 >just any change to be integrated into the public central Mozilla 
 >codebase. If you want your code to become a part of it, you need 
 >to follow rules. These rules are not like law, but basically you 
 >must convince people that your change is good.
305    </p>
306    <p>
307      The idea is, a lot of effort has been made to get the Mozil
 >la code to its current state. While the Mozilla code is, like eve
 >ry piece of software, far from being perfect, people try to avoid
 > anything that decreases maintainability, and to only allow code 
 >that seems to be correct.
308    </p>
309    <p>
310      In order to achieve this, the Mozilla community has decided
 > 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
 >eview (r=) from the owner of the code area your are changing. You
 > 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 
 >get what is called super-review (sr=) in most cases. There are on
 >ly a limited number of “Mozilla gurus” that have an accepted repu
 >tation for making good decisions on what code is good and what ne
 >eds to be changed. Once you have both reviews, your code may be c
 >hecked in most of the time. There are other levels of review in c
 >ertain instances, and that is described elsewhere.
311    </p>
312    <p>
313      Many people make changes to Mozilla. While everybody tries 
 >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.
314    </p>
315    <p>
316      If you are developing only on one combination of operating 
 >system and compiler, and you are not paying attention to the port
 >ability rules (read the documents on mozilla.org), it is very eas
 >y to break the tree. You should try your best to not break it, an
 >d getting review hopefully will find potential problems early, be
 >fore the changes are checked in.
317    </p>
318    <p>
319      A broken tree sucks. The Mozilla community has decided on t
 >he rule, that no other check-ins are allowed while the tree is br
 >oken. This is to help people who try to fix the problem. Allowing
 > additional changes would make it even more difficult to find the
 > real cause of a problem, because any new check-in could contain 
 >new problems.
320    </p>
321    <h3 name="Milestones">
322      Milestones
323    </h3>
324    <p>
325      Every several weeks mozilla.org produces a new snapshot of 
 >the source repository. The idea is, people in the world should tr
 >y out the current snapshot, and report any problems (bugs) they f
 >ind. However, mozilla.org wants to emphasize that these milestone
 >s are being produced for testing purposes only.
326    </p>
327    <p>
328      In order to prepare a more stable milestone, the rules for 
 >making changes to the source code repository get more restrictive
 > prior to producing a new milestone. mozilla.org defines a schedu
 >le, and a couple of days before a milestone date, only those chec
 >k-ins are allowed that have been approved by the mozilla.org “dri
 >vers”. Drivers are a bunch of people who have the highest authori
 >ty regarding the Mozilla repository. The drivers will also decide
 > whether the milestone seems ready, or whether the schedule will 
 >be delayed in order to allow more fixes to be produced, that will
 > make it more stable.
329    </p>
330    <h3 name="Bugzilla">
331      Bugzilla
332    </h3>
333    <p>
334      <a class="external" href="http://bugzilla.mozilla.org/">Bug
 >zilla</a> is mozilla.org’s web based bug tracking system. Wheneve
 >r a problem is encountered, people are asked to file a new bug (s
 >ometimes also known as problem ticket), with a good description o
 >f what happened. You will then be issued a bug or ticket number. 
 >This number will be used when people talk about the problem. Deve
 >lopers will subscribe to the “bug” and add comments to it, and if
 > they know a fix, they will attach a patch to show how they sugge
 >st to fix the problem. Reviews will also be tracked within this s
 >ystem.
335    </p>
336    <p>
337      The term “bug” is most often referred to as a software erro
 >r. However, within Bugzilla, a bug can be anything that needs to 
 >be tracked. This ranges from software errors to enhancement reque
 >sts. For example, the evolution of this document is tracked in <a
 > class="external" href="http://bugzilla.mozilla.org/show_bug.cgi?
 >id=123230">bug #123230</a>.
338    </p>
339    <p>
340      If you are not a C++ developer, you can also work on Bugzil
 >la. It started out as a simple bug reporting tool and has turned 
 >into quite a functional, complex system that has many users from 
 >other projects (such as <a class="external" href="http://www.redh
 >at.com/">Redhat</a>).
341    </p>
342    <h3 name="Webtools_.2F_LXR_.2F_Bonsai">
343      Webtools / LXR / Bonsai
344    </h3>
345    <p>
346      Webtools are server based tools that store information, and
 > allow their information to be displayed and maybe even manipulat
 >ed. You access such systems using a web browser, e.g. Mozilla.
347    </p>
348    <p>
349      Mozilla developers have created several tools in order to m
 >ake their life easier. We have already talked about Bugzilla.
350    </p>
351    <p>
352      <a class="external" href="http://lxr.mozilla.org/">LXR</a> 
 >is a hypertext search engine for the Mozilla source code. You can
 > look up identifiers and text, and you will see where in Mozilla 
 >it is used. Clicking on search result entries will directly bring
 > you to current source code. The code is shown in a web page, and
 > identifiers are hyperlinks, which, when clicked, will bring you 
 >the LXR search result for that identifier. You can use LXR to bro
 >wse the source code and quickly navigate through it. It is based 
 >of the Linux project’s glimpse engine with internal modifications
 >.
353    </p>
354    <p>
355      <a class="external" href="http://tinderbox.mozilla.org/">Ti
 >nderbox</a> is a tool that shows the current state of the source 
 >repository. mozilla.org hosts several machines for many different
 > operating systems, that repeatedly and constantly obtain (check 
 >out) the newest source code from the central repository, and try 
 >to compile it. When finished with compiling, some automated tests
 > are executed to check, whether the program still works correctly
 >. The results of compilation and tests are reported to the centra
 >l tinderbox system. When you access the tinderbox page, you can s
 >ee whether the source code repository is currently in good condit
 >ion, and how things changed in the past few hours. Tinderbox show
 >s a graph, where time is shown vertically and the different machi
 >nes / operating systems are displayed horizontally. Each compilat
 >ion test phase is represented by a bar, defined by the required t
 >ime for building.
356    </p>
357    <p>
358      The bar is filled with a color. Green means good. Yellow me
 >ans, compilation is still in progress, orange means compilation a
 >nd building were successful, but one of the automated tests faile
 >d. Red means, the source code did not even compile. If the tree i
 >s red, it slows down development.
359    </p>
360    <p>
361      Tinderbox is a very helpful tool, and everybody making chan
 >ges to the source repository is expected to “watch the tree”, i.e
 >. watch whether your changes cause anything to fail.
362    </p>
363    <p>
364      To assist you more, additional information is available on 
 >the tinderbox page. As people check in, their names appear on the
 > page. There is a link to a list of changes they have made. If a 
 >compilation or test failed, the box will contain links to the out
 >put from the compiler, which should show the reason for failure. 
 >Additional text on the page shows the results of performance meas
 >urement.
365    </p>
366    <p>
367      Another web tool is <a class="external" href="http://bonsai
 >.mozilla.org/">Bonsai</a>. Bonsai tracks all changes made to the 
 >source repository. You can retrieve a listing of all changes made
 > by people. It also provides a powerful interface to query the li
 >st of changes.
368    </p>
369    <h3 name="Finding_more_information">
370      Finding more information
371    </h3>
372    <p>
373      If you want to learn more about the mentioned programming t
 >echniques in general, I recommend searching the web for free docu
 >ments. Hopefully the mentioned terms in this document will guide 
 >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
 >entrate on some particular operating system.
374    </p>
375    <p>
376      Most documentation regarding to Mozilla development is publ
 >ished on the www.mozilla.org web site. If you can’t find what you
 > are looking for, try to use a search engine. Some popular search
 > engines offer an advanced search option, where one can limit the
 > search to a specific web site.
377    </p>

Back to History