667
edits
Changes
no edit summary
[[Dive into Mozilla]] > [[Dive into Mozilla Day 3]] > Incremental Build Lab
== 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.
NOTE: portions of this lab are applicable to the tree as at the time of writing (i.e., February 27, 2007), specifically the example patches discussed below.
== 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.
=== 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:
#include <stdio.h>
...
/* DEBUG_<username> is defined at build time, and Faculty is the username in the lab */
#ifdef DEBUG_Faculty
printf("Hello World!\n");
#endif
* 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, go to the parallel location in your objdir and run make there
$ cd mozilla/objdir/netwerk/protocol/http
$ 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:
$ cd mozilla/netwerk/protocol/http
$ 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/netwerk/protocol/http
$ patch -p0 < patch.txt
* 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/netwerk/protocol/http
$ patch -R -p0 < patch.txt
* Check to make sure the changes in patch.txt are gone from the file.
=== Applying a real patch ===
* One of the projects a Seneca student (Andrew Smith) has been working on is support for animated PNGs ([[APNG]]]). The work is not complete and being reviewed (see [https://bugzilla.mozilla.org/show_bug.cgi?id=257197 bug 257197]).
* Read https://bugzilla.mozilla.org/show_bug.cgi?id=257197
* Download Andrew's latest patch ([https://bugzilla.mozilla.org/attachment.cgi?id=254449 attachment 254449] at the time of writing). Save the file some to your mozilla directory.
* Apply the patch:
$ cd mozilla
$ patch -p1 < [''patch_filename'']
* Rebuild the necessary parts of your tree:
$ cd mozilla/objdir
$ cd modules/libimg
$ make
$ cd ../libpr0n
$ make
$ cd ../../browser/app
$ make clean
$ make
or, if you prefer one long command:
cd mozilla/objdir/modules/libimg && make && cd ../libpr0n && make && cd ../../browser/app && make clean && make
* Run your browser and load the APNG images at: http://littlesvr.ca/apng/
=== 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=208739
== Resources ==
* http://developer.mozilla.org/en/docs/Creating_a_patch
== 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.
NOTE: portions of this lab are applicable to the tree as at the time of writing (i.e., February 27, 2007), specifically the example patches discussed below.
== 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.
=== 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:
#include <stdio.h>
...
/* DEBUG_<username> is defined at build time, and Faculty is the username in the lab */
#ifdef DEBUG_Faculty
printf("Hello World!\n");
#endif
* 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, go to the parallel location in your objdir and run make there
$ cd mozilla/objdir/netwerk/protocol/http
$ 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:
$ cd mozilla/netwerk/protocol/http
$ 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/netwerk/protocol/http
$ patch -p0 < patch.txt
* 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/netwerk/protocol/http
$ patch -R -p0 < patch.txt
* Check to make sure the changes in patch.txt are gone from the file.
=== Applying a real patch ===
* One of the projects a Seneca student (Andrew Smith) has been working on is support for animated PNGs ([[APNG]]]). The work is not complete and being reviewed (see [https://bugzilla.mozilla.org/show_bug.cgi?id=257197 bug 257197]).
* Read https://bugzilla.mozilla.org/show_bug.cgi?id=257197
* Download Andrew's latest patch ([https://bugzilla.mozilla.org/attachment.cgi?id=254449 attachment 254449] at the time of writing). Save the file some to your mozilla directory.
* Apply the patch:
$ cd mozilla
$ patch -p1 < [''patch_filename'']
* Rebuild the necessary parts of your tree:
$ cd mozilla/objdir
$ cd modules/libimg
$ make
$ cd ../libpr0n
$ make
$ cd ../../browser/app
$ make clean
$ make
or, if you prefer one long command:
cd mozilla/objdir/modules/libimg && make && cd ../libpr0n && make && cd ../../browser/app && make clean && make
* Run your browser and load the APNG images at: http://littlesvr.ca/apng/
=== 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=208739
== Resources ==
* http://developer.mozilla.org/en/docs/Creating_a_patch
