Forgot to add the ONESHELL regression tests.
[make.git] / README.W32.template
blob3cc33b6455b37aeab029091d5c2a015f9ec467bc
1 This version of GNU make has been tested on Microsoft Windows 2000/XP/2003.
2 It has also been used on Windows 95/98/NT, and on OS/2.
4 It builds with the MinGW port of GCC (tested with GCC 3.4.2).
6 It also builds with MSVC 2.x, 4.x, 5.x, 6.x, and 2003 as well as
7 with .NET 7.x and .NET 2003.
9 The Windows 32-bit port of GNU make is maintained jointly by various
10 people.  It was originally made by Rob Tulloh.
13 Do this first, regardless of the build method you choose:
14 ---------------------------------------------------------
16  1. At the Windows command prompt run:
18       if not exist NMakefile copy NMakefile.template NMakefile
19       if not exist config.h copy config.h.W32 config.h
21     Then edit config.h to your liking (especially the few shell-related
22     defines near the end, or HAVE_CASE_INSENSITIVE_FS which corresponds
23     to './configure --enable-case-insensitive-file-system').
26 Using make_msvc_net2003.vcproj
27 ------------------------------
29  2. Open make_msvc_net2003.vcproj in MSVS71 or MSVC71 or any compatible IDE,
30     then build this project as usual.  There's also a solution file for
31     Studio 2003.
34 Building with (MinGW-)GCC using build_w32.bat
35 ---------------------------------------------
37  2. Open a W32 command prompt for your installed (MinGW-)GCC, setup a
38     correct PATH and other environment variables for it, then execute ...
40         build_w32.bat gcc
42     This produces gnumake.exe in the current directory.
45 Building with (MSVC++-)cl using build_w32.bat or NMakefile
46 ----------------------------------------------------------
48  2. Open a W32 command prompt for your installed (MSVC++-)cl, setup a
49     correct PATH and other environment variables for it (usually via
50     executing vcvars32.bat or vsvars32.bat from the cl-installation,
51     e.g. "%VS71COMNTOOLS%vsvars32.bat"; or using a corresponding start
52     menue entry from the cl-installation), then execute EITHER ...
54         build_w32.bat
56     (this produces WinDebug/gnumake.exe and WinRel/gnumake.exe)
58     ... OR ...
60         nmake /f NMakefile
62     (this produces WinDebug/make.exe and WinRel/make.exe).
65 -------------------
66 -- Notes/Caveats --
67 -------------------
69 GNU make on Windows 32-bit platforms:
71         This version of make is ported natively to Windows32 platforms
72         (Windows NT 3.51, Windows NT 4.0, Windows 2000, Windows XP,
73         Windows 95, and Windows 98). It does not rely on any 3rd party
74         software or add-on packages for building. The only thing
75         needed is a Windows compiler.  Two compilers supported
76         officially are the MinGW port of GNU GCC, and the various
77         versions of the Microsoft C compiler.
79         Do not confuse this port of GNU make with other Windows32 projects
80         which provide a GNU make binary. These are separate projects
81         and are not connected to this port effort.
83 GNU make and sh.exe:
85         This port prefers if you have a working sh.exe somewhere on
86         your system. If you don't have sh.exe, the port falls back to
87         MSDOS mode for launching programs (via a batch file).  The
88         MSDOS mode style execution has not been tested that carefully
89         though (The author uses GNU bash as sh.exe).
91         There are very few true ports of Bourne shell for NT right now.
92         There is a version of GNU bash available from Cygnus "Cygwin"
93         porting effort (http://www.cygwin.com/).
94         Other possibilities are the MKS version of sh.exe, or building
95         your own with a package like NutCracker (DataFocus) or Portage
96         (Consensys).  Also MinGW includes sh (http://mingw.org/).
98 GNU make and brain-dead shells (BATCH_MODE_ONLY_SHELL):
100         Some versions of Bourne shell do not behave well when invoked
101         as 'sh -c' from CreateProcess().  The main problem is they seem
102         to have a hard time handling quoted strings correctly. This can
103         be circumvented by writing commands to be executed to a batch
104         file and then executing the command by calling 'sh file'.
106         To work around this difficulty, this version of make supports
107         a batch mode.  When BATCH_MODE_ONLY_SHELL is defined at compile
108         time, make forces all command lines to be executed via script
109         files instead of by command line.  In this mode you must have a
110         working sh.exe in order to use parallel builds (-j).
112         A native Windows32 system with no Bourne shell will also run
113         in batch mode.  All command lines will be put into batch files
114         and executed via $(COMSPEC) (%COMSPEC%).  However, parallel
115         builds ARE supported with Windows shells (cmd.exe and
116         command.com).  See the next section about some peculiarities
117         of parallel builds on Windows.
119 Support for parallel builds
121         Parallel builds (-jN) are supported in this port, with 2
122         limitations:
124           - The number of concurrent processes has a hard limit of 64,
125             due to the way this port implements waiting for its
126             subprocesses;
128           - The job server method (available when Make runs on Posix
129             platforms) is not supported, which means you must pass an
130             explicit -jN switch to sub-Make's in a recursive Makefile.
131             If a sub-Make does not receive an explicit -jN switch, it
132             will default to -j1, i.e. no parallelism in sub-Make's.
134 GNU make and Cygnus GNU Windows32 tools:
136         Good news! Make now has native support for Cygwin sh. To enable,
137         define the HAVE_CYGWIN_SHELL in config.h and rebuild make
138         from scratch. This version of make tested with B20.1 of Cygwin.
139         Do not define BATCH_MODE_ONLY_SHELL if you use HAVE_CYGWIN_SHELL.
141 GNU make and the MKS shell:
143         There is now semi-official support for the MKS shell. To turn this
144         support on, define HAVE_MKS_SHELL in the config.h.W32 before you
145         build make.  Do not define BATCH_MODE_ONLY_SHELL if you turn
146         on HAVE_MKS_SHELL.
148 GNU make handling of drive letters in pathnames (PATH, vpath, VPATH):
150         There is a caveat that should be noted with respect to handling
151         single character pathnames on Windows systems.  When colon is
152         used in PATH variables, make tries to be smart about knowing when
153         you are using colon as a separator versus colon as a drive
154         letter.  Unfortunately, something as simple as the string 'x:/'
155         could be interpreted 2 ways: (x and /) or (x:/).
157         Make chooses to interpret a letter plus colon (e.g. x:/) as a
158         drive letter pathname.  If it is necessary to use single
159         character directories in paths (VPATH, vpath, Path, PATH), the
160         user must do one of two things:
162          a. Use semicolon as the separator to disambiguate colon. For
163             example use 'x;/' if you want to say 'x' and '/' are
164             separate components.
166          b. Qualify the directory name so that there is more than
167             one character in the path(s) used. For example, none
168             of these settings are ambiguous:
170               ./x:./y
171               /some/path/x:/some/path/y
172               x:/some/path/x:x:/some/path/y
174         Please note that you are free to mix colon and semi-colon in the
175         specification of paths.  Make is able to figure out the intended
176         result and convert the paths internally to the format needed
177         when interacting with the operating system, providing the path
178         is not within quotes, e.g. "x:/test/test.c".
180         You are encouraged to use colon as the separator character.
181         This should ease the pain of deciding how to handle various path
182         problems which exist between platforms.  If colon is used on
183         both Unix and Windows systems, then no ifdef'ing will be
184         necessary in the makefile source.
186 GNU make test suite:
188         I verified all functionality with a slightly modified version
189         of make-test-%VERSION% (modifications to get test suite to run
190         on Windows NT). All tests pass in an environment that includes
191         sh.exe.  Tests were performed on both Windows NT and Windows 95.
193 Pathnames and white space:
195         Unlike Unix, Windows 95/NT systems encourage pathnames which
196         contain white space (e.g. C:\Program Files\). These sorts of
197         pathnames are valid on Unix too, but are never encouraged.
198         There is at least one place in make (VPATH/vpath handling) where
199         paths containing white space will simply not work. There may be
200         others too. I chose to not try and port make in such a way so
201         that these sorts of paths could be handled. I offer these
202         suggestions as workarounds:
204                 1. Use 8.3 notation. i.e. "x:/long~1/", which is actually
205                    "x:\longpathtest".  Type "dir /x" to view these filenames
206                    within the cmd.exe shell.
207                 2. Rename the directory so it does not contain white space.
209         If you are unhappy with this choice, this is free software
210         and you are free to take a crack at making this work. The code
211         in w32/pathstuff.c and vpath.c would be the places to start.
213 Pathnames and Case insensitivity:
215         Unlike Unix, Windows 95/NT systems are case insensitive but case
216         preserving.  For example if you tell the file system to create a
217         file named "Target", it will preserve the case.  Subsequent access to
218         the file with other case permutations will succeed (i.e. opening a
219         file named "target" or "TARGET" will open the file "Target").
221         By default, GNU make retains its case sensitivity when comparing
222         target names and existing files or directories.  It can be
223         configured, however, into a case preserving and case insensitive
224         mode by adding a define for HAVE_CASE_INSENSITIVE_FS to
225         config.h.W32.
227         For example, the following makefile will create a file named
228         Target in the directory subdir which will subsequently be used
229         to satisfy the dependency of SUBDIR/DepTarget on SubDir/TARGET.
230         Without HAVE_CASE_INSENSITIVE_FS configured, the dependency link
231         will not be made:
233         subdir/Target:
234                 touch $@
236         SUBDIR/DepTarget: SubDir/TARGET
237                 cp $^ $@
239         Reliance on this behavior also eliminates the ability of GNU make
240         to use case in comparison of matching rules.  For example, it is
241         not possible to set up a C++ rule using %.C that is different
242         than a C rule using %.c.  GNU make will consider these to be the
243         same rule and will issue a warning.
245 SAMBA/NTFS/VFAT:
247         I have not had any success building the debug version of this
248         package using SAMBA as my file server. The reason seems to be
249         related to the way VC++ 4.0 changes the case name of the pdb
250         filename it is passed on the command line. It seems to change
251         the name always to to lower case. I contend that the VC++
252         compiler should not change the casename of files that are passed
253         as arguments on the command line. I don't think this was a
254         problem in MSVC 2.x, but I know it is a problem in MSVC 4.x.
256         The package builds fine on VFAT and NTFS filesystems.
258         Most all of the development I have done to date has been using
259         NTFS and long file names. I have not done any considerable work
260         under VFAT. VFAT users may wish to be aware that this port of
261         make does respect case sensitivity.
263 FAT:
265         Version 3.76 added support for FAT filesystems. Make works
266         around some difficulties with stat'ing of files and caching of
267         filenames and directories internally.
269 Bug reports:
271         Please submit bugs via the normal bug reporting mechanism which
272         is described in the GNU make manual and the base README.
274 -------------------------------------------------------------------------------
275 Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
276 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
277 This file is part of GNU Make.
279 GNU Make is free software; you can redistribute it and/or modify it under the
280 terms of the GNU General Public License as published by the Free Software
281 Foundation; either version 3 of the License, or (at your option) any later
282 version.
284 GNU Make is distributed in the hope that it will be useful, but WITHOUT ANY
285 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
286 A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
288 You should have received a copy of the GNU General Public License along with
289 this program.  If not, see <http://www.gnu.org/licenses/>.