README.W32.template

   1 Port of GNU make to Windows NT and Windows 95
   2 Builds natively with MSVC 2.x or MSVC 4.x compilers.
   3 Should also build fine with MSVC 5.x and 6.x (though not confirmed).
   4
   5 This Windows 32-bit port of GNU make is maintained primarily by Rob
   6 Tulloh, who is also the author of this README.
   7
   8 To build with nmake on MS-Windows:
   9
  10         1. Make sure cl.exe is in your %Path%. Example:
  11
  12                 set Path=%Path%;c:/msdev/bin
  13
  14         2. Make sure %include% is set to msvc include directory. Example:
  15
  16                 set include=c:/msdev/include
  17
  18         3. Make sure %lib% is set to msvc lib directory. Example:
  19
  20                 set lib=c:/msdev/lib
  21
  22         4. nmake /f NMakefile
  23
  24
  25     A short cut to steps 1, 2, and 3 is to run VCVARS32.bat before
  26     invoking namke. For example:
  27
  28         c:
  29         cd \msdev\bin
  30         VCVARS32.bat
  31         cd \path\to\make-%VERSION%
  32         nmake /f NMakefile
  33
  34 There is a bat file (build_w32.bat) for folks who have fear of nmake.
  35
  36 Outputs:
  37
  38         WinDebug/make.exe
  39         WinRel/make.exe
  40
  41
  42 -- Notes/Caveats --
  43
  44 GNU make on Windows 32-bit platforms:
  45
  46         This version of make is ported natively to Windows32 platforms
  47         (Windows NT 3.51, Windows NT 4.0, Windows 95, and Windows 98). It
  48         does not rely on any 3rd party software or add-on packages for
  49         building. The only thing needed is a version of Visual C++,
  50         which is the predominant compiler used on Windows32 platforms.
  51
  52         Do not confuse this port of GNU make with other Windows32 projects
  53         which provide a GNU make binary. These are separate projects
  54         and are not connected to this port effort.
  55
  56 GNU make and sh.exe:
  57
  58         This port prefers you have a working sh.exe somewhere on your
  59         system. If you don't have sh.exe, the port falls back to
  60         MSDOS mode for launching programs (via a batch file).
  61         The MSDOS mode style execution has not been tested that
  62         carefully though (The author uses GNU bash as sh.exe).
  63
  64         There are very few true ports of Bourne shell for NT right now.
  65         There is a version of GNU bash available from Cygnus "Cygwin"
  66         porting effort (http://www.cygwin.com/).
  67         Other possibilities are the MKS version of sh.exe, or building
  68         your own with a package like NutCracker (DataFocus) or Portage
  69         (Consensys).  Also MinGW includes sh (http://mingw.org/).
  70
  71 GNU make and brain-dead shells (BATCH_MODE_ONLY_SHELL):
  72
  73         Some versions of Bourne shell do not behave well when invoked
  74         as 'sh -c' from CreateProcess().  The main problem is they seem
  75         to have a hard time handling quoted strings correctly. This can
  76         be circumvented by writing commands to be executed to a batch
  77         file and then executing the command by calling 'sh file'.
  78
  79         To work around this difficulty, this version of make supports
  80         a batch mode.  When BATCH_MODE_ONLY_SHELL is defined at compile
  81         time, make forces all command lines to be executed via script
  82         files instead of by command line.  In this mode you must have a
  83         working sh.exe in order to use parallel builds (-j).
  84
  85         A native Windows32 system with no Bourne shell will also run
  86         in batch mode.  All command lines will be put into batch files
  87         and executed via $(COMSPEC) (%COMSPEC%).  Note that parallel
  88         builds (-j) require a working Bourne shell; they will not work
  89         with COM.
  90
  91 GNU make and Cygnus GNU Windows32 tools:
  92
  93         Good news! Make now has native support for Cygwin sh. To enable,
  94         define the HAVE_CYGWIN_SHELL in config.h and rebuild make
  95         from scratch. This version of make tested with B20.1 of Cygwin.
  96         Do not define BATCH_MODE_ONLY_SHELL if you use HAVE_CYGWIN_SHELL.
  97
  98 GNU make and the MKS shell:
  99
 100         There is now semi-official support for the MKS shell. To turn this
 101         support on, define HAVE_MKS_SHELL in the config.h.W32 before you
 102         build make.  Do not define BATCH_MODE_ONLY_SHELL if you turn
 103         on HAVE_MKS_SHELL.
 104
 105 GNU make handling of drive letters in pathnames (PATH, vpath, VPATH):
 106
 107         There is a caveat that should be noted with respect to handling
 108         single character pathnames on Windows systems.  When colon is
 109         used in PATH variables, make tries to be smart about knowing when
 110         you are using colon as a separator versus colon as a drive
 111         letter.  Unfortunately, something as simple as the string 'x:/'
 112         could be interpreted 2 ways: (x and /) or (x:/).
 113
 114         Make chooses to interpret a letter plus colon (e.g. x:/) as a
 115         drive letter pathname.  If it is necessary to use single
 116         character directories in paths (VPATH, vpath, Path, PATH), the
 117         user must do one of two things:
 118
 119          a. Use semicolon as the separator to disambiguate colon. For
 120             example use 'x;/' if you want to say 'x' and '/' are
 121             separate components.
 122
 123          b. Qualify the directory name so that there is more than
 124             one character in the path(s) used. For example, none
 125             of these settings are ambiguous:
 126
 127               ./x:./y
 128               /some/path/x:/some/path/y
 129               x:/some/path/x:x:/some/path/y
 130
 131         Please note that you are free to mix colon and semi-colon in the
 132         specification of paths.  Make is able to figure out the intended
 133         result and convert the paths internally to the format needed
 134         when interacting with the operating system, providing the path
 135         is not within quotes, e.g. "x:/test/test.c".
 136
 137         You are encouraged to use colon as the separator character.
 138         This should ease the pain of deciding how to handle various path
 139         problems which exist between platforms.  If colon is used on
 140         both Unix and Windows systems, then no ifdef'ing will be
 141         necessary in the makefile source.
 142
 143 GNU make test suite:
 144
 145         I verified all functionality with a slightly modified version
 146         of make-test-%VERSION% (modifications to get test suite to run
 147         on Windows NT). All tests pass in an environment that includes
 148         sh.exe.  Tests were performed on both Windows NT and Windows 95.
 149
 150 Building GNU make on Windows NT and Windows 95/98 with Microsoft Visual C:
 151
 152         I did not provide a Visual C project file with this port as
 153         the project file would not be considered freely distributable
 154         (or so I think). It is easy enough to create one, though, if
 155         you know how to use Visual C.
 156
 157         I build the program statically to avoid problems locating DLL's
 158         on machines that may not have MSVC runtime installed. If you
 159         prefer, you can change make to build with shared libraries by
 160         changing /MT to /MD in the NMakefile (or in build_w32.bat).
 161
 162         The program has not been built for non-Intel architectures (yet).
 163
 164         I have not tried to build with any other compilers than MSVC. I
 165         have heard that this is possible though so don't be afraid to
 166         notify me of your successes!
 167
 168 Pathnames and white space:
 169
 170         Unlike Unix, Windows 95/NT systems encourage pathnames which
 171         contain white space (e.g. C:\Program Files\). These sorts of
 172         pathnames are legal under Unix too, but are never encouraged.
 173         There is at least one place in make (VPATH/vpath handling) where
 174         paths containing white space will simply not work. There may be
 175         others too. I chose to not try and port make in such a way so
 176         that these sorts of paths could be handled. I offer these
 177         suggestions as workarounds:
 178
 179                 1. Use 8.3 notation. i.e. "x:/long~1/", which is actually
 180                    "x:\longpathtest".  Type "dir /x" to view these filenames
 181                    within the cmd.exe shell.
 182                 2. Rename the directory so it does not contain white space.
 183
 184         If you are unhappy with this choice, this is free software
 185         and you are free to take a crack at making this work. The code
 186         in w32/pathstuff.c and vpath.c would be the places to start.
 187
 188 Pathnames and Case insensitivity:
 189
 190         Unlike Unix, Windows 95/NT systems are case insensitive but case
 191         preserving.  For example if you tell the file system to create a
 192         file named "Target", it will preserve the case.  Subsequent access to
 193         the file with other case permutations will succeed (i.e. opening a
 194         file named "target" or "TARGET" will open the file "Target").
 195
 196         By default, GNU make retains its case sensitivity when comparing
 197         target names and existing files or directories.  It can be
 198         configured, however, into a case preserving and case insensitive
 199         mode by adding a define for HAVE_CASE_INSENSITIVE_FS to
 200         config.h.W32.
 201
 202         For example, the following makefile will create a file named
 203         Target in the directory subdir which will subsequently be used
 204         to satisfy the dependency of SUBDIR/DepTarget on SubDir/TARGET.
 205         Without HAVE_CASE_INSENSITIVE_FS configured, the dependency link
 206         will not be made:
 207
 208         subdir/Target:
 209                 touch $@
 210
 211         SUBDIR/DepTarget: SubDir/TARGET
 212                 cp $^ $@
 213
 214         Reliance on this behavior also eliminates the ability of GNU make
 215         to use case in comparison of matching rules.  For example, it is
 216         not possible to set up a C++ rule using %.C that is different
 217         than a C rule using %.c.  GNU make will consider these to be the
 218         same rule and will issue a warning.
 219
 220 SAMBA/NTFS/VFAT:
 221
 222         I have not had any success building the debug version of this
 223         package using SAMBA as my file server. The reason seems to be
 224         related to the way VC++ 4.0 changes the case name of the pdb
 225         filename it is passed on the command line. It seems to change
 226         the name always to to lower case. I contend that
 227         the VC++ compiler should not change the casename of files that
 228         are passed as arguments on the command line. I don't think this
 229         was a problem in MSVC 2.x, but I know it is a problem in MSVC 4.x.
 230
 231         The package builds fine on VFAT and NTFS filesystems.
 232
 233         Most all of the development I have done to date has been using
 234         NTFS and long file names. I have not done any considerable work
 235         under VFAT. VFAT users may wish to be aware that this port
 236         of make does respect case sensitivity.
 237
 238 FAT:
 239
 240         Version 3.76 added support for FAT filesystems. Make
 241         works around some difficulties with stat'ing of
 242         files and caching of filenames and directories internally.
 243
 244 Bug reports:
 245
 246         Please submit bugs via the normal bug reporting mechanism which
 247         is described in the GNU make manual and the base README.