Tài liệu Appendix A. Getting and Building the Mozilla Source doc

Getting and Building the Mozilla Source One of the best things about using Mozilla as an application development framework is that you don't need to get involved with the Mozilla source

Appendix A Getting and Building the Mozilla Source

One of the best things about using Mozilla as an application development framework is that you don't need to get involved with the Mozilla source code to create a Mozilla application A simple Mozilla binary that you

download and install is the only development platform you need You can create and use most procedures and samples described in this book with a precompiled version of the browser

The best way to get a working version of Mozilla quickly is to download a precompiled binary for your platform If you go to the mozilla.org

homepage, you will find links to Mozilla's most recent stable milestone build for each platform and a link to the nightly development snapshot builds These binaries come as compressed archives or with an installer, and you can use either to run Mozilla on your computer within a few minutes These binaries don't include the source for Mozilla (unless you count the XUL, CSS, and JavaScript that made up the front end, which are always available),

so read on if you want to obtain the code

Under the relevant license terms, the Mozilla source code is freely available

to anyone who has an Internet connection and a desire to explore You may want to look at this code out of curiosity or dive into the code as you figure out how it works and can be improved Whatever your reasons are for

looking at the Mozilla source, it is not much more difficult to get the code and build it yourself than it is to download the precompiled binaries To get started, you need to know a few things about how to get and use the source

A.1 Getting the Source Code

You can get the Mozilla source code in a few different ways Depending on what you are interested in doing, one method may work better for you than another This appendix provides basic information about how to get the source, but you can also find information about this topic on the Mozilla site

at http://www.mozilla.org/source.html

If you want to look at the source code and don't intend to recompile it,

experiment with it, or update it at all, the best way to get at the source is to browse the Mozilla code base with Mozilla Cross Reference (LXR) As you can see in Figure A-1, LXR is a web-based source code browsing tool

located at http://lxr.mozilla.org LXR is also hooked up to other tools, such

as Bonsai (http://bonsai.mozilla.org) and the various tinderboxen

(http://tinderbox.mozilla.org/showbuilds.cgi) Together, these tools create a powerful code maintenance system that is used widely by Mozilla

developers

Figure A-1 Mozilla Cross Reference code browsing tool

A.1.1 Downloading the Source with FTP

If you would like to get your hands on the code directly, use either File

Transfer Protocol (FTP) or Concurrent Versioning System (CVS) to grab the

source from the Mozilla site Many people prefer to start by grabbing an

archive of the source code by FTP and then working with CVS as they

modify the code

If you're sure you won't check your work back into Mozilla and you just want to get the source, using FTP is the easiest way to do so The main FTP server is at ftp://ftp.mozilla.org/ (a list of FTP mirrors is available on the mozilla.org site) To download a particular version of Mozilla, go to either /pub/mozilla/nightly/latest/ or

/pub/mozilla/releases/, depending on which build you would like

to have

When you download the source from the releases directory, you get the code for the most recent Mozilla milestone These releases are versions of Mozilla that have been tested and approved by developers at mozilla.org Milestones come out about once a month and have some implied stability The code in the "latest" directory is for the version of Mozilla currently under

development This code is not tested and stability is not guaranteed In fact, the latest code may not even work if something that was checked in recently breaks Mozilla

A.1.2 Downloading the Source with CVS

Grabbing the source with CVS requires additional steps to get things set up properly, but for many, it's worth the effort If you would like to contribute your own changes back to the community, you must understand how CVS works Pulling the source in this manner is a good way to start learning about Mozilla development

For a quick understanding of CVS, you can obtain a copy of the CVS Pocket Reference (O'Reilly) To pick up a binary distribution of CVS if it isn't

already installed, go to http://www.cvshome.org/downloads.html, where you'll also find links to documentation

Using CVS requires logging into the Mozilla site by using a CVS client, checking out the source code, modifying the source code locally, and then checking the code back into the tree Anyone is free to check out the code, but you need special permission to check in the changes you make to the source This chapter discusses only how to check out the source with CVS

You first need a CVS client Free CVS clients are available for most

operating systems, including WinCVS on Windows and MacCVS for the Mac Linux has a command-line CVS client that should come standard on most Linux distributions Here are instructions for using the Linux

command-line client to check out the source code:

1 Set the CVSROOT variable:

On Windows, the command-line interface used to obtain the Mozilla source

is very similar You just need to make a few small changes to the steps above for a Windows install Here are the steps listed for comparison:

1 Set the CVSROOT variable:

> make -f client.mk checkout

In Step 1, set the CVSROOT environment variable using the set command Use the GNU make utility (make) on Windows just as you would on Unix

Building using nmake is no longer supported on the Mozilla

development trunk, though there is a document describing this process for developers using older branches at

http://www.mozilla.org/build/win32-nmake.html

Before you pull the source code, check the tree status in the relevant

Tinderbox Grab the source only if the tree is green (success) or yellow

(building) Do not pull the source on red, which indicates that the build is broken

To pull the Mozilla source code on Macintosh, use a client like MacCVS, which automates much of the CVS process for you Mac OSX users can use the standard command-line CVS client and pull the source using a method similar to checking out the source in a Unix environment Also be sure to include the required resources XML Perl modules, MacPerl, or the

CodeWarrior development environment which are all listed later in Table A-1

The MacCVS client works with session files, which have all the information and settings you need to pull Mozilla The settings are listed on the

mozilla.org Mac build page, which even has a ready-made session file that you can download into the client Once you set your tools up and configure your session file for MacCVS, you can pull the Mozilla source by choosing

"Check Out Default Module" from the MacCVS Action menu Like the Macintosh build process, pulling the source on Macintosh involves the interaction of a series of Perl scripts The PullMozilla.pl script,

located with the other Macintosh build scripts in

mozilla/build/mac/build_scripts, can drive your MacCVS client starting it

up and pointing to the right source, setting the proper variables, and so on For more information on the Macintosh build scripts, see

http://www.mozilla.org/build/mac-build-system.html

A.1.3 Working with Branching

Branches are distinct Mozilla source code trees that are "cut" to carry out a specific purpose or used for a milestone release Developers cut branches when making large architectural changes that could make the main tree

unstable Branches in this context allow freer changing and testing off the

main trunk To work with branches, set the MOZ_BRANCH environment

variable:

> setenv MOZ_BRANCH=MOZILLA_1_0_BRANCH

The value changes according to the repository with which you work All

other steps can remain the same in the process

To find out more about using CVS to get Mozilla source and to learn about

what else you can do with CVS, go to http://www.mozilla.org/cvs.html

A.2 Building the Source Code

Now that you have the Mozilla source code, what do you do with it? Unlike

the Mozilla binaries that are available for download, you can not start using

Mozilla once you have all the source code on your computer Before you can start using the source, you need to set up your working environment and

then build Mozilla

For the Mozilla source to compile on your computer properly, two main

aspects of your build environment must be set up These aspects are the

necessary tools and the proper environment variables You would expect

such a large code base to require a large number of tools, but there aren't so

many Table A-1 lists the tools you need to build and run the source code

All information here is presented in more detail at

http://www.mozilla.org/build/, including links for getting the tools

Table A-1 Platform tools used to build the Mozilla source code

Linux Windows Macintosh

egcs 1.0.3 (or higher),

gcc 2.95.2

Microsoft Visual C++

Version 6.0 or later (with service pack 3)

Code Warrior Pro 7 (including Plugin SDK)

GTK+ / Glib 1.2.0

Cygnus toolkit for Windows (the build page lists the specific components)

Menu Sharing Toolkit 1.4

GNU make 3.74

Netscape Wintools (modified versions of gmake, shmsdos, and uname)

Perl Launch module

zip 2.3 (or higher) Zip for Win32

Compress:Zlib module

Archive::Zip module

LibIDL 0.6.3 (or higher) (Required for static

Linux Windows Macintosh

The Linux environment is usually set up by default with all the tools listed

for that platform; it therefore requires less time to retrieve and set up

programs Linux distributions usually come with a native compiler that is

compatible with the Mozilla build system Most build time is used compiling the C++ source code the language most files are written in Therefore, the

compiler is the central component of the build system Linux uses egcs or

gcc, Windows uses Microsoft Visual C++, and Macintosh uses Metroworks

Code Warrior The latest version of CVS for each platform accompanies all

tools listed in Table A-1

You can set various environment settings for each platform to configure and optimize your build environment Most settings are optional and some are

essential One essential is the CVSROOT variable, which tells the CVS

server where to look for the tree's home or root The next section looks at the differences between the Unix, Windows, and Macintosh platforms

A.2.1 Unix Environment

Unix is probably the easiest platform to configure In fact, because it's a

developer's platform, it is designed to work with little or no user interaction

In the source tree, script is provided to do all the work for you To run it, you need only the following steps:

> cd mozilla

> /configure

Running this command gathers all necessary system information and the list

of Makefiles needed to compile the source This command needs to be run only when a Makefile is added or removed from the tree After this, it is sufficient to compile Mozilla by launching gmake with no arguments

Alternatively, you can use the Unix Build Configurator, an online tool

(http://webtools.mozilla.org/build/config.cgi) that lets you change certain settings if you run into any obstacles when building It allows setting

external package configuration, a choice of Mozilla components, and

debugging and optimization options Once this setting is made, let Mozilla take over via the client.mk script:

> gmake -f client.mk

One useful post-build setting is the ability to run Mozilla from any directory

(rather than just dist/bin) To test this option, use

MOZILLA_FIVE_HOME to point to the full path, to the dist/bin, or wherever your executable resides

A.2.2 Windows Environment

The setup is different on Windows and requires more interaction on the user's part, mostly in setting up environment variables Table A-2 lists these variables and expected values Note that some values are optional

Table A-2 Windows environment variables used to build Mozilla

Variable Value Descripti

on

Specifies whether you use a 16-bit or 32-bit operating system

MOZ_DEBUG 1 (optional)

Set only if you want

a build with debug informatio

n

Remove this variable to enable it

by default

MOZ_SRC <path to top of source tree>

The directory into which

Variable Value Descripti

on

you uncompre

ss or check out the

Mozilla source Ensure that the path does not end with a trailing slash (\)

MOZ_TOOLS <usually the Cygwin root

directory>

The directory where gmake is installed, usually placed there by the

Variable Value Descripti

on

wintools.z

ip package (refer to

on for the operating system that is also used

internally

by the OS Windows

2000 takes

a value of WINNT

It matches the top-level directory

on the

Variable Value Descripti

on

filesystem that

contains all OS files

A Mozilla representation of the OS_TARGET

variable

_MSC_VER 1200 (or 1100 for VC++ 5)

The version of the

Microsoft Visual C++ runtime environme

nt running

on your machine

Variable Value Descripti

on

The value

of 1200 is Version 6, the most reliable version

DISABLE_TESTS 1 (Optional)

Set only if you do not want to build test directories and

binaries Remove this variable to leave it enabled

by default

MOZ_DISABLE_JAR_PAC

Set only if you want

to turn off

Variable Value Descripti

on

compressi

on into the chrome structure's JAR files Remove this variable to leave it enabled

by default

MOZ_CONFIG <path to config file>

This variable is required only for gmake builds

PATH

%PATH%;%MOZ_TOOLS%\bin;c:\cygwin

The PATH variable is

an existing variable

Variable Value Descripti

on

that needs the

Cygwin root and binary directories appended The

operating system looks at this variable when looking for program executable

s and DLLs

You can set these variables either by using the set command for per

session variables or the System > Advanced > Environment Variable panel

in Control Panel to set them more permanently

Once your environment is set and the tools are in place, you can begin

the build Go to the mozilla directory in the source code and from

there, run the make script (client.mk) with the necessary arguments:

>make -f client.mk build_all

Once your environment is set and the tools are in place, building can begin

Go to the mozilla directory in the source code and from there, run the

make script (client.mak) with the necessary arguments:

> nmake -f client.mak build_all

Table A-3 lists these arguments and what they do Leaving out this compile

flag starts an incremental build or a fresh build if there is no previous build

available

When building incrementally, try to use the provided make script instead of

the cvs checkout and build_all commands The latter command can

lead to inconsistencies in file versions and may re-download files that you

do not even need to your tree

Table A-3 Make flags

Flag Function

pull_all Gets only the source code

build_all Builds only the existing source code

pull_and_build_all Retrieves the source code and then

builds it