(target_environment): Don't use shell_var if its `value' field is NULL.
[make.git] / README.DOS.template
blobac6a42363c2706ce1d87039b19b3aa1ff705a1f8
1 Port of GNU Make to 32-bit protected mode on MSDOS and MS-Windows.
3 Builds with DJGPP v2 port of GNU C/C++ compiler and utilities.
6 New (since 3.74) DOS-specific features:
8    1. Supports long filenames when run from DOS box on Windows 9x.
10    2. Supports both stock DOS COMMAND.COM and Unix-style shells
11       (details in ``Notes'' below).
13    3. Supports DOS drive letters in dependencies and pattern rules.
15    4. Better support for DOS-style backslashes in pathnames (but see
16       ``Notes'' below).
18    5. The $(shell) built-in can run arbitrary complex commands,
19       including pipes and redirection, even when COMMAND.COM is your
20       shell.
22    6. Can be built without floating-point code (see below).
24    7. Supports signals in child programs and restores the original
25       directory if the child was interrupted.
27    8. Can be built without (a previous version of) Make.
29    9. The build process requires only standard tools.  (Optional
30       targets like "install:" and "clean:" still need additional
31       programs, though, see below.)
33   10. Beginning with v3.78, the test suite works in the DJGPP
34       environment (requires Perl and auxiliary tools; see below).
37 To install a binary distribution:
39    Simply unzip the makNNNb.zip file (where NNN is the version number)
40    preserving the directory structure (-d switch if you use PKUNZIP).
41    If you are installing Make on Windows 9X or Windows 2000, use an
42    unzip program that supports long filenames in zip files.  After
43    unzipping, make sure the directory with make.exe is on your PATH,
44    and that's all you need to use Make.
47 To build from sources:
49    1. Unzip the archive, preserving the directory structure (-d switch
50       if you use PKUNZIP).  If you build Make on Windows 9X or Windows
51       2000, use an unzip program that supports long filenames in zip
52       files.
54       If you are unpacking an official GNU source distribution, use
55       either DJTAR (which is part of the DJGPP development
56       environment), or the DJGPP port of GNU Tar.
58    2. Invoke the `configure.bat' batch file.
60       If you are building Make in-place, i.e. in the same directory
61       where its sources are kept, just type "configure.bat" and press
62       [Enter].  Otherwise, you need to supply the path to the source
63       directory as an argument to the batch file, like this:
65         c:\djgpp\gnu\make-%VERSION%\configure.bat c:/djgpp/gnu/make-%VERSION%
67       Note the forward slashes in the source path argument: you MUST
68       use them here.
70    3. If configure.bat doesn't find a working Make, it will suggest to
71       use the `dosbuild.bat' batch file to build Make.  Either do as it
72       suggests or install another Make program (a pre-compiled binary
73       should be available from the usual DJGPP sites) and rerun
74       configure.bat.
76    4. If you will need to run Make on machines without an FPU, you
77       might consider building a version of Make which doesn't issue
78       floating-point instructions (they don't help much on MSDOS
79       anyway).  To this end, edit the Makefile created by
80       configure.bat and add -DNO_FLOAT to the value of CPPFLAGS.
82    5. Invoke Make.
84       If you are building from outside of the source directory, you
85       need to tell Make where the sources are, like this:
87                 make srcdir=c:/djgpp/gnu/make-%VERSION%
89       (configure.bat will tell you this when it finishes).  You MUST
90       use a full, not relative, name of the source directory here, or
91       else Make might fail.
93    6. After Make finishes, if you have a Unix-style shell installed,
94       you can use the `install' target to install the package.  You
95       will also need GNU Fileutils and GNU Sed for this (they should
96       be available from the DJGPP sites).
98       By default, GNU make will install into your DJGPP installation
99       area.  If you wish to use a different directory, override the
100       DESTDIR variable when invoking "make install", like this:
102                 make install DESTDIR=c:/other/dir
104       This causes the make executable to be placed in c:/other/dir/bin,
105       the man pages in c:/other/dir/man, etc.
107       Without a Unix-style shell, you will have to install programs
108       and the docs manually.  Copy make.exe to a directory on your
109       PATH, make.i* info files to your Info directory, and update the
110       file `dir' in your Info directory by adding the following item
111       to the main menu:
113         * Make: (make.info).           The GNU make utility.
115       If you have the `install-info' program (from the GNU Texinfo
116       package), it will do that for you if you invoke it like this:
118         install-info --info-dir=c:/djgpp/info c:/djgpp/info/make.info
120       (If your Info directory is other than C:\DJGPP\INFO, change this
121       command accordingly.)
123    7. The `clean' targets also require Unix-style shell, and GNU Sed
124       and `rm' programs (the latter from Fileutils).
126    8. To run the test suite, type "make check".  This requires a Unix
127       shell (I used the DJGPP port of Bash 2.03), Perl, Sed, Fileutils
128       and Sh-utils.
131 Notes:
132 -----
134    1. The shell issue.
136       This is probably the most significant improvement, first
137       introduced in the port of GNU Make 3.75.
139       The original behavior of GNU Make is to invoke commands
140       directly, as long as they don't include characters special to
141       the shell or internal shell commands, because that is faster.
142       When shell features like redirection or filename wildcards are
143       involved, Make calls the shell.
145       This port supports both DOS shells (the stock COMMAND.COM and its
146       4DOS/NDOS replacements), and Unix-style shells (tested with the
147       venerable Stewartson's `ms_sh' 2.3 and the DJGPP port of `bash' by
148       Daisuke Aoyama <jack@st.rim.or.jp>).
150       When the $SHELL variable points to a Unix-style shell, Make
151       works just like you'd expect on Unix, calling the shell for any
152       command that involves characters special to the shell or
153       internal shell commands.  The only difference is that, since
154       there is no standard way to pass command lines longer than the
155       infamous DOS 126-character limit, this port of Make writes the
156       command line to a temporary disk file and then invokes the shell
157       on that file.
159       If $SHELL points to a DOS-style shell, however, Make will not
160       call it automatically, as it does with Unix shells.  Stock
161       COMMAND.COM is too dumb and would unnecessarily limit the
162       functionality of Make.  For example, you would not be able to
163       use long command lines in commands that use redirection or
164       pipes.  Therefore, when presented with a DOS shell, this port of
165       Make will emulate most of the shell functionality, like
166       redirection and pipes, and shall only call the shell when a
167       batch file or a command internal to the shell is invoked.  (Even
168       when a command is an internal shell command, Make will first
169       search the $PATH for it, so that if a Makefile calls `mkdir',
170       you can install, say, a port of GNU `mkdir' and have it called
171       in that case.)
173       The key to all this is the extended functionality of `spawn' and
174       `system' functions from the DJGPP library; this port just calls
175       `system' where it would invoke the shell on Unix.  The most
176       important aspect of these functions is that they use a special
177       mechanism to pass long (up to 16KB) command lines to DJGPP
178       programs.  In addition, `system' emulates some internal
179       commands, like `cd' (so that you can now use forward slashes
180       with it, and can also change the drive if the directory is on
181       another drive).  Another aspect worth mentioning is that you can
182       call Unix shell scripts directly, provided that the shell whose
183       name is mentioned on the first line of the script is installed
184       anywhere along the $PATH.  It is impossible to tell here
185       everything about these functions; refer to the DJGPP library
186       reference for more details.
188       The $(shell) built-in is implemented in this port by calling
189       `popen'.  Since `popen' calls `system', the above considerations
190       are valid for $(shell) as well.  In particular, you can put
191       arbitrary complex commands, including pipes and redirection,
192       inside $(shell), which is in many cases a valid substitute for
193       the Unix-style command substitution (`command`) feature.
196    2. "SHELL=/bin/sh" -- or is it?
198       Many Unix Makefiles include a line which sets the SHELL, for
199       those versions of Make which don't have this as the default.
200       Since many DOS systems don't have `sh' installed (in fact, most
201       of them don't even have a `/bin' directory), this port takes
202       such directives with a grain of salt.  It will only honor such a
203       directive if the basename of the shell name (like `sh' in the
204       above example) can indeed be found in the directory that is
205       mentioned in the SHELL= line (`/bin' in the above example), or
206       in the current working directory, or anywhere on the $PATH (in
207       that order).  If the basename doesn't include a filename
208       extension, Make will look for any known extension that indicates
209       an executable file (.exe, .com, .bat, .btm, .sh, and even .sed
210       and .pl).  If any such file is found, then $SHELL will be
211       defined to the exact pathname of that file, and that shell will
212       hence be used for the rest of processing.  But if the named
213       shell is *not* found, the line which sets it will be effectively
214       ignored, leaving the value of $SHELL as it was before.  Since a
215       lot of decisions that this port makes depend on the gender of
216       the shell, I feel it doesn't make any sense to tailor Make's
217       behavior to a shell which is nowhere to be found.
219       Note that the above special handling of "SHELL=" only happens
220       for Makefiles; if you set $SHELL in the environment or on the
221       Make command line, you are expected to give the complete
222       pathname of the shell, including the filename extension.
224       The default value of $SHELL is computed as on Unix (see the Make
225       manual for details), except that if $SHELL is not defined in the
226       environment, $COMSPEC is used.  Also, if an environment variable
227       named $MAKESHELL is defined, it takes precedence over both
228       $COMSPEC and $SHELL.  Note that, unlike Unix, $SHELL in the
229       environment *is* used to set the shell (since on MSDOS, it's
230       unlikely that the interactive shell will not be suitable for
231       Makefile processing).
233       The bottom line is that you can now write Makefiles where some
234       of the targets require a real (i.e. Unix-like) shell, which will
235       nevertheless work when such shell is not available (provided, of
236       course, that the commands which should always work, don't
237       require such a shell).  More important, you can convert Unix
238       Makefiles to MSDOS and leave the line which sets the shell
239       intact, so that people who do have Unixy shell could use it for
240       targets which aren't converted to DOS (like `install' and
241       `uninstall', for example).
244    3. Default directories.
246       GNU Make knows about standard directories where it searches for
247       library and include files mentioned in the Makefile.  Since
248       MSDOS machines don't have standard places for these, this port
249       will search ${DJDIR}/lib and ${DJDIR}/include respectively.
250       $DJDIR is defined automatically by the DJGPP startup code as the
251       root of the DJGPP installation tree (unless you've tampered with
252       the DJGPP.ENV file).  This should provide reasonable default
253       values, unless you moved parts of DJGPP to other directories.
256    4. Letter-case in filenames.
258       If you run Make on Windows 9x, you should be aware of the
259       letter-case issue.  Make is internally case-sensitive, but all
260       file operations are case-insensitive on Windows 9x, so
261       e.g. files `FAQ', `faq' and `Faq' all refer to the same file, as
262       far as Windows is concerned.  The underlying DJGPP C library
263       functions honor the letter-case of the filenames they get from
264       the OS, except that by default, they down-case 8+3 DOS filenames
265       which are stored in upper case in the directory and would break
266       many Makefiles otherwise.  (The details of which filenames are
267       converted to lower case are explained in the DJGPP libc docs,
268       under the `_preserve_fncase' and `_lfn_gen_short_fname'
269       functions, but as a thumb rule, any filename that is stored in
270       upper case in the directory, is a valid DOS 8+3 filename and
271       doesn't include characters invalid on MSDOS FAT filesystems,
272       will be automatically down-cased.)  User reports that I have
273       indicate that this default behavior is generally what you'd
274       expect; however, your input is most welcome.
276       In any case, if you hit a situation where you must force Make to
277       get the 8+3 DOS filenames in upper case, set FNCASE=y in the
278       environment or in the Makefile.
281    5. DOS-style pathnames.
283       There are a lot of places throughout the program sources which
284       make implicit assumptions about the pathname syntax.  In
285       particular, the directories are assumed to be separated by `/',
286       and any pathname which doesn't begin with a `/' is assumed to be
287       relative to the current directory.  This port attempts to
288       support DOS-style pathnames which might include the drive letter
289       and use backslashes instead of forward slashes.  However, this
290       support is not complete; I feel that pursuing this support too
291       far might break some more important features, particularly if
292       you use a Unix-style shell (where a backslash is a quote
293       character).  I only consider support of backslashes desirable
294       because some Makefiles invoke non-DJGPP programs which don't
295       understand forward slashes.  A notable example of such programs
296       is the standard programs which come with MSDOS.  Otherwise, you
297       are advised to stay away from backslashes whenever possible.  In
298       particular, filename globbing won't work on pathnames with
299       backslashes, because the GNU `glob' library doesn't support them
300       (backslash is special in filename wildcards, and I didn't want
301       to break that).
303       One feature which *does* work with backslashes is the filename-
304       related built-in functions such as $(dir), $(notdir), etc.
305       Drive letters in pathnames are also fully supported.
309 Bug reports:
310 -----------
312    Bugs that are clearly related to the MSDOS/DJGPP port should be
313    reported first on the comp.os.msdos.djgpp news group (if you cannot
314    post to Usenet groups, write to the DJGPP mailing list,
315    <djgpp@delorie.com>, which is an email gateway into the above news
316    group).  For other bugs, please follow the procedure explained in
317    the "Bugs" chapter of the Info docs.  If you don't have an Info
318    reader, look up that chapter in the `make.i1' file with any text
319    browser/editor.
322    Enjoy,
323                         Eli Zaretskii <eliz@is.elta.co.il>
326 -------------------------------------------------------------------------------
327 Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
328 2006, 2007 Free Software Foundation, Inc.
329 This file is part of GNU Make.
331 GNU Make is free software; you can redistribute it and/or modify it under the
332 terms of the GNU General Public License as published by the Free Software
333 Foundation; either version 3 of the License, or (at your option) any later
334 version.
336 GNU Make is distributed in the hope that it will be useful, but WITHOUT ANY
337 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
338 A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
340 You should have received a copy of the GNU General Public License along with
341 this program.  If not, see <http://www.gnu.org/licenses/>.