How to operate the Imploder should be fairly obvious to the average Amiga user. So I'll try to highlight only those aspects of the user interface that aren't immediately obvious, and of course this document will explain how certain selections influence the processing behaviour. ------------------ The User Interface ------------------ ** Configuring the Imploder ** When you run the Imploder, either from the CLI or WorkBench, you'll notice the music and NTSC size screen. This setup is configurable by way of commandline switches or tooltypes. Note that, under Kick 1.3 or less, when one sets a tooltype using the WorkBench's info option, the appended "=" is required for proper recognition. The default setting is enabled music without modifications to the filter or NTSC/PAL mode. However, you can disable the music using the "NOMUSIC" commandline switch, or the "NOMUSIC=" tooltype. The lowpass filter can be disabled for less muffled sound by specifying "NOFILTER/NOFILTER=". To people with PAL Amigas, the shrunken NTSC screen might look ugly, however if there is a fat Agnus chip in your machine, it can be toggled from a 50Hz to 60Hz display refresh rate. Setting "NTSC/NTSC=" will cause the Imploder to do this whenever its screen gets upfront. In addition to this, there's the SHORTROOT configuration switch. This option is related to using the library. See the "library" document for further information on this. ** The File Requester ** Whenever there exists the need to specify a filename, a directory window will appear in front of the message window. Only a few of its options need clarification: -Switching on the ID toggle gadget causes the directory window to display the type ID's of all files. This is useful, for example, to check if files have already been imploded. This option will increase the time needed to access a directory though. -Clicking on the proportional scroll gadget on the left will cause the list of filenames to be sorted. -Switching off the .INFO toggle gadget causes the directory window not to display the *.info files used by the WorkBench's icon system. -Selecting a file is done by placing the mouse pointer on top of its name and clicking the left mouse button. In addition to the normal ways of confirming your selection, you can double-click on a filename. -Next to the immediately obvious ways of scrolling through a long directory, one can place the pointer within the filename window, press the left button, and while holding it down move the mouse above or below the filename window, try it; it works great once you get used to it. -One does not have to wait for the entire directory to load before selecting a file or entering a sub directory. ** Keyboard Equivalents ** Many functions selectable by mouse also react to keys. The menu options have the usual right-amiga+key shortcuts. In addition to this; - Hitting any key removes the about requester displayed during startup. - Use the escape key to exit the Imploder. - The "S" key starts processing. - When the merge/compression parameter window is present, you can select the compression mode using numeric keys, and increase/decrease the merge threshold using the "+" and "-" keys. You can cancel using ESC and proceed by hitting RETURN. - The deplode query requester reacts to the "Y" and "N" keys. ** Loading / Saving ** When you have specified a file for the Imploder to load, processing will commence (detailed below), and once finished the file requester pops up to query you for the destination. The source and destination paths are maintained in a special way that minimizes the chance of the destination not being what one wants. You could e.g. implode files from one directory and store them in another, or overwrite them in the source directory. In the first case it would be annoying if the destination directory defaults back to the source; you'd have to change it every time you want to write an imploded file. In the latter case, it'd be annoying to change to a different source directory and find out that the destination still points somewhere else. So the logic the Imploder uses is as follows; if you change to a different source directory, the destination directory will follow the source directory only if the destination is equal to the source. ** Batch Mode ** The Imploder can compress a series of executables by allowing you to specify multiple files by way of ?,#,* wildcards. All non-imploded executables matching the pattern will be processed. After entering the wildcards, the "merge and compression" parameter window will appear. The options present there will be explained below. The important thing to note here is that these selections will be global to all files processed during batch mode. Next, you'll be asked to specify a destination directory. This is were all batched executables will be saved after implosion. ---------- Processing ---------- Now you're familiar with the user interface, let me get on with explaining how the Imploder processes programs. The implosion processing sequence consists of four steps; -Loading & Format Verification. -Hunk Merging & Reloc Table Cleanup. -Implosion. -Decompression code installation, Overlay table adjustment and Saving. ** The Loader ** The loader reads the selected file. During this process, the executable file is analyzed. Format defects cause the loader to either report an error, and abort processing, or to give a warning while ignoring or repairing the defect. After having loaded a file, the "merge and compression" parameter window will appear. You can click the topright icon to collapse this window and review the status information produced by the loader. ** The Merger ** The merger is disabled by default. Most executables produced by modern compilers/linkers don't require this option, so if you're impatient you can skip to the next section. If selected, the merger will try to coalesce the hunks in a program to hunks of upto the merge threshold in size. If used in a constrained manner, this will reduce the size of the program, and the chance of memory fragmentation. If you specify a large merge threshold however, the resulting file will need large contiguous regions of memory in order to load, thus reducing the chance of it being able to be loaded into a fragmented system. Merging an executable file might break it. This is because certain programs make assumptions about the format of their segment list. The most notable members of this group are BCPL programs and a few libraries and devices. Hunk merging is therefore automatically disallowed for these. Still, some other programs, especially selfdetaching programs might dislike being merged. Regardless of whether a program has been merged or not, a reloc table cleanup routine is executed upon the file. This deletes empty reloc tables, coalesces matching reloc tables, and finally sorts the relocation offsets. This is of no consequence to how the program will look after it has been decompressed and relocated. ** Compression ** The compression algorithm can operate either in turbo mode or in normal mode. The normal mode requires no additional memory, whereas the turbo mode needs some 300K of additional hashing buffers. The turbo mode kicks-in automatically whenever the required amount of additional memory can be allocated. It is about ten to twenty times faster than the normal implosion mode. Note that the parameter window will report whether or not the current memory configuration allows the turbo to be enabled or not. You might try to free a few resources in order to make the target. Whenever you select a compression mode (gadgets 0-8), the turbo capability will be reevaluated. Various compression modes can be specified. These modes vary from zero (range = 128 bytes) to eight (range = 18K). The range related to each compression mode determines the maximum distance searched while looking for redundant data. The higher compression modes therefore have a better chance of compressing data. The time required to compress a program increases proportionally to the maximum distance in case of non-turbo operation. The processing speed during turbo operation however, is only slightly affected by varying the compression mode. So it only makes sense to fiddle with the compression mode if you don't have enough memory to have the Imploder run in turbo mode, and therefore want to speed things up (at the expense of a the compression efficiency). For all other instances it suffices to leave the compression mode at its maximum value (eight); for small executables the mode will automatically be scaled down to what the Imploder thinks is probably the most efficient one for the file at hand. During compression, the level meters to the right will display various relevant parameters. Going from left to right these are: 1. Percentage of program data still to be compressed. 2. New size of executable in % of the former size. Reevaluated continuously. 3. Skip. If a large chunk of non-compressable dat is encountered within a program, its level will start to rise. When it hits the top, the encoding limit has been exceeded. This is a rare occurance. 4. Length. Gives a measure of the redundancy of the data currently being processed. High levels indicate good compression. 5. Distance. Gives a measure of the non-locality of current redundancy. ** Decompression Code Installation ** All imploded executables require some additional memory in order to be able to decompress. The additional amount of memory required is about 50% of the original program size plus a constant amount of buffer space depending on the compression mode, and never larger than 20K. After decompression this memory is freed without causing memory fragmentation. Furthermore, the normal distribution of program-data across hunks is retained. This allows for the loading of imploded files into fragmented memory, and the proper distribution of hunks across chip and fast memory. The Imploder is able to install 3 different decompression algorithms into imploded executables; Library, Normal and Overlayed. LIBRARY IMPLODED files are the default, they are generated when; -The "Compress" gadget is enabled. -The "Library" gadget is enabled. -The processed executable isn't overlayed. To be able to use library Imploded files, copy the explode.library to your LIBS: directory. When you run a library imploded program, the decompression code in this library will be called. The library code is fast and removes the need of appending decompression code to every imploded file. The library has several special useful properties discussed in the "Library" document, but for simple use it suffices to make sure the library is in LIBS:. Pure programs may be library imploded. NORMAL IMPLODED files are generated when; -The "Compress" gadget is enabled. -The "Library" gadget is disabled (this is NOT the default). -The program being processed isn't overlayed. Normal imploded files have decompression code appended to them. A normal imploded program will run just like the original, and is independent; in contrast with library imploded files, normal imploded files don't require libraries or other special files to be present in your system. Disadvantages of normal Imploded files are that they are a couple of hundred bytes larger than library Imploded files, and their decompression speed is significantly slower. This is due to need for space optimizations in the decompression code. Once you normal-implode a pure program it's no longer pure. OVERLAYED IMPLODED files are generated when; -The "Compress" gadget is enabled. -the processed executable is overlayed. Overlayed programs are executables with additional appended hunks that are loaded during runtime. The Imploder will automatically recognize whether a program is overlayed. Overlayed files are rather loosely defined; basically the program is passed a bit of information that allows it to get at the appended hunks, but the means of doing so is left up to the programmer, though there is a standard technique specified by CBM which is used by the majority of overlayed executables. Because the Imploder decreases the size of the file, the offset of the overlay data also changes, and this must be corrected for. The Imploder knows how to do this for the standard overlay format. You'll be notified when the format isn't as the Imploder expects. Thus imploding overlayed files is not something which is guaranteed to succeed, so take heed; you should only implode overlayed files when you know what you are doing, and are willing to verify the results. --------- Deplosion --------- If you select an already imploded executable for processing (the ID gadget in the directory window allows you to see if files have already been imploded, at the cost of slower listing), you will be asked if you want to deplode it. If you confirm this query, the executable will be restored to a normal non-imploded format. Note that this format isn't necessarily bitwise identical to the original; the reloc tables are sorted, and you might have applied hunk merging (which is irreversible). Also, any symbol or debug hunks present in the original will have been stripped. Still, if you run the program, things will look the same to it, and this is ofcourse what counts. Note that there is a CLI based "Deplode" command available in the Tools directory which does basically the same thing. This is purely a matter of convenience ment for people that think of the CLI as convenient.