Network PC/Network PC.iso/amiga utilities/disk utilities/compression/imploderv4.0/imploder/docs/manual

Text File | 1997-11-21 | 13.3 KB | 291 lines

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.