DJGPP Port of GNU Fileutils 4.0, release 5
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Introduction
------------

This is the Readme file for the DJGPP port of Fileutils 4.0. Please see the
file 'NEWS' for a full list of user-visible changes. Please see
'changelog.dos' for a list of bugs fixed in each release of the port.

To use the Fileutils programs, you only need to download the binary
distribution. You may also want to download the documentation distribution,
to get the documentation in HTML, PostScript and DVI formats. If you want
to examine or rebuild the Fileutils sources, you need to download
the source distribution.

The Fileutils port is available here:

  ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/fil40b.zip (binaries)
  ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/fil40d.zip (docs)
  ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2gnu/fil40s.zip (sources)

Please read the sections below for the distributions you have downloaded,
before installing Fileutils. Please also read the "Known Issues" section,
which contains important information about the DJGPP port.

Installing the Binary Distribution of Fileutils
-----------------------------------------------

Unzip the distribution preserving the directory structure (use -d
switch if you do that with PKUNZIP) from the top DJGPP installation
directory.  Since the entries for Fileutils manual already exist in
the file info/dir, you don't need to do anything else.

You should install a DPMI server such as CWSDPMI (v2misc/csdpmi5b.zip).
Windows provides a DPMI server, so you do not need CWSDPMI, to use Fileutils
under Windows.

To use 'ginstall', you should also install the following packages
(or later versions):

. DJGPP development environment 2.03 (v2/djdev203.zip);
. GNU binutils (e.g. v2gnu/bnu210b.zip).

'ginstall' may use 'stubify' from DJGPP and 'strip' from binutils.

Installing the Documentation Distribution of Fileutils
------------------------------------------------------

If you want the Fileutils documentation in a format other than info format,
then you need the documentation distribution. This contains documentation in
texinfo source, HTML, DVI (TeX) and PostScript. This documentation will be
installed in gnudocs\filutil4.0.

Rebuilding Fileutils using the Source Distribution
--------------------------------------------------

To build the DJGPP port of Fileutils from sources, I used the following
packages:

. DJGPP development environment 2.03 (v2/djdev203.zip);
. DJGPP library sources 2.03 (v2/djlsr203.zip);
. GNU C compiler 3.04 (v2gnu/gcc304b.zip);
. GNU binutils 2.11.2 (v2gnu/bnu2112b.zip);
. GNU make 3.79 (v2gnu/mak379b.zip);
. GNU bash 2.04 (v2gnu/bsh204b.zip);
. GNU sed (v2gnu/sed302b.zip);
. GNU fileutils 4.0, release 1 (v2gnu/fil40b.zip);
. GNU sh-utils 1.12 (v2gnu/shl112b.zip);
. GNU textutils 2.0 (v2gnu/txt20b.zip);
. GNU grep 2.4 (v2gnu/grep24b.zip);
. GNU bison 1.28 (v2gnu/bsn128b.zip);
. GNU texinfo 4.0 (v2gnu/txi40b.zip);
. Perl 5.005_02 (v2gnu/perl552b.zip).

I also used the following packages - you will not need these, unless you
edit the configure script or Makefile.am files.

. GNU autoconf 2.13 (v2gnu/acnf213b.zip);
. GNU automake 1.4 (v2gnu/amake14b.zip).

Fileutils 4.0 can probably be built using later versions of these packages,
where available.

If you wish to modify the configure script and you use autoconf 2.50,
you will need Laurynas Biveinis and Richard Dawe's patch for
the Fileutils 4.0 sources, fil40-acnf250.diff, which is here:

    http://www.phekda.freeserve.co.uk/richdawe/djgpp/fileutils/

If you using Fileutils 3.16, please make sure that you are using
the latest version of the port - older versions were compiled against
DJGPP 2.02. The latest version was compiled against DJGPP 2.03 and
supports features needed for installation of Fileutils 4.0
(see 'make install' below).

Firstly, change into the top-level directory of the Fileutils sources
(i.e. gnu\filutil4.0) and configure the package:

    djgpp\config.bat

This configures the package to be built without support for
internationalisation (i.e. only English is supported). It also patches
some of the test Makefiles, because some of the test files have been renamed
from the normal Fileutils distribution to fit into the 8+3 DOS filename
limitation (see djgpp\fnchange.lst).

If you want to install Fileutils somewhere other than the DJGPP directory,
modify djgpp\config.bat to use configure's '--prefix' option
(use 'bash configure --help' for more information).

Then build the package:

    make

If you are using DJGPP 2.03, you may want to build a patched version of
'src\libc\posix\dirent\opendir.c' from libc. The patched version fixes
a problem that can cause closedir() to fail on empty root directories.
This problem causes strange error messages with 'ls' and other utilities.
The script djgpp\patchexe.sh will rebuild the Fileutils appropriately.
It must be run from the djgpp directory:

   cd djgpp
   bash patchexe.sh
   cd ..

Once the Fileutils are built, install the package:

    make install

Fileutils does come with a test-suite, but this makes assumptions that are
not valid on DOS, so many of the tests will fail. The correct operation
of the programs has been checked as part of the port, so there's no need
to worry about this. To run the test-suite, use:

    make check

You may want to use 'make -k check' to continue when tests fail.

If you are interested in the test suite, please see the section entitled
'Expected test suite results' below

Changes made to the Fileutils 4.0 Sources
-----------------------------------------

The file 'gnu\filutil4.0\djgpp\diffs' contains interesting changes made to
the files - an "interesting" change is one that is needed to support DJGPP.
The diffs do not include changes to the Makefiles, etc. that result from
running autoconf, automake, etc.

If you like to start with a fresh copy of the Fileutils sources,
apply the patch like so:

    cd \path\to\fileutils\sources
    patch -p5 -i \path\to\djgpp\diff\diffs

You will need autoconf and automake to be installed, to build from
patched sources.

If you plan to build the sources without Long Filename support, you will
also need to rename some of the tests to fit into the 8+3 DOS filename
limitation and also edit the test Makefiles. The necessary rename operations
are listed in djgpp\fnchange.lst; see djgpp\config.bat and djgpp\tests.sed
for the Makefile patches.

If you plan to build the sources with Long Filename support, then run
'configure' as you would with the normal Fileutils package. 

NB: The source distribution of the DJGPP port comes with all patches applied
and will build "out of the box" with and without Long Filenames.

Features
--------

(This section is based on the section of the same name from Fileutils 3.16's
 readme file by Eli Zaretskii.)

This port has the following DOS-specific features:

- All the programs fully support long filenames. This is because DJGPP
  uses the improved file handling APIs available to DOS programs under
  Windows '95 and later. These APIs are also available under DOS, when
  an LFN driver is installed (see the DJGPP FAQ for more information).
  For instance, you get numbered backup file names as you'd see on Unix;
  'touch' can change both access and modification times, etc.

- Numbered backups work even on native DOS, although the numbered
  suffix eats last characters of the filenames on FAT filesystems.

- 'chgrp' and 'chown' are no-ops on MSDOS; however, they always return
  a successful status and describe the change as if it were actually
  happening. This allows Unix-born Makefiles to run unaltered.

- 'chmod' also behaves as above if invoked to do anything except
  making a file read-only (which is actually supported by MSDOS).
  Since the execute and other bits only exist in the program's
  imagination, they don't really change, although 'chmod' acts as
  if they did.

- 'ls' has a DOS-specific '-g' switch, which makes the long format print
  DOS attribute bits (r,h,s,v,d,m) instead of the Unix-style mode bits.
  When called with -a switch, 'ls' will display files with hidden
  and system attributes, and volume labels (if present).

- 'ginstall' will stubify a COFF executable on the fly. When given
  the -s option, 'ginstall' will strip the executable, either COFF
  or .exe program (you will need 'strip' from binutils to be able
  to strip .exe programs).

- 'ln -s' supports DJGPP-style executable "symlinks": you can say
  "ln -s grep fgrep" and get 'fgrep.exe' which, when run, will actually
  call 'grep.exe'. 'ln' without -s just copies.

- 'sync' attempts to cause the disk cache, if installed, to flush
  its buffers.

Known Issues
------------

Please also see 'changelog.dos' for a list of bugs fixed in each release
of the port.

- 'df' does not work correctly with disk partitions greater than 2GB.
  The other fileutils do not support files greater than 2GB. Windows's
  FAT32 filesystem supports partitions and files larger than 2GB.
  DJGPP 2.04, which is currently in development, has support for FAT32.
  Fileutils 4.0 should be recompiled with DJGPP 2.04, when it is released.

- 'ls c:/djgpp/../..' displays the root directory. This may seem confusing
  at first, but it is consistent with filesystems on Linux and Unix.

- If you use 'ls --color' and the screen scrolls, a directory entry with
  a long name may cause background leakage, so that the background fills
  an entire line, rather than just the part with the filename.

- 'ginstall -s' will generate a warning on programs that use
  a non-standard stub (e.g. PMODE/DJ, CWSDSTUB), because 'strip'
  will not be able to find the COFF header. Because it cannot find
  the COFF header, it cannot remove debugging information. 'ginstall' will
  still install the program, as requested.

  To avoid this problem, strip the program before applying the stub.

  Here is an example of the warning, split over two lines for clarity:

  ginstall: foo.exe: Executable may have a non-standard stub, e.g. PMODE/DJ,
  CWSDSTUB

- 'ln' behaves inconsistently, but with good reason. Hardlinks are simulated
  by copying; symlinks to programs are simulated by creating a stub
  to invoke the program.

    Hardlink: 'ln a.exe b'    creates 'b'
    Symlink:  'ln -s a.exe b' creates 'b.exe'

Expected test suite results
---------------------------

LFN and SFN environments should give the same results. However,
weird results are produced when you run the tests in an environment that
supports LFN with LFN=n, e.g. a DOS box Windows '95. Do not do this.
Switch into MS-DOS mode and run the tests there.

The following command will run the test suite in verbose, debug mode:

    make -k CANDIDATE_TMP_DIRS=a:/ VERBOSE=yes DEBUG=1 check

You may want to redirect the results into a file, for later examination:

    redir -eo make -k CANDIDATE_TMP_DIRS=a:/ VERBOSE=yes DEBUG=1 check > file

$CANDIDATE_TMP_DIRS is used by some of the tests to test inter-device
symlinks. If you have more than one hard disk partition, you may want to use
that or a subdirectory of that instead, e.g.:

    make -k CANDIDATE_TMP_DIRS=d:/test VERBOSE=yes DEBUG=1 check

You can extract a summary of the test results like so:

    grep -E '(PASS|FAIL)' file

Now to the results:

Format: <category>: (+|-)<test 1> [(+|-)<test 2> ... [(+|-)<test n>]]
Where: '+' indicates pass, '-' indicates failure, '?' indicates not run.

cp: +backup-1 -nderefl1 -nderefl2 -nderefl3 +backup-is-src -same-file
[ nderefl1, nderefl2, nderefl3 fail, because they use 'ln -s' to create ]
[ a symbolic link. same-file fails because of the way 'ln -s' creates   ]
[ target files.                                                         ]

dircolors: +simple

install: -basic-1
[ Fails because 'dd' executable gains '.exe' extension on installation. ]
[ Hand-running test shows it succeeds.                                  ]

ln: -sf-1 -misc
[ sf-1 and misc fails because they try to symlink to files in other     ]
[ directories. See 'info libc alpha symlink' for the reason this fails. ]

ls: +rt-1 -time-1
[ ctime test fails - possibly expected. Is this due to limitation in ]
[ resolution of DOS's creation time on files?                        ]

ls-2: -quoting
[ This test tries to use \a (audible bell) in filenames, which isn't valid  ]
[ on DOS. Experimenting with filenames containing characters from the set   ]
[ ' ', ',', '=', '+' and the '--quoting-style' argument shows that it seems ]
[ to work OK.                                                               ]

mkdir: +p-1 +p-2

mv: +backup-is-src +i-1 +toself -toself2 -mv-special-1
[ toself2 tries to create cross-device symlinks, which fails. ]
[ mv-special-1 uses mknod => failure.                         ]

rm: +r-1 +r-2 +r-3 +i-1 +ir-1 +f-1 +sunos-1 -deep-1
[ deep-1 tries to create very deep directory structure => failure. ]

touch: +empty-file

Finally
-------

A lot of credit for this port must go to Eli Zaretskii, since he provided me
with patches that actually did much of the port for me, and also for his
advice. Thanks also to Jim Meyering, Tim Van Holder, Jason Green,
Laurynas Biveinis, Charles Sandmann and JT Williams for their help.
Thanks also to the djgpp-workers.

If you encounter any problems with this port, please feel free to contact me
by e-mail (address below). I also try to read the DJGPP newsgroup,
comp.os.msdos.djgpp, on a regular basis.

Thanks, bye,

Richard Dawe <rich@phekda.freeserve.co.uk> 2002-03-10
