Preface One of the biggest barrier to contributing to Mozilla developement, either through mozilla.org or mozdev.org, is using CVS. Not all contributors are experienced software engineers. Some are Web developers capable of hacking XUL and javascript code. Some are technical writers who may need to hack the source code. Still some are hobbyst programmers who only want to have fun. I myself belong to these people.
I wrote this tutorial because when I first got involved with mozdev.org, I got very frustrated with learning CVS. I only wanted to hack some code, not to learn how to do CVS with horrible commandline interface, which mozilla.org and mozdev.org CVS help files concentrate on. What I needed was a step-by-step tutorial on using a graphical tutorial. Thus, this tutorial is born. This tutorial gives instructions to most CVS operations you will need when using WinCVS to access Mozilla code. This tutorial tells you how to create a repository, check out files, modify code, view source changes, commit changes, and manage files. This tutorial assumes that you are using a remote CVS server; this tutorial does not cover how to create a local CVS directory. Contents: What is CVS? [empty] Getting the source code Where to get WinCvs Intalling WinCvs Getting started Log in to CVS server Before you check out source code Checking out source files Checking out source files in a branch Browsing local source files Opening files Modifying files (and undo changes) Updating local source files Compiling [empty] Comparing revisions [incomplete] Committing changes Deleting files Managing multiple repositories References Appendix I: Mozilla source map [incomplete] Appendix II: Mozilla source tree filename conventions [empty] > What is CVS? > Getting the source code There are many ways you can access the source code. You can read mozilla.org and mozdev.org source online through LXR (<http://lxr.mozilla.org/mozilla/source/> and <http://mozdev.org/lxr/index.cgi>). You can download packed mozilla.org source <http://www.mozilla.org/download.html>. And you can access the source code through a CVS (concurrent versioning system) client. This tutorial covers how to use the WinCVS to access mozilla.org and mozdev.org source. > Where to get WinCvs You can download WinCVS from <http://www.wincvs.org>. I recommand that you get the latest stable release (currently 1.20) instead of a beta release. > Intalling WinCvs Installation is straight forward. There's nothing special you need to know. > Getting started (WinCVS 1.2) When you first start WinCVS, a preference dialog will prompt you to create one cvs repository. In the General tab, change `Authentication' from `Local mounted directory' to `"password" file on the cvs server'. If you want to read Mozilla source code, paste paste the following line to `CVSROOT': [EMAIL PROTECTED]:/cvsroot For mozilla.org site content, the cvs root is [EMAIL PROTECTED]:/cvsroot For mozdev.org projects, the cvs root is [EMAIL PROTECTED]:/cvs In the WinCvs tab, set the Home folder. This is where password files will be saved. It is recommanded that you store your CVS files there. > Getting started (WinCVS 1.3b) When you first start WinCvs, a Preferences dialog will prompt you to create one cvs repository. In the General tab, change `Authentication' from `local' to `pserver'. If you want to read Mozilla source code, paste paste the following line to `CVSROOT': [EMAIL PROTECTED]:/cvsroot For mozilla.org site content, the CVS root is [EMAIL PROTECTED]:/cvsroot For mozdev.org projects, the cvs root is [EMAIL PROTECTED]:/cvs In the CVS tab, set the Home directory. This is where password files will be saved. It is recommanded that you store your CVS files there. > Log in to CVS server (WinCvs 1.2) Open the `Admin' menu, and choose `Login...'. You will be prompt to enter the password. Enter `anonymous'. If you log in successfully, you will see the following in the bottom pane: ***** CVS exited normally with code 0 ***** Whenever you see code 0, it means the operation is successful. If you see a code 1, then the operation either aborted or failed. If the log-in fails, verify your log in information. Open the Admin menu and choose `Preferences...'. Check that CVSROOT is entered correctly. After you have logged in once, your log-in name and password will be saved. In the future, you do not have to log in first when starting a new CVS session; when you perform any CVS operation, WinCvs will automatically log in for you if you have not done so. > Log in to CVS server (WinCvs 1.3b) Open the `Admin' menu, and choose `Login...'. You will be prompted your login information. If you have more than one source repository, verify your login information. Choose OK. Then you will be prompt the password. Enter `anonymous' If you log in successfully, you will see the following in the bottom pane: ***** CVS exited normally with code 0 ***** Whenever you see code 0, it means the operation is successful. If you see a code 1, then the operation either aborted or failed. After you have logged in once, your log-in name and password will be saved. In the future, you do not have to log in first when starting a new CVS session; when you perform any CVS operation, WinCvs will automatically log in for you if you have not done so. > Before you check out source code Check out only the parts you need. Browse the source tree using LXR first to know what you want to check out. Alternatively, look at the source map in Appendix I (incomplete atm). LXR at mozilla.org is <http://lxr.mozilla.org/mozilla/source/> LXR at mozdev.org is <http://mozdev.org/lxr/index.cgi> > Checking out source files To check out source code, choose the `Create' menu, and then `Checkout module...' In the dialog prompt, enter the path of files you want to check out. You can choose to check out the entire source tree or just some files. For example, for Mozilla CVS, entering `mozilla' as the module name will gives you all source files, including Phoenix, Chimera, etc.. Entering `mozilla/browser/components/bookmarks/', on the other hand, gives you all Mozilla's bookmarks component source files. Also check your local folder setting. Files you check out will be saved, with directory information retained, to your local folder. For example, if you are checking out mozilla/browser/components/bookmarks/ and your local folder is c:\cvsroot, the files you checked out will be saved to c:\cvsroot\moziila\browser\components\bookmarks\ You can change the destination of the checked out files. To do this, check the `override' option and specify a new checkout name. > Check out source files in a branch CVS can keep multiple versions of the same file. This flexibility allows developers to develop different flavours of the same software and to separate experimental versions from stable versions. For example, after Mozilla 1.0 is released, a 1.0.0 branch is created, separated from the main development trunk, so that developers can insulate maintainence change from work-in-progress code. When checking out source files, you can specify what branch you want. In the Checkout settings dialog, navigate to the `Checkout options' tab. Check the `By revision/tag/branch' setting and specify the branch name. Names of major branches can be found at http://www.mozilla.org/releases/cvstags.html > Browsing local source files Now that you have checked out some files, we can talk about browsing and managing your files. WinCvs works similar to the Window Explorer. The left pane lets you navigate between folders. You can set the root of the folder tree to your CVS local folder instead of c: drive. To set the tree root, click on the change location toolbar button, or open the View menu, choose `Browse location', and choose Change. The right pane list files and folders. CVS files you have checked out have regular document icons; a text file has the regular text file icon, and a binary file has icon with `01'. Cvs file that you have modified are marked red. Non-CVS files have icons with a question mark. �z�w�{ �z�w�{ �z�w�{ �x==�x �x10�x �x? �x �|�w�} �|�w�} �|�w�} A CVS folder has a check mark. A non-CVS folder has no check mark. On the bottom is the Output pane. It is basically a history of current and past CVS operations. > Opening files You can open a file in two ways. You can double click on a file to open it in the associated program. You can also bring up the context menu (by double-clicking) and choose `View with Notepad' to open it in Notepad. You do not have to use Notepad as the default text viewer. To change the default viewer, open the Admin menu and choose Perferences. In the Preferences dialog, navigate to the WinCvs tab. In the `Default viewer' box, choose on the `...' button and choose a new program as the viewer. In the same tab, you can also check `Use on doube click' to open text files with the default viewer on double click. In that case, to open a file with the associated program, use the `View selection' command in the context menu. > Modifying files (and undo changes) By default, files checked out are marked read only. This is to prevent accidental change to source files. To clear the read-only file tag, select the file, open the `Query' menu and choose `Explore selection'. The Windows Explorer will appear. Clear the read-only file tag. If you do not want to check out files as read-only, when you check out files or synchronize (update) your local copies with CVS copies, in the dialog prompt clear the 'Checkout read-only' option in the `Globals' tab. After you save the file you have the modified, the respective file icon will be marked red. If you have changed a file, but want the original CVS copy back, first open the `Modify' menu and choose `Erase selection' to dump the file to the Recycle Bin. Then you update the file. > Updating local source files To update files or folders, select the files or folders. Open the `Modify' menu and choose `Update selections...'. The `Update settings' dialog will appear. If you are working with a specific branch, navigate to the `Sticky options' tab to specify the branch. If you want your files to be editable (not read-only) clear the 'Checkout read-only' option in the `Globals' tab. Choose `Ok' to update the selected files or folders to the latest versions in the CVS. Only unmodified files will be updated. If you have modified a file but want the remote CVS copy instead, first open the `Modify' menu and choose `Erase selection' to dump the file to the Recycle Bin. Then you update the file. > Compiling > Comparing revisions Using the GNU Diff tool, you can compare your local files and the respective remote CVS files and see their differences line by line. The diff output allows you or another person to review changes you have made without going over the entire code. WinCvs comes with GNU Diff. You can generate Diff output from menu. Unfortunately, the output is not very useful. By default, Diff only shows the changed lines but not the context (lines before and/or after the changed lines) In mozilla.org, Diff files used for code review are in the unified format which shows context along with the changed code. To output Diff in this format, you have to use the WinCvs command line tool. Fortunately, the command is not difficult, and revision comparsion is probably the only occassion you will have to use the command line tool. To use the command line tool, open the `Admin' menu and choose `Command line...'. Type in the command. For Diff in unified format, the command is cvs diff -u -r <revision> <filename> The option "-u" tells Diff to use the unified format. The option "-r <revision>" tells Diff what revision you are comparing your file against. For example, "-r MOZILLA_1_0_0_BRANCH" tells Diff to compare your file against the revision in the Mozilla 1.0.0 branch. If you leave out this option, Diff will compare your file against the latest revision in the trunk. Filename is a list of filenames separated by space. If you leave out this, Diff will compare all files in the current folder. Reading unified output is straightforward. Output for each revision comparsion begins with some information on what revisions are being compared, followed by the source code. At the beginning of each line is either a space, a plus ('+') sign, or a minus ('-') sign. A plus sign indicates line added. A minus ('-') sign indicates line removed. A space (' ') indicates context. More detailed description of the format can be found at <http://www.tac.nyc.ny.us/manuals/prog/diff_3.html#SEC21> You can save Diff output to a text file as a patch. �z�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�{ �xsidenote: what is Bugzilla? �x �xBugzilla is ... [note empty, contribution welcome] �x �|�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�w�} > Committing changes If you have write access to your cvs repository, you can commit changes to the source tree. A files that you have modified has a red icon. A file that you have added has a icon with a question mark. To commit modified files, select the files, open the `Modify' menu and choose `Commit selection' (`Commit' in WinCvs 1.3b). To add new files, select files, open the `Modify' menu and choose `Add selection'. You then confirm the addition by committing it. If you do not have write access, you should save the Diff as a patch and pass it on for other people to review it and commit it. > Deleting files Removing a file from CVS is very tricky and requires special previlege. So be mindful of what you are adding to the source tree. > Managing multiple repositories You can have more than one repository, for example, one for Mozilla source code, and one for mozdev projects. To better manage your code, you should have a different CVS local folder for each repository. If you have multiple repostories, check the preferences to verify the CVSROOT when you start a WinCvs session so that WinCvs will log in properly. > Appendix I: Mozilla source map Partly adopted from Nathan Torkington's Unix source roadmap LEGAL Legal issues surrounding parts of the code (not the license) Makefile Master makefile (builds portions depending on envariables) client.mk Client make file README Link to unxbuild.txt build Generate build resource numbers for Win and Mac. /mac Macintosh code for build numbers cmd Front Ends /stubfe Stub for writing your own Front End /xfe X Front End /winfe Windows Front End /macfe Macintosh Front End dbm Simple database (ndbm code) dist Object and executables that you build will be put here include Include files for Mozilla jpeg JPEG6 library, with Netscape mods (C) js Java Script js/jsd Java Script Debugger (C) js/jsd/classes/netscape/jsdebug Debugging classes from Netscape js/jsd/corba Empty holes for CORBA classes and interfaces js/jsj LiveConnect - the glue between Java and JavaScript (C) js/jsj/classes/netscape/javascript (Java) js/jsj/javax Empty js/src Actual source to JavaScript (C) l10n Localisation lib Libraries lib/htmldlgs HTML Dialogs (C) lib/layout HTML Layout (mostly C, little C++) lib/libcnv PNG, PPM, etc, image conversion (C) lib/libi18n Internationalisation (C) lib/libi18n/unicode Unicode support (C) lib/libi18n/unicode/fromftp Empty lib/libi18n/unicode/tbltool Utilities? lib/libi18n/unicode/ufrmtbl Automatically generated tables lib/libi18n/unicode/utotbl Automatically generated tables lib/liblayer Library for layers (used in streamed page layout) (C) lib/liblayer/src Code for layers (C) lib/liblayer/include .h files for layers lib/libmime MIME code (C) lib/libmisc Miscellaneous code (bookmarks, preferences, ...) (C) lib/libmocha JavaScript (C) lib/libnet Network communications (DNS, URL, ...) (mostly C, some C++) lib/libnet/tests Tests for libnet (empty) lib/libparse HTML parser (C) lib/libpics W3O Platform Independent Content-Identification System (C) lib/libpwcac Password Cache (C) lib/libstyle Style Sheets (C) lib/mac Macintosh library (details?) lib/mariner Forms? (C++) lib/mariner/public Include files for Mariner library lib/mariner/src Source for Mariner library (C++) lib/plugin Plugin handling library (C and C++) lib/xlate Postscript Translation (C) lib/xp Profile? (C) modules/edtplug Netscape Plugin Manager (C) modules/editplub/include Include files modules/editplub/src Include files (C) modules/libfont Font Library/Broker (C++) modules/libfont/classes/netscape/java Java classes to access fonts (Java) modules/libfont/jmcgen Automatically generated C source (C) ? modules/libfont/producers Empty modules/libfont/public Empty modules/libfont/src Source to libfont (C++) modules/libhook Hooks? (C) modules/libhook/public Headers modules/libhook/src Source (C) modules/libimg Image Library (decode/cache images) (C, Java and JavaScript) modules/libimg/classes/netscape/libimg Java classes for images (Java) modules/libimg/doc Empty modules/libimg/friend Empty modules/libimg/png PNG code (C) modules/libimg/public Header files (C) modules/libimg/src Code for libimg (C) modules/libimg/test Empty modules/libpref LDAP and JS Preferences ? modules/libpref/admin DLL code for Win32 (C?) modules/libpref/doc Empty modules/libpref/friend Empty modules/libpref/l10n Localisation hooks (C) modules/libpref/public Header files (C) modules/libpref/src Common source (C, JavaScript) modules/libpref/init Javascript initialisation (JavaScript) modules/libpref/mac Macintosh-specific initialisation (C? and JavaScript) modules/libpref/os2 OS2-specific initialisation (JavaScript) modules/libpref/unix Unix-specific initialisation (C and JavaScript) modules/libpref/win Windows-specific initialisation (C and JavaScript) modules/libpref/win/res Windows-specific resources modules/libpref/tests Empty modules/libreg Registry (C) modules/libreg/classes/netscape/softupdate Empty modules/libreg/include C header files (C) modules/libreg/source Empty modules/libreg/src C source (C) modules/libreg/tests Tests (C) modules/libutil Observers (wrappers around objects) (C) modules/libutil/public Header files modules/libutil/src Source (C) modules/progress Window showing progress of download modules/progress/public Header files modules/progress/src Code (C++) modules/rdf RDF Hypertree (C) modules/rdf/classes/netscape/rdf/ Java classes (Java) modules/rdf/classes/netscape/rdf/core Java classes (Java) modules/rdf/images GIF images modules/rdf/include Header files (C) modules/rdf/src C source (C) modules/rdf/win32/ Empty modules/schedulr Scheduling service modules/schedulr/public Header files modules/schedulr/src Source (C) modules/security Security: certificates, etc. modules/softupdt Stub for receiving software updates modules/zlib Standard zlib compression library, modified by Netscape nav-java/ Where Mozilla's java support should go nav-java/stubs Stubs for java support nsprpub/ Platform-independent interface to threads, etc. nsprpub/src/io/ Polling for I/O? nsprpub/src/linking/ Dynamic loading/linking? nsprpub/src/malloc/ Memory allocation nsprpub/src/md/ Threading and poll? nsprpub/src/memory/ Allocate segments of memory nsprpub/src/misc/ Envariables, longs, errors, netdb, system. nsprpub/src/pthreads/ P(OSIX?) Threads nsprpub/src/threads/ Threads sun-java/ Sun's Java VM sun-java/stubs Stubs for Sun's Java VM unxbuild.htm HTML for Unix Build Process unxbuild.txt Instructions on building Mozilla for Unix. xpcom/ Mozilla's COM-like object connectivity code
