.FP lucidasans.HTML "Cares for Mercury Poisoning.TLCares for Mercury Poisoning.brA tutorial for NIX's patch(1).AUFrancisco J. Ballesterosnemo@lsub.org.ABMercury poisoning (also known as hydrargyria or mercurialism) is adisease caused by exposure to mercury or its compounds.This document describes how to use NIX's patch(1) to avoidexposure to dangerous metal compounds..AE.SHMotivation.PPPlan 9 uses patches for sending contributions and a file replica tool to updateinstallations. For some time, NIX used mercurial to propagate updates and contributions.But this had a number of problems..IP 1The tool is not well suited to distribute binaries and does not preserve permissions..IP 2The Plan 9 support for the tool is buggy, to say the least..IP 3The tool is a departure from UNIX development in that you lose control over yourfiles, and it's not easy to edit updates and/or fix problems when they happen..IP 4Last but not least, it's not fun..LPAs an effort to make it easier and more amenable to contribute to NIX and toupdate NIX installations,.I patch (1)was written..PP.I Patchis a set of simple scripts that try to preserve the following properties:.IP 1Patches should have an easy to understand structure. If there are problems, usersshould be able to edit them and/or fix them..IP 2Patches should not depend on time-stamps, or other coherency enforcingmechanisms that force users to remove everything, and reinstall everything toget back into a coherent state. This happen to some replica users..IP 3Patches should respect changes made to a local installation, and respect theuser's freedom to customize the local system..SHUser interface.LPThere are a few scripts available:.IP \(bu.I Patch/createcan be used to create a patch..IP \(bu.I Patch/pullcan be used to update a local installation..LPOther tools are aimed at people maintaining the distribution, and will bedescribed later..SHPatch creation.LPTo create a patch, you can supply a list of files (and/or directories!) thatchange. Perhaps some of them have been removed, in which case the patchwill try to remove them when applied. For example:.P1; rm -rf /386/bin/hg /sys/src/cmd/hg; patch/create noexposure nemo@lsub.org /386/bin/hg /sys/src/cmd/hg <<EOFRemove things dangerous for health.EOF;.P2.LPwould create a patch called.I noexposurethat would remove the named files when applied. Well, actually, it would not removeanything, but print commands you can run to remove them..PPA more usual example is creating a patch that adds or edits some files:.P1; patch/create pwd-errors user@host.dom /sys/src/cmd/pwd.c /386/bin/pwdFix pwd to print errors to fd 2 rather than 1.^D.P2.LPThis creates a patch would change.I pwdwhen applied, and include a new binary for the command..PPThe created patch is kept at.I patches.lsub.orgfor others to look, until it's applied or forgotten..SHListing patches.LPAt any time, you can run.I patch/listto see which patches are still out for discussion, but are not yet applied to thedistribution:.P1; patch/listApr 18 11:55 morepmc: Changes in the pmc that somehow got lost.Apr 19 05:55 cppnsec: The change in nsec() not to cache fds broke cpp.Apr 19 07:00 liberror: rename nerrors to errstacksize in liberrorApr 19 10:10 plan9-20120419: Sync with plan 9 as of today.Apr 19 10:20 realloc: Ptal, I followed what lucio/forsyth suggested and added a delta variable..P2.LPYou could also list all the patches, including those already applied:.P1; patch/list -aApr 13 10:49 applied newprocess: Describe the new contribution process using patch(1).Apr 13 10:52 applied patchman: man updated for nix patch(1)..B ....P2.LPOr ask for more information about one patch (or all patches):.P1; patch/list -v newupapplied: newupdate: Apr 18 09:55	New version of up to use in the upcomming patch/pullbin.from: nemo@lsub.orgfiles:	/386/bin/up up	/sys/src/cmd/up.c up.c	/sys/man/1/up up.1removed:.P2.LPUnder.I filesyou get a list of files that are new or changed (they are listed in a file named.I fileswithin the patch directory).Under.I removedyou get a list of files that are going to be removed (listed in a file named.I removedwithin the patch directory)..SHPulling patches.LPTo get your NIX installation up to date with respect to the distribution, you can run.I patch/pullas shown:.P1; patch/pullpatch/apply creepyhalt/dist/patch/creepyhaltmerge...conflicts merging /sys/src/cmd/creepy/9p.c; 	see /n/dist/dist/patch/creepyhalt/9p.c.newconflicts merging /sys/src/cmd/creepy/cfg.c;	see /n/dist/dist/patch/creepyhalt/cfg.c.newconflicts merging /sys/src/cmd/creepy/fsys.c;	see /n/dist/dist/patch/creepyhalt/fsys.c.newconflicts merging /sys/src/cmd/creepy/ix.c;	see /n/dist/dist/patch/creepyhalt/ix.c.newexiting without changesapply failed.P2.LPIn this example, we have shown that.I applydetected some local changes and declared a conflict between the patch and yourlocal editions..PP.I Patch/pulltakes all the patches applied to the main distribution an applies one by one to your treeuntil one fails or all have been applied..PPIf we have our.I / '' ``mounted read-only, or want to pull to a different tree, we can bind at.I /n/distthe tree to be patched. If there is no tree bound there,.I pull(or actually,.I apply )binds your.I / '' ``directory there.For example, under 9vx we could:.P1; bind -c '#Z/usr/nemo/nix-os' /n/dist ; patch/pull.B ....P2.SHConflicts.LPWhat do we do upon conflicts? Here is where the simple structure of a patch helps.In the example of the last section, we had conflicts for files:.I 9p.c ,.I cfg.c ,and.I ix.c ..PPFirst, we have to see what to do. As you may note from the output shown in theexample of the previous section, you were asked to see files like.I /n/dist/dist/patch/creepyhalt/9p.c.new ..PPIn your local tree, that file is actually at.I /dist/patch/creepyhalt/9p.c.new .Patches that are being applied are copied to.I /dist/patchwhere it's more convenient for you to edit and/or adjust them at will beforeretrying to apply them..PPThe original file by the time of the patch creation for.I 9p.ccan be found in.I 9p.c.orig ,at the patch directory. So, this reports the diferences between what youwere expected to have, and your local version for the file:.P1; diff /dist/patch/creepyhalt/9p.c.orig /sys/src/cmd/creepy/9p.c31c31< ninestats(char *s, char *e, int clr, int verb)---> ninestats(char *s, char *e, int clr).B ....P2.LPYou may take several courses of action:.IP \(buDrop your changes. This can be done by simply copying the original fileas it was expected to be to your file:.P1; cp -x /dist/patch/creepyhalt/9p.c.orig /sys/src/cmd/creepy/9p.c.P2.LP.IP \(buDrop the changes in the distribution. Easy!, just remove the file from thelist of files to be patched:.P1; B /dist/patch/creepyhalt/files.I "... edit the file to remove the line for 9p.c ....P2.LP.IP \(buHand-edit the merge that failed..P1; cp -x /dist/patch/creepyhalt/9p.c.new /sys/src/cmd/creepy/9p.c; B /sys/src/cmd/creepy/9p.c.I "... locate the <<<<< and >>>> lines and edit at will ...; B /dist/patch/creepyhalt/files.I "... edit the file to remove the line for 9p.c ....P2.IPAn alternative could be to to copy the.I 9p.c.newto.I 9p.cin the patch directory, and then  copy.I 9p.c.origfrom the patch directory to your local version, after editing.I 9p.c.new ..LPIn general, you are welcome to edit the.I /dist/patch/*/filesand.I /dist/patch/*/removedfiles that list new or changed files and removed files..PPAfter resolving the conflicts, you can run.I patch/pullagain. It will use your local version for the patch as kept in.I /dist/patch ..PPAnother trick is to adjust the contents of.I /dist/patch/applied .That file contains the names of patches that have been applied.Thus, you can add a name there to skip or ignore that patch..I Pulltakes the list of applied patches from the main distribution, your one,and then goes one by one trying to apply patches that you have not yet applied.This command does also the trick:.P1; patch/applied creepyhalt.P2.LPIn this section we could see conflicts for files that exist. However, the conflictmay happen because the file was removed, or because it was not removed.The process in this case is exactly the same. When the.I .origfile does not exist in the patch directory, that means that the file was notexpected to exist in your tree..PPAlso, files to be removed when applying the patch are simply listed at.I /dist/patch/*/removed ,and you are of course welcome to edit that file..PPThe apply process will usually not remove any of your files, but printcommands that you could run to remove them if you want..SHReviewing code.LPYou might want to try a patch to drop some comments on it for reviewing.This can be done as follows:.P1; patch/apply newup/dist/patch/newupmerge...backup...copy...cpfile up /n/dist/386/bin/upcpfile up.c /n/dist/sys/src/cmd/up.ccpfile up.1 /n/dist/sys/man/1/updone.P2.LPNow you can play with the new.I upfrom the patch. Once you are done, you can get back to where you werebefore applying this patch by running:.P1; patch/undo newup.B ....P2.LPThis relies on the.I .backupfiles copied to the patch directory to restore your previous state..PP.SHUpdating a patch.LPSo, what do we do if due to a review or to a change of mind wewant to update a patch? Easy. We just create it again with the newset of files relevant for the patch (added, changed, or removed files).A new mail will be sent notifying the patch creation, and that mustbe understood as an update for the patch.The old versions for the patch are kept in sibling (renamed) directories,until the patch is applied to the main distribution..SHWhen everything fails....LPRemember that patches can be edited.First, you should probably make sure that your set of.I patchscripts is up to date. Newer versions of.I patchtake care of that by showing you which commands you have to runto update it when needed. But, in any case, we can always:.P1; 9fs sources.lsub.orgpost...; fcp -x /n/sources.lsub.org/nix/rc/bin/patch/* /rc/bin/patch.P2.LPOr using.I up (1)perhaps....P1; 9fs sources.lsub.org; up /n/sources.lsub.org/nix/rc/bin/patch /rc/bin/patch |rc.P2.LP