############################################################ Gnucash 1.9.x README.patches file. NOTE: THIS IS A DEVELOPMENT RELEASE!!! THIS VERSION HAS NOT BEEN TESTED PROPERLY AND MAY DO ABSOLUTELY ANYTHING! USE AT YOUR OWN RISK (AND KEEP *LOTS* OF BACKUPS) If you want something a bit more tested, please use the 1.8 stable series. ------------------------------------------------------------ Submitting a Patch: Once you have done some work that you would like to submit, you need to send a patch. There are two ways to submit a patch. First, if you're using SVN and only made changes to existing SVN files you can generate the patch using: svn diff > /tmp/mypatch and send /tmp/mypatch to gnucash-devel@gnucash.org with `[PATCH]' prefixed to the Subject: of the email. Note that this ONLY WORKS if you have NOT added any new files to the source tree. If your patch adds new files, use the `-N' flag to diff between a clean directory and your development directory. E.g. $ diff -urN {gnucash-pristine} {gnucash-mydevel} > /tmp/mypatch ******************************************************************* NOTE: The rest of this file describes an out-of-date utility that has not been adapted to SVN. Don't use it. ******************************************************************* If you've added new files then you should use a script called "make-gnucash-patch" to help you create the patch for submission. The script make-gnucash-patch is a perl script provided with the gnucash distribution that you can use to create your patch. The rest of this file explains how to use that perl script. This file comes in two parts: - A quick summary of the common ways to use make-gnucash-patch; and - A "users guide" style section giving detailed information on all the options for make-gnucash-patch. COMMON USAGE There are two methods. 1) Run ./make-gnucash-patch in your source directory. The script will then create two directories ../diff and ../tmp. In ../tmp it will then do a checkout of the cvs sources. If gnucash has already been checked out into this directory then only an update will occur. As a consequence of this you should make sure you are merged with current CVS before running make-gnucash-patch or you will find parts of the patch are reversing recent changes in CVS. make-gnucash-patch will then use makepatch to create a patch between the original directory and ../tmp/gnucash. makepatch will ask you for a description of the patch. And then the diff will be written to the diff file ../diffs/gnucash-YYYYMMDD-hhmmss-.diff.gz where Y=year, M=month, D=day, h=hour, m=minute, and s=second. make-gnucash-patch will then uuencode the diff to ../diffs/.uue. There are three vars you can set in a ~/.gnucash-patch.rc file. The file should look like this ---------------------------------------------------------------------- # -*- perl -*- $::should_uuencode = 0; $::ask_description = 0; $::diffcmd = "diff -up"; 1; ---------------------------------------------------------------------- This is basically a perl file that is sourced by the script. If you don't want the diff to be uuencoded (say you'll send the patch in email using mime and don't need it double encoded). Set $::should_uuencode to 0. If you don't want makepatch to ask you for the patch description (so the process is more automated possibly) set $::ask_description to 0. If you want to use a different diff command (not recommended for most) set $::diffcmd to something else (say, "gdiff -up"). 2) The second method is basically described below but it also includes the vars you can set from above. This method gives you more control over which directories are used. First, set up your development directories as follows: < GnuCash home development directory > | |---- < directory containing original GnuCash sources > | |---- < directory containing your modified GnuCash sources > A concrete example of those directories might be: /home/me/gnucash | |---- /home/me/gnucash/gnucash.pristine (original sources) | |---- /home/me/gnucash/gnucash.mywork (original sources + my edits) Copy the make-gnucash-patch script to the home development directory (/home/me/gnucash above). Now set three environment variables to reflect the names of your directories. Given the names above, you would use: export GNC_MAKEPATCH_OLD_DIR=gnucash.pristine export GNC_MAKEPATCH_NEW_DIR=gnucash.mywork export GNC_MAKEPATCH_HOME_DIR=/home/me/gnucash Right before you make your patch, make sure *both* your working and your pristine directories are in sync with cvs. Run 'cvs -z3 update -dP' in both directories to ensure that is the case. Updating from cvs in your working directory may cause conficts in a file. You must resolve those conficts before making a patch. Now run the script. Note that this script requires the programs 'makepatch', 'gzip', a 'diff' work-a-like, and 'uuencode' (and, of course, 'perl') to run. The same files will be generated for this method as the last (../diffs/*.diff.gz and ../diffs/*.diff.gz.uue). USERS GUIDE make-gnucash-patch supports a number of ways of providing required information. Some information can be provided through the use of environment variables or in the .gnucash-patch.rc file in your home directory. All information can be provided by command-line options. In all cases, the options given on the command-line override the information in both environment variables and the .gnucash-patch.rc file. Environment variables (where permitted) will override the .gnucash-patch.rc file. The general format for using make-gnucash-patch is: ./make-gnucash-patch where valid options are (in arbitrary order): --help, --h Display a short help message explaining available options. --prefix "homedir" Specifies the home directory path to use. This path is prepended to both the new and old directory names to give the full path for those directories. Defaults to: the parent directory. Environment variable: GNC_MAKEPATCH_HOME_DIR --old "olddir" The name of the directory containing the "pristine" or unmodified copy of the gnucash CVS tree. The directory path as determined by --prefix is prepended to this name to give the full directory path. Defaults to: ../tmp and will create if it doesn't exist. Environment variable: GNC_MAKEPATCH_OLD_DIR --new "newdir" The name of the directory containing the modified copy of the gnucash CVS tree. The directory path as determined by --prefix is prepended to this name to give the full directory path. Defaults to: the current directory. Environment variable: GNC_MAKEPATCH_NEW_DIR --diff "diffname" The name to give to the output ("diff") file containing the patch code. Defaults to: gnucash-YYYYMMDD-HHmmSS-XXXX.diff where: YYYY = current year (4 digit form) MM = current month (2 digit form) DD = current date (2 digit form) HH = current hour (24-hour 2 digit form) mm = current minutes (2 digit form) SS = current seconds (2 digit form) XXXX = userid of current user (arbitrary length) --diffcmd "command" The command to give to makepatch to generate the differences between two files. *NOT* Recommended for most users, only for those whom diff -up is non-functional. Defaults to: diff -up --file "filename" Generate a patch for ONLY this file. The path within the CVS tree must be specified (eg. src/MultiLedger.c) or the file cannot be matched. You can specify multiple files by seperating them by commas. You can also include this option multiple times. You *CANNOT* use this option with wildcards, regexps, or partial matches. Defaults to: none. See Also: --manifest --manifest "file" Use "file" as a manifest file (file that contains a list of all files to be compared in the making of the diff). Manifest files must contain one filename per line. Lines starting with # are ignored. --ignore "igname" Name of the file in the parent directory which contains regular expressions matching files which are to be excluded from the patch. This is in addition to a number of files which are automatically excluded by the script. Defaults to: none. --uuencode Specifies whether the resultant diff file should be --nouuencode uuencoded or not. uuencoding is a way of encrypting the file so that it is less likely to be corrupted during transmission over the internet. You should generally use it. Defaults to: On. .gnucash-patch.rc file: Yes ("$::should_uuencode = 0;" to override default). --zip Specifies whether the resultant diff file should be --nozip compressed or not. This is not always necessary when the patch is a small one. Defaults to: On. --ask Controls whether makepatch should ask for a description of --noask this patch or not. Defaults to: On. .gnucash-patch.rc file: Yes ("$::ask_description = 0;" to override default). THINGS TO NOTE - the script assumes (when using defaults) that it is being executed in the top directory of the modified CVS tree. This can be overridden by specifying prefix, old, and new directories. - the script assumes that both the "pristine" and modified copy are children of the same parent directory. - the script will check out a "pristine" copy of the CVS tree automatically if it cannot find the old directory you specify. Thanks in advance for your contribution!