plainblack.com
Username Password
search
Bookmark and Share

Appendix 2: Writing Patches for WebGUI

As you continue to develop applications or core modules for WebGUI, you may find yourself in the precarious situation of needing to update existing code or apply changes to core prior to an update. A good way to do this is to create a patch file and apply the patch to existing source.

 

Before getting started with writing patches, you'll need two packages: GNU patch and GNU diffutils. Your operating system vendor should provide these as part of the default installation. If not, you'll typically find pre-compiled packages for them in your operating system's package collection. If neither option is available, you can learn more about the packages at their respective homepages. Learn more about GNU patch at http://www.gnu.org/software/patch/ ; learn more about GNU diffutils at http://www.gnu.org/software/diffutils/ . Windows users can download binary packages at http://gnuwin32.sourceforge.net/ . Before using either command for the first time, it is wise to read the documentation included with each.

 

diff and patch work together to allow developers to distribute changes to existing code. diff compares two files, or directory trees, given as command line arguments and outputs a summary of how the two differ from one another. This summary is encoded in one of several formats. By default, diff outputs a format compatible with the POSIX standard to the standard output. However, developers frequently use the context format (-c command line option) and the unified format (-u command line option) for patches intended for distribution to other developers.

 

This is only the first part of the process, however. One needs a program to apply the changes documented in the diff file. This chapter uses the patch program (first developed by Larry Wall, who also created Perl). patch reads the output of the diff command on standard input by default. patch has many options, including the -p option. This specifies how many directories to remove from the file paths in the diff output, used for locating the original and modified files on disk. See patch's documentation for more information.

 

Developing Against a Release

To develop new code based on the version of WebGUI you have installed, you'll need to make a copy of the existing code. This serves two purposes. First, it serves as a backup copy in case you somehow break WebGUI in a way you cannot fix. Second, it creates a pristine copy against which you'll run the diff command.

 

To create a patch file for WebGUI, start by making a copy of the WebGUI core you'll be changing.

 

cp -R /data/WebGUI /data/WebGUIOrig

 

Once you've made all of the changes to source, create a patch or diff file containing all of the changes made to code.

 

cd /data/WebGUI

diff -urN /data/WebGUIOrig . > mypatch.diff

 

Before applying the patch to the new code, it is wise to verify that the patch will apply correctly. patch provides a command line option (--dry-run in newer versions, --check in older versions) to verify that the patch will apply correctly. For example:

 

patch -p0 --dry-run < /path/to/mypatch.diff

 

The output will be the same as if --dry-run had not been specified. patch will remain mostly quiet upon success, and will complain about errors. However, no files will be written or changed with the --dry-run option present.

 

This file can then be moved to a matching WebGUI distribution and applied to the source as follows:

 

cd /data/WebGUI

patch -p0 < /path/to/mypatch.diff

 

Patch will attempt to apply all of the changes specified in the diff file created to existing source, making it an extremely convenient way to patch for WebGUI.

 

Developing With the Latest Code

In addition to modifying code in the installed version of WebGUI, you can also develop against the latest code from WebGUI's Subversion repository. If you want to contribute new features to WebGUI, this is the way to go. The procedure is largely similar to that described above, with a couple of exceptions. First, there is no need to make a copy of the source code. Your backup and basis of comparison live in the Subversion repository. Second, use svn diff rather than diff:

 

cd /data/WebGUI

svn diff > mypatch.diff

 

Patching remains the same. Remember to frequently update your checkout so that you're not developing against old code.

Keywords:

Search | Most Popular | Recent Changes | Wiki Home
© 2018 Plain Black Corporation | All Rights Reserved