home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / general / progs / patch / !Patch / ReadMe < prev    next >
Encoding:
Text File  |  1992-05-11  |  10.5 KB  |  258 lines
  1.  
  2. Writing patch definitions for !Patch.
  3. -------------------------------------
  4. It is recommended that any patch files supplied separately from !Patch be
  5. neatly bundled into an application directory which Filer_Runs them all for
  6. you when you double click on it. In this way a path variable can be set up
  7. for the directory, allowing unambiguous yet directory and filing system
  8. independent file paths to be quoted for accessing other patch files,
  9. transform files and *commands.
  10.  
  11. Directory verification.
  12. -----------------------
  13. When writing patch files, you should remember that !Patch needs to be able
  14. to verify that the correct application directory is being dealt with. So
  15. for example the sole purpose of the patch may be to put a !Sprites22 file
  16. into the application directory, but this will not be sufficient for
  17. !Patch to be certain that it is patching the correct directory. The best
  18. way is to specify some words in the !RunImage that !Patch can verify. It
  19. will then only move the !Sprites22 file in if the words in the !RunImage
  20. match.
  21.  
  22. There should always be some words, bytes or strings in a patch that
  23. actually change (or a file which is created or deleted). If not, !Patch
  24. cannot tell the difference between a directory which has had the patch
  25. applied to it and one which has not. This is not a particularly great
  26. restriction - there is always a version number in some file or other
  27. that should be modified anyway.
  28.  
  29. File extension.
  30. ---------------
  31. It is possible to extend the file being patched, simply by specifying
  32. ChangeWord commands which are off the end of the file. In this case, the
  33. old bytes should be specified as &00.
  34.  
  35. File types.
  36. -----------
  37. When specifying file types, as well as the standard (real) file types the
  38. following numbers may be used:
  39.  
  40.         &2000           Application directory
  41.         &1000           Standard directory
  42.         0               File type not important (anything will match)
  43.         -1              Untyped file (load and exec addresses)
  44.  
  45. Patch file format.
  46. ------------------
  47. The BootStrap patch file inside !Patch is read on startup, which causes the
  48. patch files stored inside the Patches sub-directory to be read. Patch files
  49. should have a filetype of Patch (&FC3). Files with any other filetype will
  50. be ignored.
  51.  
  52. The patch files are textual in nature. Each line of a patch file can
  53. be one of:
  54.  
  55.     blank
  56.     start with a # to be a comment line
  57.     of the form Command:other parameters
  58.  
  59. Blank and comment lines are ignored.
  60. Other lines have the following meanings:
  61.  
  62. PatchesDir:<file or directory path>
  63. This causes the path specified to be recursively scanned for more patch
  64. files. This is typically used so that you only have to Filer_Run one
  65. patch file (eg. Filer_Run MyPatch:StartUp) in your !Run file to get
  66. !Patch to automatically find all the patch files in the directory
  67. specified.
  68. eg.
  69. PatchesDir:Patch:Patches
  70.  
  71. TransformsFile:<file path>
  72. This adds the file specified to the list of files looked in to build the
  73. *commands for performing transformations.
  74. eg:
  75. TransformsFile:Patch:Transforms
  76.  
  77. Application:<program name> <file type>
  78. This introduces some patches for the named application.
  79. eg:
  80. Application:!PCEm &2000
  81.  
  82. Description:<program description>
  83. This is a textual description of the application.
  84. eg:
  85. Description:Acorn PC Emulator
  86.  
  87. Patch:<patch name>
  88. This introduces a patch and gives it a textual name. This name will be what
  89. is quoted in the patch query window.
  90. eg:
  91. Patch:Fix bug in version 1.60 with DOSDisc hard disk images
  92.  
  93. File:<file name> <file type>
  94. This introduces some patches for the named file in the application. Note
  95. that the file name quoted should always start with the application directory
  96. - this allows individual files to have patches for them.
  97. eg:
  98. File:!PCEm.!RunImage &FF8
  99.  
  100. Transform:<transform>
  101. This optional field indicates that the file has had the named transform
  102. applied to it. The patches will be applied to the untransformed form of
  103. the file. A list of default transforms can be found in the Transforms
  104. file of !Patch. Currently this is Squeeze, and do nothing (Copy).
  105. eg:
  106. Transform:Squeeze
  107.  
  108. Location:<location>
  109. This indicates the byte location in the unsqueezed (or whatever) file for
  110. the following changes. To specify in decimal just give the number. To
  111. specify in hex prefix the number with an &. The location is always in the
  112. unpatched file. Where the patched file ends up with a different length,
  113. appropriate adjustments are made to the location in the target file.
  114. Effectively this means that two locations are maintained.
  115. eg:
  116. Location:&1B2D0
  117.  
  118. ChangeWord:<from> <to>
  119. This describes the change required to a single word at the current location.
  120. Location advances by four each change, so you may give a sequence. The
  121. current location should be word aligned (a multiple of four) when this
  122. keyword is specified.
  123. eg:
  124. ChangeWord:&059D0008 &13500003
  125. ChangeWord:&028DD010 &13A00000
  126. ChangeWord:&13A00000 &059D0008
  127. ChangeWord:&128DD010 &E95BA800
  128.  
  129. VerifyWord:<word>
  130. This specifies that the word at the current location must match the word
  131. specified. The locations are advanced by four.
  132. eg:
  133. VerifyWord:&54230001
  134.  
  135. ChangeByte:<from> <to>
  136. This describes the change required to a single byte at the current location.
  137. Location advances by one each change, so you may give a sequence.
  138. eg:
  139. ChangeByte:&BD 65
  140.  
  141. VerifyByte:<byte>
  142. This specifies that the byte at the current location must match the byte
  143. specified. The locations are advanced by one.
  144. eg:
  145. VerifyByte:&23
  146.  
  147. ChangeString:<from> <to>
  148. This describes the change required to a string at the given location.
  149. <from> and <to> must be of the same length, and are in GSTrans format.
  150. The strings must not contain spaces, as space is the seperator between the
  151. two strings. Use <32> instead of space. The current location advances by
  152. the length of the strings, so you may give a sequence.
  153. eg:
  154. ChangeString:Verify<32>:4|M Verify<32>4|M<0>
  155.  
  156. VerifyString:<string>
  157. This specifies a string which must match the string found at the current
  158. location. The locations are then advanced by the length of the string.
  159. eg:
  160. VerifyString:<127>foobar<32><0>
  161.  
  162. ReplaceFile:<file name>
  163. OldContents:<file name> <file type>
  164. NewContents:<file name> <file type>
  165. This causes the file in the application directory to be replaced with a
  166. new version of the file supplied within the patches directory. The old
  167. version of the file is also supplied in the patches directory to allow
  168. patch removal. No checking of the file contents is performed, so you
  169. should ensure there is enough verify or change data for other files in
  170. the application to allow !Patch to be certain it is dealing with the
  171. correct directory eg. verify some words in the !RunImage. You may use
  172. verify data for the file to be replaced, so for example you could verify
  173. the comment string at the start of a !Run file since that is unlikely to
  174. have been edited by the user. If you do this, the data verified must be
  175. present and correct in both the OldContents file and the NewContents file.
  176. eg:
  177. ReplaceFile:!PCEm.!Boot
  178. OldContents:Patch:Files.Acorn.PCEm.Old.!Boot &FEB
  179. NewContents:Patch:Files.Acorn.PCEm.New.!Boot &FEB
  180.  
  181. CreateFile:<file name>
  182. NewContents:<file name> <file type>
  183. This causes the file in the application directory to be created, its
  184. contents being taken from the file specified in the patches directory.
  185. eg:
  186. CreateFile:!PCEm.!Sprites22
  187. NewContents:Patch:Files.Acorn.PCEm.New.!Sprites22 &FF9
  188. CreateFile:!PCEm.!Sprites23
  189. NewContents:Patch:Files.Acorn.PCEm.New.!Sprites23 &FF9
  190.  
  191. DeleteFile:<file name>
  192. OldContents:<file name> <file type>
  193. This causes the file in the application directory to be deleted. Its
  194. contents are provided to allow patch removal.
  195. eg:
  196. DeleteFile:!PCEm.!Boot
  197. OldContents:Patch:Files.Acorn.PCEm.Old.!Boot &FEB
  198.  
  199. Transforms file format.
  200. -----------------------
  201. The transforms files are processed using MessageTrans. The tokens looked up
  202. for a given transform are <transform>_Prepare and <transform>_Finish to get
  203. the actual *commands, and <transform>_PrepareSlot and <transform>_FinishSlot
  204. to get the Wimp slot size (in K) that each command gets to start with. The
  205. documentation for the transforms is here rather than in the Transforms file
  206. as MessageTrans reads the entire of the Transforms file into memory,
  207. comments and all.
  208.  
  209. For <transform>_Prepare, %0 is the initial file and %1 is the file that
  210. will actually be patched.
  211.  
  212. For <transform>_Finish, %0 is the patched file and %1 is the final file.
  213.  
  214. In both cases, %2 is a filename that printed output from the transforming
  215. program should be redirected to. For a program that does not print anything
  216. (eg. UnSqueeze) it need not be specified. After the transformation
  217. program has been run, if the error file exists and is of non zero size its
  218. contents will be displayed in an error box. !Patch will then attempt to
  219. continue ie. it is not assumed that the presence of output means an error
  220. occured. In fact in the case of squeeze, if there is any output there
  221. was an error, and !Patch will get a "File not found" error when it attempts
  222. to continue. (Note that use of %2 in this way is not yet implemented.)
  223.  
  224. After SWI MessageTrans_GSLookup has been called, the results should be
  225. a valid *command which will perform the job, which is passed to SWI
  226. Wimp_StartTask. This may of course be an Obey file. Application space
  227. may be used however you like, as the *command is running as a new wimp
  228. task with its own application space.
  229.  
  230. The Prepare transformation is exercised a lot. Not only is it used while
  231. performing the actual patching but it is also used while scanning
  232. directories and after patching has been performed to work out whether
  233. the patches for a file can be applied, removed, or neither. Therefore
  234. the prepare transformation should ideally be fast, small and memory
  235. resident eg. UnSqueeze is performed by a small module loaded by !Patch.!Run.
  236. The benefit of being memory resident is that you have to swap floppy disks
  237. much less often. The benefit of being small is that you can afford to be
  238. memory resident. Squeeze takes a lot of memory to run, so you should not
  239. rmload huge modules just so you can have memory resident prepare transforms
  240. as this may then mean there is insufficient memory for Squeeze to run
  241. when a particularly large file is patched eg. !DTP.!RunImage.
  242.  
  243. 'Copy' is the standard "transform" used for files which need no
  244. transforming. This is because we patch in <Wimp$Scrap> and the transform
  245. performs the copying operations.
  246.  
  247. 'Squeeze' is the transform used for programs which have been run through
  248. the squeeze program supplied with the Acorn C and Assembler packages.
  249.  
  250. eg:
  251. Copy_PrepareSlot/Copy_FinishSlot:8
  252. Copy_Prepare/Copy_Finish:Copy %0 %1 ~A ~C ~D F ~L ~N ~P Q ~R S ~T ~V
  253.  
  254. Squeeze_PrepareSlot:0
  255. Squeeze_Prepare:UnSqueeze %0 %1
  256. Squeeze_FinishSlot:32
  257. Squeeze_Finish:Run Patch:Library.squeeze %0 %1
  258.