2003-09-26 Joel Sherrill <joel@OARcorp.com>

	* nt.t: Significant update of Windows information. Hopefully this is
	now more useful.

1 files changed, 84 insertions, 316 deletions

diff --git a/doc/started/nt.t b/doc/started/nt.t
index 24cc0663a0..b07261d274 100644
--- a/doc/started/nt.t
+++ b/doc/started/nt.t
@@ -9,10 +9,31 @@
 @appendix Using MS-Windows as a Development Host
 
 This chapter discusses the installation of the GNU tool chain
-on a computer running the Microsoft Windows NT operating system.
+on a computer running the Microsoft Windows operating system.
 
-@section Cygwin 1.0 or Newer
+This chapter was originally written by 
+@uref{mailto:g_montel@@yahoo.com, Geoffroy Montel <g_montel@@yahoo.com>} 
+with input from 
+@uref{mailto:<D.J@@fiddes.surfaid.org>, David Fiddes <D.J@@fiddes.surfaid.org>}.
+It was based upon his successful but unnecessarily
+painful efforts with Cygwin beta versions.
+Cygwin and this chapter have been updated multiple times since
+those early days although their pioneering efforts
+and input is still greatly appreciated.
+
+@section Microsoft Windows Version Requirements
+
+RTEMS users report fewer problems when using Microsoft
+Windows NT, 2000, or XP.  Although, the open source tools
+that are used in RTEMS development do execute on Windows 95,
+98, or ME, they tend to be more stable when used with
+the modern Windows variants.
 
+@section Cygwin 
+
+For RTEMS development, the recommended approach is to use
+Cygwin 1.0 or later. Cygwin is  available from
+@uref{http://sources.redhat.com/cygwin, http://sources.redhat.com/cygwin} 
 Recent versions of Cygwin are vastly improved over the beta
 versions.  Most of the oddities, instabilities, and performance
 problems have been resolved.  The installation procedure
@@ -24,18 +45,39 @@ environment.
 
 @item There is no @code{cc} program by default.  The GNU configure
 scripts used by RTEMS require this to be present to work properly.
-The solution is to link @code{gcc.exe} to @code{cc.exe}.
+The solution is to link @code{gcc.exe} to @code{cc.exe} as follows:
 
-@item Make sure you unarchive and build in a binary mounted
-filesystem (e.g. mounted with the @code{-b} option).  Otherwise,
-many confusing errors will result.
+@example
+ln -s /bin/gcc.exe  /bin/cc.exe
+@end example
+
+@item Make sure @code{/bin/sh.exe} is GNU Bash.  Some Cygwin
+versions provide a light Bourne shell which is insufficient to build
+RTEMS.  To see which shell is installed as @code{/bin/sh.exe}, execute
+the command @code{/bin/sh --version}.  If it looks similar to
+the following, then it is GNU Bash and you are OK:
+
+@example
+GNU bash, version 2.04.5(12)-release (i686-pc-cygwin)
+Copyright 1999 Free Software Foundation, Inc.
+@end example
+
+If you get an error or it claims to be any other shell, you need 
+to copy it to a fake name and copy
+@code{/bin/bash.exe} to @code{/bin/sh.exe}:
+
+@example
+cd /bin
+mv sh.exe old_sh.exe
+cp bash.exe sh.exe
+@end example
 
-@item If you want to use RPM, you will have to obtain that
-separately by following the links from the main Cygwin site.
+The Bourne shell has to be present in @code{/bin} directory to run
+shell scripts properly.
 
-@item When using the RPMs, there may be warnings about
-@code{/etc/mtab} while installing the info files.  This can be
-ignored.
+@item Make sure you unarchive and build in a binary mounted
+filesystem (e.g. mounted with the @code{-b} option).  Otherwise,
+many confusing errors will result.  
 
 @item A user has reported that they needed 
 to set CYGWIN=ntsec for chmod to work correctly, but had to set 
@@ -45,36 +87,7 @@ complaints about permissions on a temporary file).
 @item If you want to build the tools from source, you have the 
 same options as UNIX users.
 
-@end itemize
-
-@section Cygwin B19
-
-This section is based on a draft provided by 
-@uref{mailto:g_montel@@yahoo.com, Geoffroy Montel <g_montel@@yahoo.com>}.
-Geoffroy's procedure was based on information from 
-@uref{mailto:<D.J@@fiddes.surfaid.org>, David Fiddes <D.J@@fiddes.surfaid.org>}.
-Their input and feedback is greatly appreciated.
-
-@b{STATUS:}  This chapter should be considered preliminary.
-Please be careful when following these instructions.
-
-This installation process works well under Windows NT. 
-Using Windows 95 or 98 is not recommended although it 
-should be possible with version 3.77 of GNU make and an updated
-cygwinb19.dll.
-
-This procedure should also work with newer versions of 
-the tool versions listed in this chapter, but this has
-not been verified.  
-
-@subsection MS-Windows Host Specific Requirements
-
-This section details the components required to install
-and build a Windows hosted GNU cross development toolset.
-
-@subsubsection Unzipping Archives
-
-You will have to uncompress many archives during this
+@item You may have to uncompress archives during this
 process.  You must @b{NOT} use @code{WinZip} or
 @code{PKZip}.  Instead the un-archiving process uses
 the GNU @code{zip} and @code{tar} programs as shown below:
@@ -83,308 +96,63 @@ the GNU @code{zip} and @code{tar} programs as shown below:
 tar -xzvf archive.tgz 
 @end example
 
-@code{tar} is provided with Cygwin32.
+@code{tar} is provided with Cygwin.
 
-@subsubsection Text Editor
+@end itemize
+
+@section Text Editor
 
 You absolutely have to use a text editor which can 
-save files with Unix format (so don't use Notepad 
-nor Wordpad).  There are a number of editors
+save files with Unix format. So do @b{NOT} use Notepad 
+or Wordpad!  There are a number of editors
 freely available that can be used.  
 
 @itemize @bullet
 @item @b{VIM} (@b{Vi IMproved}) is available from
-@b{http://www.vim.org/}.  This editor has the very
-handy ability to easily read and write files in 
-either DOS or UNIX style.
+@uref{http://www.vim.org/,http://www.vim.org/}.  
+This editor has the very handy ability to easily
+read and write files in either DOS or UNIX style.
 
 @item @b{GNU Emacs} is available for many platforms
 including MS-Windows.  The official homepage 
-is @b{http://www.gnu.org/software/emacs/emacs.html}.
-The GNU Emacs on Windows NT and Windows 95/98 FAQ is
-at @b{http://www.gnu.org/software/emacs/windows/ntemacs.html}.
-
-@item @b{PFE} (@b{Programmers File Editor}) may be downloaded
-from @b{http://www.simtel.net/pub/simtelnet/win95/editor/pfe101i.zip}.  Note this
-editor is no longer actively supported.
-
-@c @uref{http://www.simtel.net/pub/simtelnet/win95/editor/pfe101i.zip}
+is @uref{http://www.gnu.org/software/emacs/emacs.html,
+http://www.gnu.org/software/emacs/emacs.html}.
+The GNU Emacs on Windows NT and Windows 95/98 FAQ is at
+@uref{http://www.gnu.org/software/emacs/windows/ntemacs.html,
+http://www.gnu.org/software/emacs/windows/ntemacs.html}.
 
 @end itemize
 
-@subsubsection Bug in Patch Utility
-
-There is a bug in the @code{patch} utility
-provided in Cygwin32 B19. The files modified end up 
-having MS-DOS style line termination. They must have
-Unix format, so a @code{dos2unix}-like command must
-be used to put them back into Unix format as shown below:
+If you do accidentally end up with files 
+having MS-DOS style line termination, then you
+may have to convert them to Unix format for some
+Cygwin programs to operate on them properly. The 
+program @code{dos2unix} can be used to put them
+back into Unix format as shown below:
 
 @example
 $ dos2unix XYZ
 Dos2Unix: Cleaning file XYZ ...
 @end example
 
-The dos2unix utility may be downloaded from:
-
-@c @uref{ftp://ftp.micros.hensa.ac.uk/platforms/ibm-pc/ms-dos/simtelnet/txtutl/dos2unix.zip,ftp://ftp.micros.hensa.ac.uk/platforms/ibm-pc/ms-dos/simtelnet/txtutl/dos2unix.zip}
-@b{ftp://ftp.micros.hensa.ac.uk/platforms/ibm-pc/ms-dos/simtelnet/txtutl/dos2unix.zip}
-
-You @b{must} change the format of every patched file 
-for the toolset build to work correctly.
-
-@subsubsection Files Needed
-
-This section lists the files required to build and install
-a Windows hosted GNU cross development toolset and their
-home WWW site.  In addition to the sources required 
-for the RTEMS cross environment listed earlier in this manual,
-you may need to  download the following
-files from their respective sites using your favorite
-Web browser or ftp client. [NOTE: This information was current when B19
-was released and URLs may no longer be correct.]
-
-@table @b
-
-@item cdk.exe
-@c @uref{http://www.cygnus.com/misc/gnu-win32/,http://www.cygnus.com/misc/gnu-win32/}
-@b{http://www.cygnus.com/misc/gnu-win32/}
-
-@item coolview.tar.gz
-@c @uref{http://www.lexa.ru/sos/,http://www.lexa.ru/sos/}
-@b{http://www.lexa.ru/sos/}
-
-@end table
-
-@subsubsection System Requirements
+@section System Requirements
 
 Although the finished cross-compiler is fairly easy on resources,
 building it can take a significant amount of processing power and 
-disk space. The recommended build system spec is:
+disk space.  
 
-@enumerate
+@itemize @bullet
 
-@item An AMD K6-300, Pentium II-300 or better processor. GNU C and Cygwin32 are
+@item The faster the CPU, the better. The tools and Cygwin can be
 @b{very} CPU hungry.
 
-@item At least 64MB of RAM.
-
-@item At least 400MB of FAT16 disk space or 250MB if you have an NTFS partition. 
-
-@end enumerate
-
-Even with this spec of machine expect the full suite to take over 2 hours to 
-build with a further half an hour for RTEMS itself.
-
-
-@subsection Installing Cygwin32 B19
-
-This section describes the process of installing the 
-version B19 of the Cygwin32 environment.  It assumes
-that this toolset is installed in a directory 
-referred to as @code{<RTOS>}.
-
-@enumerate
-
-@item Execute cdk.exe. These instructions assume that you 
-install Cygwin32 under the <RTOS>\cygnus\b19 directory.
-
-@item Execute Cygwin.bat (either on the start menu or 
-under <RTOS>\cygnus\b19).
-
-@item At this point, you are at the command line of @code{bash},
-a Unix-like shell. You have to mount the "/" directory. Type:
-
-@example 
-umount /
-mount -b <RTOS> /
-@end example
-
-For example, the following sequence mounts the @code{E:\unix} as the 
-root directory for the Cygwin32 environment. Note the use of two @code{\}s 
-when specifying DOS paths in bash:
-
-@example
-umount /
-mount -b e:\\unix /
-@end example
-
-@item Create the /bin, /tmp, /source and /build directories.
-
-@example
-mkdir /bin
-mkdir /tmp
-mkdir /source
-mkdir /build
-mkdir /build/binutils
-mkdir /build/gcc
-@end example
-
-@item The light Bourne shell provided with Cygwin B19 is buggy.
-You should copy it to a fake name and copy @code{bash.exe} to @code{sh.exe}:
-
-@example
-cd <RTOS>/cygnus/b19/H-i386-cygwin32/bin
-mv sh.exe old_sh.exe
-cp bash.exe sh.exe
-@end example
-
-The Bourne shell has to be present in /bin directory to run shell scripts properly:
-
-@example
-cp <RTOS>/cygnus/b19/H-i386-cygwin32/bin/sh.exe /bin
-cp <RTOS>/cygnus/b19/H-i386-cygwin32/bin/bash.exe /bin
-@end example
-
-
-@item Open the file 
-@code{/cygnus/b19/H-i386-cygwin32/lib/gcc-lib/i386-cygwin32/2.7-b19/specs},
-and append
-
-@example
--ladvapi32
-@end example
-
-to the following line:
-
-@example
--lcygwin %@{mwindows:-luser32 -lgdi32 -lcomdlg32@} -lkernel32
-@end example
-
-@end enumerate
-
-At this point, you have a native installation of Cygwin32 and
-are ready to proceed to building a cross-compiler.
-
-@c
-@c  BINUTILS
-@c
-
-@subsection Installing binutils
-
-@enumerate
-
-@item Unarchive @value{BINUTILSTAR} following the 
-instructions in @ref{Unarchiving the Tools} into the /source directory.
-Apply the appropriate RTEMS specific patch as detailed in
-@ref{Applying RTEMS Patches}.
-
-@item In the @code{/build/binutils} directory, execute the following
-command to configure binutils @value{BINUTILSVERSION}:
-
-@example
-/source/@value{BINUTILSUNTAR}/configure \
-    --verbose --target=m68k-rtems \
-    --prefix=/gcc-m68k-rtems --with-gnu-as --with-gnu-ld 
-@end example
-
-Replace @code{m68k-rtems} with the target configuration
-of your choice.  See @ref{Using the RTEMS configure Script Directly} for a
-list of the targets available.
-
-@item Execute the following command to compile the toolset:
-
-@example
-make
-@end example
-
-@item Install the full package with the following command:
-
-@example
-make -k install
-@end example
-
-There is a problem with the gnu info package which will cause an 
-error during installation. Telling make to keep going with @code{-k} allows 
-the install to complete.
-
-@item In the @code{cygnus.bat} file, add the directory
-containing the cross-compiler executables to your search path
-by inserting the following line:
+@item The more RAM, the better.  Reports are that when building GCC
+and GDB, peak memory usage can exceed 256 megabytes.
 
-@example
-PATH=E:\unix\gcc-m68k-rtems\bin;%PATH%
-@end example
-
-@item You can erase the /build/binutils directory content if 
-disk space is tight.
-
-@item Exit bash and run @code{cygnus.bat} to restart
-the Cygwin32 environment with the new path.
-
-@end enumerate
-
-@c
-@c  GCC
-@c
-
-@subsection Installing GCC AND NEWLIB
+@item The more disk space, the better. You need more if you are building
+the GNU tools and the amount of disk space for binaries is obviously
+directly dependent upon the number of CPUs you have cross toolsets
+installed for.
 
-@enumerate
-@item Unarchive and patch @value{GCCTAR} and @value{NEWLIBTAR}
-following the instructions in @ref{Unarchiving the Tools}. 
-Apply the appropriate RTEMS specific patches as detailed in
-@ref{Applying RTEMS Patches}.
-
-@b{NOTE}: See @ref{Bug in Patch Utility}.
-
-@item Remove the following directories (we cannot use Fortran
-or Objective-C as Cygwin32 cross-compilers):
-
-@example
-/source/@value{GCCUNTAR}/libf2c
-/source/@value{GCCUNTAR}/gcc/objc
-/source/@value{GCCUNTAR}/gcc/f
-@end example
-
-@b{NOTE}: See @ref{Bug in Patch Utility}.
-
-@item Link the following directories from Newlib to the main GCC directory, 
-/source/@value{GCCUNTAR}/ :
-
-@itemize @bullet
-@item ln -s ../@value{NEWLIBUNTAR}/newlib newlib
-@item ln -s ../@value{NEWLIBUNTAR}/libgloss libgloss
 @end itemize
 
-@item Change to the /build/gcc directory to configure the compiler:
-
-@example
-/source/@value{GCCUNTAR}/configure \
-    --verbose --target=m68k-rtems \
-    --prefix=/gcc-m68k --with-gnu-as --with-gnu-ld \
-    --with-newlib
-@end example
-
-Replace @code{m68k-rtems} with the target configuration
-of your choice.  See @ref{Using the RTEMS configure Script Directly} for a
-list of the targets available.
-
-@item Compile the toolset as follows:
-
-@example
-make cross
-@end example
-
-You must do a @code{make cross} (not a simple @code{make})
-to insure that the different packages are built in the correct
-order.   Making the compiler can take several hours even on
-fairly fast machines, beware.
-
-@item Install with the following command:
-
-@example
-make -k install
-@end example
-
-@item Just as with binutils package, a problem with the gnu
-info package not building correctly requires that you use -k to 
-keep going.
-
-@end enumerate
-
-With any luck, at this point you having a working cross-compiler.  So
-as Geoffroy said:
-
-@center @b{That's it! Celebrate!}
-