summaryrefslogtreecommitdiffstats
path: root/src/kmk/README.DOS.template
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-11 08:21:29 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-11 08:21:29 +0000
commit29cd838eab01ed7110f3ccb2e8c6a35c8a31dbcc (patch)
tree63ef546b10a81d461e5cf5ed9e98a68cd7dee1aa /src/kmk/README.DOS.template
parentInitial commit. (diff)
downloadkbuild-29cd838eab01ed7110f3ccb2e8c6a35c8a31dbcc.tar.xz
kbuild-29cd838eab01ed7110f3ccb2e8c6a35c8a31dbcc.zip
Adding upstream version 1:0.1.9998svn3589+dfsg.upstream/1%0.1.9998svn3589+dfsg
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/kmk/README.DOS.template')
-rw-r--r--src/kmk/README.DOS.template340
1 files changed, 340 insertions, 0 deletions
diff --git a/src/kmk/README.DOS.template b/src/kmk/README.DOS.template
new file mode 100644
index 0000000..bc31adb
--- /dev/null
+++ b/src/kmk/README.DOS.template
@@ -0,0 +1,340 @@
+Port of GNU Make to 32-bit protected mode on MSDOS and MS-Windows.
+
+Builds with DJGPP v2 port of GNU C/C++ compiler and utilities.
+
+
+New (since 3.74) DOS-specific features:
+
+ 1. Supports long filenames when run from DOS box on Windows 9x.
+
+ 2. Supports both stock DOS COMMAND.COM and Unix-style shells
+ (details in 'Notes' below).
+
+ 3. Supports DOS drive letters in dependencies and pattern rules.
+
+ 4. Better support for DOS-style backslashes in pathnames (but see
+ 'Notes' below).
+
+ 5. The $(shell) built-in can run arbitrary complex commands,
+ including pipes and redirection, even when COMMAND.COM is your
+ shell.
+
+ 6. Can be built without floating-point code (see below).
+
+ 7. Supports signals in child programs and restores the original
+ directory if the child was interrupted.
+
+ 8. Can be built without (a previous version of) Make.
+
+ 9. The build process requires only standard tools. (Optional
+ targets like "install:" and "clean:" still need additional
+ programs, though, see below.)
+
+ 10. Beginning with v3.78, the test suite works in the DJGPP
+ environment (requires Perl and auxiliary tools; see below).
+
+
+To install a binary distribution:
+
+ Simply unzip the makNNNb.zip file (where NNN is the version number)
+ preserving the directory structure (-d switch if you use PKUNZIP).
+ If you are installing Make on Windows 9X or Windows 2000, use an
+ unzip program that supports long filenames in zip files. After
+ unzipping, make sure the directory with make.exe is on your PATH,
+ and that's all you need to use Make.
+
+
+To build from sources:
+
+ 1. Unzip the archive, preserving the directory structure (-d switch
+ if you use PKUNZIP). If you build Make on Windows 9X or Windows
+ 2000, use an unzip program that supports long filenames in zip
+ files.
+
+ If you are unpacking an official GNU source distribution, use
+ either DJTAR (which is part of the DJGPP development
+ environment), or the DJGPP port of GNU Tar.
+
+ 2. Invoke the 'configure.bat' batch file.
+
+ If you are building Make in-place, i.e. in the same directory
+ where its sources are kept, just type "configure.bat" and press
+ [Enter]. Otherwise, you need to supply the path to the source
+ directory as an argument to the batch file, like this:
+
+ c:\djgpp\gnu\make-%VERSION%\configure.bat c:/djgpp/gnu/make-%VERSION%
+
+ Note the forward slashes in the source path argument: you MUST
+ use them here.
+
+ 3. If configure.bat doesn't find a working Make, it will suggest to
+ use the 'dosbuild.bat' batch file to build Make. Either do as it
+ suggests or install another Make program (a pre-compiled binary
+ should be available from the usual DJGPP sites) and rerun
+ configure.bat.
+
+ 4. If you will need to run Make on machines without an FPU, you
+ might consider building a version of Make which doesn't issue
+ floating-point instructions (they don't help much on MSDOS
+ anyway). To this end, edit the Makefile created by
+ configure.bat and add -DNO_FLOAT to the value of CPPFLAGS.
+
+ 5. Invoke Make.
+
+ If you are building from outside of the source directory, you
+ need to tell Make where the sources are, like this:
+
+ make srcdir=c:/djgpp/gnu/make-%VERSION%
+
+ (configure.bat will tell you this when it finishes). You MUST
+ use a full, not relative, name of the source directory here, or
+ else Make might fail.
+
+ 6. After Make finishes, if you have a Unix-style shell installed,
+ you can use the 'install' target to install the package. You
+ will also need GNU Fileutils and GNU Sed for this (they should
+ be available from the DJGPP sites).
+
+ By default, GNU make will install into your DJGPP installation
+ area. If you wish to use a different directory, override the
+ DESTDIR variable when invoking "make install", like this:
+
+ make install DESTDIR=c:/other/dir
+
+ This causes the make executable to be placed in c:/other/dir/bin,
+ the man pages in c:/other/dir/man, etc.
+
+ Without a Unix-style shell, you will have to install programs
+ and the docs manually. Copy make.exe to a directory on your
+ PATH, make.i* info files to your Info directory, and update the
+ file 'dir' in your Info directory by adding the following item
+ to the main menu:
+
+ * Make: (make.info). The GNU make utility.
+
+ If you have the 'install-info' program (from the GNU Texinfo
+ package), it will do that for you if you invoke it like this:
+
+ install-info --info-dir=c:/djgpp/info c:/djgpp/info/make.info
+
+ (If your Info directory is other than C:\DJGPP\INFO, change this
+ command accordingly.)
+
+ 7. The 'clean' targets also require Unix-style shell, and GNU Sed
+ and 'rm' programs (the latter from Fileutils).
+
+ 8. To run the test suite, type "make check". This requires a Unix
+ shell (I used the DJGPP port of Bash 2.03), Perl, Sed, Fileutils
+ and Sh-utils.
+
+
+Notes:
+-----
+
+ 1. The shell issue.
+
+ This is probably the most significant improvement, first
+ introduced in the port of GNU Make 3.75.
+
+ The original behavior of GNU Make is to invoke commands
+ directly, as long as they don't include characters special to
+ the shell or internal shell commands, because that is faster.
+ When shell features like redirection or filename wildcards are
+ involved, Make calls the shell.
+
+ This port supports both DOS shells (the stock COMMAND.COM and its
+ 4DOS/NDOS replacements), and Unix-style shells (tested with the
+ venerable Stewartson's 'ms_sh' 2.3 and the DJGPP port of 'bash' by
+ Daisuke Aoyama <jack@st.rim.or.jp>).
+
+ When the $SHELL variable points to a Unix-style shell, Make
+ works just like you'd expect on Unix, calling the shell for any
+ command that involves characters special to the shell or
+ internal shell commands. The only difference is that, since
+ there is no standard way to pass command lines longer than the
+ infamous DOS 126-character limit, this port of Make writes the
+ command line to a temporary disk file and then invokes the shell
+ on that file.
+
+ If $SHELL points to a DOS-style shell, however, Make will not
+ call it automatically, as it does with Unix shells. Stock
+ COMMAND.COM is too dumb and would unnecessarily limit the
+ functionality of Make. For example, you would not be able to
+ use long command lines in commands that use redirection or
+ pipes. Therefore, when presented with a DOS shell, this port of
+ Make will emulate most of the shell functionality, like
+ redirection and pipes, and shall only call the shell when a
+ batch file or a command internal to the shell is invoked. (Even
+ when a command is an internal shell command, Make will first
+ search the $PATH for it, so that if a Makefile calls 'mkdir',
+ you can install, say, a port of GNU 'mkdir' and have it called
+ in that case.)
+
+ The key to all this is the extended functionality of 'spawn' and
+ 'system' functions from the DJGPP library; this port just calls
+ 'system' where it would invoke the shell on Unix. The most
+ important aspect of these functions is that they use a special
+ mechanism to pass long (up to 16KB) command lines to DJGPP
+ programs. In addition, 'system' emulates some internal
+ commands, like 'cd' (so that you can now use forward slashes
+ with it, and can also change the drive if the directory is on
+ another drive). Another aspect worth mentioning is that you can
+ call Unix shell scripts directly, provided that the shell whose
+ name is mentioned on the first line of the script is installed
+ anywhere along the $PATH. It is impossible to tell here
+ everything about these functions; refer to the DJGPP library
+ reference for more details.
+
+ The $(shell) built-in is implemented in this port by calling
+ 'popen'. Since 'popen' calls 'system', the above considerations
+ are valid for $(shell) as well. In particular, you can put
+ arbitrary complex commands, including pipes and redirection,
+ inside $(shell), which is in many cases a valid substitute for
+ the Unix-style command substitution (`command`) feature.
+
+
+ 2. "SHELL=/bin/sh" -- or is it?
+
+ Many Unix Makefiles include a line which sets the SHELL, for
+ those versions of Make which don't have this as the default.
+ Since many DOS systems don't have 'sh' installed (in fact, most
+ of them don't even have a '/bin' directory), this port takes
+ such directives with a grain of salt. It will only honor such a
+ directive if the basename of the shell name (like 'sh' in the
+ above example) can indeed be found in the directory that is
+ mentioned in the SHELL= line ('/bin' in the above example), or
+ in the current working directory, or anywhere on the $PATH (in
+ that order). If the basename doesn't include a filename
+ extension, Make will look for any known extension that indicates
+ an executable file (.exe, .com, .bat, .btm, .sh, and even .sed
+ and .pl). If any such file is found, then $SHELL will be
+ defined to the exact pathname of that file, and that shell will
+ hence be used for the rest of processing. But if the named
+ shell is *not* found, the line which sets it will be effectively
+ ignored, leaving the value of $SHELL as it was before. Since a
+ lot of decisions that this port makes depend on the gender of
+ the shell, I feel it doesn't make any sense to tailor Make's
+ behavior to a shell which is nowhere to be found.
+
+ Note that the above special handling of "SHELL=" only happens
+ for Makefiles; if you set $SHELL in the environment or on the
+ Make command line, you are expected to give the complete
+ pathname of the shell, including the filename extension.
+
+ The default value of $SHELL is computed as on Unix (see the Make
+ manual for details), except that if $SHELL is not defined in the
+ environment, $COMSPEC is used. Also, if an environment variable
+ named $MAKESHELL is defined, it takes precedence over both
+ $COMSPEC and $SHELL. Note that, unlike Unix, $SHELL in the
+ environment *is* used to set the shell (since on MSDOS, it's
+ unlikely that the interactive shell will not be suitable for
+ Makefile processing).
+
+ The bottom line is that you can now write Makefiles where some
+ of the targets require a real (i.e. Unix-like) shell, which will
+ nevertheless work when such shell is not available (provided, of
+ course, that the commands which should always work, don't
+ require such a shell). More important, you can convert Unix
+ Makefiles to MSDOS and leave the line which sets the shell
+ intact, so that people who do have Unixy shell could use it for
+ targets which aren't converted to DOS (like 'install' and
+ 'uninstall', for example).
+
+
+ 3. Default directories.
+
+ GNU Make knows about standard directories where it searches for
+ library and include files mentioned in the Makefile. Since
+ MSDOS machines don't have standard places for these, this port
+ will search ${DJDIR}/lib and ${DJDIR}/include respectively.
+ $DJDIR is defined automatically by the DJGPP startup code as the
+ root of the DJGPP installation tree (unless you've tampered with
+ the DJGPP.ENV file). This should provide reasonable default
+ values, unless you moved parts of DJGPP to other directories.
+
+
+ 4. Letter-case in filenames.
+
+ If you run Make on Windows 9x, you should be aware of the
+ letter-case issue. Make is internally case-sensitive, but all
+ file operations are case-insensitive on Windows 9x, so
+ e.g. files 'FAQ', 'faq' and 'Faq' all refer to the same file, as
+ far as Windows is concerned. The underlying DJGPP C library
+ functions honor the letter-case of the filenames they get from
+ the OS, except that by default, they down-case 8+3 DOS filenames
+ which are stored in upper case in the directory and would break
+ many Makefiles otherwise. (The details of which filenames are
+ converted to lower case are explained in the DJGPP libc docs,
+ under the '_preserve_fncase' and '_lfn_gen_short_fname'
+ functions, but as a thumb rule, any filename that is stored in
+ upper case in the directory, is a valid DOS 8+3 filename and
+ doesn't include characters invalid on MSDOS FAT filesystems,
+ will be automatically down-cased.) User reports that I have
+ indicate that this default behavior is generally what you'd
+ expect; however, your input is most welcome.
+
+ In any case, if you hit a situation where you must force Make to
+ get the 8+3 DOS filenames in upper case, set FNCASE=y in the
+ environment or in the Makefile.
+
+
+ 5. DOS-style pathnames.
+
+ There are a lot of places throughout the program sources which
+ make implicit assumptions about the pathname syntax. In
+ particular, the directories are assumed to be separated by '/',
+ and any pathname which doesn't begin with a '/' is assumed to be
+ relative to the current directory. This port attempts to
+ support DOS-style pathnames which might include the drive letter
+ and use backslashes instead of forward slashes. However, this
+ support is not complete; I feel that pursuing this support too
+ far might break some more important features, particularly if
+ you use a Unix-style shell (where a backslash is a quote
+ character). I only consider support of backslashes desirable
+ because some Makefiles invoke non-DJGPP programs which don't
+ understand forward slashes. A notable example of such programs
+ is the standard programs which come with MSDOS. Otherwise, you
+ are advised to stay away from backslashes whenever possible. In
+ particular, filename globbing won't work on pathnames with
+ backslashes, because the GNU 'glob' library doesn't support them
+ (backslash is special in filename wildcards, and I didn't want
+ to break that).
+
+ One feature which *does* work with backslashes is the filename-
+ related built-in functions such as $(dir), $(notdir), etc.
+ Drive letters in pathnames are also fully supported.
+
+
+
+Bug reports:
+-----------
+
+ Bugs that are clearly related to the MSDOS/DJGPP port should be
+ reported first on the comp.os.msdos.djgpp news group (if you cannot
+ post to Usenet groups, write to the DJGPP mailing list,
+ <djgpp@delorie.com>, which is an email gateway into the above news
+ group). For other bugs, please follow the procedure explained in
+ the "Bugs" chapter of the Info docs. If you don't have an Info
+ reader, look up that chapter in the 'make.i1' file with any text
+ browser/editor.
+
+
+ Enjoy,
+ Eli Zaretskii <eliz@is.elta.co.il>
+
+
+-------------------------------------------------------------------------------
+Copyright (C) 1996-2016 Free Software Foundation, Inc.
+This file is part of GNU Make.
+
+GNU Make is free software; you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation; either version 3 of the License, or (at your option) any later
+version.
+
+GNU Make is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <http://www.gnu.org/licenses/>.