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