Building the Fox

Aim

To build the Mozilla Firefox browser from source code.

Apparatus

Hardware

AMD Athlon XP @ 1.82 GHz 512 MB RAM

Software

• Microsoft® Windows XP® Professional with Service Pack 2.
• Microsoft® Visual Studio .NET 2003® (with C++ module installed).(available from ACS: Disc 0 (Pre-requesite), Disc 1, Disc 2)
• Cygwin
• moztools
• Microsoft ® Windows Server® 2003 R2 Platform SDK
• NSIS Installer
• Make 3.80 (Needed to overwrite make 3.81 which is part of the Cygwin default install)
• 7-zip or similar archiving utility.

Method

Install all software in the default directory unless otherwise specified as it will save time and effort in the long run.

1. Install Visual Studio .NET 2003 (with Visual C++ modules)
2. Install Microsoft ® Windows Server® 2003 R2 Platform SDK
3. Install Cygwin . Remember to install all the package binaries listed below as specified in the Windows Build Pre-requisites made available by the Mozilla Developer Center. To install a package simply expand the desired category and place a check in the bin check box. Source files are not required. Don't worry if you realize you made an error i.e. forgotten a required package. The Cygwin installer is smart enough to accomodate this situation. Simply re-run the Cygwin setup.exe and select the packages you want to add, remove or re-install).:
   • ash -- UNIX-like command line interpreter shell (Base category)
   • coreutils -- GNU core utilities (includes fileutils, install, sh-utils, and textutils) (Base category)
   • cvs -- concurrent versions system (Devel category)
   • diffutils -- file comparison utility (Base category)
   • findutils (Base category)
   • gawk -- pattern matching language (Base and Interpretors categories)
   • grep -- text search tool (Base category)
   • libiconv -- character set conversion (Devel category)
   • make -- dependency analyzer for software builds (Devel category) (Don't worry if it is ver 3.81, we will correct this problem later).
   • patchutils -- a small collection of programs that operate on patch files (Devel category)
   • perl -- a scripting language used to control parts of the build (Interpreters category)
   • sed -- a search and replace language (Base category)
   • unzip -- zip file extraction (Archive category)
   • zip -- zip file creation (Archive category)
4. Install Make 3.80
   1. Download and extract Make 3.80 (make-3.80-1.tar.bz2) to any folder of your choosing. A file named make-3.80-1.tar is created.
   2. Proceed to extract the make-3.80-1.tar file.
   3. Copy the make.exe file located within the usr/bin folder and overwrite the make.exe located in C:\cygwin\bin
   4. To Confirm that the version has changed to 3.80 by launching Cygwin. At the prompt type: make -v
   5. To close Cygwin type: exit
5. Download and Extract moztools to a folder of your chosing.
6. Create an batch file containing steps needed to properly configure your build environment prior to proceeding with the build. The contents of the this batch file can be found within the Batch File section of the Appendix. Make changes to the batch file as necessary to reflect the different installation paths of the various applications in question. This will ensure that all the environment variables needed for the build to succeed are properly initialized. More information relating to the specifics of this file can be found in the Configuring the Environment section of the Windows build guide made available by the Mozilla Developer Center.
7. Rename \bin\link.exe located within the Cygwin installation folder to any different name (e.g. oldlink.exe). This prevents the receipt of an error message stating that the "incremental linker version does not match the compiler suite version" as documented in the Configure the environment section of the Windows Build Pre-requiste guide from the Mozilla Developer Center.
8. Create the c:\proj folder to store the source and object files that will result from the checkout and build respectively.
9. Execute the batch file created in step # 6 above. This should set all the required environment variables and automatically open a cygwin prompt window.
10. For the build to work properly we must ensure we are in the c:\proj folder before logging on #:to CVS to checkout the source files. Issue the following commands at the Cygwin prompt #:accomplish this:
    • cd c:
    • cd proj
11. Logon to CVS.

    • At the command prompt type: cvs logon
    • Enter "anonymous" as the password (without the quotes)

12. Checkout the code

    • At the prompt enter: cvs co mozilla/browser/config mozilla/client.mk
    • The above step creates a folder called mozilla within the proj director.
    • Navigate to this folder by typing: cd mozilla

13. Create a file named .mozconfig and place it in this c:\proj\mozilla directory. This file contains the settings The contents of the this file can be found within the .mozconfig File section of the Appendix. You will notice that the last line of the .mozconfig file disables the installer thus NSIS is not required. If you omit this line then, NSIS (2.17 or greater) must be installed and its install directory (and not the 'bin' directory) added to your path.More information relating to the specifics of this file can be found in the Configuring Build Options section of the Windows build guide made available by the Mozilla Developer Center.
14. Begin source file download by issuing the following command: make -f client.mk checkout
15. Once the above step is completed issue the following command to compile the source: make -f client.mk build

Observations

The first problem I encountered related to downloading the source files. I was trying to figure out how this could be done i.e. via HTTP or FTP download or CVS. I was also trying to figure out if I would need the entire Mozilla source or simply that relating to firefox for the build. The answer to this problem was quite simple and common mistake. I realized that in my haste I failed to read the entire source download documentation before starting my attack. Upon reading the notes more carefully, I quicly learnt that CVS was the method of choice. To proceed with CVS I know had to re-run the Cygwin setup to install the CVS package that I had skipped initially (since I thought I would download the source via FTP/HTTP).

I was still unable to logon to CVS. I was getting error messages saying that the CVS root was not specified even though I was issuing the commands specified in the Mozilla build documentation: cvs -d :pserver:anonymous:anonymous@cvs-mirror.mozilla.org:/cvsroot co mozilla/browser/config/mozconfig

I found the answer to this problem in Professor Humphrey's guide to building Firefox on Win32. I noticed that my batch file was lacking the following lines required for proper CVS setup to the mozilla servers:

SET CVSROOT=:pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot
SET CVS_RSH=ssh

I added the above lines at the beginning of my batch file and restarted the process. This time I was able to logon to CVS without any problems.

The next hurdle was determining how to proceed after checking out the source files using the following command

make -f client.mk checkout

I spent a great deal of time at this juncture trying to extract various archives of the newly downloaded source via the Cygwin command prompt in a effort to start the build. I scoured through all the folders looking for an installer or build file. The most worrying part of this excercise was that I could not find my objdir even though I explicitly specified one in my .mozconfig file (i.e. firefox-objdir). Little did I know that I needed to issue a single command to proceed to the next step:

make -f client.mk build

which would initiate the build. Many thanks to Liz Chak for providing me with this information. However, in defense of the mozilla build documentation, I must say that it is clearly stated there (in the Building section) and I would have seen it had I read the documentation more thoroughly and perceived that those two commands (though similar) are not one and the same.

After the build completed I tried to launch firefox.exe (located within the C:\proj\mozilla\firefox-objdir\dist\bin folder). This opened up a console window, which scrolled through various pages after page of info before displaying a NSGlue_Assertion error message similar to sample error listed in the Appendix. After finding no results on a google search, I decided to just click ignore for this message (and the 2 that followed seconds later). The console kept scrolling and a few seconds later a GUI Firefox Brower Application Window entitle Minefield opened ! After taking the required screen shots of the Help->About page, I decided to see if I could actually browse the web. This worked with no problems. Upon closing the GUI Minefield Browser Window received a few more of the error messages mentioned above. However, after clicking ignore on all of them, the console window proceed to close. After discussing the matter with a few colleagues (Dean Woodside, Colin Guy, Aditya Kuswanto and Richard Chu), we disovered that we were all receiving the same error messages during startup and exit. The messages do not appear everytime the program is opened or closed but seems to happen very irregularly. Richard believes that the problem may be related to settings in the .mozconfig file relating to debugging. He proposed that it may be the result of the presence of the "ac_add_options --enable-debug" statement or the absence of some other flag required to suppress such debug errors.

Conclusion

This was the first time I have built an open source application from source. As so, I must say the final result is very rewarding. I think the hardest part was overcoming the initial trepidation. The documentation on the process is very good provided you read and follow it carefully. I tried to attempt to answer any questions that arose by doing some research on the web. I learned that in most instances the answer was already well documented out on the web since someone out there had already encountered that problem. The runtime debug error message incident is a good example of this, as I would not have known it was a common problem had I not spoken with a few colleagues about the matter. Initiative, determination, persistence and patience are also keys to the success of any endeavour and this was no different.

Appendix

Batch File

SET CVSROOT=:pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot
SET CVS_RSH=ssh

rem --- Set HOME so that cvs and ssh work correctly
rem --- cvs uses HOME to locate your .cvspass file, and ssh to locate your .ssh file
rem --- if you are using ssh, your HOME should match the home directory specified in /etc/passwd. See http://www.cygwin.com/faq/faq0.html.
set HOME=C:\home

rem --- Set VCVARS to wherever the MSVC vcvars.bat file is found
set VCVARS=C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin\vcvars32.bat

rem --- Set MSSDK to wherever the MS SDK is installed
rem --- Only required for MSVC7 or the Free MSVC editions that don't come with an SDK
set MSSDK=C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2

rem --- Set MOZ_TOOLS to wherever you have the moztools packaged installed
set MOZ_TOOLS=C:\moztools\moztools-static\moztools

rem --- Set CYGWINBASE to wherever cygwin is installed
rem --- Do not use CYGWIN or else cygserver, cygrunsrv, and Cygwin services will not function properly
rem --- Variable CYGWIN is also used to modify Cygwin's behaviour a little bit.
set CYGWINBASE=C:\cygwin
rem --- Make sure Cygwin does not print out a DOS style path warning
set CYGWIN=nodosfilewarning

rem --- Prepend Cygwin path
rem --- This is necessary so that cygwin find is ahead of windows find.exe in the PATH, but cgywin link is after MSVC link.exe.
set PATH=%CYGWINBASE%\bin;%PATH%

rem --- Set MSVC environment vars
call "%VCVARS%"

rem --- Prepend SDK paths
rem --- Only required for MSVC7 or the Free MSVC editions that don't come with an SDK
set PATH=%MSSDK%\bin;%PATH%
set INCLUDE=%MSSDK%\include;%INCLUDE%
set LIB=%MSSDK%\lib;%LIB%

rem --- moztools comes last
set PATH=%PATH%;%MOZ_TOOLS%\bin

rem --- Now the PATH variable contains:
rem MS-SDK; MSVC; Cygwin; Windows; glib/libIDL; Moztools

rem --- Typically the last thing the script does is launch a cygwin shell
rem --- watch for your ~/.profile and /etc/profile which may overwrite your carefully setup PATH!
bash --login -i

.mozconfig File

# Building Firefox Trunk with Debugging
. $topsrcdir/browser/config/mozconfig

# Put all obj files in one place, not in src tree
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/firefox-objdir
ac_add_options --disable-static
ac_add_options --enable-shared

# Debug Build Setup Options
ac_add_options --disable-optimize
ac_add_options --enable-debug

# I'm using Canvas for my work
ac_add_options --enable-canvas

ac_add_options --disable-installer

Screenshots

Help->About

Sample Error

References & Acknowledgements

• Mozilla Developer Center, Build Documentation
  
• Humphrey, David -Building Firefox on Win32
  
• Chak, Liz - For realizing that the source of the initial confusion was the fact the fact that I missed perhaps most important command of all during the build process. i.e. make -f client.mk build.
• Chu, Richard, Guy, Colin, Kuswanto, Aditya and Woodside, Dean for alerting me other to the fact that they too received the runtime NSGlue Assertion debug errors.