1 Overview: -*-text-mode-*-
4 This version of GNU make has been tested on:
5 OpenVMS V8.3/V8.4 (Alpha) and V8.4 (Integrity) AND V7.3 (VAX)
7 This version of GNU Make is intended to be run from DCL to run
8 make scripts with a special syntax that is described below. It
9 likely will not be able to run unmodified Unix makefiles.
11 There is an older implementation of GNU Make that was ported to GNV.
12 Work is now in progress to merge that port to get a single version
13 of GNU Make available. When that merge is done, GNU Make will auto
14 detect that it is running under a Posix shell and then operate as close to
15 GNU Make on Unix as possible.
17 The descriptions below are for running GNU make from DCL or equivalent.
22 GNU Make for OpenVMS can not currently run native Unix make files because of
23 differences in the implementation.
25 I am trying to document the current behavior in this section. This is based
26 on the information in the file NEWS. and running the test suite.
27 TODO: More tests are needed to validate and demonstrate the OpenVMS
30 In some cases the older behavior of GNU Make when run from DCL is not
31 compatible with standard makefile behavior.
33 This behavior can be changed when running GNU Make from DCL by setting
34 either DCL symbols or logical names of the format GNV$. The settings
35 are enabled with a string starting with one of '1', 'T', or 'E' for "1",
36 "TRUE", or "ENABLE". They are disabled with a '0', 'F', or 'D' for "1",
37 "FALSE", or "DISABLE". If they are not explicitly set to one of these
38 values, then they will be set to their default values.
40 The value of the setting DECC$FILENAME_UNIX_REPORT or
41 DECC$FILENAME_UNIX_ONLY will now cause the $(dir x) function to return
42 './' or '[]' as appropriate.
44 The name GNV$MAKE_OLD_VMS when enabled will cause GNU Make to behave as
45 much as the older method as can be done with out disabling VMS features.
46 When it is disabled GNU Make have the new behavior which more closely
47 matches Unix Make behavior.
49 The default is currently the old behavior when running GNU Make from DCL.
50 In the future this may change. When running make from GNV Bash the new
51 behavior is the default.
53 This is a global setting that sets the default behavior for several other
54 options that can be individually changed. Many of the individual settings
55 are to make it so that the self tests for GNU Make need less VMS specific
58 The name GNV$MAKE_COMMA when enabled will cause GNU Make to expect a comma
59 for a path separator and use a comma for the separator for a list of files.
60 When disabled, it will cause GNU Make to use a colon for a path separator
61 and a space for the separator for a list of files. The default is to be
62 enabled if the GNU Make is set to the older behavior.
64 The name GNV$MAKE_SHELL_SIM when enabled will cause GNU Make to try to
65 simulate a Posix shell more closely. The following behaviors occur:
67 * Single quotes are converted to double quotes and any double
68 quotes inside of them are doubled. No environment variable expansion
70 * A exit command status will be converted to a Posix Exit
71 where 0 is success and non-zero is failure.
72 * The $ character will cause environment variable expansion.
73 * Environent variables can be set on the command line before a command.
75 VMS generally uses logical name search lists instead of path variables
76 where the resolution is handled by VMS independent of the program. Which
77 means that it is likely that nothing will notice if the default path
78 specifier is changed in the future.
80 Currently the built in VMS specific macros and recipes depend on the comma
81 being used as a file list separator.
82 TODO: Remove this dependency as other functions in GNU Make depend on a
83 space being used as a separator.
85 The format for recipes are a combination of Unix macros, a subset of
86 simulated UNIX commands, some shell emulation, and OpenVMS commands.
87 This makes the resulting makefiles unique to the OpenVMS port of GNU make.
89 If you are creating a OpenVMS specific makefile from scratch, you should also
90 look at MMK (Madgoat Make) available at https://github.com/endlesssoftware/mmk
91 MMK uses full OpenVMS syntax and a persistent subprocess is used for the
92 recipe lines, allowing multiple line rules.
94 The default makefile search order is "makefile.vms", "gnumakefile",
95 "makefile". TODO: See if that lookup is case sensitive.
97 When Make is invoked from DCL, it will create a foreign command
98 using the name of executable image, with any facility prefix removed,
99 for the duration of the make program, so it can be used internally
100 to recursively run make(). The macro MAKE_COMMAND will be set to
101 this foreign command.
103 When make is launched from an exec*() command from a C program,
104 the foreign command is not created. The macro MAKE_COMMAND will be
105 set to the actual command passed as argv[0] to the exec*() function.
107 If the DCL symbol or logical name GNV$MAKE_USE_MCR exists, then
108 the macro MAKE_COMMAND will be set to be an "MCR" command with the
109 absolute path used by DCL to launch make. The foreign command
112 The macro MAKE is set to be the same value as the macro MAKE_COMMAND
115 Each recipe command is normally run as a separate spawned processes,
116 except for the cases documented below where a temporary DCL command
119 BUG: Testing has shown that the commands in the temporary command files
120 are not always created properly. This issue is still under investigation.
122 Any macros marked as exported are temporarily created as DCL symbols
123 for child images to use. DCL symbol substitution is not done with these
125 Untested: Symbol substitution.
127 When a temporary DCL command file is used, DCL symbol substitution
130 For VMS 7.3-1 and earlier, command lines are limited to 255 characters
131 or 1024 characters in a command file.
132 For VMS 7.3-2 and later, command lines are limited to 4059 characters
133 or 8192 characters in a command file.
135 VMS limits each token of a command line to 256 characters, and limits
136 a command line to 127 tokens.
138 Command lines above the limit length are written to a command file
141 In order to handle Unix style extensions to VMS DCL, GNU Make has
142 parsed the recipe commands and them modified them as needed. The
143 parser has been re-written to resolve numerous bugs in handling
144 valid VMS syntax and potential buffer overruns.
146 The new parser may need whitespace characters where DCL does not require
147 it, and also may require that quotes are matched were DCL forgives if
148 they are not. There is a small chance that existing VMS specific makefiles
151 The '<', '>' was previously implemented using command files. Now
152 GNU Make will check to see if the is already a VMS "PIPE" command and
153 if it is not, will convert the command to a VMS "PIPE" command.
155 The '>>' redirection has been implemented by using a temporary command file.
156 This will be described later.
158 The DCL symbol or logical name GNV$MAKE_USE_CMD_FILE when set to a
159 string starting with one of '1','T', or 'E' for "1", "TRUE", or "ENABLE",
160 then temporary DCL command files are always used for running commands.
162 Some recipe strings with embedded new lines will not be handled correctly
163 when a command file is used.
165 GNU Make generally does text comparisons for the targets and sources. The
166 make program itself can handle either Unix or OpenVMS format filenames, but
167 normally does not do any conversions from one format to another.
168 TODO: The OpenVMS format syntax handling is incomplete.
169 TODO: ODS-5 EFS support is missing.
170 BUG: The internal routines to convert filenames to and from OpenVMS format
171 do not work correctly.
173 Note: In the examples below, line continuations such as a backslash may have
174 been added to make the examples easier to read in this format.
175 BUG: That feature does not completely work at this time.
177 Since the OpenVMS utilities generally expect OpenVMS format paths, you will
178 usually have to use OpenVMS format paths for rules and targets.
179 BUG: Relative OpenVMS paths may not work in targets, especially combined
180 with vpaths. This is because GNU make will just concatenate the directories
183 The variables $^ and $@ separate files with commas instead of spaces.
184 This is controlled by the name GNV$MAKE_COMMA as documented in the
187 While this may seem the natural thing to do with OpenVMS, it actually
188 causes problems when trying to use other make functions that expect the
189 files to be separated by spaces. If you run into this, you need the
190 following workaround to convert the output.
191 TODO: Look at have the $^ and $@ use spaces like on Unix and have
192 and easy to use function to do the conversions and have the built
193 in OpenVMS specific recipes and macros use it.
199 space := $(empty) $(empty)
201 foo: $(addsuffix .3,$(subs $(comma),$(space),$^)
204 Makefile variables are looked up in the current environment. You can set
205 symbols or logicals in DCL and evaluate them in the Makefile via
206 $(<name-of-symbol-or-logical>). Variables defined in the Makefile
207 override OpenVMS symbols/logicals.
209 OpenVMS logical and symbols names show up as "environment" using the
210 origin function. when the "-e" option is specified, the origion function
211 shows them as "environment override". On Posix the test scripts indicate
212 that they should show up just as "environment".
214 When GNU make reads in a symbol or logical name into the environment, it
215 converts any dollar signs found to double dollar signs for convenience in
216 using DCL symbols and logical names in recipes. When GNU make exports a
217 DCL symbol for a child process, if the first dollar sign found is followed
218 by second dollar sign, then all double dollar signs will be convirted to
221 The variable $(ARCH) is predefined as IA64, ALPHA or VAX respectively.
222 Makefiles for different OpenVMS systems can now be written by checking
223 $(ARCH). Since IA64 and ALPHA are similar, usually just a check for
224 VAX or not VAX is sufficient.
226 You may have to update makefiles that assume VAX if not ALPHA.
231 $(ECHO) "On the ALPHA or IA64"
234 Empty commands are handled correctly and don't end in a new DCL process.
236 The exit command needs to have OpenVMS exit codes. To pass a Posix code
237 back to the make script, you need to encode it by multiplying it by 8
238 and then adding %x1035a002 for a failure code and %x1035a001 for a
239 success. Make will interpret any posix code other than 0 as a failure.
240 TODO: Add an option have simulate Posix exit commands in recipes.
242 Lexical functions can be used in pipes to simulate shell file test rules.
247 b : c ; [ -f $@ ] || echo >> $@
250 b : c ; if f$$search("$@") then pipe open/append xx $@ ; write xx "" ; close xx
253 You can also use pipes and turning messages off to silently test for a
259 <tab>pipe set mess/nofac/noiden/nosev/notext ; type $^/output=$@ || exit $(x)
264 The OpenVMS C Runtime has a convention for encoding a Posix exit status into
265 to OpenVMS exit codes. These status codes will have the hex value of
266 0x35a000. OpenVMS exit code may also have a hex value of %x10000000 set on
267 them. This is a flag to tell DCL not to write out the exit code.
269 To convert an OpenVMS encoded Posix exit status code to the original code
270 You subtract %x35a000 and any flags from the OpenVMS code and divide it by 8.
272 WARNING: Backward-incompatibility!
273 The make program exit now returns the same encoded Posix exit code as on
274 Unix. Previous versions returned the OpenVMS exit status code if that is what
275 caused the recipe to fail.
276 TODO: Provide a way for scripts calling make to obtain that OpenVMS status
279 Make internally has two error codes, MAKE_FAILURE and MAKE_TROUBLE. These
280 will have the error "-E-" severity set on exit.
282 MAKE_TROUBLE is returned only if the option "-q" or "--question" is used and
283 has a Posix value of 1 and an OpenVMS status of %x1035a00a.
285 MAKE_FAILURE has a Posix value of 2 and an OpenVMS status of %x1035a012.
287 Output from GNU make may have single quotes around some values where on
288 other platforms it does not. Also output that would be in double quotes
289 on some platforms may show up as single quotes on VMS.
291 There may be extra blank lines in the output on VMS.
292 https://savannah.gnu.org/bugs/?func=detailitem&item_id=41760
294 There may be a "Waiting for unfinished jobs..." show up in the output.
296 Error messages generated by Make or Unix utilities may slightly vary from
297 Posix platforms. Typically the case may be different.
299 When make deletes files, on posix platforms it writes out 'rm' and the list
300 of files. On VMS, only the files are writen out, one per line.
303 There may be extra leading white space or additional or missing whitespace
304 in the output of recipes.
306 GNU Make uses sys$scratch: for the tempfiles that it creates.
308 The OpenVMS CRTL library maps /tmp to sys$scratch if the TMP: logical name
309 does not exist. As the CRTL may use both sys$scratch: and /tmp internally,
310 if you define the TMP logical name to be different than SYS$SCRATCH:,
311 you may end up with only some temporary files in TMP: and some in SYS$SCRATCH:
313 The default include directory for including other makefiles is
314 SYS$SYSROOT:[SYSLIB] (I don't remember why I didn't just use
315 SYS$LIBRARY: instead; maybe it wouldn't work that way).
316 TODO: A better default may be desired.
318 If the device for a file in a recipe does not exist, on OpenVMS an error
319 message of "stat: <file>: no such device or address" will be output.
321 Make ignores success, informational, or warning errors (-S-, -I-, or
322 -W-). But it will stop on -E- and -F- errors. (unless you do something
323 to override this in your makefile, or whatever).
326 Unix compatibilty features:
327 ---------------------------
329 If the command 'echo' is seen, any single quotes on the line will be
330 converted to double quotes.
332 The variable $(CD) is implemented as a built in Change Directory
333 command. This invokes the 'builtin_cd' Executing a 'set default'
334 recipe doesn't do the trick, since it only affects the subprocess
335 spawned for that command.
337 The 'builtin_cd' is generally expected to be on its own line.
338 The 'builtin_cd' either from the expansion of $(CD) or directly
339 put in a recipe line will be executed before any other commands in
340 that recipe line. DCL parameter substitution will not work for the
341 'builtin_cd' command.
343 Putting a 'builtin_cd' in a pipeline or an IF-THEN line should not be
344 done because the 'builtin_cd' is always executed
345 and executed first. The directory change is persistent.
347 Unix shell style I/O redirection is supported. You can now write lines like:
348 "<tab>mcr sys$disk:[]program.exe < input.txt > output.txt &> error.txt"
350 Posix shells have ":" as a null command. These are now handled.
351 https://savannah.gnu.org/bugs/index.php?41761
353 A note on appending the redirected output. A simple mechanism is
354 implemented to make ">>" work in action lines. In OpenVMS there is no simple
355 feature like ">>" to have DCL command or program output redirected and
356 appended to a file. GNU make for OpenVMS implements the redirection
357 of ">>" by using a command procedure.
359 The current algorithm creates the output file if it does not exist and
360 then uses the DCL open/append to extend it. SYS$OUTPUT is then directed
363 The implementation supports only one redirected append output to a file
364 and that redirection is done before any other commands in that line
365 are executed, so it redirects all output for that command.
367 The older implementation wrote the output to a temporary file in
368 in sys$scratch: and then attempted to append the file to the existing file.
369 The temporary file names looked like "CMDxxxxx.". Any time the created
370 command procedure can not complete, this happens. Pressing Ctrl+Y to
371 abort make is one case.
373 In case of Ctrl+Y the associated command procedure is left in SYS$SCRATCH:.
374 The command procedures will be named gnv$make_cmd*.com.
376 The CtrlY handler now uses $delprc to delete all children. This way also
377 actions with DCL commands will be stopped. As before the CtrlY handler
378 then sends SIGQUIT to itself, which is handled in common code.
380 Temporary command files are now deleted in the OpenVMS child termination
381 handler. That deletes them even if a Ctrl+C was pressed.
382 TODO: Does the previous section about >> leaving files still apply?
384 The behavior of pressing Ctrl+C is not changed. It still has only an effect,
385 after the current action is terminated. If that doesn't happen or takes too
386 long, Ctrl+Y should be used instead.
391 Added support to have case sensitive targets and dependencies but to
392 still use case blind file names. This is especially useful for Java
396 <TAB>.SUFFIXES : .class .java
399 <TAB>HelloWorld.class : HelloWorld.java
401 A new macro WANT_CASE_SENSITIVE_TARGETS in config.h-vms was introduced.
402 It needs to be enabled to get this feature; default is disabled.
403 TODO: This should be a run-time setting based on if the process
404 has been set to case sensitive.
407 Unimplemented functionality:
409 The new feature "Loadable objects" is not yet supported. If you need it,
410 please send a change request or submit a bug report.
412 The new option --output-sync (-O) is accepted but has no effect: GNU make
413 for OpenVMS does not support running multiple commands simultaneously.
416 Self test failures and todos:
417 -----------------------------
419 The test harness can not handle testing some of the VMS specific modes
420 because of the features needed for to be set for the Perl to run.
421 Need to find a way to set the VMS features before running make as a
424 GNU make was not currently translating the OpenVMS encoded POSIX values
425 returned to it back to the Posix values. I have temporarily modified the
426 Perl test script to compensate for it. This should be being handled
428 TODO: Verify and update the Perl test script.
430 The features/parallelism test was failing. OpenVMS is executing the rules
431 in sequence not in parallel as this feature was not implemented.
432 GNU Make on VMS no longer claims it is implemented.
435 Symlink support is not present. Symlinks are supported by OpenVMS 8.3 and
438 Error messages should be supressed with the "-" at the beginning of a line.
439 On openVMS they were showing up. TODO: Is this still an issue?
441 The internal vmsify and unixify OpenVMS to/from UNIX are not handling logical
448 Don't use the HP C V7.2-001 compiler, which has an incompatible change
449 how __STDC__ is defined. This results at least in compile time warnings.
452 $ @makefile.com ! ignore any compiler and/or linker warning
453 $ copy make.exe 1st-make.exe
455 Use the 1st version to generate a 2nd version as a test.
456 $ mc sys$disk:[]1st-make clean ! ignore any file not found messages
457 $ mc sys$disk:[]1st-make
459 Verify your 2nd version by building Make again.
460 $ copy make.exe 2nd-make.exe
461 $ mc sys$disk:[]2nd-make clean
462 $ mc sys$disk:[]2nd-make
468 Running the tests on OpenVMS requires the following software to be installed
469 as most of the tests are Unix oriented.
471 * Perl 5.18 or later.
472 https://sourceforge.net/projects/vmsperlkit/files/
473 * GNV 2.1.3 + Updates including a minimum of:
477 https://sourceforge.net/p/gnv/wiki/InstallingGNVPackages/
478 https://sourceforge.net/projects/gnv/files/
480 As the test scripts need to create some foreign commands that persist
481 after the test is run, it is recommend that either you use a subprocess or
482 a dedicated login to run the tests.
484 To get detailed information for running the tests:
486 $ set default [.tests]
487 $ @run_make_tests help
489 Running the script with no parameters will run all the tests.
491 After the the test script has been run once in a session, assuming
492 that you built make in sys$disk:[make], you can redefined the
493 "bin" logical name as follows:
495 $ define bin sys$disk:[make],gnv$gnu:[bin]
497 Then you can use Perl to run the scripts.
499 $ perl run_make_tests.pl
505 See NEWS. for details of past changes.
507 These are the currently known contributers to this port.