Difference between revisions of "Real World Mozilla Incremental Build Lab"
(→Apply a patch) |
Backinblakk (talk | contribs) (→Apply a patch) |
||
| (11 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
| − | [[ | + | [[Real World Mozilla]] > [[Real World Mozilla Day 3]] > Incremental Build Lab |
== Overview == | == Overview == | ||
This lab is designed to give you first-hand experience creating and applying patches, and doing incremental builds of your source tree. The concepts introduced in this lab will help you understand how to make small changes to your tree, share those with others, or use other people's changes. | This lab is designed to give you first-hand experience creating and applying patches, and doing incremental builds of your source tree. The concepts introduced in this lab will help you understand how to make small changes to your tree, share those with others, or use other people's changes. | ||
| − | |||
| − | |||
== Instructions == | == Instructions == | ||
Because the source tree is so large, developers use patches as the basic unit of work for passing code back and forth. A patch is a text file that contains information necessary to add or remove lines from a source tree. Patches are created using the '''cvs diff''' command. | Because the source tree is so large, developers use patches as the basic unit of work for passing code back and forth. A patch is a text file that contains information necessary to add or remove lines from a source tree. Patches are created using the '''cvs diff''' command. | ||
| + | |||
| + | '''NOTE: All instructions below assume the use of an objdir. Replace all uses of ''objdir'' with your object directory path.''' | ||
=== Making a change and doing incremental builds === | === Making a change and doing incremental builds === | ||
| − | * Make a small change to a file in your tree, for example, a .cpp file in '''mozilla/netwerk/protocol/http'''. Here is a possible change: | + | * Make a small change to a file in your tree, for example, a .cpp file in '''mozilla/netwerk/protocol/http/src'''. Here is a possible change: |
#include <stdio.h> | #include <stdio.h> | ||
... | ... | ||
| + | ...''inside a function somewhere''... | ||
/* DEBUG_<username> is defined at build time, and Faculty is the username in the lab */ | /* DEBUG_<username> is defined at build time, and Faculty is the username in the lab */ | ||
#ifdef DEBUG_Faculty | #ifdef DEBUG_Faculty | ||
printf("Hello World!\n"); | printf("Hello World!\n"); | ||
#endif | #endif | ||
| + | ...''inside a function somewhere''... | ||
| + | ... | ||
* Make sure your change compiles. You need to rebuild your tree in order to test using one of the following methods: | * Make sure your change compiles. You need to rebuild your tree in order to test using one of the following methods: | ||
| Line 27: | Line 30: | ||
$ make -f client.mk build | $ make -f client.mk build | ||
| − | or, go to the parallel location in your objdir and run make there | + | or, to make things go faster, move to the parallel location in your ''objdir'' and run make there |
| − | $ cd mozilla/objdir/netwerk/protocol/http | + | $ cd mozilla/''objdir''/netwerk/protocol/http/src |
$ make | $ make | ||
=== Create a patch === | === Create a patch === | ||
| − | * Now create a patch containing the changes you just made using the so called 'unified' format (-u), with 8 lines of context. By default the diff is printed to stdout, so you should redirect it to a file: | + | * Now create a patch containing the changes you just made using the so called 'unified' format (-u), with 8 lines of context. By default the diff is printed to stdout, so you should redirect it to a file. Typically patches are created from the '''mozilla/''' root directory, so that they can be easily applied later on (i.e., people don't have to figure out where to apply the patch, and can just use their tree's root directory): |
| − | $ cd mozilla | + | $ cd mozilla |
$ cvs diff -u8p . > patch.txt | $ cvs diff -u8p . > patch.txt | ||
| Line 45: | Line 48: | ||
* Trade patches with someone else in the class (use http://pastebin.mozilla.org and IRC), and take turns trying to apply their patch to your tree: | * Trade patches with someone else in the class (use http://pastebin.mozilla.org and IRC), and take turns trying to apply their patch to your tree: | ||
| − | $ cd mozilla | + | $ cd mozilla |
$ patch -p0 < patch.txt | $ patch -p0 < patch.txt | ||
| + | |||
| + | (unless you are using hg checkout/patches then you want to look here [https://developer.mozilla.org/en/Mercurial_FAQ#How_can_I_diff_and_patch_files.3f for updated instructions]) | ||
* Here '''-p0''' means strip 0 leading directories from each filename in the patch. We do this because we are in the same location (i.e., ./) as the person who created the patch. If the directories were mis-aligned, we would have to strip leading directories using -p1, -p2, etc. | * Here '''-p0''' means strip 0 leading directories from each filename in the patch. We do this because we are in the same location (i.e., ./) as the person who created the patch. If the directories were mis-aligned, we would have to strip leading directories using -p1, -p2, etc. | ||
| Line 56: | Line 61: | ||
* Now try backing-out this same patch. To do this you can call patch with the -R or --reverse option to tell it to swap the old and new files, basically reversing the patch. | * Now try backing-out this same patch. To do this you can call patch with the -R or --reverse option to tell it to swap the old and new files, basically reversing the patch. | ||
| − | $ cd mozilla | + | $ cd mozilla |
$ patch -R -p0 < patch.txt | $ patch -R -p0 < patch.txt | ||
| Line 63: | Line 68: | ||
=== Applying a real patch === | === Applying a real patch === | ||
| − | + | Mozilla's [http://shaver.off.net/diary/2007/08/25/tbeachball/ Mike Shaver wrote] about an idea to add instrumentation to Firefox in order to determine how much time is spent away from the main event loop. His blog post included prototype code in the form of a [http://shaver.off.net/misc/latency-tracing-patch.txt patch]. | |
| − | + | Download Mike's [http://shaver.off.net/misc/latency-tracing-patch.txt patch]. '''Save the file''' (do not copy-paste it) to your '''mozilla/''' directory. | |
* Apply the patch, using what you learned above. Remember the '''--dry-run''' option and to examine the paths of files in the patch. | * Apply the patch, using what you learned above. Remember the '''--dry-run''' option and to examine the paths of files in the patch. | ||
| Line 71: | Line 76: | ||
* Rebuild the necessary parts of your tree: | * Rebuild the necessary parts of your tree: | ||
| − | $ cd mozilla/objdir | + | $ cd mozilla/''objdir'' |
| − | $ cd | + | $ cd xpcom |
$ make | $ make | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | * Run your browser and | + | * Run your browser and watch for messages in stderr |
=== Life-cycle of a patch in review === | === Life-cycle of a patch in review === | ||
| Line 95: | Line 91: | ||
== Resources == | == Resources == | ||
| − | * http://developer.mozilla.org/en/docs/Creating_a_patch | + | * [http://developer.mozilla.org/en/docs/Creating_a_patch Creating a patch for Mozilla] |
| + | * [http://developer.mozilla.org/devnews/index.php/2007/07/10/getting-a-patch-checked-in/ Instructions for getting a patch checked into the tree] | ||
| + | * There are many tutorials on using diff/patch, for example [http://tools.devchannel.org/devtoolschannel/04/06/02/1521207.shtml?tid=46 this one]. | ||
Latest revision as of 17:03, 6 October 2009
Real World Mozilla > Real World Mozilla Day 3 > Incremental Build Lab
Contents
Overview
This lab is designed to give you first-hand experience creating and applying patches, and doing incremental builds of your source tree. The concepts introduced in this lab will help you understand how to make small changes to your tree, share those with others, or use other people's changes.
Instructions
Because the source tree is so large, developers use patches as the basic unit of work for passing code back and forth. A patch is a text file that contains information necessary to add or remove lines from a source tree. Patches are created using the cvs diff command.
NOTE: All instructions below assume the use of an objdir. Replace all uses of objdir with your object directory path.
Making a change and doing incremental builds
- Make a small change to a file in your tree, for example, a .cpp file in mozilla/netwerk/protocol/http/src. Here is a possible change:
#include <stdio.h>
...
...inside a function somewhere...
/* DEBUG_<username> is defined at build time, and Faculty is the username in the lab */
#ifdef DEBUG_Faculty
printf("Hello World!\n");
#endif
...inside a function somewhere...
...
- Make sure your change compiles. You need to rebuild your tree in order to test using one of the following methods:
$ cd mozilla $ make -f client.mk build
or, to make things go faster, move to the parallel location in your objdir and run make there
$ cd mozilla/objdir/netwerk/protocol/http/src $ make
Create a patch
- Now create a patch containing the changes you just made using the so called 'unified' format (-u), with 8 lines of context. By default the diff is printed to stdout, so you should redirect it to a file. Typically patches are created from the mozilla/ root directory, so that they can be easily applied later on (i.e., people don't have to figure out where to apply the patch, and can just use their tree's root directory):
$ cd mozilla $ cvs diff -u8p . > patch.txt
- Open patch.txt in a text editor and notice the changes you made are prefixed with + signs. Any code you deleted will be prefixed with a - sign.
Apply a patch
- Trade patches with someone else in the class (use http://pastebin.mozilla.org and IRC), and take turns trying to apply their patch to your tree:
$ cd mozilla $ patch -p0 < patch.txt
(unless you are using hg checkout/patches then you want to look here for updated instructions)
- Here -p0 means strip 0 leading directories from each filename in the patch. We do this because we are in the same location (i.e., ./) as the person who created the patch. If the directories were mis-aligned, we would have to strip leading directories using -p1, -p2, etc.
- You can use the --dry-run option to test and see what would happen if you did apply the patch. Some people like to call patch with the -s or --silent or --quiet option (all do the same thing). This will suppress all output except error messages, and can make it easier to see which parts don't work.
Backing-out a patch
- Now try backing-out this same patch. To do this you can call patch with the -R or --reverse option to tell it to swap the old and new files, basically reversing the patch.
$ cd mozilla $ patch -R -p0 < patch.txt
- Check to make sure the changes in patch.txt are gone from the file.
Applying a real patch
Mozilla's Mike Shaver wrote about an idea to add instrumentation to Firefox in order to determine how much time is spent away from the main event loop. His blog post included prototype code in the form of a patch.
Download Mike's patch. Save the file (do not copy-paste it) to your mozilla/ directory.
- Apply the patch, using what you learned above. Remember the --dry-run option and to examine the paths of files in the patch.
- Rebuild the necessary parts of your tree:
$ cd mozilla/objdir $ cd xpcom $ make
- Run your browser and watch for messages in stderr
Life-cycle of a patch in review
When someone submits a patch, it goes through extensive review. It is rare that a patch is accepted "as is." Usually it will go through many iterations, with comments being made at each step.
Read the comments in the following bug to see an example of this process, and watch the evolution of the patch in terms of stylistic changes to the code, fixes, optimizations, etc:
https://bugzilla.mozilla.org/show_bug.cgi?id=343416
Resources
- Creating a patch for Mozilla
- Instructions for getting a patch checked into the tree
- There are many tutorials on using diff/patch, for example this one.
