    A port of GNU Tar 1.12 to MS-DOS/MS-Windows using DJGPP tools
    =============================================================

Features
--------

  This port of GNU Tar includes significant improvements as compared
to the official FSF distribution of version 1.12.  The official code
was failing in a lot of ways on MS-DOS (my favorite is that commands
like "tar cf d:/foo.tar" would fail because `tar' treated file names
with a colon as archives on remote machines and was trying to connect
to a machine called `d').  I believe that all the features in the
original Unix code work in this DOS port; the single most important
exception is the lack of support for remote archives (see the
"Missing" section below).

Here's the list of bug fixes and enhancements in this port:

  1.  Compressed archives are now fully supported (yeah!).  All the
      options which support compressed archives in the Unix version,
      work on MS-DOS.  Compressed archives are produced by piping the
      output of `tar' to or from `gzip', so it is a bit slow, since
      DOS simulates pipes via disk files.  If you have a fast,
      memory-abundant machine, point your TMPDIR to a large RAM drive,
      which will greatly speed up compressed archive operations.

  2.  Backup files are fully supported, including numbered backups,
      even on plain MS-DOS and other non-LFN platforms.  You should
      always unpack .tar.gz files of Unix origin with numbered backups
      turned on, since file name collisions in the restricted 8+3 DOS
      namespace might otherwise overwrite files (unlike `djtar', `tar'
      will not prompt you to supply an alternate name).

  3.  Automatic renaming of file names which are illegal on DOS.  When
      extracting files, `tar' will automatically attempt to rename
      file names such as `Makefile.in.in', `.emacs', `foo:bar;baz,'
      and others.  Note that even Windows 9X disallows some characters
      from appearing in a file name; this port correctly identifies
      the set of characters which need to be replaced, depending on
      whether long file names are or aren't available on the
      filesystem where the file is being extracted.  The algorithm for
      generating converted names is almost identical to what `djtar'
      does, except that `tar' doesn't prompt you for another name when
      it fails to extract a file.  Under verbose operation, `tar'
      prints a message about renamed files.

  4.  Similarly, any file in the archive whose name is reserved on
      MS-DOS by a character device driver (e.g., `prn.txt', `aux.c',
      `nul.foo' etc.), is automatically renamed.  This prevents
      wedging `tar' and/or your system when unpacking Unix archives
      with such files.  Tar renames such files by prepending a `_' to
      their basename.

  5.  Extraction of hard and symbolic links are simulated by copying
      files.  The --diff (-d) mode compares the contents of two files
      in this case.

  6.  Full support of DOS absolute file names with drive letters (the
      original code won't even work on tar file names like
      `d:/foo/bar.tar').  Numerous snafus with root directories on
      other drives and other such subtleties were resolved.  Tar now
      supports backslashes in file names (but they are converted into
      forward slashes before accessing the archives).

  7.  Using -O option when `tar's stdout is redirected to a file would
      corrupt binary files.  This is corrected in this port.

  8.  When given the -C option, `tar' now correctly restores the
      original directory before it exits.

  9.  The -N and --newer-mtime options now work.  (They were disabled
      in the DOS version for reasons that are beyond me.)  All the
      time comparisons, including for -N, --newer-mtime and --diff,
      now compare time stamps with a 2-second granularity, so you
      won't see false "Mod times differ" messages due to DOS rounding
      of file times to the nearest even second.

  10. When --verify (-W) option is given, `tar' will flush the disk
      cache, if one is installed.  This prevents some overly smart
      caches from supplying disk data from memory, instead of
      accessing the media, thus defeating the very goal of verifying.

  11. The manual has been revised, most of the missing cross-
      references fixed, and DOS-specific information added.  The
      manual is under construction by the GNU project, and, IMHO,
      still looks like a car crash (e.g., many subjects are described
      twice, evidently from two different versions of the manual).
      But I really couldn't afford rewriting the manual.  What's there
      should be good enough, I think; if it's not, submit bug reports
      to the GNU package maintainer.

  12. The --recursive-unlink option now really works.  (This was
      actually a genuine bug in the official release which is NOT
      specific to DOS.)

  13. You can use --group and --owner options to give files away to
      any user and any group.  Thus you can create archives on DOS
      with files that would be writable by specific users on Unix.
      (The official code had a bug whereby numeric GIDs and UIDs would
      not work, even on Unix; this is corrected in this port.)

  14. The feature of the Unix code whereby `tar' will not dump the
      archive it is creating into itself, works in this port.  (Due to
      the peculiarities of inode number simulation in the DJGPP
      library, this will NOT work on Windows 9X, Windows 3.11 with
      32-bit File Access, and on networked drives.)

  15. This port supports the optimization in cases that `tar's output
      is meant for the NUL device.  This makes `tar' much faster in
      these cases.

  16. `Tar' will no more switch the console to binary mode.  It only
      switches stdin and stdout to binary mode when they are
      redirected to a file, and then only when `tar' reads or writes
      the archive to one of these streams.  (Switching the console to
      binary mode has unpleasant side-effects.  For example, it
      disables SIGINT generation when you press Ctrl-C, so you cannot
      interrupt a runaway `tar'.)  The original code also had a bug
      with invoking a subsidiary shell when switching volumes in a
      multi-volume tar file; this is now corrected.

  17. All the scripts in the test suite work, except the `ignfail.sh'
      test.  The latter will never work because it deals with file
      permission bits which are impossible on MS-DOS (e.g.,
      non-readable directories or files non-writeable by the owner).


Missing
-------

  The following (short) list explains what functions are missing from
this port:

  1.  Direct device access.

      It would be nice to be able to say "tar cvf /dev/fd0 c:/" and
      have an archive created on a floppy drive A: such that it could
      be taken to a Unix box and untarred without mounting it as a DOS
      filesystem.  At least for floppies with the most popular formats
      (1.2M and 1.44M) this shouldn't be too hard; one just have to
      use the DJGPP Filesystem Extensions feature to hook the
      low-level I/O functions and read/write the diskette on the BIOS
      level.  Any takers?

  2.  Remote archive support.

      The code in rtapelib.c which opens a pipe to `/etc/rsh', should
      be tweaked to work on DOS.

  3.  Internal compression/decompression.

      Linking `tar' with parts of `gzip' code should make compressed
      archive operations MUCH faster.  `djtar' already does that, but
      it cannot create archives.


Installation the of pre-compiled binary distribution
----------------------------------------------------

  1. Go to the root of your DJGPP installation.  Assuming that DJGPP
     is installed in C:\DJGPP:

		  c:
		  cd c:\djgpp

     If you don't have DJGPP installed, you can do this from any
     directory on your disk, but you will need to ensure that:

	* You have DPMI services available.  This port was compiled
          with DJGPP and will not run unless a DPMI server is
          installed.  If you get an error message saying "No DPMI",
          get a free DPMI server csdpmiNb.zip (N is the version
          number) from the sibling v2misc directory of the same site
          where you got this Tar distribution.

	* After unzipping the distribution, you will need to move the
          file tar.exe to a directory on your PATH.

	* To read the on-line docs, you will need an Info reader.  A
          stand-alone info.exe should be available in txiNNNb.zip (NNN
          is a version number) from the same place where you got this
          port of Tar.

  2. Unzip the binary distribution preserving directory structure.
     With PKUNZIP, type this:

		  pkunzip -d tar112b

     With InfoZip's UNZip, type this:

		  unzip tar112b

     If you are installing on Windows 9X, be sure to use an unzip
     program that supports long file names!

  3. Edit your main Info menu on the `info/dir' file, and add the
     following item:

	* Tar: (tar).		Making tape (or disk) archives.

     (The asterisk which begins this line should be flushed to the
     leftmost column of the file.)

  4. Compressed archive (.tar.gz and .tar.Z) support requires an
     external `gzip' (GNU Zip) program, or its close work-alike.  A
     DJGPP port of `gzip' should be available in the gzpNNNb.zip
     distribution from the same place where you got this Tar port.

  5. WARNING!!!  Working with large compressed archives needs a lot of
     temporary free disk space, since `tar' invokes `gzip' via a pipe,
     which on MS-DOS is simulated with a disk file.  If you set the
     TMPDIR environment variable to a RAM disk, make sure you have
     enough space there for the uncompressed archive.  (For unpacking
     .tar.gz files, the size of uncompressed archive can be estimated
     by multiplying the compressed size by 4.)  When in doubt, point
     TMPDIR to your hard drive before invoking `tar'.  If there's not
     enough space on the drive where TMPDIR points, `tar' will
     complain about unexpected end-of-file (depending on whether you
     are creating or extracting files, the message might actually come
     from `gzip').

  6. GNU `tar' is a large and extremely complex program.  The same
     multitude of options that makes it so powerful, also makes its
     testing harder.  While testing this port, I made a point of using
     every option and some popular combinations of different options;
     that is how many bugs were found and corrected.  Still, other
     bugs are probably lurking undetected.  If you find any of them,
     please report them.  Bugs specific to MS-DOS should be posted to
     the comp.os.msdos.djgpp news group first; otherwise, use the
     address printed by "tar --help", at the end of the help screen.
     The file DIFFS in the source distribution shows the source-level
     changes agains the original GNU sources, in case you need to see
     what I broke.



Building `tar' from sources
---------------------------

  First, unzip the binary distribution preserving directory structure.
  With PKUNZIP, type this:

		pkunzip -d tar112s

  With InfoZip's UNZip, type this:

		unzip tar112s

  If you are building on Windows 9X, be sure to use an unzip program
  that supports long file names!

  The source distribution comes already configured for DJGPP, so you
  only need to run Make.  For this to work, you will need the
  following tools:

	- The basic DJGPP development environment (GCC, Binutils and
          djdev distributions);

	- DJGPP port of GNU Make 3.75 or later;

	- DJGPP port of Bash;

	- GNU Sed;

	- `rm' from GNU Fileutils.

  To build `tar', make sure all the above are installed, then type
  "make" and press [Enter].  This will produce tar.exe in the src
  subdirectory.

  To test the package, say "make check".  Running the test suite
  requires the following tools, in addition to those listed above:

	- `cp', `mkdir', `ln' and `touch' from Fileutils;

	- `sleep' from GNU Sh-utils;

	- `cat' from GNU Textutils;

	- `cmp' from GNU Diffutils.

  All of these are available from the usual DJGPP archives.

  All of the tests should pass; they did for me.  The only test that
  sometimes fails on fast machines is incremen.sh; if it fails for
  you, simply run it a few more times, and it will succeed.  I believe
  these failures are due to the 2-second granularity of DOS file
  timestamps.  (The original test suite includes a script called
  `ignfail.sh' that cannot work on MS-DOS, so the DJGPP configuration
  script edits it out of the list of tests that tests/Makefile runs.)

  Typing "make install" will install the program and the docs in the
  relevant directories; you will need the `ginstall' program (from
  Fileutils).  Alternatively, install the files by hand.

  If you need to reconfigure `tar', you will need to install many
  other GNU utilities.  I cannot be bothered to list them all here;
  your best bet is to install all of the following: Fileutils,
  Textutils, Sh-utils, Diffutils, Gawk, Sed, Findutils, and of course
  Bash.  Then configure the package with the following command:

	      djgpp\config

  This sets up some environment variables, then runs the ./configure
  script.  When it is done, run "make" as above.


				Eli Zaretskii <eliz@is.elta.co.il>
