Tài liệu Appendix B. Development Tools- P1 pdf

Appendix B. Development Tools- P1
This book describes how to create applications using Mozilla. Generally, all
parts that go into an application (including XUL, CSS, XBL, and DTD files)
need to be built by hand since no complete ready-made development tools or
development applications are available that would make these manual
processes easier.
Creating all these files by hand is a great way to familiarize yourself with the
way Mozilla works, and becoming more familiar with the inner workings of
a Mozilla application certainly helps you see how the various parts fit
together. Once you are comfortable creating these files by hand, using the
platform becomes much easier and Mozilla fulfills its promise as a rich
application development framework.
Development tools are important, though, and platforms like Mozilla can't
obtain the sort of developer base they deserve until tools that make
application creation easier are available. Although some people want to learn
everything there is to know about creating applications with Mozilla, many
simply want to create something without a lot of fuss.
Mozilla does not yet have a full set of development tools, but currently
several development projects help with part of the application creation
process. These tools don't make up a full-featured development
environment, but they are useful. They also point the way to an area in
Mozilla development that has a bright future and is worth watching.
This appendix describes some of the new tools including XULKit, Patch
Maker, the DOM Inspector, the JavaScript Debugger, and MozillaTranslator
that are already becoming a part of the regular repertoire of Mozilla
developers. By learning about how to use these tools for your own project,
you can radically simplify the application development process, especially
when you combine these tools.
B.1. XULKit
Much of the manual editing described in Chapters Chapter 6
, Chapter 7, and

Chapter 8
can be automated with special scripts and templates being
developed in the Mozilla source tree's tools/wizards section (these
files are referred to collectively as the XULKit and can be found at

These tools help you develop your Mozilla application by generating as
much of the basic content, structure, and packaging of an application as
possible, leaving you free to work only on the aspects of your application
that you care about. We mention XULKit first because it can make setting
up new Mozilla applications a snap.
XULKit is essentially a set of two scripts: new-from-template.pl,
which creates a new application framework, and makexpi.pl, which
packages your application once you finish developing it.
B.1.1. new-from-template.pl Script
Though it's not named very elegantly, the new-from-template.pl Perl
script takes information you provide in the form of a simple text file and
uses it to create various parts of a Mozilla application. These parts include
the XUL content, which has a basic menubar you can add to; an overlay that
puts an item for your application into the Tools menu in the Mozilla
browser; CSS for your XUL; and an installation script for the application
package. You can base your application off of a couple of different
templates, including a sophisticated one that lets you generate XPCOM
interfaces for components you wish to use in your application, described
below.
Using these scripts, you can add content and logic to your application,
restyle it, or build your application however you would like. You can also
register the resulting directory with the chrome registry to see it working in
your local copy of Mozilla, and when you finish developing it, the
application directory is already structured in exactly the way it must be to be
checked into the Mozilla source tree's extensions directory (if you want to

check it into this common location for applications that become a part of
Mozilla). When you want to distribute your application as described in
Chapter 6
, you can use the other script in the XULKit, makexpi.pl, to
package your application files into a cross-platform archive that can be
installed from a regular web page.
To use the new-from-template.pl script, point it at a template that
you filled out with your own information. It then generates the basic
application code in the appropriate subdirectory structure:
new-from-template.pl -t FILE [-o DIRECTORY] [-
f[d]] [-h] [-?]
When you run the script, the XULKit creates a new top-level application
directory. In this directory, the script creates the three main package
directories, and it places some basic content in each one: a CSS file called
mozreg.css in the skins subdirectory, a few XUL files in the
content directory (including the overlay that defines a new menu item for
the main browser that opens this new application), and localizable data in the
mozref.dtd file in the locale subdirectory.
In addition to these files, the XULKit script creates contents.rdf files
that describe each package, some Makefiles that instruct the Mozilla build
process how to integrate this application into the build (which is a later step
and not necessary to run the application), and an install.js file that
executes the installation of this application when it appears in a XPI. (See
Chapter 6
for more information about XPI, Mozilla's cross-platform
installation file format.)
If you look at Example B-1 xul-app.tpl, which comes with the
distribution of new-from-template.pl you can see how easy it is to
fill out the basic information and create your own template.
Example B-1. Sample application template

# load default template for a XUL app
include "${top_wizard_dir}templates/xul-app.tpl"
# short app name (can not contain spaces.)
# until

is fixed, this needs
# to be all lowercase.
app_name_short=xulsample
# long app name (spaces are OK.)
app_name_long=Sample XUL Application (generated
from sample.xul-app.tpl)
# name as it should appear in the menu
app_name_menu=Sample XUL App
# version to tell the .xpi installer
app_version=1.0
# author, used in various chrome and app
registration calls
app_author=mozilla.org
# size of the package when installed, in kilobytes.
# this number is used by the install.js script to
check for enough disk space
# before the .xpi is installed. You can just guess
for now, or put 1, and fix it
# in install.js before you make your .xpi file.
install_size_kilobytes=1
You can adapt the xul-app.tpl for your own purposes or use the
sample.xul-app.tpl that is already filled out. Table B-1 details
different options for new-from-template.pl.
Table B-1. Options for the new-from-template.pl script
Option Description

-d
Recursively deletes the output
directory before starting; requires the
-f option.
Option Description
-f
Forces file overwriting in the output
directory.
-h
Displays a description of the
specified template with -o. The
template will not be processed. The
template description is taken from the
value of the template_description
variable in the template file.
template_descriptions provided by
the main template file's template
file(s) are not displayed.
-o DIRECTORY
Generates the template into the
directory specified by DIRECTORY.
If this directory already exists, new-
from-template.pl will fail. This
failure prevents you from
accidentally overwriting an existing
application. Use the -f option to
continue anyway. Use -fd to force
DIRECTORY to be deleted before the
template is processed.
Option Description

-t TEMPLATE
Processes the template specified by
TEMPLATE. This file is usually in the
my/ sub-directory, ending in .tpl.
-?
Shows usage information and exits.
B.1.1.1. XULKit templates
Two different application templates come with new-from-
template.tpl, each with its own empty and sample versions. Example
B-1 shows sample.xul-app.tpl in its entirety. The other template,
xpcom-component.tpl, uses information you supply to create the
framework for an XPCOM component. As with xul-app.tpl, the
template comes with a sample that's already filled out.
This script creates an IDL file, a header file, and a stubbed-out CPP file in an
application subdirectory structure you can use to begin coding your XPCOM
component. In the xpcom-component.tpl, many variables do not need
to be changed, but required fields are set aside in the template:
# variables the user's .tpl file MUST declare
required_variables = ${component_name},
${implementation_guid}, \
${interface_name},
${interface_guid}
Using this script, you can fill out a subset of the template with the
information XPCOM requires, and XPCOM will generate the basic files you
need, as Example B-2 shows.
Example B-2. Sample XPCOM component template
# include default values
include "${top_wizard_dir}templates/xpcom-
component.tpl"
component_name = SampleComponent

implementation_guid = c6793b0c-1dd1-11b2-a246-
92bf95c9d097
interface_name = tstISampleComponent
interface_guid = d03ea960-1dd1-11b2-9682-
81ecad6a042a
B.1.2. makexpi.pl Script
In addition to the template-generating script described above, a second script
takes your working application and creates an installable package, or XPI,
out of it. This way, you can distribute it to others in the same way the
various components of the Mozilla browser are distributed and installed
when you use the Mozilla installer.
This script, makexpi.pl, takes an application directory as input and
generates an XPI archive. It also manifests for various parts of your
application, the installation script that goes inside this archive, and even the
installation web page itself. While new-from-template.pl is designed
to help you start your application, makexpi.pl takes your locally
developed application and makes it into a package that can be distributed to
other users and installed via the Web.
To use makexpi.pl, point it at a configuration file that you have edited to
point at your application directory:
makexpi.pl [-c <config-file>] [-d] [-r
<revision>] [-?]
For example, to create a XPI out of your MyApp application directory, in
which you created a file called MyApp.conf that defines the variables
makexpi.pl needs, execute the script as follows:
perl makexpi.pl -c ~/appdev/MyApp/makexpi.conf -r
0.9.9
A makexpi.conf file defines the variables makexpi.pl needs to know
about. Example B-3 shows an example of this file.
Example B-3. makexpi.conf file

# directory where xpi should be created
workdir = /home/rginda/src/xulkit/sample-app/
# directory where jar.mn is
mndir = ${workdir}/sampleapp/resources/
# location of templatized install.js file
installfile =
${xulkit_dir}/templates/xpi/install.js
# directory where mozilla's make-jars.pl and
friends are
mozcfgdir = ${xulkit_dir}/bin/
# name of resulting xpi file
xpifile = ${app_name_short}-${revision}.xpi
Table B-2 lists the options that are recognized by makexpi.pl.
Table B-2. Options for the makexpi.pl script
Options Description
-c FILE
Specifies the configuration file to use.
-d
Doesn't remake the JAR, but
packages the existing contents of the
chrome/ directory as an XPI.
-r REVISION
Specifies the value of the ${revision}
variable. This specification overrides
any value specified in the
configuration file and defaults to
"0.01". Typically, this number is used
in the install.js script and as
part of the XPI filename.
-?

Shows usage information and exits.
When you run the script against the configuration file, you end up with two
separate pieces the XPI in which your application and its installation script
are stored and a web page that you can post on a server to guide the XPI's
installation. As described in Chapter 6
, the web page interacts with the XPI's
install.js to install and register your application in Mozilla. If you start
your application with the new-from-template.pl script, then a
template-processed version of install.js that works with your
application is included as templates/xpi/install.js as part of the
XULKit package.
B.1.3. Using XULKit
Given these two scripts and the templates that go with them, the XULKit
encourages and makes the following application development workflow
possible:
1. Fill out a new-from-template.pl template with your
application information.
2. Run the new-from-template.pl script to generate the
application directory.
3. Register your application in flat mode: as a directory in your local
copy of Mozilla.
4. Develop your application: the XUL content, the CSS, the application
code in JS, etc.
5. Test the application code.
6. Run makexpi.pl against your working application to create an
installable package.
7. Put the XPI and the web page up on a server to create an install for
your application.
That's it!

B.2. Patch Maker 2.0
Patch Maker is a free software program written by Gervase Markham that
lets you change and improve Mozilla's user interface by using only a nightly
build.
When you don't build the Mozilla source tree yourself, finding and getting to
the files that need to be edited in Mozilla can be difficult. However, you can
use the various Patch Maker commands in Build Mode to extract files from
the right JARs, add them to your Patch Maker project, edit them, and create
the patches, all in an integrated and easily traceable way. These patches can
then be submitted back to mozilla.org so that developers working in the
source tree can apply and test them. See the Section B.2.2
section later in
this appendix for more information about using Patch Maker in this way.
This process is possible because Mozilla's user interface is written in XUL,
JavaScript, and CSS, and interpreted at runtime. Because understanding
CVS or compiling code isn't necessary, Patch Maker greatly lowers the
barrier to entry for contributing code to Mozilla. Significant patches, such as
one used for draggable toolbars, are made using this tool.
Patch Maker runs under Linux and Windows, and is experimental on Mac
OS X. The latest version of Patch Maker is at
This application can be used in
one of two modes. CVS mode is used by developers who develop and
maintain code in a CVS tree and make their changes in the tree. Build mode
makes it possible to produce patches that fix some bugs in Mozilla without
downloading and compiling the source.
B.2.1. CVS Mode
In CVS mode, Patch Maker manages and tracks multiple patches to a bit of
software. It uses unique tags (patch references such as bug numbers) to
separate patches, knows what files are in each patch, and can perform
operations on them. In CVS mode, Patch Maker can greatly speed up the

process of creating, diffing, uploading, refreshing, and checking in a patch.
CVS mode's basic commands for Patch Maker give you an idea of how
developers working in the Mozilla source tree can use it to work more
efficiently with patches and diffs. The basic CVS mode commands are
described in Table B-3.
Table B-3. Patch Maker's CVS mode commands
Command Description
pmlist
Shows the file list.
pmadd <filename>
Adds filename to the file list.
pmremove
<filename>
Removes filename from the file list.
pmdiff
Does a cvs diff -u of all files in the file list.
Extra arguments, such as -w, are passed through
to diff. This command won't clobber your old
diff if the new one has a size of zero.
pmview
Brings up your diff in an editor window.
pmupdate
Updates CVS on all files in the file list. Extra
Command Description
arguments to this command are passed through
to the CVS update.
pmpatch
Patches your diff into your CVS tree. Takes a -R
to back the patch out again.
pmedit <pattern>

Brings up files matching the pattern in your
editor. The pattern is a glob, not a regexp. If
there are no arguments supplied, then all files are
opened.
pmwhich
Prints the current patch reference.
pmswitch
<patchref>
Changes Patch Maker to work with a new patch
reference. It automatically creates a
pmupdate( ) and a pmpatch( ) (which
won't have any effect if the patch is already
applied.)
pmgrep <pattern>
Greps for pattern in all of the current patch's
files. Good if you can't remember where you put
some code.
pmcopy
Copies all files in the file list to their positions in
your installed Mozilla tree. Takes a -f argument
to force copying of all the files.
Command Description
pmsetpath
Points Patch Maker to your current Mozilla-built
installation's chrome directory. Use
/usr/src/mozilla/dist/bin/chrome/
if you build yourself.
pmunjar
Unjars the chrome in your setpath installation.
pmexecute

Runs the executable in the setpath installation.
Extra arguments to this command, such as &, are
passed through to the executable.
pmcheckin
Runs pmwhich, pmupdate, pmdiff, and
pmview to show what you are about to change,
and then asks you if you really want to check in.
pmcvsadd
Does a CVS add of all files. Previously added
files fail with a harmless message. You need to
use this command for new files so the CVS diff
will work properly.
See the CVS Mode instructions at the Patch Maker web site for instructions
on how to use Patch Maker with your source tree.
B.2.2. Build Mode
The fact that Mozilla's user interface is interpreted at runtime rather than
compile time makes it possible to change the interface and see your changes
in the browser. In Build mode, Patch Maker can help you make these
changes and apply, package, and send them to the developers who own the
interface modules you edit. The Patch Maker's Build mode is a boon for
Mozilla developers who do not build the CVS tree, but who want to take part
in developing the interface, in the bug-fixing process, and in other aspects of
Mozilla development.
In Mozilla-specific mode, which is triggered when you sit in a Mozilla build
install point's chrome directory, you can make patches to Mozilla chrome
without using a CVS tree. Patch Maker can cope with multiple patches and
has a notion of the "current patch" the one you are working on at the
moment. Patches are identified by a patch reference, or patchref, which is
any combination of characters that make a legal filename on your platform.
Bug numbers make very good patchrefs. You can add and remove files from

Patch Maker's internal list of files that comprise the current patch.
B.2.2.1. Using Patch Maker in Build mode
Here are the steps to use Patch Maker in Build mode (flip the slashes in
these paths if you are on Windows):
1. Set up Patch Maker (see the installation instructions at

2. Change to the chrome directory of a Mozilla nightly build.
3. Execute pmuj to unjar your chrome.
4. Run Mozilla ( /mozilla) to see if it still works. Turn off the XUL
cache in the Debug > Networking preferences and quit Mozilla.
5. Execute pms test. Patch Maker will tell you that you are working
on patch "test."
6. Confirm this with pmw.
7. Execute pml. Note that no files are currently in your patch.
8. Execute pma content/navigator/navigator.xul to add
navigator.xul to your patch.
9. Execute pml again and see if it was added. Experiment with pma and
pmr if you like.
10. Execute pme. Notice that navigator.xul appears in your editor.
Try pme foo to make sure you have no files that match "foo."
11. Change navigator.xul e.g., search for "&mainWindow.title;"
and replace that string with "MyBrowser." Save this file.
12. Run Mozilla ( /mozilla).
13. You should have a Mozilla titled "MyBrowser."
14. Edit the file again to make it "YourBrowser." Save the file.
15. Press Ctrl-N in your Mozilla window. The new window should be
titled "YourBrowser."
16. Execute pmd and pmv. You should now have an editor window with a
unified diff showing the changes you made.
17. You could attach your patch to a Bugzilla bug by fishing the CVS

version (test.diff) out of your Patch Maker data directory.