home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 247.lha / PowerPaker_v2.2a / Packer.doc < prev    next >
Encoding:
Text File  |  1989-05-26  |  22.2 KB  |  522 lines
  1.  
  2.  
  3.  
  4.                         Power Packer 2.2a User Manual
  5.  
  6.                                  May 8, 1989
  7.  
  8.  
  9.  
  10. Preface
  11. =======
  12.  
  13.      Congratulations, you have just obtained a copy of the PowerPacker 2.2a,
  14. Power Peak's command and data cruncher for the Amiga.
  15.      If you have suggestions or remarks about this program, or if you find
  16. any bugs, please let me know.
  17.      This version of the PowerPacker is shareware, this means that if you use
  18. it a lot I would appreciate it if you'd send me a contribution of $10 or the
  19. same amount in any other currency.  This money will enable me to produce more
  20. programs on the Amiga.  If you send $15 I will send you the latest version of
  21. the PowerPacker.
  22.      Write to the following address:
  23.  
  24.                                 Nico François
  25.                                 Corbielaan 13
  26.                              3060 Bertem BELGIUM
  27.  
  28.  
  29. Contents
  30. ========
  31.  
  32. 1. The Packer
  33.      1.1 An introduction
  34.      1.2 The file requester
  35.      1.3 The basic menus
  36.           1.3.1 Project
  37.           1.3.2 Prefs
  38.  
  39. 2. Recrunch
  40.      2.1 How ?
  41.      2.2 Why ?
  42.  
  43. 3. The HunkLab
  44.      3.1 Preferences
  45.      3.2 Process file
  46.  
  47. 4. The Script Menu
  48.  
  49. 5. The Supervisor Window
  50.  
  51. 6. A Sample Session
  52.  
  53. 7. PowerPacker 2.2a & the CLI
  54.  
  55.  
  56. 1. The Packer
  57. -------------
  58.  
  59. 1.1 An introduction
  60.  
  61.      The PowerPacker is a userfriendly command and data cruncher, this means
  62. a menu driven utility that can crunch almost any file on your disks.  When
  63. you use it for the first time it's best to maintain a certain order in your
  64. actions (as we will see in chapter 6 of this document):
  65.  
  66.   (a) Set the packer options at the beginning of a session (Prefs menu)
  67.   (b) Load the file from disk (Project menu)
  68.   (c) Wait for the file to (de)crunch.
  69.   (d) Save the file back to disk (Project menu)
  70.  
  71.      Apart from crunching, you can also recrunch files that were crunched by
  72. most other crunchers.
  73.      The HunkLab enables you to e.g. force code or data in chip ram.
  74.      The script allows you to e.g. crunch a dozen of files overnight.
  75.  
  76.      Before I demonstrate how to use the PowerPacker, let's look at the file
  77. requester and a brief overview of the menus and capabilities.
  78.  
  79.  
  80. 1.2 The file requester
  81.  
  82.     Whenever you are required to enter a filename, the packer sets up a file
  83. requester.  This requester automatically contains all devices connected to
  84. your Amiga and lists all the files (and their length) of a selected
  85. directory.  You don't have to wait for the directory read to end.  You can
  86. select a file or directory the moment you see it, or you can enter it in the
  87. appropriate string gadget.
  88.  
  89.     However, if you wait for the directory read to end and quit the file
  90. requester, the next time you use it all the files will still be there, so you
  91. don't have to wait for the directory to be read again (This is very useful
  92. when you are recording a script, as you'll see later).  This feature has one
  93. disadvantage :  if files are changed or added to the selected directory they
  94. won't be shown in the list, or they will be shown with the wrong filelength,
  95. the next time the requester appears.  Therefore, if you think anything has
  96. been changed to the selected directory, use the 'GET DIR' gadget to re-read
  97. the directory.  (E.g.  when you save a crunched file on top of the old one,
  98. the old file length will be shown in the requester.)
  99.  
  100.  
  101. 1.3 The basic menus
  102.  
  103. 1.3.1 Project
  104.  
  105.     The project menu contains the file manipulation options.  Most of them
  106. speak for themselves:
  107.  
  108.   Load      ->  Load a file from disk and start the (de)crunching.
  109.   Save      ->  Save the (de)crunched or processed file in memory to disk.
  110.   Delete    ->  Delete a file from disk.
  111.   WorkBench ->  Open or close WorkBench if possible. (Adds 42K !)
  112.   Sleep     ->  Put the PowerPacker to sleep on the WorkBench Screen, this
  113.                 frees 40-50K.
  114.                 WARNING: All buffers will be deallocated, so you are advised
  115.                          to save things first.
  116.   About...  ->  Show general information and my address.
  117.   Quit      ->  Quit the program.
  118.  
  119. 1.3.2 Prefs
  120.  
  121.      The prefs menu contains all the (de)cruncher settings.  You can select
  122. to (de)crunch command files or a data files.  If you want the crunched
  123. version of your file to be executable, select 'Command file'.  Now the
  124. PowerPacker knows it has to add a decrunch header (572 bytes).  If the file
  125. you want to crunch only contains data (e.g. Source codes of your own
  126. programs), select the 'Data file' option.  This can be handy if you're going
  127. to use the PowerPacker CLI commands.  I'll discuss these commands in chapter
  128. 5 of this document.  Finally you have to choose whether you want to crunch or
  129. decrunch the load file.
  130.  
  131. Note: - The PowerPacker will automatically decrunch a previously crunched
  132.         file.  You don't have to select crunch or decrunch mode anymore as
  133.         in PowerPacker 2.0a.
  134.  
  135.      The 'Decrunch Color' submenu contains the following options :
  136.  
  137.   Color 0   ->  The background color will change while decrunching
  138.   Color 1   ->  The text color changes
  139.   Pointer   ->  Only the mousepointer's color changes
  140.   Scroll    ->  Handy for decrunching a demo (just try it out !)
  141.   None      ->  If your eyes are wearing out.
  142.  
  143.      These options indicate what color will flash when a file is decrunched.
  144. You can change this option before saving a crunched file, so you can save a
  145. version of your crunched program that flashes in color 1, and one that
  146. flashes in the mouse pointer.
  147.      If the 'Color Crunch' option is selected, the PowerPacker will use the
  148. same color while crunching the file, giving you an idea what the decrunching
  149. will look like (provided that you don't change any options just before saving
  150. to disk).  The default value is 'Color 1'.
  151.  
  152.      In the efficiency submenu you will find the following possibilities :
  153.  
  154.   Fast      ->  Use for small files, or for quick crunch.
  155.   Mediocre  ->  Better but slower.
  156.   Good      ->  Default, gains 40-50% in most cases.
  157.   Very Good ->  Also very slow !
  158.   Best      ->  Advised for script use only, ultra slow !!!
  159.  
  160. Note: - 'Fast' is approx. 4 times faster than 'Good', 'Very Good' is
  161.         2 times slower and 'Best' 4 times.
  162.       - 'Best' isn't always the best.  Small files crunch best with
  163.         'Very Good' or even 'Good'.
  164.  
  165.      You can set Amiga's multitasking off to increase the crunching speed
  166. (slightly).  The default setting is on.  When you want to use the PowerPacker
  167. in a multitasking environment, you'll probably start a crunching job and at
  168. the same time continue your work.  In that case, it might be interesting to
  169. set the 'LED Crunch' option on.  Now your power-LED flashes while crunching,
  170. just like the screencolors.  (but I presume they're already turned off
  171. because editing a file with flashing text really gets on your nerves.)
  172.      You can even turn off your monitor and still see when the cruncher has
  173. finished.
  174.  
  175.      Finally, you can set 'Paging' in the supervisor window on so you can
  176. read the crunch and hunk information, without everything racing off the
  177. screen before you've had a chance to see it.
  178.  
  179. Note: - While crunching, you can press both mousebuttons at the same
  180.         time to abort.
  181.       - Do *NOT* change disks when you are crunching with the multitasking
  182.         switched off !!!  The Amiga will crash !!!
  183.  
  184. 2. Recrunch
  185. -----------
  186.  
  187. 2.1 How ?
  188.  
  189.      This menu is provided for the people who were using another cruncher or
  190. an older version of the PowerPacker.  Just select 'Recrunch File' or
  191. 'Decrunch Only' and load the file.  The PowerPacker will start the correct
  192. decrunch algorithm.  If you selected 'Recrunch' the PowerPacker will start to
  193. crunch the decrunched file.  If the PowerPacker doesn't recognize the
  194. cruncher it will say so, no harm is done.  If you select 'Recrunch Always'
  195. the PowerPacker will always recrunch, even if the file was crunched with this
  196. version of the PowerPacker.  Useful for recrunching files using a higher
  197. efficiency.  (E.g. recrunch a 'Fast' crunched file with 'Best')
  198.  
  199.      Crunchers currently supported are:  'ANC Cruncher', 'TNM Cruncher 1.1',
  200. 'Relokit 1.0', 'HQC Cruncher 2.0', 'MasterCruncher 3.0', 'DragPack 1.0' and
  201. older PowerPacker files.  If you'd like to see other crunchers supported,
  202. send me the cruncher and some programs crunched with it.  (Together with a
  203. contribution I hope).  If it is possible to develop a decrunch algorithm I
  204. will include it in the next version of the PowerPacker.
  205.  
  206. 2.2 Why ?
  207.  
  208.      The PowerPacker always crunches better than the 'ANC Cruncher',
  209. 'TNM Cruncher' and 'HQC Cruncher'.  It crunches better than 'Relokit' most of
  210. the time, but even if it doesn't, I advise you to recrunch because 'Relokit'
  211. has some serious disadvantages (e.g.  while the decrunched file is running,
  212. the crunched version still eats memory).  In contrast the PowerPacker only
  213. eats about 580 bytes while your file is running, and (of course) frees it
  214. afterwards.
  215.  
  216. Note: - If you want to recrunch a PowerPacker 1.1 or 2.0 crunched file, the
  217.         PowerPacker just replaces the file header with the improved and
  218.         debugged 2.2 header. (Unless you've selected 'Recrunch Always')
  219.       - The recrunch menu only supports command files !  You can't recrunch
  220.         data files from e.g. PowerPacker 1.0, sorry.
  221.  
  222. 2. The Hunklab
  223. --------------
  224.  
  225. 2.1 Preferences
  226.  
  227.      This menu is not really part of the PowerPacker crunch/decrunch routines
  228. but it wasn't worth writing a separate program for and a HunkLab is after all
  229. a very interesting utility.  You can e.g. use it to remove symbol and debug
  230. hunks from files that wouldn't crunch otherwise.
  231.  
  232.      You can force a program's code, data or BSS (uninitialised data) into
  233. chip ram or you can remove symbol tables and debug information just by
  234. toggling the marker on/off.  So in future, when you want your programs to be
  235. able to run on a one megabyte system, a simple click on the mousebutton will
  236. do.
  237.  
  238. 2.2 Process file
  239.  
  240.      'Process file' reads the file from disk and changes it according to your
  241. preferences.  To save the processed file, use 'Save' from the Project menu.
  242.      'Process & Crunch' will process the file and crunch the file afterwards
  243. (if possible).  To save use 'Save' in the Project menu.
  244.  
  245. Note: - Debug and symbol hunks are only used in debuggers, so you can safely
  246.         remove them from a program. (Unless you want to debug the program.)
  247.  
  248. 3. The Script Menu
  249. ------------------
  250.  
  251.      The script is something that will save you a lot of time, it allows you
  252. to record 80 different commands to be executed after each other.  It is ideal
  253. for crunching a lot of files overnight.  Menu options are:
  254.  
  255.      'Clear Script' and 'List Script':
  256.           will do just that.
  257.      'Script Log File':
  258.           is used to specify a file to redirect output to.  If you cancel
  259.           the requester no log file is used.
  260.      'Destination Dir':
  261.           is used to specify the directory to save to.  It is ghosted in
  262.           normal use.
  263.      'Start Recording':
  264.           is used to start the recording of the script. If the script was
  265.           empty you will be asked for the destination directory.  You will
  266.           also be asked whether to append '.pp22' to the destination file.
  267.           You're advised to do this for data files.
  268.               After selecting the destination you can start entering the
  269.           script commands.  Everything that is ghosted is not available as a
  270.           command.  Just enter everything as if you were actually using the
  271.           PowerPacker.  When you e.g. choose 'Load' the PowerPacker will
  272.           ask a list of files to be (de)crunched. Press 'CANCEL' to exit the
  273.           entry.
  274.           Note: - You can still change the source and destination dir while
  275.                   recording.
  276.           Every command you enter will be displayed in the supervisor window.
  277.      'Stop Recording':
  278.           is used to exit the recording mode.
  279.      'Delete Last':
  280.           will delete the last command after a confirmation.
  281.      'Execute Script':
  282.           will start the playback of the script commands.  If you press the
  283.           menu button a requester will appear to ask you if you want to abort
  284.           the script execution.
  285.               After executing the script a request to clear the script will
  286.           appear.
  287.  
  288. Note: - It is advisable to let the filerequester buffer fill before you
  289.         start selecting files.  It is also better not to change the source
  290.         directory too often.
  291.       - The screen turns grey to indicate a script is executing.
  292.       - While executing a script, the PowerPacker will always act
  293.         destructive !  Files will allways be overwritten and deleted !!!
  294.  
  295. 4. The Supervisor Window
  296. ------------------------
  297.  
  298.      This window displays all kind of useful information like the file
  299. status, crunch messages, and error messages.  You can follow all steps, from
  300. the original file that is loaded into memory, to the final crunched version
  301. on disk.  When an executable file is loaded, its hunk information is
  302. displayed.  This information is rather technical, but it can be useful for
  303. programmers.  If you're not interested, just ignore it.
  304.  
  305.      I think it might be useful to give a list of possible error messages:
  306.  
  307. (De)crunch :  Buffer overflow !
  308.                 (Crunched file is getting longer than original file)
  309.               Crunch aborted !
  310.                 (Crunching stopped by user or by buffer overflow)
  311.               No memory for decrunch buffer !
  312.               Out of memory !
  313.                 (Buy some more, try selling your WorkBench :-)
  314.               Sorry, can't crunch !
  315.                 (This is a polite program)
  316.               Can't find hunk_header.
  317.               Hunk not allowed in load file!
  318.               Unknown Hunk !
  319.                 (Not a command file)
  320.               Hunk not supported (yet ?) !
  321.                 (If it's a symbol or debug hunk, try removing it in HunkLab)
  322.               Nothing to save !
  323.                 (Buffer is empty)
  324.               Save Aborted !
  325.               Error reading file !
  326.               Can't open file !
  327.               Error writing data header !
  328.               Error writing buffer !
  329.               File not found !
  330.               Couldn't delete file !
  331.               Can't open file !
  332.                 (Disk errors)
  333.  
  334. Recrunch :    No need to recrunch 'PowerPacker 1.1' command file,
  335.               Replacing 1.1 decrunch header with 2.2 header...
  336.                 (2.2 header is shorter and bugfree, 1.1 isn't !!)
  337.               No need to recrunch 'PowerPacker 2.0' command file,
  338.               Replacing 2.0 decrunch header with 2.2 header...
  339.                 (There was still a small bug in 2.0 header, so replace it.)
  340.               Not crunched with one of the supported crunchers !!
  341.                 (Or file isn't crunched at all !)
  342.               Sorry, can't recrunch !
  343.                 (Please don't sue me :-)
  344.  
  345. Process :     Sorry, can't process file !
  346.                 (File is probably not a command file)
  347.               Can't crunch file !
  348.                 (File contains unsupported hunks)
  349.  
  350. Script :      Script buffer full !! Please stop recording.
  351.                 (Script is limited to 80 commands, select 'Stop Recording')
  352.  
  353. 5. A Sample Session
  354. -------------------
  355.  
  356.      Now that I have explained the PowerPacker's capabilities, it's time for
  357. a little demonstation.  Let's say we want to crunch the 'CLI' command in the
  358. System directory on your Workbench 1.2 disk.
  359.  
  360.      Select 'Pointer' in the Prefs/Decrunch Color menu (When I wrote this
  361. text, it was very late and I couldn't stand the other decrunch colors
  362. anymore !)
  363.  
  364.      Set 'Prefs' to 'Command file'.  Now select 'Load' in the Project menu
  365. (a file requester will appear), insert your WorkBench 1.2 disk and choose the
  366. 'CLI' command in the system directory.  Now you'll see a lot of hunk
  367. information about the CLI command:
  368.  
  369.                                                                              
  370.      Loading command file 'df0:System/CLI'...                                
  371.                                                                              
  372.      Hunk_header (0x03F3)                                                    
  373.         9 hunks (0 to 8).                                                    
  374.      Hunk  0 : Hunk_code (0x03E9)     (524 bytes)                            
  375.                Hunk_reloc32 (0x03EC)                                         
  376.      Hunk  1 : Hunk_data (0x03EA)     (428 bytes, 0 BSS)                     
  377.      Hunk  2 : Hunk_code (0x03E9)     (472 bytes)                            
  378.                Hunk_reloc32 (0x03EC)                                         
  379.      Hunk  3 : Hunk_data (0x03EA)     (52 bytes, 0 BSS)                      
  380.      Hunk  4 : Hunk_code (0x03E9)     (16 bytes)                             
  381.      Hunk  5 : Hunk_code (0x03E9)     (0 bytes)                              
  382.      Hunk  6 : Hunk_code (0x03E9)     (196 bytes)                            
  383.                Hunk_reloc32 (0x03EC)                                         
  384.      Hunk  7 : Hunk_code (0x03E9)     (68 bytes)                             
  385.                Hunk_reloc32 (0x03EC)                                         
  386.      Hunk  8 : Hunk_data (0x03EA)     (0 bytes, 0 BSS)                       
  387.                                                                              
  388.      Crunching command file...                                                  
  389.      Press left and right button to abort.                                   
  390.      Crunching, please wait.                                                 
  392.  
  393.      The cruncher displays the percentage of the file already crunched and
  394. the gain so far. After some time your screen will look like this:
  395.  
  396.                                                                              
  397.      100% crunched.                                                          
  398.      Done.                                                                   
  399.      Original length : 2356 bytes.                                           
  400.      Crunched length : 1204 (1776) bytes.                                    
  401.      Gained 49% (1152 bytes) !                                               
  403.  
  404.      The only thing you have to do now is save this back to disk as an
  405. executable file.  Now enjoy the crunched CLI command.
  406.  
  407.  
  408. 6. PowerPacker 2.2a & the CLI
  409. -----------------------------
  410.  
  411.      For your convenience, I have also written two CLI commands, one to
  412. crunch and one to decrunch.
  413.      Attention:  These commands only (de)crunch DATA files !!!!  (So to
  414. crunch executable files, you'll still have to use the PowerPacker 2.2a).
  415.      A usage line is given by typing 'Crunch' or 'Decrunch' without
  416. arguments.  You'll get something like this:
  417.  
  418. 1>
  419. 1> crunch
  420. POWER-PACKER 2.2a Data Cruncher.
  421.   Written by Nico François (POWER PEAK)
  422. USAGE : Crunch <source> <destination> [efficiency (1-5) default 3] [P] [F]
  423.         Where P stands for no percentage, F for Forbid() crunching.
  424. 1>
  425. 1> decrunch
  426. POWER-PACKER 2.2a Data Decruncher.
  427.   Written by Nico François (POWER PEAK)
  428. USAGE : Decrunch <source> <destination> [decrunch color (0-4)]
  429.    With decrunch color 0/1 -> Color 0/1, 2 -> Pointer, 3 -> Scroll, 4 -> None
  430.    If <destination> is a * the file will be typed to Output().
  431. 1>
  432.  
  433.      These commands are useful to be included in your startup-sequence or to
  434. read crunched text files quickly.
  435.  
  436.      I don't think these commands need any further explanation.  They work
  437. just like the CLI Copy command.  Just try them out and you'll see what
  438. happens.  E.g. when you have a crunched source file of a program on your
  439. disk, typing
  440.  
  441.      Decrunch filename.c *
  442.  
  443. will display the file as if you were using the 'Type' command for textfiles.
  444.  
  445.                                                    Enjoy !!!
  446.  
  447.  
  448.                               PROGRAM HISTORY:
  449.  
  450. *****************************************************************************
  451. VERSION 1.0a
  452.  
  453.      First release.
  454.  
  455. *****************************************************************************
  456. VERSION 1.1a
  457.  
  458.      Fixed bugs.
  459.      Improved crunch algorithm by about 5%.
  460.      'Delete' and 'Multitask' added.
  461.      Better menu structure.
  462.      Improved the file requester.
  463.      Written CLI commands.
  464.  
  465. *****************************************************************************
  466. VERSION 2.0a
  467.  
  468.      Fixed some more bugs.
  469.      Added buffer and automatic device-list to the file requester.
  470.      Added 'LED Crunch', useful for turning the monitor off while crunching,
  471.      and 'Paging'.
  472.      New header, bug fixed. (1.1 didn't free mem when started from WorkBench)
  473.      Added the hunklab.
  474.      Improved CLI commands.
  475.  
  476. *****************************************************************************
  477. VERSION 2.1a
  478.  
  479.      Fixed last bug in header (2.0 crashed when you were out of memory, oops)
  480.      Added script feature, now possible to crunch files overnight.
  481.      Improved requesters.
  482.      Automatic crunch/decrunch.
  483.      Improved menu structure considerably.
  484.      Intelligent recrunch implemented.
  485.      Automatic crunch/decrunch.
  486.      Added 'Color Crunch' option.
  487.      New efficiency 'Best' added.
  488.  
  489. *****************************************************************************
  490. VERSION 2.1b
  491.  
  492.      Bug fixed in script abort.
  493.      Added ability to open a log file during script execute.
  494.      Now possible to recrunch PowerPacker files with a higher efficiency.
  495.      Recrunch detects unsupported crunchers a lot faster.
  496.      The PowerPacker now automatically opens a PAL/NTSC screen.
  497.  
  498. *****************************************************************************
  499. VERSION 2.2a
  500.  
  501.      All known bugs (or better, undocumented features) fixed.
  502.      'Sleep' mode implemented, useful for multitasking freaks.
  503.      While crunching the gain percentage so far is displayed.
  504.      Recrunch now supports 'HQC Cruncher 2.0', 'MasterCruncher 3.0'
  505.        and 'Dragpack 1.0'.
  506.      New graphics in title.
  507.  
  508. *****************************************************************************
  509.  
  510.  
  511. P.S. This text file crunches to 42% of it's original length. (Gains 58% !)
  512.  
  513. The PowerPacker 2.2a written by Nico François. (Yes, Nico is my first name)
  514. Special thanks to Pauwels Luc for the icons and writing the 2.0a manual,
  515.                   Tybergein Jorrit for the extensive debugging.
  516.  
  517. (c) 1989 Nico François / Power Peak
  518.  
  519.                                    //
  520.                        Thanks to \X/ Amiga for being the best computer ever !
  521.  
  522.