README.W32

   1 This version of GNU Make has been tested on:
   2   Microsoft Windows 2000/XP/2003/Vista/7/8/10
   3 It has also been used on Windows 95/98/NT, and on OS/2.
   4
   5 It builds with the MinGW port of GCC (tested with GCC 3.4.2, 4.8.1,
   6 and 4.9.3).
   7
   8 It also builds with MSVC 2.x, 4.x, 5.x, 6.x, 2005, 2008, 2010, 2012,
   9 2013, and 2015 as well as with .NET 7.x and .NET 2003.
  10
  11 Building with Guile is supported (tested with Guile 2.0.x).  To build
  12 with Guile, you will need, in addition to Guile itself, its dependency
  13 libraries and the pkg-config program.  The latter is used to figure out
  14 which compilation and link switches and libraries need to be mentioned
  15 on the compiler command lines to correctly link with Guile.  A Windows
  16 port of pkg-config can be found on ezwinports site:
  17
  18   https://sourceforge.net/projects/ezwinports/
  19
  20 The libraries on which Guile depends can vary depending on your
  21 version and build of Guile.  At the very least, the Boehm's GC library
  22 will be needed, and typically also GNU MP, libffi, libunistring, and
  23 libtool's libltdl.  Whoever built the port of Guile you have should
  24 also provide you with these dependencies or a URL where to download
  25 them.  A precompiled 32-bit Windows build of Guile is available from
  26 the ezwinports site mentioned above.
  27
  28 The Windows port of GNU Make is maintained jointly by various people.
  29 It was originally made by Rob Tulloh.
  30 It is currently maintained by Eli Zaretskii.
  31
  32
  33 Do this first, regardless of the build method you choose:
  34 ---------------------------------------------------------
  35
  36  1. If you have special requirements, edit config.h.W32 to your liking
  37     (especially the shell-related defines, or HAVE_CASE_INSENSITIVE_FS which
  38     corresponds to './configure --enable-case-insensitive-file-system').  We
  39     don't recommend to define HAVE_CASE_INSENSITIVE_FS, but you may wish to
  40     consider that if you have a lot of files whose names are in upper case,
  41     while Makefile rules are written for lower-case versions.
  42
  43     If you don't have special requirements no changes are needed.
  44
  45
  46 Building with (MinGW-)GCC using build_w32.bat
  47 ---------------------------------------------
  48
  49  2. Open a W32 command prompt for your installed (MinGW-)GCC, setup a
  50     correct PATH and other environment variables for it, then execute ...
  51
  52         .\build_w32.bat gcc
  53
  54     This produces gnumake.exe in the GccRel directory.
  55
  56     If you want a version of GNU Make built with debugging enabled,
  57     add the --debug option.  Output goes into the GccDebug directory.
  58
  59     The batch file will probe for Guile installation, and will build
  60     gnumake.exe with Guile if it finds it.  If you have Guile
  61     installed, but want to build Make without Guile support, type
  62
  63         .\build_w32.bat --without-guile gcc
  64
  65
  66 Building with (MSVC++-)cl using build_w32.bat
  67 ---------------------------------------------
  68
  69  2. Open a command shell, then execute ...
  70
  71         .\build_w32.bat
  72
  73     This produces a 64bit Release build of gnumake.exe in .\WinRel, using
  74     the compiler found on the %Path%.  If no compiler is found, the batch
  75     file will probe your system and choose the newest MSVC version it can
  76     find.
  77
  78     If you want a 32bit version of GNU Make, add the --x86 option.
  79
  80     If you want a Debug build of GNU Make, add the --debug option.  Output
  81     will go into the .\WinDebug directory.
  82
  83     The batch file will probe for Guile installation, and will build
  84     gnumake.exe with Guile if it finds it.  If Guile is installed,
  85     but you prefer to build GNU Make without Guile support, add the
  86     --without-guile option.
  87
  88
  89 Building with (MinGW-)GCC using GNU Make
  90 ----------------------------------------
  91
  92  2. If you already have a version of GNU Make available you can use it
  93     to build this version.  Open a W32 command prompt for your installed
  94     (MinGW-)GCC, setup a correct PATH and other environment variables
  95     for it, then execute ...
  96
  97         make -f Basic.mk TOOLCHAIN=gcc
  98
  99     This produces GccRel\gnumake.exe.
 100     If you want a version of GNU Make built with debugging enabled,
 101     add the TARGET_TYPE=debug option:
 102
 103         make -f Basic.mk TOOLCHAIN=gcc TARGET_TYPE=debug
 104
 105     The makefile doesn't support Guile integration.  Use build_w32.bat
 106     if you want to build with Guile support.
 107
 108
 109 Building with (MSVC++-)cl using GNU Make
 110 ----------------------------------------
 111
 112  2. If you already have a version of GNU Make available you can use it
 113     to build this version.  Open a W32 command prompt for your installed
 114     (MSVC++-)cl, setup a correct PATH and other environment variables
 115     for it (usually via executing vcvars32.bat or vsvars32.bat from the
 116     cl-installation, or using a corresponding start menu entry from the
 117     cl-installation), then execute ...
 118
 119         make -f Basic.mk
 120
 121     This produces an optimized WinRel/gnumake.exe.
 122     If you want a version of GNU Make built with debugging enabled,
 123     add the TARGET_TYPE=debug option:
 124
 125         make -f Basic.mk TARGET_TYPE=debug
 126
 127     The makefile doesn't support Guile integration.  Use build_w32.bat
 128     if you want to build with Guile support.
 129
 130
 131 Running the test suite
 132 ----------------------
 133
 134  3. You will need an installation of Perl.  Be sure to use a relatively
 135     modern version: older versions will sometimes throw spurious errors.
 136
 137     To run the suite after building using GNU Make, use:
 138
 139         make -f Basic.mk check
 140
 141     Alternatively if you'd like to run tests by hand, use:
 142
 143         cd tests
 144         .\run_make_tests.bat -make <path-to-make>
 145
 146     I've found <path-to-make> seems to want forward-slashes in the path.
 147     For example if building with .\build_w32.bat non-debug, use:
 148
 149         cd tests
 150         .\run_make_tests.bat -make ../WinRel/gnumake.exe
 151
 152     I've tested this with the MSYS2 shell and POSIX tools installation
 153     that you get by installing Git for Windows.
 154
 155
 156
 157 -------------------
 158 -- Notes/Caveats --
 159 -------------------
 160
 161 GNU Make on Windows 32-bit platforms:
 162
 163         This version of make is ported natively to Windows32 platforms
 164         (Windows NT 3.51, Windows NT 4.0, Windows 2000, Windows XP,
 165         Windows 95, and Windows 98). It does not rely on any 3rd party
 166         software or add-on packages for building. The only thing
 167         needed is a Windows compiler.  Two compilers supported
 168         officially are the MinGW port of GNU GCC, and the various
 169         versions of the Microsoft C compiler.
 170
 171         Do not confuse this port of GNU Make with other Windows32 projects
 172         which provide a GNU Make binary. These are separate projects
 173         and are not connected to this port effort.
 174
 175 GNU Make and sh.exe:
 176
 177         This port prefers if you have a working sh.exe somewhere on
 178         your system. If you don't have sh.exe, the port falls back to
 179         MSDOS mode for launching programs (via a batch file).  The
 180         MSDOS mode style execution has not been tested that carefully
 181         though (The author uses GNU bash as sh.exe).
 182
 183         There are very few true ports of Bourne shell for NT right now.
 184         There is a version of GNU bash available from Cygnus "Cygwin"
 185         porting effort (https://www.cygwin.com/).
 186         Other possibilities are the MKS version of sh.exe, or building
 187         your own with a package like NutCracker (DataFocus) or Portage
 188         (Consensys).  Also MinGW includes sh.
 189
 190 GNU Make and brain-dead shells (BATCH_MODE_ONLY_SHELL):
 191
 192         Some versions of Bourne shell do not behave well when invoked
 193         as 'sh -c' from CreateProcess().  The main problem is they seem
 194         to have a hard time handling quoted strings correctly. This can
 195         be circumvented by writing commands to be executed to a batch
 196         file and then executing the command by calling 'sh file'.
 197
 198         To work around this difficulty, this version of make supports
 199         a batch mode.  When BATCH_MODE_ONLY_SHELL is defined at compile
 200         time, make forces all command lines to be executed via script
 201         files instead of by command line.  In this mode you must have a
 202         working sh.exe in order to use parallel builds (-j).
 203
 204         A native Windows32 system with no Bourne shell will also run
 205         in batch mode.  All command lines will be put into batch files
 206         and executed via $(COMSPEC) (%COMSPEC%).  However, parallel
 207         builds ARE supported with Windows shells (cmd.exe and
 208         command.com).  See the next section about some peculiarities
 209         of parallel builds on Windows.
 210
 211 Support for parallel builds
 212
 213         Parallel builds (-jN) are supported in this port.  The number of
 214         concurrent processes has a hard limit of 4095.
 215
 216 GNU Make and Cygnus GNU Windows32 tools:
 217
 218         Good news! Make now has native support for Cygwin sh. To enable,
 219         define the HAVE_CYGWIN_SHELL in config.h and rebuild make
 220         from scratch. This version of make tested with B20.1 of Cygwin.
 221         Do not define BATCH_MODE_ONLY_SHELL if you use HAVE_CYGWIN_SHELL.
 222
 223 GNU Make and the MKS shell:
 224
 225         There is now semi-official support for the MKS shell. To turn this
 226         support on, define HAVE_MKS_SHELL in the config.h.W32 before you
 227         build make.  Do not define BATCH_MODE_ONLY_SHELL if you turn
 228         on HAVE_MKS_SHELL.
 229
 230 GNU Make handling of drive letters in pathnames (PATH, vpath, VPATH):
 231
 232         There is a caveat that should be noted with respect to handling
 233         single character pathnames on Windows systems.  When colon is
 234         used in PATH variables, make tries to be smart about knowing when
 235         you are using colon as a separator versus colon as a drive
 236         letter.  Unfortunately, something as simple as the string 'x:/'
 237         could be interpreted 2 ways: (x and /) or (x:/).
 238
 239         Make chooses to interpret a letter plus colon (e.g. x:/) as a
 240         drive letter pathname.  If it is necessary to use single
 241         character directories in paths (VPATH, vpath, Path, PATH), the
 242         user must do one of two things:
 243
 244          a. Use semicolon as the separator to disambiguate colon. For
 245             example use 'x;/' if you want to say 'x' and '/' are
 246             separate components.
 247
 248          b. Qualify the directory name so that there is more than
 249             one character in the path(s) used. For example, none
 250             of these settings are ambiguous:
 251
 252               ./x:./y
 253               /some/path/x:/some/path/y
 254               x:/some/path/x:x:/some/path/y
 255
 256         Please note that you are free to mix colon and semi-colon in the
 257         specification of paths.  Make is able to figure out the intended
 258         result and convert the paths internally to the format needed
 259         when interacting with the operating system, providing the path
 260         is not within quotes, e.g. "x:/test/test.c".
 261
 262         You are encouraged to use colon as the separator character.
 263         This should ease the pain of deciding how to handle various path
 264         problems which exist between platforms.  If colon is used on
 265         both Unix and Windows systems, then no ifdef'ing will be
 266         necessary in the makefile source.
 267
 268 Pathnames and white space:
 269
 270         Unlike Unix, Windows 95/NT systems encourage pathnames which
 271         contain white space (e.g. C:\Program Files\). These sorts of
 272         pathnames are valid on Unix too, but are never encouraged.
 273         There is at least one place in make (VPATH/vpath handling) where
 274         paths containing white space will simply not work. There may be
 275         others too. I chose to not try and port make in such a way so
 276         that these sorts of paths could be handled. I offer these
 277         suggestions as workarounds:
 278
 279                 1. Use 8.3 notation. i.e. "x:/long~1/", which is actually
 280                    "x:\longpathtest".  Type "dir /x" to view these filenames
 281                    within the cmd.exe shell.
 282                 2. Rename the directory so it does not contain white space.
 283
 284         If you are unhappy with this choice, this is free software
 285         and you are free to take a crack at making this work. The code
 286         in w32/pathstuff.c and vpath.c would be the places to start.
 287
 288 Pathnames and Case insensitivity:
 289
 290         Unlike Unix, Windows 95/NT systems are case insensitive but case
 291         preserving.  For example if you tell the file system to create a
 292         file named "Target", it will preserve the case.  Subsequent access to
 293         the file with other case permutations will succeed (i.e. opening a
 294         file named "target" or "TARGET" will open the file "Target").
 295
 296         By default, GNU Make retains its case sensitivity when comparing
 297         target names and existing files or directories.  It can be
 298         configured, however, into a case preserving and case insensitive
 299         mode by adding a define for HAVE_CASE_INSENSITIVE_FS to
 300         config.h.W32.
 301
 302         For example, the following makefile will create a file named
 303         Target in the directory subdir which will subsequently be used
 304         to satisfy the dependency of SUBDIR/DepTarget on SubDir/TARGET.
 305         Without HAVE_CASE_INSENSITIVE_FS configured, the dependency link
 306         will not be made:
 307
 308         subdir/Target:
 309                 touch $@
 310
 311         SUBDIR/DepTarget: SubDir/TARGET
 312                 cp $^ $@
 313
 314         Reliance on this behavior also eliminates the ability of GNU Make
 315         to use case in comparison of matching rules.  For example, it is
 316         not possible to set up a C++ rule using %.C that is different
 317         than a C rule using %.c.  GNU Make will consider these to be the
 318         same rule and will issue a warning.
 319
 320 SAMBA/NTFS/VFAT:
 321
 322         I have not had any success building the debug version of this
 323         package using SAMBA as my file server. The reason seems to be
 324         related to the way VC++ 4.0 changes the case name of the pdb
 325         filename it is passed on the command line. It seems to change
 326         the name always to to lower case. I contend that the VC++
 327         compiler should not change the casename of files that are passed
 328         as arguments on the command line. I don't think this was a
 329         problem in MSVC 2.x, but I know it is a problem in MSVC 4.x.
 330
 331         The package builds fine on VFAT and NTFS filesystems.
 332
 333         Most all of the development I have done to date has been using
 334         NTFS and long file names. I have not done any considerable work
 335         under VFAT. VFAT users may wish to be aware that this port of
 336         make does respect case sensitivity.
 337
 338 FAT:
 339
 340         Version 3.76 added support for FAT filesystems. Make works
 341         around some difficulties with stat'ing of files and caching of
 342         filenames and directories internally.
 343
 344 Bug reports:
 345
 346         Please submit bugs via the normal bug reporting mechanism which
 347         is described in the GNU Make manual and the base README.
 348 \f
 349 -------------------------------------------------------------------------------
 350 Copyright (C) 1996-2022 Free Software Foundation, Inc.
 351 This file is part of GNU Make.
 352
 353 GNU Make is free software; you can redistribute it and/or modify it under the
 354 terms of the GNU General Public License as published by the Free Software
 355 Foundation; either version 3 of the License, or (at your option) any later
 356 version.
 357
 358 GNU Make is distributed in the hope that it will be useful, but WITHOUT ANY
 359 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 360 A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 361
 362 You should have received a copy of the GNU General Public License along with
 363 this program.  If not, see <https://www.gnu.org/licenses/>.