
			    ********

          READ THIS FILE AND THE FAQ (ESPECIALLY SECTION 1)
                  BEFORE INSTALLING E2COMPR.

      PLEASE, READ AND FOLLOW VERY CAREFULLY THE INSTALLATION
    INSTRUCTIONS, *EVEN* IF YOU ALREADY INSTALLED E2COMPR ONCE.

      I TAKE NO RESPONSIBILITY FOR WHATEVER MAY ARISE BECAUSE
          OF THE USE OF THIS CODE. USE AT YOUR OWN RISK.

			    ********

Newbie note: When shell commands are printed on a line by themselves in this
  document, they are generally preceded by "# ", which indicates that the
  command should be issued as the superuser (unless you know yourself
  what permissions are required and, like me, are hesitant about using
  superuser privileges unnecessarily).

  Thus:

	# ls

  means that you should either have logged in as `root' or have run `su' (and
  responded with root's password when asked) prior to issuing an `ls' command.
  Do not type the `# ' as part of the command.

 [pjm: Since I'm supposed to be making this package less of a hackers-only
  affair, I thought I might as well include the above clarification.]


This file is organised into 3 sections.  Section A describe how to
build a new kernel.  Part B describes how to build and install the
utilities.  Part C describes how to update e2fsck in order to make
e2compr more powerful.

If this is the first time you're installing e2compr, you may choose
to do only parts A and B and then experiment with it.  You will have a
restricted version, but you can play with it.

Then you can go to part C, and install a new version of e2fsck.  This
will allow you to compress much bigger files.

			    ********

  Foreword about e2fsck:
  ----------------------

The unrestricted version of e2compr needs some changes in e2fsck.  A
patch is provided for that if you have the sources of e2fsck (as found
in e2fsprogs); otherwise, there is a precompiled version of e2fsck
that you can install if you wish.  It is statically linked, so there
shouldn't be any problems.  It is installed when you do `make install'
(or `make install.e2fsck') from the `prebuilt' directory of this
distribution.

Alternatively you can install it by doing:

   # install -o root -g root -m 755 e2fsck /sbin
   # ln -sf e2fsck /sbin/fsck.ext2

if you don't want the existing e2fsck to be backed up (as
/sbin/e2fsck-VERS).

			    ********

  A) Updating the kernel
  ----------------------

E2compr is a simple patch against the ext2 fs code.  You just have to
apply the patch and recompile your kernel.

Here are more precise instructions.  I assume you have the correct
permissions for everything (e.g. by running the commands as root), and
that you are in the directory that was created after extracting the
e2compr archive (i.e. the directory where you find this file).

  1. First, check if you have the correct kernel sources and
     patch.  If you have a recent 2.0 kernel, then the correct patch is
     included in this distribution.  If you have an older kernel, take a
     look at Antoine's page (or upgrade your kernel).  No patch is
     available for 2.1 kernels, though creating one shouldn't be difficult.

     For kernel 2.0.x (certainly with 18 <= x <= 27; probably for others),
     the correct patch file is "e2compr-patch-2.0.18+".  This file was
     derived from D. Niemi's work by Peter Moulder.

     For kernel 1.3.x with x >= 9 and x < {some number I haven't tried to find
     out}, the correct patch file is 'e2compr.patch-1.3.9'.  This file was
     derived from the original patch by D. Niemi.

     For kernel 1.3.x, with x < 9, you can use the same patch as for
     kernel 1.2.x.

     If you have kernel 1.2.x, the correct patch file is
     'e2compr.patch-1.2.0'.  This is the work of Antoine de Maricourt.

     If you have only 1.1.xx, it may work, but you'd better update the
     kernel first. 

     In the following text, PATCH_FILE will refer to the correct patch
     file for your kernel version.

  2. IF, AND ONLY IF, THIS IS THE FIRST TIME YOU INSTALL THE PATCH,
     make sure there is absolutely no file on your ext2 partitions that has
     the EXT2_COMPR_FL turned on.  One way of achieving this is:

       # find /ext2/partition/paths -xdev -type f -o -type d -print0 |
         xargs -0 lsattr -d | grep -v '^..-'

     (where /ext2/partition/paths might be `/ /usr /home').  If there
     are some compressed files, try to find why, and to turn it off
     (e.g. by doing `chattr -c').  If such files are left on the file
     system after you built the new kernel, they will probably cause
     errors when accessed (the data should however not be lost).

     Note: there is absolutely no reason to have files with the
           COMPR_FL set, unless you played with chattr before.

  3. Apply the patch.  If your kernel source tree is in the directory
     /usr/src/linux, you can do the following commands:

       # patch -d /usr/src/linux -p1 < PATCH_FILE

     Note: if you have a previous version installed, you will first need
	   either to uninstall that one with `patch -d /usr/src/linux -R
	   -p1 < OLD_PATCH_FILE', or else to start with a clean kernel source
	   tree.

  4. Verify if the patch has been correctly applied:

       # find /usr/src/linux/fs/ext2 -name '*.rej' -print
       # find '/usr/src/linux/include/linux -name 'ext2*.rej' -print

     If one of these commands echoes some file name, the patch has
     not been correctly applied.  You should abort now.  In this case,
     you can cancel the effect of applying the patch at step 3 with
     the command 'patch -R -d /usr/src/linux -p1 < PATCH_FILE'.

  5. Remove the original files (this is optional):

       # find /usr/src/linux/fs/ext2 -name '*.orig' -exec rm {} \;
       # find '/usr/src/linux/include/linux -name '*.orig' -exec rm {} \;

  6. Tune the configuration: look at the file ext2_fs.h in directory
     /usr/src/linux/include/linux, and search for the string
     'Compression configuration parameters'.  Just below are a few
     parameters you can change.
 
     Note: skipping this step is safe.  The default configuration
	   is to use LZV1 and GZIP only.

     a) You must first select the available algorithms.  In order to 
     do that you must define one or many of:

        EXT2_USE_LZV1
	EXT2_USE_LZRW3A
        EXT2_USE_GZIP

     These are the only algorithms available in the current version.

     *N.B.*: before deciding if you use an algorithm, please check that there
     is no patent that restricts your use of it.  As far as I know, LZV1
     seems to be patent free, while LZRW3A is patented in USA and maybe in other
     countries.  GZIP is patent free.  Check the FAQ of the comp.compression
     group for patent questions.  (Here LZV1 is the algorithm known under the
     name of LZV.)

     The default configuration is:

	#define EXT2_USE_LZV1
	#undef  EXT2_USE_LZRW3A
	#define EXT2_USE_GZIP

     which will make the code use only LZV1 and GZIP (inflate).

     [However, if you picked up a 2.0 patch before November '96,
     EXT2_USE_LZRW31 will also be defined by default.  This is because
     Peter forgot to change it back for distribution.]

     b) Then, you must select the default algorithm by giving a value
     to EXT2_DEFAULT_COMPR_METHOD, which should be one of:

	EXT2_LZV1_ID
	EXT2_LZRW3A_ID
	EXT2_GZIP6_ID

     Make sure the default algorithm has been made available at the
     previous step.

     The default configuration is:

	#define EXT2_DEFAULT_COMPR_METHOD EXT2_LZV1_ID

     which will cause LZV1 to be the default algorithm.

     c) Then you must select the default cluster size by giving a
     value to EXT2_DEFAULT_CLUSTER_BITS, which is the log (base 2) of
     the default cluster size.  The value must be 2, 3, 4 or 5, for a
     cluster size of 4, 8, 16 or 32 respectively.

     The default configuration is:

	#define EXT2_DEFAULT_CLUSTER_BITS 3

     which will make a cluster represent 8 uncompressed blocks.

     Note: There is another constraint that the cluster must not hold
     more than 32 kilobytes.  Thus, it is not possible to have 32
     blocks in a cluster if your file system has blocks of size 2048.
     Another constraint is that a PAGE must fit into a cluster.  Thus
     on an Alpha, where the standard page size is 8KB, it is not
     possible to have only 4 blocks in a cluster if your file system
     has blocks of size 1024 bytes.  This will be checked however when
     compressing files, but it is advisable to give a reasonable
     default cluster size.

     d) You can define EXT2_COMPR_DEBUG, if you really want to have a
     lot a debugging messages ... 

     e) If your machine is an i386 or i486, assembly version of some 
     compression routines are provided.  They are much more faster (BTW, I 
     was terrified how gcc is bad for register allocation).  You can select
     them by replacing the line:

        ZLIB_SUBDIR := zlib
     
     with:

        ZLIB_SUBDIR := zlib-i386

     in the file /usr/src/linux/fs/ext2/Makefile. 

     *BUT* you can only do that if you compile your kernel with an a.out
     compiler.  If you wish to compiler as ELF, use the C version
     (or better, patch the assembly files and send me the diff).  If I
     remember correctly, kernels from 2.1 onwards do not allow compiling the
     kernel as a.out.

     *** DON'T CHANGE ANYTHING ELSE ***


  [pjm: I'm not sure that the rules regarding defining or not of
   EXT2_IND_BITMAP in items 7 and 8 below are correct.  I'd have thought
   the rule would be simply:
	"If you don't plan to use the modified e2fsck yet (e.g. because you
	are just testing this out), make sure that EXT2_IND_BITMAP is
	undefined; otherwise, you might as well define it, so that
	large files compress better."]

  7. IF this is the FIRST time that you're installing e2compr, make
     sure that 'EXT2_IND_BITMAP' is not defined in the file ext2_fs.h.
     You should find the following line in this file:

	#undef EXT2_IND_BITMAP

     *REALLY* check for that *every* time you install a new version of
     e2compr!

     Then go to step 9 until 12, and eventually install the new e2fsck
     as explained in section C. 

  8. IF this is NOT the FIRST time that you're installing e2compr,
     make sure that you have enabled every algorithm that you did
     enable the last time you installed it.  The default configuration
     only enables LZV1 and GZIP because of the patent problems.

     If you don't have an e2compression-enabled e2fsck installed, make
     sure that 'EXT2_IND_BITMAP' is not defined in file ext2_fs.h.  You
     should find the following line in this file :

	#undef EXT2_IND_BITMAP

     If you do hove the patched e2fsck installed (see section C), then
     you can have 'EXT2_IND_BITMAP' defined in the file ext2_fs.h.  You
     should find the following line in this file :

	#define EXT2_IND_BITMAP

     *REALLY* check for this *every* time you install a new
     e2compression version!
    
  9. Update dependencies:

       # cd /usr/src/linux
       # make dep

 10. Build your kernel:
   
       # cd /usr/src/linux
       # make zlilo
    or # make zImage
    or # make zdisk
    or whatever you usually do when rebuilding your kernel

 11. Reboot your machine:

       # shutdown -r now
     (or however you usually do it)

 12. That's all.  There is no need to change the fstab, nor to
     repartition your disk.



  B) Building utilities
  ---------------------

ELF binaries of the utilities are included in the distribution.
(cd to prebuilt, examine the makefile, type `make install'.)

However, if you wish to rebuild from source, follow the following
instructions.

To build everything from source, you will need to have the source for
e2fsprogs, which should be available for ftp from ftp.ibp.fr and
tsx-11.mit.edu in /pub/linux/packages/ext2fs .

Apply the e2fsprogs patch.

    # tar xzf e2fsprogs-1.06.tar.gz
    # cd e2fsprogs-1.06
    # patch -s -F0 -p1 < somewhere/e2fsprogs-1.06-patch-961031

Then just follow the instructions included with e2fsprogs.

*Note*:  You may wish to keep a copy of the old lsattr and chattr, in
case you want to de-install the patch.  (Myself I wouldn't bother,
because the new ones should work fine on an unpatched system.)

    B2) e2compress and e2ratio
    --------------------------

To build from source, go to the directory that was created by unpacking
the archive, cd src, look at the Makefile to see if the destination for
binaries (/usr/bin) and for manual pages (/usr/man/man1) is correct for
you, change them if not.  You may also have to edit the Makefile and
update the value of LINUXSRC which should point to the directory where
your kernel sources are.  Then, just type:

	# make
	# make install



  C) Updating e2fsck
  ------------------

If you want to take the full advantage of e2compr, you must update
e2fsck (see explanations above to understand why).  A binary exists in
the prebuilt/ directory of the e2compr distribution, which you can
install by typing `make install.e2fsck' from that directory (or type
`make install' to install lsattr, e2compress etc. as well).

The instructions for building e2fsck from source follow, for those who
wish to do so.

In order to do that, there is a little patch that comes with the
distribution.  Note that you can perfectly use the e2compr patch
without changing e2fsck (if you want to experiment or test it), but
then only the first 16 clusters of a file are eligible for
compression.  (The maximum cluster size is 32KB, in which case 16
clusters would represent 512KB of uncompressed data.)

If you want to update e2fsck, the following preconditions must hold:

 + you must have installed the e2compr patch as described in
   section A.
 + you must have the sources for e2fsck as found in the e2fsprogs
   source package.  A possible location for this is
   <ftp://ftp.ibp.fr/pub/linux/tsx-11/packages/ext2fs/e2fsprogs-1.06.tar.gz>

 + I also strongly suggest that you first install e2fsprogs at least
   once without applying any patch, so that you become familiar
   with the installation procedure. 

Then you must do the following:

  1. Patch e2fsck: copy the file 'e2fsck.patch' into the directory
     created after unpacking the e2fsprogs distribution.  Go into this
     directory, and do the following command :

	# patch -p1 < e2fsck.patch

     Check also for rejections with the following command :

	# find . -name '*.rej' -print

     This command should print nothing.  If it does, give up right now,
     you probably don't have the good version of e2fsprogs.

  2. Rebuild e2fsck, as described in the file INSTALL from the
     e2fsprogs distribution.  Make sure that the test suite is passed
     without any problem except for the `swapfs' test.

  3. Install the new e2fsck so that this will be the one used the next
     time your machine needs it.

     Note: using the `make install' of e2fsprogs will not back up your
     existing e2fsck, so you may wish to do that manually beforehand.

  4. Edit again the file /usr/src/linux/include/linux/ext2_fs.h and
     change the line :

	#undef EXT2_IND_BITMAP

     into

	#define EXT2_IND_BITMAP

  5. Go to step 10 of the section A (i.e, rebuild your kernel, and
     reboot your machine)
