Power Packer 2.3a User Manual Aug 14, 1989 Preface ======= Congratulations, you have just obtained a copy of PowerPacker 2.3a, PowerPeak's command and data cruncher for the Amiga. If you have suggestions or remarks about this program, or if you find any bugs, please let me know. This version of 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 US or the same amount in any other currency. This money will enable me to produce more programs on the Amiga. If you send $15 US ($20 US overseas) I will send you the latest version of PowerPacker. Please send money by international money order, EuroCheck (in Belgian Francs (BF) !!!!!) or cash, it's difficult for me to cash in other checks. If you send for an update please state your current version, if there is no higher version at the time I get your letter I won't reply until I finish the next version, so don't be alarmed if it takes a while ! Write to the following address: Nico François 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 1.3.3 Crypt 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 1. The Packer ------------- 1.1 An introduction PowerPacker is a userfriendly command and data cruncher, this means a menu driven utility that can crunch almost any file on your disks. It can be started from the CLI or the WorkBench, just type it's name in the CLI window or doubleclick it's icon. PowerPacker will detach itself from the CLI so you can close the CLI window. 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) Check the packer options at the beginning of a session (Prefs menu) (b) Load the file from disk (Project menu) (c) Wait for the file to (de)crunch. (d) Save the file back to disk (Project menu) Apart from crunching, you can also recrunch files that were crunched by most other crunchers. The HunkLab enables you to e.g. force code or data in chip ram. The script allows you to e.g. crunch a dozen of files overnight. Before I demonstrate how to use 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.) When the 'Sort Files' switch in the prefs menu is checked the files will be alphabetically sorted in the requester. This switch is present because some people don't like the files being sorted and jumping up and down the requester, they think it's annoying to try and catch the file you want. (and they are right of course :-) 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 !) Sleep -> Put PowerPacker to sleep on the WorkBench Screen, this frees 40-50K. WARNING: All buffers will be deallocated, so you are advised to save things first. 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 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 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 7 of this document. Finally you have to choose whether you want to crunch or decrunch the load file. NOTE: - 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 your 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. The default value is 'Pointer'. 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. - 'Best' isn't always the best. Small files crunch best with 'Very Good' or even 'Good'. The remaining preference switches: Data suffix -> Attach '.pp' suffix to data files after crunching or remove '.pp' after decrunching. It is advised that you leave this switch on so you can easily spot crunched data files. Encrypt Data -> See section 1.3.3 of this manual. Color Crunch -> Flash the selected decrunch color when crunching, giving you an idea what the decrunching will look like (provided that you don't change any options just before saving to disk). LED Crunch -> Your power-LED flashes while crunching, just like the screencolors. Now, you can even turn off your monitor and still see when the cruncher has finished. Multitask -> Switch multitasking off to (sligtly) increase the crunching speed. Paging -> Pause and wait for mouse button when supervisor window fills up. Overwrite -> Don't prompt if it's ok to overwrite a file when saving. Sort files -> Sort files in file requester. Use 'Save prefs' to save the preferences to your boot disk. The preferences will be saved in the file 's:PowerPacker.prefs', this file will be enormous, euh, 6 bytes big. When PowerPacker 2.3a is first started it will attempt to load this file and adjust the preferences. 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 !!! 1.3.3 Crypt When the 'Encrypt Data' switch is on PowerPacker will not only crunch data files, it will also encrypt them so nobody else but you can decrunch them. Just before crunching a data file PowerPacker will ask you for a password. You will be presented with a string gadget with a special feature, it won't show you what you are typing ! After entering your password you will be asked to enter it again, this is done to verify that you haven't made a typing error (unless you make the same error twice :-). You can also use the 'Last' gadget to re-enter your last password again, or the 'Abort' gadget to abort the encryption and just crunch the file. When you try to load a crunched encrypted data file PowerPacker will once again prompt you for your password. If you enter the correct one the data file will be decrypted and decrunched. If you don't know the password, bad luck, there is no way you can decrunch this file !! NOTE: - Encryption can currently not be used in a script. - Your password can be up to 16 characters long, any character is accepted, lowercase and uppercase are DIFFERENT !!!! - Take care when using the 'Last' gadget, be sure to know what your last password was. - Don't forget your password !! It is *IMPOSSIBLE* to decrypt a file without the password !!!!! 2. Recrunch ----------- 2.1 How ? This menu is provided for the people who were using another cruncher or an older version of PowerPacker. Just select 'Recrunch File' or 'Decrunch Only' and load the file. PowerPacker will start the correct decrunch algorithm. If you selected 'Recrunch' PowerPacker will start to crunch the decrunched file. If PowerPacker doesn't recognize the cruncher it will say so, no harm is done. If you select 'Recrunch Always' PowerPacker will always recrunch, even if the file was crunched with this version of PowerPacker. Useful for recrunching files using a higher efficiency. (e.g. recrunch a 'Fast' crunched file with 'Best') Crunchers currently supported are: 'ANC Cruncher', 'TNM Cruncher 1.1', 'Relokit 1.0', 'HQC Cruncher 2.0', 'MasterCruncher 3.0', 'DragPack 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. (Together with a contribution I hope). If it is possible to develop a decrunch algorithm I will include it in the next version of PowerPacker. 2.2 Why ? PowerPacker always crunches better than the 'ANC Cruncher', 'TNM Cruncher' and 'HQC 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 PowerPacker only eats about 530 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, 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.1, sorry. - 'Decrunch Only' is not 100% guaranteed for 'Relokit 1.0' files, 'Recrunch' however is 100% ok ! (It's a strange world ! :-) - Several people sent me 'dirty' crunchers, these are crunchers that use absolute addresses (an absolute TABOO !!!). It is impossible to develop a decrunch algorithm for these. (In fact, nothing should have been crunched with these crunchers in the first place !) 3. The Hunklab -------------- 3.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. 3.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. NOTE: - Debug and symbol hunks are only used in debuggers, so you can safely remove them from a program. (Unless you want to debug the program.) 4. The Script Menu ------------------ The script is something that will save you a lot of time, 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 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. 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 PowerPacker. When you e.g. choose 'Load' 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': will 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, PowerPacker will always act destructive ! Files will allways be overwritten and deleted !!! 5. 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, try selling your 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.3 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.3 header... (There was still a small bug in 2.0 header, so replace it.) Not crunched with one of the supported crunchers !! (Or file isn't crunched at all !) Sorry, can't recrunch ! (Please don't sue me :-) Process : Sorry, can't process file ! (File is probably not a command file) Can't crunch file ! (File contains unsupported hunks) Script : Script buffer full !! Please stop recording. (Script is limited to 80 commands, select 'Stop Recording') 6. A Sample Session ------------------- Now that I have explained 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 (the 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 (or junk ?? :-) information about the CLI command:   Scanning file 'df0:System/CLI'...  Loading command file...   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)  (68 bytes)  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 the gain so far. 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. Enjoy this program !!! 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 memory, oops) 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 execution. Now possible to recrunch PowerPacker files with a higher efficiency. Recrunch detects unsupported crunchers a lot faster. PowerPacker now automatically opens a PAL/NTSC screen. ***************************************************************************** VERSION 2.2a All known bugs (or better, undocumented features) fixed. 'Sleep' mode implemented, useful for multitasking freaks. While crunching the gain percentage so far is displayed. Recrunch now supports 'HQC Cruncher 2.0', 'MasterCruncher 3.0' and 'Dragpack 1.0'. New graphics in title. ***************************************************************************** VERSION 2.3a PowerPacker detaches itself from the CLI, so the CLI window can be closed or used for other things. CLI commands are greatly enhanced, they now use ARP. New switch : 'Overwrite' to surpress 'OK to overwrite ?' request. File requester now able to sort files, 'Sort files' switch. By popular demand: encryption of data files is now possible using the new 'Encrypt Data' switch. Encryption should be IMPOSSIBLE to crack !! Also by popular demand: Now possible to save preferences to boot disk. More memory efficient decrunch and recrunch of PowerPacker files. Decrunch source included, so other programs could be written that would load data files crunched with PowerPacker. 'Data Suffix' switch to improve adding/removing of '.pp' suffix. Decrunch color default 'Pointer'. Improved scanning of files when loading or recrunching. Fixed small bug (version 2.2a lost 256 bytes every time it was run). More info in about window. ***************************************************************************** PowerPacker 2.3a written by Nico François (Yes, Nico is my first name :-) Special thanks go to - Luc Pauwels for the icons and writing the 2.0a manual, - Jorrit Tybergein for the extensive debugging. - everybody who mailed me suggestions or remarks. (c) 1989 Nico François / Power Peak // Thanks to \X/ Amiga for being the best computer ever !