How to build and install GNU Tar for MS-DOS/MS-Windows using DJGPP tools
========================================================================

Features
--------

  This port of GNU Tar includes significant improvements as compared
to previous versions as distribution by FSF.  I believe that all the
features in the original Unix code also work in the DOS/Windows port;
the single most important exception is the lack of support for remote
archives (see the "Missing" section below).

Here's the list of features that work now, but didn't work in previous
releases:

  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;
      this 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 invalid 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/NT 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/MS-Windows 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-style absolute file names with drive
      letters.  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 will
      not corrupt binary files anymore.

  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 old DOS versions for reasons that are beyond me.)  All the
      time comparisons, including those performed under options -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 rounding of file times to the nearest even
      second on FAT volumes.

  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, and DOS-specific information added.

  12. 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.

  13. 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/NT, Windows 3.11 with
      32-bit File Access, and on networked drives.)

  14. 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.

  15. `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'.)

  16. The test suite works for DOS/Windows.  Tests which cannot work
      on these systems because they test features unsupported by
      Microsoft patforms are automatically omitted by the test suite.


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?

      The same goes for tape drive access.  Using some standard, like
      the ASPI interface, it shouldn't be too hard.

  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
----------------------------------------------------

  0. The list of places where you can get binary distributions can be
     found in the file contrib/README.

  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 (where NNN is the version number):

		  pkunzip -d tarNNNb

     With InfoZip's UNZip, type this:

		  unzip tarNNNb

     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 its line.)

     DJGPP v2.02 and later come with `info/dir' that already includes
     this menu item, so you don't need to add it.

  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.



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

  DJGPP archives, listed in the file contrib/README, include source
  distributions of `tar' in zip format; these are already configured
  for DJGPP, so building from those distributions is easier.  If you
  have sources from one of the DJGPP sites, then unzip the source
  distribution preserving directory structure.  With PKUNZIP, type
  this (NNN is the version number):

		pkunzip -d tarNNNs

  With InfoZip's UNZip, type this:

		unzip tarNNNs

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

  In case you are unpacking the official FSF sources in .tar.gz form,
  you will need to use either a compiled binary of (a previous version
  of) `tar', or the `djtar' program supplied with the basic DJGPP
  development environment in the file v2/djdevNNN.zip.  To unpack with
  `djtar', use this command:

		djtar -x tar-N.NN.tar.gz

  And here's a command for using `tar':

		tar -xvvzf tar-N.NN.tar.gz --backup=numbered

  The source distributions from the DJGPP archives (v2gnu/tarNNNs.zip)
  come 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, and CWSDPMI on plain DOS); you need
          DJGPP v2.03 or later;

	- DJGPP port of GNU Make 3.78.1 or later;

	- DJGPP port of Bash v2.03 or later;

	- 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.

  DJGPP versions earlier than v2.02 have bugs in `popen', `pathconf'
  and `difftime' library functions which can affect `tar'.  Upgrade to
  DJGPP v2.02 or later, or ask for patched versions of these functions
  on the comp.os.msdos.djgpp news group.

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

	- `cp', `mkdir', `ln', `chmod', `rmdir' 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.

  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', or to build the official FSF
  distribution from tar-N.NN.tar.gz archives, you will need to install
  DJGPP ports of 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:

	      config

  This sets up some environment variables, then runs the ./configure
  script.

  If you are building `tar' from outside the directory where the
  source distribution is, you need to tell config.bat where to find
  the sources, by passing the source directory as its first argument.
  For example:

	      c:\dir\subdir\config c:/dir/subdir

  You MUST use forward slashes in the argument to config.bat.

  When config.bat is done, run "make" as above.


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