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

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 application

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

http://www.hacksrus.com/~ginda/xulkit/doc/)

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

http://bugzilla.mozilla.org/show_bug.cgi?id=75670

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

http://www.gerv.net/software/patch-maker/ 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