Skip to main content

Building Mozilla on Microsoft Windows 32-bit Platforms

Daniel Nunes, leaf@mozilla.org

How to build Mozilla on a Microsoft Windows System.

1. Introduction

2. Building Mozilla

3. Common Problems and Hints

4. Win32 Debugging FAQ

1. Introduction

This document is a guide to building Mozilla on Windows platforms. The Windows build uses a UNIX emulator for Windows, cygwin, to control the build process, and command line tools from Microsoft's Visual C++ to build its source files. Mozilla uses a variety of tools and scripting languages during its build process, including makefiles, shell scripts, xpidl and perl scripts.

Mozilla is large and complex. It may be necessary for you to solve configuration and version problems to build it. We regret any inconvenience, and if you have problems, please report them.

If you're looking for documentation on developing features or fixing bugs, the Mozilla Hacking Documents are probably what you're looking for.

Historical note: Building using nmake is no longer supported on the main trunk. The nmake build instructions are still available for developers using older branches such as the Mozilla 1.0 branch.  For the Mozilla 1.0 branch, the nmake build is the recommended build system.

2. Building Mozilla

Here are the requirements and steps to build Mozilla.

2.1 Hardware and OS Requirements

Mozilla takes time to build. You will want a development class system.

  • Pentium or equivalent processor, 266 MHz or better, 600MHz+ recommended
  • 128 MB RAM, 512 MB recommended
  • 1.5 GB NTFS or 3 GB FAT disk space, or more
  • NT 3.51, NT 4.0, Win95, Win98, Win2000 (preferred), or WinXP.

2.2 Software Installation

The following software needs to be installed for a standard Windows build.

Mozilla may not build if some tools are installed at a path that contains spaces or other breaking characters such as pluses, quotation marks, or meta characters. This does not apply to Visual C++ tools.

cvs for Windows

You do not need cvs, the source control system used by Mozilla, if you are only going to build from source tarballs gotten by ftp. If so, you may skip this step.

To pull Mozilla sources, cvs version 1.10 or higher is required. You may use either a Windows or a UNIX-like version of cvs.

If you wish to use WinCVS, download it from http://www.cvshome.org/dev/codewindow.html.

WinCVS is recommended if you wish to use notepad.exe or another standard Windows program to edit cvs commit comments. If you want to use editors that only understand DOS path names, then you must use WinCVS.

You may use the cvs in cygwin instead. The editor and cvs packages can be installed with cygwin. The cygwin version of cvs will work ONLY if you pull a fresh tree using cygwin cvs; see Common Problems for details.

GNU Tools for Microsoft Windows (Cygwin)

cygwin is a UNIX-like environment for Windows, free from Red Hat. Mozilla uses a developer set of cygwin packages, which must be installed. These include gawk, make and zip utilities. GCC is not used and does not need to be installed.

You must have cygwin 1.1.6 or higher. b20.x will not build Mozilla.

Go to http://www.cygwin.com/ and follow the installation instructions. The cygwin installer wizard runs as a Windows program. One page of the wizard presents an outline view of categories and packages. You must add packages beyond the default set.

If you'll be using cygwin only to build Mozilla, then install only the default packages and the packages needed by Mozilla. In the version of the installer current at this writing, the non-default packages are found under the categories Devel, Interpreters, and Archive: make (under Devel), perl and gawk (under Interpreters), and unzip and zip (under Archive). These categories are subject to change.

If you may be using cygwin's UNIX-like tools for additional development, then install the editors, developer tools and interpreters, as well as anything else that looks interesting. Make sure you get all the packages Mozilla needs too, such as unzip and zip!

Here is the complete cygwin package list for building Mozilla. You can use it to double-check your packages, or to understand and customize the build process.

  • ash -- UNIX-like command line interpreter shell
  • diffutils -- file comparison utility
  • fileutils
  • findutils
  • gawk -- pattern matching language (Devel category)
  • grep -- text search tool
  • make -- dependency analyzer for software builds (Devel category)
  • perl -- a scripting language used to control parts of the build (Interpreters category)
  • sed -- a search and replace language
  • sh-utils
  • textutils
  • unzip -- zip file extraction (Archive category)
  • zip -- zip file creation (Archive category)
If you plan to modify the build system's configure.in files, you will need to install the autoconf-2.13 (autoconf-stable) package as well.

You may use ActiveState perl instead of the perl package in cygwin if you prefer.

If you chose to use cygwin cvs instead of WinCVS, cvs and editors are not installed by default. Install one or more editors such as vim or emacs from the Editor category, as well as cvs from the Devel category. cygwin cvs and other cygwin apps can use the standard windows text file format if you tell it to use DOS line-endings when you run the cygwin installer.

Netscape wintools

Netscape's wintools.zip contains pre-built libraries and tools which are needed to build Mozilla.

Unpack the zip file into a temporary directory, open a Windows command window, and set MOZ_TOOLS to the directory you want the build tools installed to, for example:

set MOZ_TOOLS=C:\moztools

The MOZ_TOOLS directory should not be inside your cygwin installation directory, nor in a subdirectory of cygwin. This may cause your build to fail.

Run the wintools install script. This batch script will install the files into %MOZ_TOOLS%/bin.

cd buildtools\windows
install.bat

Win32 development kit

You will need to install one of the following compiler development kits in order to build Mozilla on Win32:

Microsoft Visual C++

Microsoft Visual C++ must be obtained from Microsoft. The GUI features of the environment are not used, only the command-line tools CL, the C compiler; LINK, the linker; and RC, the resource compiler. These tools are invoked from cygwin's GNU make.

You must have version 6.0 or later, with the service pack and processor pack below. Version 5.0 is not supported and probably will not build Mozilla.

Version 7.0 has additional build requirements which are outlined below.

Make sure you have set up the compiler using the vcvars32.bat script that came with it. Run this file from the Windows command line shell.

Microsoft Visual C++ Service Pack 5
Microsoft Visual C++ Processor Pack (includes ml.exe)
.NET/MSVC 7 required libraries

When building with MSVC++ 7, you must install VC7 built versions of the glib & libIDL libraries. You can find the prebuilt VC7 versions of these libraries at ftp://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/ .

It is recommended that you do NOT install these libraries over your existing moztools directory. It is recommened that you pick a separate location and set GLIB_PREFIX & LIBIDL_PREFIX appropriate in your MOZCONFIG file or in your environment. 

# Example mozconfig entry
GLIB_PREFIX=c:/apps/vc7
LIBIDL_PREFIX=c:/apps/vc7
GCC for Win32 (mingw or cygwin)

As of Mozilla 1.4b, it is possible to build Mozilla for Win32 using GCC. 
However, there are certain caveats that anyone attempting to use this development kit should be aware of:

  • Due to the nature of C++ compilers, libraries built with GCC will likely be incompatible with libraries built with MSVC. For example, XPCOM plugins will not work.  This includes the Java plugin.
  • Due to the use of MSVC-specific code in the tree and the relative immaturity of the w32api, certain functionality will not be available in the GCC build. The dependency tree for bug 203303 tracks the list of MinGW GCC-specific issues.
  • GCC on Win32 is a tier-3 platform whereas MSVC on Win32 is a tier-1 platform

GCC for Win32 is available as part of the MinGW project.  The following mingw packages are required for building:

  • gcc >= 3.2.2 (20030208)
  • binutils >= 2.14.90 (20030807)
  • w32api >= 2.4
  • mingw-runtime >= 2.4
 GCC for Win32 is also available as part of the cygwin project if you install the following additional cygwin packages:
  • binutils
  • gcc
  • gcc-mingw
  • mingw-runtime
  • w32api
It is recommended that you use the standalone MinGW setup to avoid any potential conflicts with the default cygwin development environment.

You will also need the cygutils package from cygwin so that you can run dos2unix on the headers inside of the Netscape wintools.zip package.

2.3 Set Up Environment Variables

Both the cygwin and MSVC++ tools are controlled by environment variables which specify options, directories, and search paths. cygwin inherits Windows environment variables and maps them into its own UNIX-style file system name space, so there are a variety of places you can set the variables. To build in cygwin, you can set both types in cygwin.bat at the root of the cygwin directory. To build from the Windows command shell, you may set these in a configuration file or through a settings dialog, depending on your version of Windows.

Your build may fail if your paths have breaking characters. Make sure that you did not install software into locations with such paths, except Visual C++.

The following environment variables must be set.

set MOZ_TOOLS=C:\moztools
Set to the place where you want Netscape's wintools.zip to install its binaries. Mozilla will not build if you install the wintools directory inside the cygwin directory.

The build looks for MOZ_TOOLS\include\glib.h, so make sure that the glib.h from the Windows Build Tools package resides there.

set PATH=%PATH%;c:\mingw\bin;%MOZ_TOOLS%\bin;c:\cygwin\bin
Include both the Netscape wintools and the cygwin UNIX-like tools in your command search path.

Note for .NET/VC7 users: GLIB_PREFIX/bin & LIBIDL_PREFIX/bin must be in your path before MOZ_TOOLS/bin. 

set HOME=C:\home
HOME is not needed if you are not using cvs. If you are, set it to the place where you want cvs to create your .cvspass file. By setting HOME, you tell cvs to use the same .cvspass file whether you use the Windows shell or a cygwin shell. Because cygwin cvs or other cygwin programs may use this variable, it should not contain breaking characters. 
set MOZCONFIG
Set to the location of your mozconfig file. This file contains your build options. To use default settings, do not set this variable.

The Unix Build Configurator is used to create build settings files. To customize a build, use the Unix Build Configurator to create a mozconfig file, then copy it into a convenient directory and set MOZCONFIG to point to it before starting a build.

Example environment variable file

This sets up to build Mozilla using simple install locations on C for mozilla, mingw (if used), cygwin, and moztools, and the default build settings. 
set MOZ_TOOLS=C:\moztools
set PATH=%PATH%;c:\mingw\bin;%MOZ_TOOLS%\bin;c:\cygwin\bin
set HOME=C:\home

2.4 Get The Code

Mozilla is an open source project hosted on the source control system cvs. You can get the code for Mozilla from cvs or use source tarballs for particular milestones or nightly builds.

If you will only build with respect to a Mozilla milestone, or if you want to update sources infrequently, you can use ftp to get a source tarball for a milestone or nightly build. A tarball can be decompressed and built; it is known to build as a unit. Ftp drops of tarballs are usually produced daily, and always at milestones. Tarballs are kept at mozilla.org.

You will need to use a utility such as cygwin tar or Aladdin's Stuffit Expander to decompress tarballs. WinZip should not be used to decompress a source tarball. Some versions of WinZip do not extract zero length files from .tar.gz archives by default.

If you will be part of ongoing development on the Mozilla sources, then you probably want to get cvs, and pull a current source tree from the repository. cvs provides the most current code for building, but it is slower than ftp, and the latest sources may not always build.

To pull or update the tree:

make -f client.mk checkout

2.5 Compile The Code

You may compile from either the Windows command shell or cygwin's bash, provided they have the correct environment variables.

To build the tree:

make -f client.mk build

To rebuild without pulling the tree:

make -f client.mk build_all_depend

The Unix Build Configurator is used to create build settings files. You can change between different build options by setting the MOZCONFIG environment variable to point to different build settings created with the Unix Build Configurator.

When building with GCC, it is required that you tell the build system the name of certain compiler tools.  Here is an example of a MOZCONFIG file used to build with GCC:

# basic mozconfig file with minimum requirements for MinGW gcc build
CC=gcc
CXX=g++
CPP=cpp
AS=as
LD=ld

# the following options don't yet work under gcc-on-win32
ac_add_options --disable-accessibility
ac_add_options --disable-activex

3. Common Problems and Hints

  • Make sure your source tree isn't under /home; paths that start with /cygdrive are handled better.
  • Make sure all the tools are stable builds of at least the minimum required version.
  • Mozilla may not build if you install the wintools directory inside the cygwin directory.
  • Source pulls from cvs are not guaranteed to work due to bad checkins and timing conflicts. Check Tinderbox before pulling, and repull if you get build errors when the tree is green. Building from tarballs should give you a set of sources that build together.
  • The build may fail if your path names have breaking characters in them. Do not install Mozilla build tools into such locations, except Visual C++.
  • The build may fail if your PATH environment variable contains quotes ("). Quotes are not properly translated when passed down to the cygwin sub-shells. Quotes are usually not needed so they can be removed.
  • Double-check to make sure that you have the complete cygwin package list. If not, launch the cygwin installer and add the missing packages.
  • When in doubt, make sure you have correctly installed each tool, and that it is running without errors.
  • Check enviroment variables against the example.
  • Microsoft tools (CL, LINK, RC) gives file not found errors

    The INCLUDE and LIB environment variables are used by the Microsoft Visual C++ tools. They are ordinarily set up in vcvars32.bat. Depending on which modules you build, you may or may not need MFC and ATL. Below are paths that work if Visual C++ is installed at "C:\msvs".

    set INCLUDE=C:\msvs\VC98\Include;C:\msvs\VC98\MFC\Include;C:\msvs\VC98\ATL\Include
    set LIB=C:\msvs\VC98\Lib;C:\msvs\VC98\MFC\Lib
  • cvs fails with the message:
    cvs update: authorization failed: server XXXX rejected access
    cvs update: used empty password; try "cvs login" with a real password

    Current versions of cygwin cvs (1.10.8) do not appear to be able to read files created by WinCVS. You will need to make sure that WinCVS is in your path before cygwin cvs. Alternatively, you can pull a fresh tree using cygwin cvs.

  • Make spits out an error about not being able to find a .dtd file

    You probably used WinZip to unpack the source archive. Don't do that. WinZip, by default, doesn't unpack 0 length files from tar.gz archives. Use another utility, or use the pull script to checkout the files that WinZip didn't extract.

  • nsinstall or another native win32 program complains about a file not being found

    First check your cygwin mount table. Running the mount command should return something similar to:

    c: on /cygdrive/c type user (binmode,noumount)
    e: on /cygdrive/e type user (binmode,noumount)
    c:\cygwin on / type system (textmode)
    c:\cygwin\bin on /usr/bin type system (textmode)
    c:\cygwin\lib on /usr/lib type system (textmode)

    The build system expects that drive partitions are mounted using /cygdrive as the drive prefix. If c: or e: does not use /cygdrive as the drive prefix, then you cannot build Mozilla using those drives. You will need to manually mount the drive at the expected spot by using the command:

    mount -s "e:\" /cygdrive/e

    Note: binmode (unix lineendings) or textmode (dos lineendings) doesn't matter as long as you use an editor (emacs, msdev) which can handle the appropriate line-endings.

  • xpidl.exe crashes with an access violation at 0x00000010

    If you are building with .NET/VC7, then you must link against the VC7 built version of the glib & libIDL libraries. The directory containing the VC7 versions of these dlls must be in your PATH before any other version of those dlls.

    If you are building with VC6, then you must make sure that you are NOT using the VC7 libraries at buildtime or at runtime.

  • cvs fails with the message:

    cvs [checkout aborted]: cannot rename file CVS/Entries.Backup to CVS/Entries: Permission denied

    As of cygwin 1.3.13, ntsec is enabled by default.  ntsec is cygwin's attempt to get a more UNIX like permission structure based upon the security features of Windows NT.  The error message indicates that there's a mapping discrepancy between the unix permissions listed in cygwin's /etc/passwd file and those used by Windows NT.

    As a workaround, you can add "nontsec" to your CYGWIN environment variable.  The proper fix would be to fix the mapping problem.

  • initial cvs checkout fails with the message:

    cvs [checkout aborted]: *PANIC* administration files missing

    You cannot create a cvs tree under a directory named "CVS". This is a feature/bug of cvs. cvs expects to find certain administration files under the CVS directory and will complain if they are missing.

  • a gcc/mingw build fails under mozilla/nsprpub with the message:

    exec: cl: not found

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

  • Mozilla 1.7a is the earliest version whose source code builds out of the box on MS Visual Studio .NET 2003. Earlier versions need code patches; see e.g. bug 208314.

4. Win32 Debugging FAQ

Tips on how to debug Mozilla on Windows have been collected in the Win32 Debugging FAQ.