Power Packer V2.1b User Manual March 21, 1989 Preface ======= Congratulations, you have just obtained a copy of Power Peak's new and improved PowerPacker 2.1b. If you have suggestions or remarks about this program, or if you find any bugs, please let me know. This version of the PowerPacker is shareware, this means that if you use it a lot I would appreciate it if you'd send me a contribution of $10 or the same amount in any other currency.This money will enable me to produce more programs on the Amiga. If you send $15 I will send you the latest version of the PowerPacker. Write to the following address: Franois Nico Corbielaan 13 3060 Bertem BELGIUM Contents ======== 1. The Packer 1.1 An introduction 1.2 The file requester 1.3 The basic menus 1.3.1 Project 1.3.2 Prefs 2. Recrunch 2.1 How ? 2.2 Why ? 3. The HunkLab 3.1 Preferences 3.2 Process file 4. The Script Menu 5. The Supervisor Window 6. A Sample Session 7. PowerPacker 2.1b & the CLI 1. The Packer ------------- 1.1 An introduction The PowerPacker is a userfriendly command and data cruncher, this means a menu driven utility that can crunch almost any file on your disks. When you use it for the first time it's best to maintain a certain order in your actions (as we will see in chapter 6 of this document): (a) set the packer options at the beginning of a session (Prefs menu) (b) load the file from disk (Project menu) (c) save the file back to disk (Project menu) Apart from the crunching, you can also recrunch files that were crunched by some other crunchers. The HunkLab enables you to e.g. force code or data in chip ram The script, a new feature in 2.1b, allows you to e.g. crunch a dozen of files overnight. Before I demonstrate how to use the PowerPacker, let's look at the file requester and a brief overview of the menus and capabilities. 1.2 The file requester Whenever you are required to enter a filename, the packer sets up a file requester. This requester automatically contains all devices connected to your Amiga and lists all the files (and their length) of a selected directory. You don't have to wait for the directory read to end. You can select a file or directory the moment you see it, or you can enter it in the appropriate string gadget. However, if you wait for the directory read to end and quit the file requester, the next time you use it all the files will still be there, so you don't have to wait for the directory to be read again (This is very useful when you are recording a script, as you'll see later). This feature has one disadvantage : if files are changed or added to the selected directory they won't be shown in the list, or they will be shown with the wrong filelength, the next time the requester appears. Therefore, if you think anything has been changed to the selected directory, use the 'GET DIR' gadget to re-read the directory. (E.g. when you save a crunched file on top of the old one, the old file length will be shown in the requester.) 1.3 The basic menus 1.3.1 Project The project menu contains the file manipulation options. Most of them speak for themselves: Load -> Load a file from disk and start the (de) crunching. Save -> Save the (de)crunched or processed file in memory to disk. Delete -> Delete a file from disk. WorkBench -> Open or close WorkBench if possible. (Adds 42K !) About... -> Show general information and my address. Quit -> Quit the program. 1.3.2 Prefs The prefs menu contains all the (de)cruncher settings. You can select to (de)crunch command files or a data files. If you want the crunched version of your file to be executable, select 'Command file'. Now the PowerPacker knows it has to add a decrunch header (572 bytes). If the file you want to crunch only contains data (e.g. Source codes of your own programs) select the 'Data file' option. This can be handy if you're going to use the PowerPacker CLI commands. I'll discuss these commands in chapter 5 of this document. Finally you have to choose whether you want to crunch or decrunch the load file. Note: - The PowerPacker will automatically decrunch a previously crunched file. You don't have to select crunch or decrunch mode anymore as in PowerPacker 2.0a. The 'Decrunch Color' submenu contains the following options : Color 0 -> The background color will change while decrunching Color 1 -> The text color changes Pointer -> Only the mousepointer's color changes Scroll -> Handy for decrunching a demo (just try it out !) None -> If you're eyes are wearing out. These options indicate what color will flash when a file is decrunched. You can change this option before saving a crunched file, so you can save a version of your crunched program that flashes in color 1, and one that flashes in the mouse pointer. If the 'Color Crunch' option is selected, the PowerPacker will use the same color while crunching the file, giving you an idea what the decrunching will look like (provided that you don't change any options just before saving to disk). The default value is color 1. In the efficiency submenu you will find the following possibilities : Fast -> Use for small files, or for quick crunch. Mediocre -> Better but slower. Good -> Default, gains 40-50% in most cases. Very Good -> Also very slow ! Best -> Advised for script use only, ultra slow !!! Note: - 'Fast' is approx. 4 times faster than 'Good', 'Very Good' is 2 times slower and 'Best' 4 times. You can set Amiga's multitasking off to increase the crunching speed. The default setting is on. When you want to use the PowerPacker in a multitasking environment, you'll probably start a crunching job and at the same time continue your work. In that case, it might be interesting to set the 'LED Crunch' option on. Now your power-LED flashes while crunching,just like the screencolors. (but I presume they're already turned off because editing a file with flashing text really gets on your nerves) You can even turn off your monitor and still see when the cruncher has finished. Finally, you can set the paging in the supervisor window on so you can read the crunch and hunk information, without everything racing off the screen before you've had a chance to see it. Note: - While crunching, you can press both mousebuttons at the same time to abort. - Do *NOT* change disks when you are crunching with the multitasking switched off !!! The Amiga will crash !!! 2. Recrunch ----------- 2.1 How ? This menu is provided for the people who were using another cruncher or an older version of the PowerPacker. Just select 'Recrunch File' or 'Decrunch Only' and load the file. The PowerPacker will start the correct decrunch algorithm. If you selected 'Recrunch' the PowerPacker will start to crunch the decrunched file. If the PowerPacker doesn't recognize the cruncher it will say so, no harm is done. If you select 'Recrunch Always' the PowerPacker will always recrunch, even if the file was crunched with this version of the PowerPacker. Useful for recrunching files using a higher efficiency. (E.g. recrunch a 'Fast' crunched file in 'Best') Crunchers currently supported are: 'ANC Cruncher' 'TNM Cruncher 1.1','Relokit 1.0' and older PowerPacker files. If you'd like to see other crunchers supported, send me the cruncher and some programs crunched with it. (With a contribution I hope). If it is possible to develop a decrunch algorithm I will include it in the next version of the PowerPacker. 2.2 Why ? The PowerPacker always crunches better than the 'ANC Cruncher' and the 'TNM Cruncher'. It crunches better than 'Relokit' most of the time, but even if it doesn't, I advise you to recrunch because 'Relokit' has some serious disadvantages (e.g. while the decrunched file is running, the crunched version still eats memory). In contrast the PowerPacker only eats about 580 bytes while your file is running, and (of course) frees it afterwards. Note: - If you want to recrunch a PowerPacker 1.1 or 2.0 crunched file, the PowerPacker just replaces the file header with the improved and debugged 2.1 header. (Unless you've selected 'Recrunch Always') - The recrunch menu only supports command files ! You can't recrunch data files from e.g. PowerPacker 1.0, sorry 2. The Hunklab -------------- 2.1 Preferences This menu is not really part of the PowerPacker crunch/decrunch routines but it wasn't worth writing a separate program for and a HunkLab is after all a very interesting utility. You can e.g. use it to remove symbol and debug hunks from files that wouldn't crunch otherwise. You can force a program's code, data or BSS (uninitialised data) into chip ram or you can remove symbol tables and debug information just by toggling the marker on/off. So in future,when you want your programs to be able to run on a one megabyte system, a simple click on the mousebutton will do. 2.2 Process file 'Process file' reads the file from disk and changes it according to your preferences. To save the processed file, use 'Save' from the Project menu. 'Process & Crunch' will process the file and crunch the file afterwards (if possible). To save use 'Save' in the Project menu. 3. The Script Menu ------------------ This menu is a new feature in version 2.1b. It allows you to record 80 different commands to be executed after each other. It is ideal for crunching a lot of files overnight. Menu options are: 'Clear Script' and 'List Script' will do just that. 'Script Log File' is used to specify a file to redirect output to. If you cancel the requester no log file is used. 'Destination Dir' is used to specify the directory to save to. It is ghosted in the normal use. 'Start Recording' is used to start the recording of the script. If the script was empty you will be asked for the destination directory. You will also be asked whether to append '.pp21' to the destination file. You're advised to do this for data files. After selecting the destination you can start entering the script commands. Everything that is ghosted is not available as a command. Just enter everything as if you were actually using the PowerPacker. When you e.g. choose 'Load' the PowerPacker will ask a list of files to be (de)crunched. Press 'CANCEL' to exit the entry. Note: - You can still change the source and destination dir while recording. Every command you enter will be displayed in the supervisor window. 'Stop Recording' is used to exit the recording mode.'Delete Last' will delete the last command after a confirmation. 'Execute Script' finally, is used to start the playback of the script commands. If you press the menu button a requester will appear to ask you if you want to abort the script execution. After executing the script a request to clear the script will appear. Note: - It is advisable to let the filerequester buffer fill before you start selecting files. It is also better not to change the source directory too often. - The screen turns grey to indicate a script is executing. - While executing a script, the PowerPacker will always act destructive ! Files will allways be overwritten and deleted !!! 4. The Supervisor Window ------------------------ This window displays all kind of useful information like the file status, crunch messages, and error messages. You can follow all steps, from the original file that is loaded into memory, to the final crunched version on disk. When an executable file is loaded, its hunk information is displayed. This information is rather technical, but it can be useful for programmers. If you're not interested, just ignore it. I think it might be useful to give a list of possible error messages: (De)crunch : Buffer overflow ! (Crunched file is getting longer than original file) Crunch aborted ! (Crunching stopped by user or by buffer overflow) No memory for decrunch buffer ! Out of memory ! (Buy some more, or try closing the WorkBench) Sorry, can't crunch ! (This is a polite program) Can't find hunk_header. Hunk not allowed in load file! Unknown Hunk ! (Not a command file) Hunk not supported (yet ?) ! (If it's a symbol or debug hunk, try removing it in HunkLab) Nothing to save ! (Buffer is empty) Save Aborted ! Error reading file ! Can't open file ! Error writing data header ! Error writing buffer ! File not found ! Couldn't delete file ! Can't open file ! (Disk errors) Recrunch : No need to recrunch 'PowerPacker 1.1' command file, Replacing 1.1 decrunch header with 2.1 header... (2.1 header is shorter and bugfree,1.1 isn't) No need to recrunch 'PowerPacker 2.0' command file,Replacing 2.0 decrunch header with 2.1 header...(There was still a small bug in 2.0 header, so replace it.) Not crunched with one of the supported crunchers !! (Or file is not crunched at all !) Sorry, can't recrunch ! (We're always polite) Process : Sorry, can't process file ! (File is probably not a command file) Can't crunch file ! (File still contains unsupported hunks) Script : Script buffer full !! Please stop recording. (Script is limited to 80 commands, choose 'Stop Recording') 5. A Sample Session ------------------- Now that I have explained the PowerPacker's capabilities, it's time for a little demonstation. Let's say we want to crunch the 'CLI' command in the System directory on your Workbench 1.2 disk. Select 'Pointer' in the Prefs/Decrunch Color menu (When I wrote this text, it was very late and I couldn't stand the other decrunch colors anymore !) Set 'Prefs' to 'Command file'. Now select 'Load' in the Project menu (a file requester will appear), insert your WorkBench 1.2 disk and choose the 'CLI' command in the system directory. Now you'll see a lot of hunk information about the CLI command: Loading command file 'df0:System/CLI'... Hunk_header (0x03F3) 9 hunks (0 to 8). Hunk 0 : Hunk_code (0x03E9) (524 bytes) Hunk_reloc32 (0x03EC) Hunk 1 : Hunk_data (0x03EA) (428 bytes, 0 BSS) Hunk 2 : Hunk_code (0x03E9) (472 bytes) Hunk_reloc32 (0x03EC) Hunk 3 : Hunk_data (0x03EA) (52 bytes, 0 BSS) Hunk 4 : Hunk_code (0x03E9) (16 bytes) Hunk 5 : Hunk_code (0x03E9) (0 bytes) Hunk 6 : Hunk_code (0x03E9) (196 bytes) Hunk_reloc32 (0x03EC) Hunk 7 : Hunk_code (0x03E9) Hunk_reloc32 (0x03EC) Hunk 8 : Hunk_data (0x03EA) (0 bytes, 0 BSS) Crunching command file... Press left and right button to abort. Crunching, please wait. The cruncher displays the percentage of the file already crunched and after some time your screen will look like this: 100% crunched. Done. Original length : 2356 bytes. Crunched length : 1204 (1776) bytes. Gained 49% (1152 bytes) ! The only thing you have to do now is save this back to disk as an executable file. Now enjoy the crunched CLI command. 6. PowerPacker 2.1b & the CLI ----------------------------- For your convenience, I have also written two CLI commands, one to crunch and one to decrunch. Attention: These commands only (de)crunch DATA files !!!! (So to crunch executable files, you'll still have to use the PowerPacker 2.1b). A usage line is given by typing 'Crunch' or 'Decrunch' without arguments. You'll get something like this: 1> 1> crunch POWER-PACKER 2.1a Data Cruncher. Written by Lone Wolf from POWERPEAK. USAGE : Crunch [efficiency (1-5) default 3] [P] [F] Where P stands for no percentage, F for Forbid() crunching. 1> 1> decrunch POWER-PACKER 2.1a Data Decruncher. Written by Lone Wolf from POWERPEAK. USAGE : Decrunch [decrunch color (0-4)] With decrunch color 0/1 -> Color 0/1, 2 -> Pointer, 3 -> Scroll, 4 -> None If is a * the file will be typed to Output(). 1> These commands are useful to be included in your startup-sequence or to read crunched text files quickly. I don't think these commands need any further explanation. Just try them out and you'll see what happens. E.g. when you have a crunched source file of a program on your disk, typing Decrunch filename.c * will display the file as if you were using the 'Type' command for textfiles. Enjoy !!! PROGRAM HISTORY: ********************************************************* VERSION 1.0a First release. ********************************************************* VERSION 1.1a Fixed bugs. Improved crunch algorithm by about 5%. 'Delete' and 'Multitask' added. Better menu structure. Improved the file requester. Written CLI commands. ********************************************************* VERSION 2.0a Fixed some more bugs. Added buffer and automatic device-list to the file requester. Added 'LED Crunch', useful for turning the monitor off while crunching, and 'Paging'. New header, bug fixed. (1.1 didn't free mem when started from WorkBench) Added the hunklab.Improved CLI commands. ********************************************************* VERSION 2.1a Fixed last bug in header (2.0 crashed when you were out of mem) Added script feature, now possible to crunch files overnight. Improved requesters. Automatic crunch/decrunch. Improved menu structure considerably. Intelligent recrunch implemented. Automatic crunch/decrunch. Added 'Color Crunch' option. New efficiency 'Best' added. ********************************************************** VERSION 2.1b Bug fixed in script abort. Added ability to open a log file during script execute. Now possible to recrunch PowerPacker files with a higher efficiency. Recrunch detects unsupported crunchers a lot faster. Version supposed to work on NTSC Amiga (not tested !) ********************************************************** P.S. This text file crunched to 42% of it's original length. (Gained 58% !) The PowerPacker 2.1b written by François Nico (Lone Wolf). Special thanks to Pauwels Luc (Red Eagle) for writing the 2.0a manual and Tybergein Jorrit (Edain) for the extensive debugging. (c) 1989 François Nico / Power Peak // Thanks to \X/ Amiga for being the best computer ever !