This tutorial is designed to show you how to use those features of C.P.W. which enable you to modify CPW's code. It assumes that you know about wikis and the UsemodWiki conventions already. A general how-to-use-a-wiki page will be added later. Please feel free to post questions onto these pages if anything is unclear. Please note that we are in the middle of a name change (from SPW to CPW). So, some things are still "spw" (specifically, all of the actual program code uses "spw", as does much of the docs). Please pardon the confusion. ---- == Introduction == CPW is a wiki written in Perl which allows arbitrary community members to make changes to the wiki engine code. CPW runs as the user "spw", and it "owns" the directory <code>/spw</code>. Accordingly, the community can modify anything under the <code>/spw</code> directory (but not most other parts of the filing system). See FilesysCommands for a list of commands which view or modify the filesystem. The basic process for submitting a change to CPW's code is: # Download and prepare a local copy of CPW # Make your modifications to the code # Create a suitable patch file # Post your patch on the wiki (using the DoPatch command to indicate that it is not just conversation) # The patch will not be made until a peer review period has elapsed. During this period, any other user can veto the patch or extend the review period. After the peer review period (if no one has vetoed), CPW applies the patch. All proposed changes to the code must be approved by the community. When you submit a change, there is a 4 day peer review period. During this period, anyone may effectively veto your change -- either because they don't like it, or just because they want more than 4 days to consider it. To "veto" a change, modify the page containing the change in any way -- this restarts the approval period. Note that any change may be re-vetoed indefinitely (even by a single person). If/when a 4-day period elapsed without any new vetos, the proposed patch is applied automatically by the CPW software. == Example of modifying the code of CPW == This example should only take a few minutes to work through. (please update this estimate if I'm wrong). This example was checked against a GNU/Linux system. Maybe it works for other systems, too (let us know). ==== Step #1: Download and prepare your copy of CPW ==== : <code> cd /tmp wget -O spw.tar 'http://purl.net/net/cpw/spw.pl?action=download&path=\/spw\/spw.tar' tar -xovf spw.tar /tmp/spw/qsetup.pl </code> : While testing, remember that CPW currently does NOT work with mod_perl; under Apache, you may need to put an <code>.htaccess</code> file in <code>/tmp</code> or somewhere else with the line <code>SetHandler cgi-scipt</code> to turn off mod_perl. : If you need more information on this step, please see MakingALocalCopyOfSpw. : Some hints about running your own copy of CPW are at RunningALocalCopyOfSPW ==== Step #2: Make your modifications to the code ==== : <code> cd /tmp/spw/bin cp /tmp/spw/bin/spw_main.pl /tmp/spw/bin/spw_main.pl.old </code> : Now make your desired changes to /tmp/spw/bin/spw_main.pl. For example, you might add in : <code> } elsif ($action eq "stupid") { &ReportError(Ts("I'm stupid")); </code> : to the long chain of elsifs in sub DoOtherRequest. You should test and debug your changes on your own computer. ==== Step #3: Create a suitable patch file ==== : First, do this (<code>diffs</code> isn't a typo): : <code> ../diffs spw_main.pl.old spw_main.pl > my_patch </code> : This produces a unix patch file with absolute paths relative to CPW's base installation directory. For more information, see DiffsScript. ==== Step #4: Post your patch on the wiki ==== : Now, create a wiki page on CPW. Call it TestPatch. Put this in the editbox (it must be at the top, with nothing else before it): : <code> #DoPatch <nowiki><pre></pre></nowiki> </code> : Using a text editor, copy the contents of your patch file (<code>my_patch</code> in the example) and paste it into the wiki page, in between <nowiki><pre></nowiki> tags. You should have something a lot like <pre> #DoPatch <pre> *** /spw/bin/spw_main.pl.old Mon May 12 23:50:15 2003 --- /spw/bin/spw_main.pl Tue May 13 00:33:11 2003 *************** *** 2450,2453 **** --- 2450,2455 ---- } elsif ($action eq "showls") { &DoShowLs(); + } elsif ($action eq "stupid") { + &ReportError(Ts("I'm stupid")); } else { # Later improve error reporting </pre><code></pre></code> : If you need more information on this step, please see DoPatch. ==== Step #5: Wait ==== : Now save the page and wait 4 days. If no one modifies the page TestPatch for 4 days (i.e. if there are no vetos), your patch will be applied. If this happens, RecentChanges will show an entry like :: * (diff) TestPatch 6:58 am (65 changes) [EXECUTED PATCH COMMAND] . . . . . SPW : and the page TestPatch will be changed to show you the results of the patch; it will look something like: : #DidPatch; ::: Result: ::: <code>patching file /spw/bin/spw_main.pl</code> <pre> *** /spw/bin/spw_main.pl.old Mon May 12 23:50:15 2003 --- /spw/bin/spw_main.pl Tue May 13 00:33:11 2003 *************** *** 2450,2453 **** --- 2450,2455 ---- } elsif ($action eq "showls") { &DoShowLs(); + } elsif ($action eq "stupid") { + &ReportError(Ts("I'm stupid")); } else { # Later improve error reporting </pre> ==== End of example ==== == Other comments == Please be sure and read over other people's proposed changes to make sure they are good (and not hazardous to security). Be liberal in vetoing changes that you would like more time to read or think about. That's all you need to get started. For example, with this method you should be able to take a patch from UseMod:WikiPatches and apply it to spw_main.pl! If you are interested in learning more about how CPW works, you might be interested in the other pages in CategoryOverview. ---- CategoryOverview CategoryDocumentation
Summary:
This change is a minor edit.
To save this page you must answer this question:
How many letters are in the word SIX?
Username: