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