MkLibZ - What is it ?

View previous topic View next topic Go down

MkLibZ - What is it ?

Post  Yann on Tue 26 Aug - 3:57

******************* MKLIBZ v0.5 ********************
** **
** Based on MkLib v2.3, by Detlef Muller **
** Compression Feature added by Yann Collet **
*******************************************************



1) WHAT IS MKLIBZ

MKLIBZ is a Library Builder tool for HP48 (GX&SX)
which creates automatically Compressed Libraries
from a standard HP48 directory.

The resulting library transparently uncompress itself on the fly,
resulting in transparent memory savings.

EXAMPLE : Using PHANTASIE CONQUEST V1.16 (Lib 1782)
Uncompressed library size : 51 104 Bytes
MkLibZ, using BZ : 36 163 Bytes (decoder included)
Savings : 14 941 Bytes, -29%
MkLibZ, using TNT : 35 106 Bytes
Savings : 15 998 Bytes, -31%


As simple as it may sound, compression is not trivial for objects
which have references to other objects, such as programs (secondaries)
or lists for exemple.
In this case, references must be first translated into XLIB pointers.

Therefore, compression must happen during building process,
at the very moment when the object is translated with XLIB pointer,
but not yet merged into the main library output.
This is what proposes MkLibZ.




2) HOW TO USE IT

2.1) STANDARD USE

Just use MkLibZ as you would use original MkLib.
The original complete documentation is included in the package for reference.

The only compulsory control variable is the Library Number,
which must be saved into $ROMID in the same directory.

MkLib also offers advanced features, such as Library Title string,
selectable visibility, excluded variables, and much more.
Please refer to MkLib documentation to know all the possibilities.

By default, MkLibZ will try to compress all files to be included into the target library,
using the integrated default compressor, based on BZ2.


2.2) $NOCOMPRESS CONTROL VARIABLE

On top of existing control variables, a new optional one is provided,
$NOCOMPRESS
which offers selective compression.

This is a list of names, with all the objects you DON'T WANT to compress,
for whatever reason, performance being the one that comes to mind.

If $NOCOMPRESS is defined with NULL{} empty list :
' {} $NOCOMPRESS STO '
then compression will be disabled.

$NOCOMPRESS is optional.
If not present, all files will try compression.


2.3) USING AN EXTERNAL COMPRESSOR

You can choose to use your own compressor.
To trigger this mode, an UNCOMPRESS program must be present into the target directory.

In this case, the D->LIB builder will call 2 external programs :

- COMPRESS : This is the compressor.
It is a Global Id, typically in your Home directory,
but can also be declared into any directory above the target one.
You do not need to have COMPRESS into target directory.
If your compressor is a library (TNT-packer, for example)
then you simply need to call the compressor from the COMPRESS program.
(Example : << TNT >> 'COMPRESS' STO )

- UNCOMPRESS : This is the decompressor.
It *MUST* be present in the directory being built,
and it will be integrated into the final library.
It will be used by all compressed programs within the library.
UNCOMPRESS will be hidden in the resulting Library,
except if explicitly selected in $VISIBLE control variable.

If UNCOMPRESS is not present, D->LIB fallback to using the default compressor.
Note that, if $NOCOMPRESS = NULL{}, compression will be disabled, wether UNCOMPRESS is present or not.

You may use whatever compressor/decompressor you want, as long as
COMPRESS and UNCOMPRESS are present in there respective directory.

If UNCOMPRESS is present, but COMPRESS cannot be found, an error message will be displayed.



3) ADDITIONNAL COMMENTS

3.1) Q: I don't need to include a decompressor into my library.
I just want to call the decompressor from another library.
A: Use UNCOMPRESS to reference your decompressor.
For example, if TNT Library is installed, just type in target directory :
<< TNT >> 'UNCOMPRESS' STO
Although it is not visible on the stack, TNT is automatically translated into its XLIB reference pointer.
Of course, you will then need both libraries to be installed on the same calculator for the compressed one to work properly.

3.2) BZ
Once MKLibZ library is installed, you can use the included BZ program.
It is the last command in the library menu (Lib-->MkLibZ-->Prev-->BZ).
You may also simply type BZ on the calculator.
BZ can both compress and uncompress objects.

3.3) Known side effect :
Please note that a compressed Library cannot be translated if splitted with L->DIR.
What you'll get is a serie of compressed strings,
but the XLIB pointers will still be there, not translated.
It is a known limitation.

3.4) Efficiency
MkLibZ does not "blindly" compress everything.
A comparison is done after compression, and only files which bring tangible benefits
are allowed in their compressed form within the library.
For the time being, "tangible benefit" means
compressed output is at least 20 bytes (40 nibbles) shorter than original input.
This rule could be refined in future versions.
A (complex) idea could be to make it controllable through a Control Variable.

3.5) External compressors
A few programs are included in this package :
BZ(Mika Heiskanen) : The long-term standard compressor for HP48. Superseded by BZ2.
BZ2(Yann Collet) : 100% compatible BZ compressor, improved,
faster, and with better compression ratio.
Default compressor, integrated into MkLibZ
TNT(Damien Harper) : Rip of BZ, better compression ratio but much slower,
decoding speed especially is quite slow.
TNT2(Yann Collet) : Improved & compatible TNT compressor, much faster,
and with improved compression ratio. Best compression available.
LZD (Yann Collet) : Fast compressor, with an extremely fast optimized decoder.
Advised for improved responsiveness.



3.5) Contacts
MkLibZ is hosted at the "Phantasie Conquest" website, from the same author.
Website : http://phantasie.tonempire.net/portal.htm
Link : http://HPUtils.Webhop.org


Detlef Muller is the original author of MkLib.
Note that Detlef does not support MkLibZ by the time this documentation is written.
WebSite : http://www.klatho.com/detlef
Unfortunately, i could not contact him to inform him of this fork (email failure delivery).
So if you happen to know him, you're gladly welcomed to pass the word.

Yann
Admin

Number of posts : 174
Registration date : 2008-05-01

http://phantasie.tonempire.net

Back to top Go down

View previous topic View next topic Back to top


 
Permissions in this forum:
You cannot reply to topics in this forum