home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / watc11up.zip / core_hlp_os2.zip / binp / help / tools.inf (.txt) < prev   
OS/2 Help File  |  2001-08-28  |  204KB  |  6,951 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. The Watcom C/C++ Compile and Link Utility ΓòÉΓòÉΓòÉ
  3.  
  4.  
  5. The Watcom C/C++ Compile and Link Utility is designed for generating 
  6. applications, simply and quickly, using a single command line.  On the command 
  7. line, you can list source file names as well as object file names.  Source 
  8. files are either compiled or assembled based on file extension; object files 
  9. and libraries are simply included in the link phase.  Options can be passed on 
  10. to both the compiler and linker. 
  11.  
  12.  
  13. ΓòÉΓòÉΓòÉ 1.1. WCL/WCL386 Command Line Format ΓòÉΓòÉΓòÉ
  14.  
  15.  
  16. The format of the command line is: 
  17.  
  18.  
  19.    WCL [files] [options] 
  20.    WCL386 [files] [options] 
  21.  
  22. The square brackets [ ] denote items which are optional. 
  23.  
  24.  WCL 
  25.       is the name of the Watcom Compile and Link utility that invokes the 
  26.       16-bit compiler. 
  27.  
  28.  WCL386 
  29.       is the name of the Watcom Compile and Link utility that invokes the 
  30.       32-bit compiler. 
  31.  
  32.  The files and options may be specified in any order.  The Watcom Compile and 
  33.  Link utility uses the extension of the file name to determine if it is a 
  34.  source file, an object file, or a library file.  Files with extensions of 
  35.  "OBJ" and "LIB" are assumed to be object files and library files respectively. 
  36.  Files with extensions of "ASM" are assumed to be assembler source files and 
  37.  will be assembled by the Watcom Assembler.  Files with any other extension, 
  38.  including none at all, are assumed to be C/C++ source files and will be 
  39.  compiled.  Pattern matching characters ("*" and "?") may be used in the file 
  40.  specifications. 
  41.  
  42.  If no file extension is specified for a file name then the Watcom Compile and 
  43.  Link utility will check for a file with one of the following extensions. 
  44.  
  45.  
  46.     Order  Name.Ext     Assumed to be 
  47.     -----  --------     --------------- 
  48.      1.   file.ASM     Assembler source code 
  49.      2.   file.CXX     C++ source code 
  50.      3.   file.CPP     C++ source code 
  51.      4.   file.CC     C++ source code 
  52.      5.   file.C      C  source code 
  53.  
  54.  It checks for each file in the order listed.  By default, the Watcom Assembler 
  55.  will be selected to compile files with the extension "ASM".  By default, the 
  56.  Watcom C++ compiler will be selected to compile files with any of the 
  57.  extensions "CXX", "CPP" or "CC".  By default, the Watcom C compiler will be 
  58.  selected to compile a file with a "C" extension.  The default selection of 
  59.  compiler can be overridden by the "cc" and "cc++" options, described below. 
  60.  
  61.  Options are prefixed with a slash (/) or a dash (-) and may be specified in 
  62.  any order.  Options can include any of the Watcom C/C++ compiler options plus 
  63.  some additional options specific to the Watcom Compile and Link utility.  A 
  64.  summary of options is displayed on the screen by simply entering the "WCL" or 
  65.  "WCL386" command with no arguments. 
  66.  
  67.  
  68. ΓòÉΓòÉΓòÉ 1.2. Watcom Compile and Link Options Summary ΓòÉΓòÉΓòÉ
  69.  
  70.  c 
  71.       compile the files only, do not link them 
  72.  
  73.  cc 
  74.       treat source files as C code 
  75.  
  76.  cc++ 
  77.       treat source files as C++ code 
  78.  
  79.  y 
  80.       ignore the WCL/WCL386 environment variable 
  81.  
  82.  0 
  83.       (16-bit only) 8088 and 8086 instructions (default for 16-bit) 
  84.  
  85.  1 
  86.       (16-bit only) 188 and 186 instructions 
  87.  
  88.  2 
  89.       (16-bit only) 286 instructions 
  90.  
  91.  3 
  92.       (16-bit only) 386 instructions 
  93.  
  94.  4 
  95.       (16-bit only) 486 instructions 
  96.  
  97.  5 
  98.       (16-bit only) Pentium instructions 
  99.  
  100.  6 
  101.       (16-bit only) Pentium Pro instructions 
  102.  
  103.  3r 
  104.       (32-bit only) generate 386 instructions based on 386 instruction timings 
  105.       and use register-based argument passing conventions 
  106.  
  107.  3s 
  108.       (32-bit only) generate 386 instructions based on 386 instruction timings 
  109.       and use stack-based argument passing conventions 
  110.  
  111.  4r 
  112.       (32-bit only) generate 386 instructions based on 486 instruction timings 
  113.       and use register-based argument passing conventions 
  114.  
  115.  4s 
  116.       (32-bit only) generate 386 instructions based on 486 instruction timings 
  117.       and use stack-based argument passing conventions 
  118.  
  119.  5r 
  120.       (32-bit only) generate 386 instructions based on Intel Pentium 
  121.       instruction timings and use register-based argument passing conventions 
  122.       (default for 32-bit) 
  123.  
  124.  5s 
  125.       (32-bit only) generate 386 instructions based on Intel Pentium 
  126.       instruction timings and use stack-based argument passing conventions 
  127.  
  128.  6r 
  129.       (32-bit only) generate 386 instructions based on Intel Pentium Pro 
  130.       instruction timings and use register-based argument passing conventions 
  131.  
  132.  6s 
  133.       (32-bit only) generate 386 instructions based on Intel Pentium Pro 
  134.       instruction timings and use stack-based argument passing conventions 
  135.  
  136.  bc 
  137.       (C++ only) build target is a console application 
  138.  
  139.  bd 
  140.       build target is a Dynamic Link Library (DLL) 
  141.  
  142.  bg 
  143.       (C++ only) build target is a GUI application 
  144.  
  145.  bm 
  146.       build target is a multi-thread environment 
  147.  
  148.  br 
  149.       build target uses DLL version of C/C++ run-time libraries 
  150.  
  151.  bt[=<os>] 
  152.       build target for operating system <os> 
  153.  
  154.  bw 
  155.       build target uses default windowing support 
  156.  
  157.  d0 
  158.       (C++ only) no debugging information 
  159.  
  160.  d1 
  161.       line number debugging information 
  162.  
  163.  d1+ 
  164.       (C only) line number debugging information plus typing information for 
  165.       global symbols and local structs and arrays 
  166.  
  167.  d2 
  168.       full symbolic debugging information 
  169.  
  170.  d2i 
  171.       (C++ only) d2 and debug inlines; emit inlines as external out-of-line 
  172.       functions 
  173.  
  174.  d2s 
  175.       (C++ only) d2 and debug inlines; emit inlines as static out-of-line 
  176.       functions 
  177.  
  178.  d2t 
  179.       (C++ only) full symbolic debugging information, without type names 
  180.  
  181.  d3 
  182.       full symbolic debugging with unreferenced type names ,* 
  183.  
  184.  d3i 
  185.       (C++ only) d3 plus debug inlines; emit inlines as external out-of-line 
  186.       functions 
  187.  
  188.  d3s 
  189.       (C++ only) d3 plus debug inlines; emit inlines as static out-of-line 
  190.       functions 
  191.  
  192.  d<name>[=text] 
  193.       preprocessor #define name [text] 
  194.  
  195.  d+ 
  196.       allow extended -d macro definitions 
  197.  
  198.  db 
  199.       generate browsing information 
  200.  
  201.  e<number> 
  202.       set error limit number (default is 20) 
  203.  
  204.  ee 
  205.       call epilogue hook routine 
  206.  
  207.  ef 
  208.       use full path names in error messages 
  209.  
  210.  ei 
  211.       force enum base type to use at least an int 
  212.  
  213.  em 
  214.       force enum base type to use minimum 
  215.  
  216.  en 
  217.       emit routine name before prologue 
  218.  
  219.  ep[<number>] 
  220.       call prologue hook routine with number of stack bytes available 
  221.  
  222.  eq 
  223.       do not display error messages (they are still written to a file) 
  224.  
  225.  er 
  226.       (C++ only) do not recover from undefined symbol errors 
  227.  
  228.  et 
  229.       Pentium profiling 
  230.  
  231.  ew 
  232.       (C++ only) generate less verbose messages 
  233.  
  234.  ez 
  235.       (32-bit only) generate Phar Lap Easy OMF-386 object file 
  236.  
  237.  fc=<file_name> 
  238.       (C++ only) specify file of command lines to be batch processed 
  239.  
  240.  fh[q][=<file_name>] 
  241.       use precompiled headers 
  242.  
  243.  fhd 
  244.       store debug info for pre-compiled header once (DWARF only) 
  245.  
  246.  fhr 
  247.       (C++ only) force compiler to read pre-compiled header 
  248.  
  249.  fhw 
  250.       (C++ only) force compiler to write pre-compiled header 
  251.  
  252.  fhwe 
  253.       (C++ only) don't include pre-compiled header warnings when "we" is used 
  254.  
  255.  fi=<file_name> 
  256.       force file_name to be included 
  257.  
  258.  fo=<file_name> 
  259.       set object or preprocessor output file specification 
  260.  
  261.  fpc 
  262.       generate calls to floating-point library 
  263.  
  264.  fpi 
  265.       (16-bit only) generate in-line 80x87 instructions with emulation 
  266.       (default) 
  267.  
  268.       (32-bit only) generate in-line 387 instructions with emulation (default) 
  269.  
  270.  fpi87 
  271.       (16-bit only) generate in-line 80x87 instructions 
  272.  
  273.       (32-bit only) generate in-line 387 instructions 
  274.  
  275.  fp2 
  276.       generate in-line 80x87 instructions 
  277.  
  278.  fp3 
  279.       generate in-line 387 instructions 
  280.  
  281.  fp5 
  282.       generate in-line 80x87 instructions optimized for Pentium processor 
  283.  
  284.  fp6 
  285.       generate in-line 80x87 instructions optimized for Pentium Pro processor 
  286.  
  287.  fpd 
  288.       enable generation of Pentium FDIV bug check code 
  289.  
  290.  fpr 
  291.       generate 8087 code compatible with older versions of compiler 
  292.  
  293.  fr=<file_name> 
  294.       set error file specification 
  295.  
  296.  ft 
  297.       (C++ only) try truncated (8.3) header file specification 
  298.  
  299.  fx 
  300.       (C++ only) do not try truncated (8.3) header file specification 
  301.  
  302.  g=<codegroup> 
  303.       set code group name 
  304.  
  305.  h{w,d,c} 
  306.       set debug output format (Watcom, Dwarf, Codeview) 
  307.  
  308.  i=<directory> 
  309.       add directory to list of include directories 
  310.  
  311.  j 
  312.       change char default from unsigned to signed 
  313.  
  314.  k 
  315.       (C++ only) continue processing files (ignore errors) 
  316.  
  317.  m{f,s,m,c,l,h} 
  318.       memory model - mf=flat ms=small mm=medium mc=compact ml=large mh=huge 
  319.       (default is "ms" for 16-bit and Netware, "mf" for 32-bit) 
  320.  
  321.  nc=<name> 
  322.       set name of the code class 
  323.  
  324.  nd=<name> 
  325.       set name of the "data" segment 
  326.  
  327.  nm=<name> 
  328.       set module name different from filename 
  329.  
  330.  nt=<name> 
  331.       set name of the "text" segment 
  332.  
  333.  o{a,b,c,d,e,f,f+,h,i,i+,k,l,l+,m,n,o,p,r,s,t,u,x,z} 
  334.       control optimization 
  335.  
  336.  p{e,l,c,w=<num>} 
  337.       preprocess file only, sending output to standard output; "c" include 
  338.       comments; "e" encrypt identifiers (C++ only); "l" include #line 
  339.       directives; w=<num> wrap output lines at <num> columns (zero means no 
  340.       wrap) 
  341.  
  342.  r 
  343.       save/restore segment registers 
  344.  
  345.  ri 
  346.       return chars and shorts as ints 
  347.  
  348.  s 
  349.       remove stack overflow checks 
  350.  
  351.  sg 
  352.       generate calls to grow the stack 
  353.  
  354.  st 
  355.       touch stack through SS first 
  356.  
  357.  t=<num> 
  358.       (C++ only) set tab stop multiplier 
  359.  
  360.  u<name> 
  361.       preprocessor #undef name 
  362.  
  363.  v 
  364.       output function declarations to .def file (with typedef names) 
  365.  
  366.  vc... 
  367.       (C++ only) VC++ compatibility options 
  368.  
  369.  w<number> 
  370.       set warning level number (default is w1) 
  371.  
  372.  wcd=<num> 
  373.       warning control:  disable warning message <num> 
  374.  
  375.  wce=<num> 
  376.       warning control:  enable warning message <num> 
  377.  
  378.  we 
  379.       treat all warnings as errors 
  380.  
  381.  wo 
  382.       (C only) (16-bit only) warn about problems with overlaid code 
  383.  
  384.  wx 
  385.       set warning level to maximum setting 
  386.  
  387.  xd 
  388.       (C++ only) disable exception handling (default) 
  389.  
  390.  xdt 
  391.       (C++ only) disable exception handling (same as "xd") 
  392.  
  393.  xds 
  394.       (C++ only) disable exception handling (table-driven destructors) 
  395.  
  396.  xr 
  397.       (C++ only) enable RTTI 
  398.  
  399.  xs 
  400.       (C++ only) enable exception handling 
  401.  
  402.  xst 
  403.       (C++ only) enable exception handling (direct calls for destruction) 
  404.  
  405.  xss 
  406.       (C++ only) enable exception handling (table-driven destructors) 
  407.  
  408.  z{a,e} 
  409.       disable/enable language extensions (default is ze) 
  410.  
  411.  zc 
  412.       place literal strings in code segment 
  413.  
  414.  zd{f,p} 
  415.       allow DS register to "float" or "peg" it to DGROUP (default is zdp) 
  416.  
  417.  zdl 
  418.       (32-bit only) load DS register directly from DGROUP 
  419.  
  420.  zf{f,p} 
  421.       allow FS register to be used (default for all but flat memory model) or 
  422.       not be used (default for flat memory model) 
  423.  
  424.  zg 
  425.       output function declarations to .def (without typedef names) 
  426.  
  427.  zg{f,p} 
  428.       allow GS register to be used or not used 
  429.  
  430.  zk0 
  431.       double-byte char support for Kanji 
  432.  
  433.  zk0u 
  434.       translate Kanji double-byte characters to UNICODE 
  435.  
  436.  zk1 
  437.       double-byte char support for Chinese/Taiwanese 
  438.  
  439.  zk2 
  440.       double-byte char support for Korean 
  441.  
  442.  zkl 
  443.       double-byte char support if current code page has lead bytes 
  444.  
  445.  zku=<codepage> 
  446.       load UNICODE translate table for specified code page 
  447.  
  448.  zl 
  449.       suppress generation of library file names and references in object file 
  450.  
  451.  zld 
  452.       suppress generation of file dependency information in object file 
  453.  
  454.  zm 
  455.       place each function in separate segment (near functions not allowed) 
  456.  
  457.  zmf 
  458.       place each function in separate segment (near functions allowed) 
  459.  
  460.  zp[{1,2,4,8,16}] 
  461.       set minimal structure packing (member alignment) (default is zp1) 
  462.  
  463.  zpw 
  464.       output warning when padding is added in a struct/class 
  465.  
  466.  zq 
  467.       operate quietly 
  468.  
  469.  zs 
  470.       syntax check only 
  471.  
  472.  zt<number> 
  473.       set data threshold (default is zt32767) 
  474.  
  475.  zu 
  476.       do not assume that SS contains segment of DGROUP 
  477.  
  478.  zv 
  479.       (C++ only) enable virtual function removal optimization 
  480.  
  481.  zw 
  482.       Microsoft Windows prologue/epilogue code sequences 
  483.  
  484.  zW 
  485.       (16-bit only) Microsoft Windows optimized prologue/epilogue code 
  486.       sequences 
  487.  
  488.  zWs 
  489.       (16-bit only) Microsoft Windows smart callback sequences 
  490.  
  491.  zz 
  492.       remove "@size" from __stdcall function names (10.0 compatible) 
  493.  
  494.  See the Watcom C/C++ User's Guide for a full description of compiler options. 
  495.  
  496.  k<stack_size> 
  497.       set stack size 
  498.  
  499.  fd[=<directive_file>] 
  500.       keep directive file and, optionally, rename it (default name is 
  501.       "__WCL__.LNK"). 
  502.  
  503.  fe=<executable> 
  504.       name executable file 
  505.  
  506.  fm[=<map_file>] 
  507.       generate map file and name it (optional) 
  508.  
  509.  lp 
  510.       (16-bit only) create an OS/2 protected-mode program 
  511.  
  512.  lr 
  513.       (16-bit only) create a DOS real-mode program 
  514.  
  515.  l=<system_name> 
  516.       link a program for the specified system.  Among the supported systems 
  517.       are: 
  518.  
  519.       286 
  520.                 16-bit DOS executables (synonym for "DOS") under DOS and NT 
  521.                 hosted platforms; 16-bit OS/2 executables (synonym for "OS2") 
  522.                 under 32-bit OS/2 hosted OS/2 session. 
  523.  
  524.       386 
  525.                 32-bit DOS executables (synonym for "DOS4G") under DOS; 32-bit 
  526.                 NT character-mode executables (synonym for "NT") under Windows 
  527.                 NT; 32-bit OS/2 executables (synonym for "OS2V2") under 32-bit 
  528.                 OS/2 hosted OS/2 session. 
  529.  
  530.       ADS 
  531.                 32-bit AutoCAD ADS executables 
  532.  
  533.       COM 
  534.                 16-bit DOS "COM" files 
  535.  
  536.       DOS 
  537.                 16-bit DOS executables 
  538.  
  539.       DOS4G 
  540.                 32-bit Tenberry Software DOS Extender executables 
  541.  
  542.       DOS4GNZ 
  543.                 32-bit Tenberry Software DOS Extender non-zero base executables 
  544.  
  545.       EADI 
  546.                 32-bit AutoCAD ADI executables (emulation) 
  547.  
  548.       FADI 
  549.                 32-bit AutoCAD ADI executables (floating-point) 
  550.  
  551.       NETWARE 
  552.                 32-bit Novell NetWare 386 NLMs 
  553.  
  554.       NOVELL 
  555.                 32-bit Novell NetWare 386 NLMs (synonym for NETWARE) 
  556.  
  557.       NT 
  558.                 32-bit Windows NT character-mode executables 
  559.  
  560.       NT_DLL 
  561.                 32-bit Windows NT DLLs 
  562.  
  563.       NT_WIN 
  564.                 32-bit Windows NT windowed executables 
  565.  
  566.       OS2 
  567.                 16-bit OS/2 V1.x executables 
  568.  
  569.       OS2V2 
  570.                 32-bit OS/2 executables 
  571.  
  572.       OS2V2_PM 
  573.                 32-bit OS/2 PM executables 
  574.  
  575.       PHARLAP 
  576.                 32-bit PharLap DOS Extender executables 
  577.  
  578.       QNX 
  579.                 16-bit QNX executables 
  580.  
  581.       QNX386 
  582.                 32-bit QNX executables 
  583.  
  584.       TNT 
  585.                 32-bit Phar Lap TNT DOS-style executable 
  586.  
  587.       WIN386 
  588.                 32-bit extended Windows 3.x executables/DLLs 
  589.  
  590.       WIN95 
  591.                 32-bit Windows 95 executables/DLLs 
  592.  
  593.       WINDOWS 
  594.                 16-bit Windows executables 
  595.  
  596.       WINDOWS_DLL 
  597.                 16-bit Windows Dynamic Link Libraries 
  598.  
  599.       X32R 
  600.                 32-bit FlashTek (register calling convention) executables 
  601.  
  602.       X32RV 
  603.                 32-bit FlashTek Virtual Memory (register calling convention) 
  604.                 executables 
  605.  
  606.       X32S 
  607.                 32-bit FlashTek (stack calling convention) executables 
  608.  
  609.       X32SV 
  610.                 32-bit FlashTek Virtual Memory (stack calling convention) 
  611.                 executables 
  612.       These names are among the systems identified in the Watcom Linker 
  613.       initialization file, "WLSYSTEM.LNK".  The Watcom Linker "SYSTEM" 
  614.       directives, found in this file, are used to specify default link options 
  615.       for particular (operating) systems.  Users can augment the Watcom Linker 
  616.       initialization file with their own system definitions and these may be 
  617.       specified as an argument to the "l=" option.  The "system_name" specified 
  618.       in the "l=" option is used to create a "SYSTEM system_name" Watcom Linker 
  619.       directive when linking the application. 
  620.  
  621.  x 
  622.       make names case sensitive 
  623.  
  624.  @<directive_file> 
  625.       include additional directive file 
  626.  
  627.  "linker directives" 
  628.       allows use of any linker directive 
  629.  
  630.  
  631. ΓòÉΓòÉΓòÉ 1.3. WCL/WCL386 Environment Variables ΓòÉΓòÉΓòÉ
  632.  
  633.  
  634. The WCL environment variable can be used to specify commonly used WCL options. 
  635. The WCL386 environment variable can be used to specify commonly used WCL386 
  636. options.  These options are processed before options specified on the command 
  637. line. 
  638.  
  639. Example: 
  640.  
  641.    C>set wcl=/d1 /ot 
  642.  
  643.    C>set wcl386=/d1 /ot 
  644.  
  645. The above example defines the default options to be "d1" (include line number 
  646. debugging information in the object file), and "ot" (favour time optimizations 
  647. over size optimizations). 
  648.  
  649. Whenever you wish to specify an option that requires the use of an "=" 
  650. character, you can use the "#" character in its place.  This is required by the 
  651. syntax of the "SET" command. 
  652.  
  653. Once the appropriate environment variable has been defined, those options 
  654. listed become the default each time the WCL or WCL386 command is used. 
  655.  
  656. The WCL environment variable is used by WCL only.  The WCL386 environment 
  657. variable is used by WCL386 only.  Both WCL and WCL386 pass the relevant options 
  658. to the Watcom C/C++ compiler and linker.  This environment variable is not 
  659. examined by the Watcom C/C++ compiler or the linker when invoked directly. 
  660.  
  661. Hint:  If you are running DOS and you use the same WCL or WCL386 options all 
  662. the time, you may find it handy to place the "SET WCL" or "SET WCL386" command 
  663. in your DOS system initialization file, AUTOEXEC.BAT.  If you are running OS/2 
  664. and you use the same WCL or WCL386 options all the time, you may find it handy 
  665. to place the "SET WCL" or "SET WCL386" command in your OS/2 system 
  666. initialization file, CONFIG.SYS. 
  667.  
  668.  
  669. ΓòÉΓòÉΓòÉ 1.4. WCL/WCL386 Command Line Examples ΓòÉΓòÉΓòÉ
  670.  
  671.  
  672. For most small applications, the WCL or WCL386 command will suffice.  We have 
  673. only scratched the surface in describing the capabilities of the WCL and WCL386 
  674. commands.  The following examples describe the WCL and WCL386 commands in more 
  675. detail. 
  676.  
  677. Suppose that your application is contained in three files called APDEMO.C, 
  678. APUTILS.C, and APDATA.C.  We can compile and link all three files with one 
  679. command. 
  680.  
  681. Example 1: 
  682.  
  683.    C>wcl /d2 apdemo.c aputils.c apdata.c 
  684.    C>wcl386 /d2 apdemo.c aputils.c apdata.c 
  685.  
  686. The executable program will be stored in APDEMO.EXE since APDEMO appeared first 
  687. in the list.  Each of the three files is compiled with the "d2" debug option. 
  688. Debugging information is included in the executable file. 
  689.  
  690. We can issue a simpler command if the current directory contains only our three 
  691. C/C++ source files. 
  692.  
  693. Example 2: 
  694.  
  695.    C>wcl /d2 *.c 
  696.    C>wcl386 /d2 *.c 
  697.  
  698. WCL or WCL386 will locate all files with the ".c" filename extension and 
  699. compile each of them.  The name of the executable file will depend on which of 
  700. the C/C++ source files is found first.  Since this is a somewhat haphazard 
  701. approach to naming the executable file, WCL and WCL386 have an option, "fe", 
  702. which will allow you to specify the name to be used. 
  703.  
  704. Example 3: 
  705.  
  706.    C>wcl /d2 /fe=apdemo *.c 
  707.    C>wcl386 /d2 /fe=apdemo *.c 
  708.  
  709. By using the "fe" option, the executable file will always be called APDEMO.EXE 
  710. regardless of the order of the C/C++ source files in the directory. 
  711.  
  712. If the directory contains other C/C++ source files which are not part of the 
  713. application then other tricks may be used to identify a subset of the files to 
  714. be compiled and linked. 
  715.  
  716. Example 4: 
  717.  
  718.    C>wcl /d2 /fe=apdemo ap*.c 
  719.    C>wcl386 /d2 /fe=apdemo ap*.c 
  720.  
  721. Here we compile only those C/C++ source files that begin with the letters "ap". 
  722.  
  723. In our examples, we have recompiled all the source files each time.  In 
  724. general, we will only compile one of them and include the object code for the 
  725. others. 
  726.  
  727. Example 5: 
  728.  
  729.    C>wcl /d2 /fe=apdemo aputils.c ap*.obj 
  730.    C>wcl386 /d2 /fe=apdemo aputils.c ap*.obj 
  731.  
  732. The source file APUTILS.C is recompiled and APDEMO.OBJ and APDATA.OBJ are 
  733. included when linking the application.  The ".obj" filename extension indicates 
  734. that this file need not be compiled. 
  735.  
  736. Example 6: 
  737.  
  738.    C>wcl /fe=demo *.c utility.obj 
  739.    C>wcl386 /fe=demo *.c utility.obj 
  740.  
  741. All of the C/C++ source files in the current directory are compiled and then 
  742. linked with UTILITY.OBJ to generate DEMO.EXE. 
  743.  
  744. Example 7: 
  745.  
  746.    C>set wcl=/mm /d1 /ox /k4096 
  747.    C>wcl /fe=grdemo gr*.c graph.lib /fd=grdemo 
  748.  
  749.    C>set wcl386=/d1 /ox /k4096 
  750.    C>wcl386 /fe=grdemo gr*.c graph.lib /fd=grdemo 
  751.  
  752. All C/C++ source files beginning with the letters "gr" are compiled and then 
  753. linked with GRAPH.LIB to generate GRDEMO.EXE which uses a 4K stack.  The 
  754. temporary linker directive file that is created by WCL or WCL386 will be kept 
  755. and renamed to GRDEMO.LNK. 
  756.  
  757. Example 8: 
  758.  
  759.    C>set libos2=c:\watcom\lib286\os2;c:\os2 
  760.    C>set lib=c:\watcom\lib286\dos;c:\watcom\lib286 
  761.    C>set wcl=/mm /lp 
  762.    C>wcl grdemo1 \watcom\lib286\os2\graphp.obj phapi.lib 
  763.  
  764. The file GRDEMO1 is compiled for the medium memory model and then linked with 
  765. GRAPHP.OBJ and PHAPI.LIB to generate GRDEMO1.EXE which is to be used with Phar 
  766. Lap's 286 DOS Extender.  The "lp" option indicates that an OS/2 format 
  767. executable is to be created.  The file GRAPHP.OBJ in the directory 
  768. "\WATCOM\LIB286\OS2" contains special initialization code for Phar Lap's 286 
  769. DOS Extender.  The file PHAPI.LIB is part of the Phar Lap 286 DOS Extender 
  770. package.  The LIBOS2 environment variable must include the location of the OS/2 
  771. libraries and the LIB environment variable must include the location of the DOS 
  772. libraries (in order to locate GRAPH.LIB).  The LIBOS2 environment variable must 
  773. also include the location of the OS/2 file DOSCALLS.LIB which is usually 
  774. "C:\OS2". 
  775.  
  776. For more complex applications, you should use the "Make" utility. 
  777.  
  778.  
  779. ΓòÉΓòÉΓòÉ 2. The Watcom Assembler ΓòÉΓòÉΓòÉ
  780.  
  781.  
  782.  
  783. This chapter describes the Watcom Assembler.  It takes as input an assembler 
  784. source file (a file with extension ".asm") and produces, as output, an object 
  785. file. 
  786.  
  787. The Watcom Assembler command line syntax is the following. 
  788.  
  789.  
  790.    WASM [options] [d:][path]filename[.ext] [options] [@env_var] 
  791.  
  792. The square brackets [ ] denote items which are optional. 
  793.  
  794.  WASM 
  795.       is the name of the Watcom Assembler. 
  796.  
  797.  d: 
  798.       is an optional drive specification such as "A:", "B:", etc.  If not 
  799.       specified, the default drive is assumed. 
  800.  
  801.  path 
  802.       is an optional path specification such as "\PROGRAMS\ASM\".  If not 
  803.       specified, the current directory is assumed. 
  804.  
  805.  filename 
  806.       is the file name of the assembler source file to be assembled. 
  807.  
  808.  ext 
  809.       is the file extension of the assembler source file to be assembled.  If 
  810.       omitted, a file extension of ".asm" is assumed.  If the period "." is 
  811.       specified but not the extension, the file is assumed to have no file 
  812.       extension. 
  813.  
  814.  options 
  815.       is a list of valid options, each preceded by a slash ("/") or a dash 
  816.       ("-").  Options may be specified in any order. 
  817.  
  818.  The options supported by the Watcom Assembler are: 
  819.  
  820.  {0,1,2,3,4,5}{p}{r,s} 
  821.  
  822.       0 
  823.                 same as ".8086" 
  824.  
  825.       1 
  826.                 same as ".186" 
  827.  
  828.       2{p} 
  829.                 same as ".286" or ".286p" 
  830.  
  831.       3{p} 
  832.                 same as ".386" or ".386p" (also defines "__386__" and changes 
  833.                 the default USE attribute of segments from "USE16" to "USE32") 
  834.  
  835.       4{p} 
  836.                 same as ".486" or ".486p" (also defines "__386__" and changes 
  837.                 the default USE attribute of segments from "USE16" to "USE32") 
  838.  
  839.       5{p} 
  840.                 same as ".586" or ".586p" (also defines "__386__" and changes 
  841.                 the default USE attribute of segments from "USE16" to "USE32") 
  842.  
  843.       p 
  844.                 protect mode 
  845.  
  846.       add r 
  847.                 defines "__REGISTER__" 
  848.  
  849.       add s 
  850.                 defines "__STACK__" 
  851.       Example: 
  852.  
  853.          /2    /3p   /4pr   /5p 
  854.  
  855.  bt=<os> 
  856.       defines "__<os>__" and checks the "<os>_INCLUDE" environment variable for 
  857.       include files 
  858.  
  859.  c 
  860.       do not output OMF COMENT records that allow WDISASM to figure out when 
  861.       data bytes have been placed in a code segment 
  862.  
  863.  d<name>[=text] 
  864.       define text macro 
  865.  
  866.  d1 
  867.       line number debugging support 
  868.  
  869.  e 
  870.       stop reading assembler source file at END directive.  Normally, anything 
  871.       following the END directive will cause an error. 
  872.  
  873.  e<number> 
  874.       set error limit number 
  875.  
  876.  fe=<file_name> 
  877.       set error file name 
  878.  
  879.  fo=<file_name> 
  880.       set object file name 
  881.  
  882.  fi=<file_name> 
  883.       force <file_name> to be included 
  884.  
  885.  fpc 
  886.       same as ".no87" 
  887.  
  888.  fpi 
  889.       inline 80x87 instructions with emulation 
  890.  
  891.  fpi87 
  892.       inline 80x87 instructions 
  893.  
  894.  fp0 
  895.       same as ".8087" 
  896.  
  897.  fp2 
  898.       same as ".287" or ".287p" 
  899.  
  900.  fp3 
  901.       same as ".387" or ".387p" 
  902.  
  903.  fp5 
  904.       same as ".587" or ".587p" 
  905.  
  906.  i=<directory> 
  907.       add directory to list of include directories 
  908.  
  909.  j or s 
  910.       force signed types to be used for signed values 
  911.  
  912.  m{t,s,m,c,l,h,f} 
  913.       memory model:  (Tiny, Small, Medium, Compact, Large, Huge, Flat) 
  914.  
  915.       -mt 
  916.                 Same as ".model tiny" 
  917.  
  918.       -ms 
  919.                 Same as ".model small" 
  920.  
  921.       -mm 
  922.                 Same as ".model medium" 
  923.  
  924.       -mc 
  925.                 Same as ".model compact" 
  926.  
  927.       -ml 
  928.                 Same as ".model large" 
  929.  
  930.       -mh 
  931.                 Same as ".model huge" 
  932.  
  933.       -mf 
  934.                 Same as ".model flat" 
  935.       Each of the model directives also defines "__<model>__" (e.g., ".model 
  936.       small" defines "__SMALL__"). They also affect whether something like "foo 
  937.       proc" is considered a "far" or "near" procedure. 
  938.  
  939.  nd=<name> 
  940.       set data segment name 
  941.  
  942.  nm=<name> 
  943.       set module name 
  944.  
  945.  nt=<name> 
  946.       set name of text segment 
  947.  
  948.  o 
  949.       allow C form of octal constants 
  950.  
  951.  zq or q 
  952.       operate quietly 
  953.  
  954.  ?  or h 
  955.       print this message 
  956.  
  957.  w<number> 
  958.       set warning level number 
  959.  
  960.  we 
  961.       treat all warnings as errors 
  962.  
  963.  
  964. ΓòÉΓòÉΓòÉ 2.1. Assembly Directives and Opcodes ΓòÉΓòÉΓòÉ
  965.  
  966.  
  967. It is not the intention of this chapter to describe assembly-language 
  968. programming in any detail.  You should consult a book that deals with this 
  969. topic.  However, we present an alphabetically ordered list of the directives, 
  970. opcodes and register names that are recognized by the assembler. 
  971.  
  972.  
  973.    .186      .286      .286c      .286p 
  974.    .287      .386      .386p      .387 
  975.    .486      .486p      .586      .586p 
  976.    .8086      .8087      aaa       aad 
  977.    aam       aas       abs       adc 
  978.    add       addr      ah       al 
  979.    alias      align      .alpha     and 
  980.    arpl      assume     at       ax 
  981.    basic      bh       bl       bound 
  982.    bp       .break     bsf       bsr 
  983.    bswap      bt       btc       btr 
  984.    bts       bx       byte      c 
  985.    call      callf      casemap     catstr 
  986.    cbw       cdq       ch       cl 
  987.    clc       cld       cli       clts 
  988.    cmc       cmp       cmps      cmpsb 
  989.    cmpsd      cmpsw      cmpxchg     cmpxchg8b 
  990.    .code      comm      comment     common 
  991.    compact     .const     .continue    cpuid 
  992.    cr0       cr2       cr3       cr4 
  993.    .cref      cs       cwd       cwde 
  994.    cx       daa       das       .data 
  995.    .data?     db       dd       dec 
  996.    df       dh       di       div 
  997.    dl       .dosseg     dp       dq 
  998.    dr0       dr1       dr2       dr3 
  999.    dr6       dr7       ds       dt 
  1000.    dup       dw       dword      dx 
  1001.    eax       ebp       ebx       echo 
  1002.    ecx       edi       edx       else 
  1003.    elseif     end       endif      endp 
  1004.    ends      .endw      enter      eq 
  1005.    equ       equ2      .err      .errb 
  1006.    .errdef     .errdif     .errdifi    .erre 
  1007.    .erridn     .erridni    .errnb     .errndef 
  1008.    .errnz     error      es       esi 
  1009.    esp       even      .exit      export 
  1010.    extern     externdef    extrn      f2xm1 
  1011.    fabs      fadd      faddp      far 
  1012.    .fardata    .fardata?    farstack    fbld 
  1013.  
  1014.    fbstp      fchs      fclex      fcom 
  1015.    fcomp      fcompp     fcos      fdecstp 
  1016.    fdisi      fdiv      fdivp      fdivr 
  1017.    fdivrp     feni      ffree      fiadd 
  1018.    ficom      ficomp     fidiv      fidivr 
  1019.    fild      fimul      fincstp     finit 
  1020.    fist      fistp      fisub      fisubr 
  1021.    flat      fld       fld1      fldcw 
  1022.    fldenv     fldenvd     fldenvw     fldl2e 
  1023.    fldl2t     fldlg2     fldln2     fldpi 
  1024.    fldz      fmul      fmulp      fnclex 
  1025.    fndisi     fneni      fninit     fnop 
  1026.    fnrstor     fnrstord    fnrstorw    fnsave 
  1027.    fnsaved     fnsavew     fnstcw     fnstenv 
  1028.    fnstenvd    fnstenvw    fnstsw     for 
  1029.    forc      fortran     fpatan     fprem 
  1030.    fprem1     fptan      frndint     frstor 
  1031.    frstord     frstorw     fs       fsave 
  1032.    fsaved     fsavew     fscale     fsetpm 
  1033.    fsin      fsincos     fsqrt      fst 
  1034.    fstcw      fstenv     fstenvd     fstenvw 
  1035.    fstp      fstsw      fsub      fsubp 
  1036.    fsubr      fsubrp     ftst      fucom 
  1037.    fucomp     fucompp     fwait      fword 
  1038.    fxam      fxch      fxtract     fyl2x 
  1039.    fyl2xp1     ge       global     group 
  1040.    gs       gt       high      highword 
  1041.    hlt       huge      idiv      if 
  1042.    if1       if2       ifb       ifdef 
  1043.    ifdif      ifdifi     ife       ifidn 
  1044.    ifidni     ifnb      ifndef     ignore 
  1045.    imul      in       inc       include 
  1046.    includelib   ins       insb      insd 
  1047.    insw      int       into      invd 
  1048.    invlpg     invoke     iret      iretd 
  1049.    irp       ja       jae       jb 
  1050.    jbe       jc       jcxz      je 
  1051.    jecxz      jg       jge       jl 
  1052.    jle       jmp       jmpf      jna 
  1053.    jnae      jnb       jnbe      jnc 
  1054.    jne       jng       jnge      jnl 
  1055.    jnle      jno       jnp       jns 
  1056.    jnz       jo       jp       jpe 
  1057.    jpo       js       jz       label 
  1058.    lahf      lar       large      lds 
  1059.    le       lea       leave      length 
  1060.    lengthof    les       .lfcond     lfs 
  1061.    lgdt      lgs       lidt      .list 
  1062.    .listall    .listif     .listmacro   .listmacroall 
  1063.    lldt      lmsw      local      lock 
  1064.    lods      lodsb      lodsd      lodsw 
  1065.    loop      loope      loopne     loopnz 
  1066.    loopz      low       lowword     lroffset 
  1067.    lsl       lss       lt       ltr 
  1068.    macro      mask      medium     memory 
  1069.    mod       .model     mov       movs 
  1070.    movsb      movsd      movsw      movsx 
  1071.    movzx      mul       name      ne 
  1072.    near      nearstack    neg       no87 
  1073.    .nocref     .nolist     nop       not 
  1074.    nothing     offset     opattr     option 
  1075.    or       org       os_dos     os_os2 
  1076.    out       outs      outsb      outsd 
  1077.    outsw      para      pascal     pop 
  1078.    popa      popad      popcontext   popf 
  1079.    popfd      private     proc      proto 
  1080.    ptr       public     purge      push 
  1081.    pusha      pushad     pushcontext   pushf 
  1082.    pushfd     pword      qword      .radix 
  1083.    rcl       rcr       rdmsr      rdtsc 
  1084.    readonly    record     rep       repe 
  1085.    .repeat     repne      repnz      repz 
  1086.    ret       retf      retn      rol 
  1087.    ror       rsm       sahf      sal 
  1088.    .sall      sar       sbb       sbyte 
  1089.    scas      scasb      scasd      scasw 
  1090.    sdword     seg       segment     .seq 
  1091.    seta      setae      setb      setbe 
  1092.    setc      sete      setg      setge 
  1093.    setl      setle      setna      setnae 
  1094.    setnb      setnbe     setnc      setne 
  1095.    setng      setnge     setnl      setnle 
  1096.    setno      setnp      setns      setnz 
  1097.    seto      setp      setpe      setpo 
  1098.    sets      setz      .sfcond     sgdt 
  1099.    shl       shld      short      shr 
  1100.    shrd      si       sidt      size 
  1101.    sizeof     sldt      small      smsw 
  1102.    sp       ss       st       .stack 
  1103.    .startup    stc       std       stdcall 
  1104.    sti       stos      stosb      stosd 
  1105.    stosw      str       struc      struct 
  1106.    sub       sword      syscall     tbyte 
  1107.    test      textequ     .tfcond     this 
  1108.    tiny      tr3       tr4       tr5 
  1109.    tr6       tr7       typedef     union 
  1110.    .until     use16      use32      uses 
  1111.    vararg     verr      verw      wait 
  1112.    watcom_c    wbinvd     .while     width 
  1113.    word      wrmsr      xadd      xchg 
  1114.    .xcref     xlat      xlatb      .xlist 
  1115.    xor 
  1116.  
  1117.  
  1118. ΓòÉΓòÉΓòÉ 2.2. Unsupported Directives ΓòÉΓòÉΓòÉ
  1119.  
  1120.  
  1121. Other assemblers support directives that this assembler does not.  The 
  1122. following is a list of directives that are ignored by the Watcom Assembler (use 
  1123. of these directives results in a warning message). 
  1124.  
  1125.  
  1126.    .alpha     .cref      .lfcond     .list 
  1127.    .listall    .listif     .listmacro   .listmacroall 
  1128.    .nocref     .nolist     page      .sall 
  1129.    .seq      .sfcond     subtitle    subttl 
  1130.    .tfcond     title      .xcref     .xlist 
  1131.  
  1132. The following is a list of directives that are flagged by the Watcom Assembler 
  1133. (use of these directives results in an error message). 
  1134.  
  1135.  
  1136.    addr      .break     casemap     catstr 
  1137.    .continue    echo      endmacro    .endw 
  1138.    .exit      high      highword    invoke 
  1139.    low       lowword     lroffset    mask 
  1140.    opattr     option     popcontext   proto 
  1141.    purge      pushcontext   .radix     record 
  1142.    .repeat     .startup    this      typedef 
  1143.    union      .until     .while     width 
  1144.  
  1145.  
  1146. ΓòÉΓòÉΓòÉ 2.3. Watcom Assembler Diagnostic Messages ΓòÉΓòÉΓòÉ
  1147.  
  1148.  1 Size doesn't match with previous definition 
  1149.  
  1150.  2 Invalid instruction with current CPU setting 
  1151.  
  1152.  3 LOCK prefix is not allowed on this instruction 
  1153.  
  1154.  4 REP prefix is not allowed on this instruction 
  1155.  
  1156.  5 Invalid memory pointer 
  1157.  
  1158.  6 Cannot use 386 addressing mode with current CPU setting 
  1159.  
  1160.  7 Too many base registers 
  1161.  
  1162.  8 Invalid index register 
  1163.  
  1164.  9 Scale factor must be 1, 2, 4 or 8 
  1165.  
  1166.  10 invalid addressing mode with current CPU setting 
  1167.  
  1168.  11 ESP cannot be used as index 
  1169.  
  1170.  12 Too many base/index registers 
  1171.  
  1172.  13 Memory offset cannot reference to more than one label 
  1173.  
  1174.  14 Offset must be relocatable 
  1175.  
  1176.  15 Memory offset expected 
  1177.  
  1178.  16 Invalid indirect memory operand 
  1179.  
  1180.  17 Cannot mix 16 and 32-bit registers 
  1181.  
  1182.  18 CPU type already set 
  1183.  
  1184.  19 Unknown directive 
  1185.  
  1186.  20 Expecting comma 
  1187.  
  1188.  21 Expecting number 
  1189.  
  1190.  22 Invalid label definition 
  1191.  
  1192.  23 Invalid use of SHORT, NEAR, FAR operator 
  1193.  
  1194.  24 No memory 
  1195.  
  1196.  25 Cannot use 386 segment register with current CPU setting 
  1197.  
  1198.  26 POP CS is not allowed 
  1199.  
  1200.  27 Cannot use 386 register with current CPU setting 
  1201.  
  1202.  28 Only MOV can use special register 
  1203.  
  1204.  29 Cannot use TR3, TR4, TR5 in current CPU setting 
  1205.  
  1206.  30 Cannot use SHORT with CALL 
  1207.  
  1208.  31 Only SHORT displacement is allowed 
  1209.  
  1210.  32 Syntax error 
  1211.  
  1212.  33 Prefix must be followed by an instruction 
  1213.  
  1214.  34 No size given before 'PTR' operator 
  1215.  
  1216.  35 Invalid IMUL format 
  1217.  
  1218.  36 Invalid SHLD/SHRD format 
  1219.  
  1220.  37 Too many commas 
  1221.  
  1222.  38 Syntax error:  Unexpected colon 
  1223.  
  1224.  39 Operands must be the same size 
  1225.  
  1226.  40 Invalid instruction operands 
  1227.  
  1228.  41 Immediate constant too large 
  1229.  
  1230.  42 Can not use short or near modifiers with this instruction 
  1231.  
  1232.  43 Jump out of range 
  1233.  
  1234.  44 Displacement cannot be larger than 32k 
  1235.  
  1236.  45 Initializer value too large 
  1237.  
  1238.  46 Symbol already defined 
  1239.  
  1240.  47 Immediate data too large 
  1241.  
  1242.  48 Immediate data out of range 
  1243.  
  1244.  49 Can not transfer control to stack symbol 
  1245.  
  1246.  50 Offset cannot be smaller than WORD size 
  1247.  
  1248.  51 Can not take offset of stack symbol 
  1249.  
  1250.  52 Can not take segment of stack symbol 
  1251.  
  1252.  53 Segment too large 
  1253.  
  1254.  54 Offset cannot be larger than 32k 
  1255.  
  1256.  55 Operand 2 too big 
  1257.  
  1258.  56 Operand 1 too small 
  1259.  
  1260.  57 Too many arithmetic operators 
  1261.  
  1262.  58 Too many open square brackets 
  1263.  
  1264.  59 Too many close square brackets 
  1265.  
  1266.  60 Too many open brackets 
  1267.  
  1268.  61 Too many close brackets 
  1269.  
  1270.  62 Invalid number digit 
  1271.  
  1272.  63 Assembler Code is too long 
  1273.  
  1274.  64 Brackets are not balanced 
  1275.  
  1276.  65 Operator is expected 
  1277.  
  1278.  66 Operand is expected 
  1279.  
  1280.  67 Too many tokens in a line 
  1281.  
  1282.  68 Bracket is expected 
  1283.  
  1284.  69 Illegal use of register 
  1285.  
  1286.  70 Illegal use of label 
  1287.  
  1288.  71 Invalid operand in addition 
  1289.  
  1290.  72 Invalid operand in subtraction 
  1291.  
  1292.  73 One operand must be constant 
  1293.  
  1294.  74 Constant operand is expected 
  1295.  
  1296.  75 A constant operand is expected in addition 
  1297.  
  1298.  76 A constant operand is expected in subtraction 
  1299.  
  1300.  77 A constant operand is expected in multiplication 
  1301.  
  1302.  78 A constant operand is expected in division 
  1303.  
  1304.  79 A constant operand is expected after a positive sign 
  1305.  
  1306.  80 A constant operand is expected after a negative sign 
  1307.  
  1308.  81 Label is not defined 
  1309.  
  1310.  82 More than one override 
  1311.  
  1312.  83 Label is expected 
  1313.  
  1314.  84 Only segment or group label is allowed 
  1315.  
  1316.  85 Only register or label is expected in override 
  1317.  
  1318.  86 Unexpected end of file 
  1319.  
  1320.  87 Label is too long 
  1321.  
  1322.  88 This feature has not been implemented yet 
  1323.  
  1324.  89 Internal Error #1 
  1325.  
  1326.  90 Can not take offset of group 
  1327.  
  1328.  91 Can not take offset of segment 
  1329.  
  1330.  92 Invalid character found 
  1331.  
  1332.  93 Invalid operand size for instruction 
  1333.  
  1334.  94 This instruction is not supported 
  1335.  
  1336.  95 size not specified -- BYTE PTR is assumed 
  1337.  
  1338.  96 size not specified -- WORD PTR is assumed 
  1339.  
  1340.  97 size not specified -- DWORD PTR is assumed 
  1341.  
  1342.  500 Segment parameter is defined already 
  1343.  
  1344.  501 Model parameter is defined already 
  1345.  
  1346.  502 Syntax error in segment definition 
  1347.  
  1348.  503 'AT' is not supported in segment definition 
  1349.  
  1350.  504 Segment definition is changed 
  1351.  
  1352.  505 Lname is too long 
  1353.  
  1354.  506 Block nesting error 
  1355.  
  1356.  507 Ends a segment which is not opened 
  1357.  
  1358.  508 Segment option is undefined 
  1359.  
  1360.  509 Model option is undefined 
  1361.  
  1362.  510 No segment is currently opened 
  1363.  
  1364.  511 Lname is used already 
  1365.  
  1366.  512 Segment is not defined 
  1367.  
  1368.  513 Public is not defined 
  1369.  
  1370.  514 Colon is expected 
  1371.  
  1372.  515 A token is expected after colon 
  1373.  
  1374.  516 Invalid qualified type 
  1375.  
  1376.  517 Qualified type is expected 
  1377.  
  1378.  518 External definition different from previous one 
  1379.  
  1380.  519 Memory model is not found in .MODEL 
  1381.  
  1382.  520 Cannot open include file 
  1383.  
  1384.  521 Name is used already 
  1385.  
  1386.  522 Library name is missing 
  1387.  
  1388.  523 Segment name is missing 
  1389.  
  1390.  524 Group name is missing 
  1391.  
  1392.  525 Data emitted with no segment 
  1393.  
  1394.  526 Seglocation is expected 
  1395.  
  1396.  527 Invalid register 
  1397.  
  1398.  528 Cannot address with assumed register 
  1399.  
  1400.  529 Invalid start address 
  1401.  
  1402.  530 Label is already defined 
  1403.  
  1404.  531 Token is too long 
  1405.  
  1406.  532 The line is too long after expansion 
  1407.  
  1408.  533 A label is expected after colon 
  1409.  
  1410.  534 Must be associated with code 
  1411.  
  1412.  535 Procedure must have a name 
  1413.  
  1414.  536 Procedure is alreadly defined 
  1415.  
  1416.  537 Language type must be specified 
  1417.  
  1418.  538 End of procedure is not found 
  1419.  
  1420.  539 Local variable must immediately follow PROC or MACRO statement 
  1421.  
  1422.  540 Extra character found 
  1423.  
  1424.  541 Cannot nest procedures 
  1425.  
  1426.  542 No procedure is currently defined 
  1427.  
  1428.  543 Procedure name does not match 
  1429.  
  1430.  544 Vararg requires C calling convention 
  1431.  
  1432.  545 Model declared already 
  1433.  
  1434.  546 Model is not declared 
  1435.  
  1436.  547 Backquote expected 
  1437.  
  1438.  548 COMMENT delimiter expected 
  1439.  
  1440.  549 End directive required at end of file 
  1441.  
  1442.  550 Nesting level too deep 
  1443.  
  1444.  551 Symbol not defined 
  1445.  
  1446.  552 Insert Stupid warning #1 here 
  1447.  
  1448.  553 Insert Stupid warning #2 here 
  1449.  
  1450.  554 Spaces not allowed in command line options 
  1451.  
  1452.  555 Error: 
  1453.  
  1454.  556 Source File 
  1455.  
  1456.  557 No filename specified. 
  1457.  
  1458.  558 Out of Memory 
  1459.  
  1460.  559 Cannot Open File - 
  1461.  
  1462.  560 Cannot Close File - 
  1463.  
  1464.  561 Cannot Get Start of Source File - 
  1465.  
  1466.  562 Cannot Set to Start of Source File - 
  1467.  
  1468.  563 Command Line Contains More Than 1 File To Assemble 
  1469.  
  1470.  564 include path %s. 
  1471.  
  1472.  565 Unknown option %s.  Use /?  for list of options. 
  1473.  
  1474.  566 read more command line from %s. 
  1475.  
  1476.  567 Internal error in %s(%u) 
  1477.  
  1478.  568 OBJECT WRITE ERROR !! 
  1479.  
  1480.  569 NO LOR PHARLAP !! 
  1481.  
  1482.  570 Parameter Required 
  1483.  
  1484.  571 Expecting closing square bracket 
  1485.  
  1486.  572 Expecting file name 
  1487.  
  1488.  573 Floating point instruction not allowed with /fpc 
  1489.  
  1490.  574 Too many errors 
  1491.  
  1492.  575 Build target not recognised 
  1493.  
  1494.  576 Public constants should be numeric 
  1495.       0 written 
  1496.  
  1497.  577 Expecting symbol 
  1498.  
  1499.  578 Do not mix simplified and full segment definitions 
  1500.  
  1501.  579 Parms passed in multiple registers must be accessed separately, use %s 
  1502.  
  1503.  580 Ten byte variables not supported in register calling convention 
  1504.  
  1505.  581 Parameter type not recognised 
  1506.  
  1507.  582 forced error: 
  1508.  
  1509.  583 forced error:  Value not equal to 0 :  %d 
  1510.  
  1511.  584 forced error:  Value equal to 0:  %d 
  1512.  
  1513.  585 forced error:  symbol defined:  %s 
  1514.  
  1515.  586 forced error:  symbol not defined:  %s 
  1516.  
  1517.  587 forced error:  string blank :  <%s> 
  1518.  
  1519.  588 forced error:  string not blank :  <%s> 
  1520.  
  1521.  589 forced error:  strings not equal :  <%s> :  <%s> 
  1522.  
  1523.  590 forced error:  strings equal :  <%s> :  <%s> 
  1524.  
  1525.  591 included by file %s(%d) 
  1526.  
  1527.  592 macro called from file %s(%d) 
  1528.  
  1529.  593 Symbol %s not defined 
  1530.  
  1531.  594 Extending jump 
  1532.  
  1533.  595 Ignoring inapplicable directive 
  1534.  
  1535.  596 Unknown symbol class '%s' 
  1536.  
  1537.  597 Symbol class for '%s' already established 
  1538.  
  1539.  598 number must be a power of 2 
  1540.  
  1541.  599 alignment request greater than segment alignment 
  1542.  
  1543.  600 '%s' is already defined 
  1544.  
  1545.  601 %u unclosed conditional directive(s) detected 
  1546.  
  1547.  
  1548. ΓòÉΓòÉΓòÉ 3. The Watcom Library Manager ΓòÉΓòÉΓòÉ
  1549.  
  1550.  
  1551. The Watcom Library Manager can be used to create and update object library 
  1552. files.  It takes as input an object file or a library file and creates or 
  1553. updates a library file.  For OS/2, Win16 and Win32 applications, it can also 
  1554. create import libraries from Dynamic Link Libraries. 
  1555.  
  1556. An object library is essentially a collection of object files.  These object 
  1557. files generally contain utility routines that can be used as input to the 
  1558. Watcom Linker to create an application.  The following are some of the 
  1559. advantages of using library files. 
  1560.  
  1561.    1. Only those modules that are referenced will be included in the executable 
  1562.       file.  This eliminates the need to know which object files should be 
  1563.       included and which ones should be left out when linking an application. 
  1564.  
  1565.    2. Libraries are a good way of organizing object files.  When linking an 
  1566.       application, you need only list one library file instead of several 
  1567.       object files. 
  1568.  
  1569.  The Watcom Library Manager currently runs under the following operating 
  1570.  systems. 
  1571.  
  1572.      DOS 
  1573.      OS/2 
  1574.      QNX 
  1575.      Windows 
  1576.  
  1577.  
  1578. ΓòÉΓòÉΓòÉ 3.1. The Watcom Library Manager Command Line ΓòÉΓòÉΓòÉ
  1579.  
  1580.  
  1581. The following describes the Watcom Library Manager command line. 
  1582.  
  1583.  
  1584.    WLIB [options_1] lib_file [options_2] [cmd_list] 
  1585.  
  1586. The square brackets "[]" denote items which are optional. 
  1587.  
  1588.  lib_file 
  1589.       is the file specification for the library file to be processed.  If no 
  1590.       file extension is specified, a file extension of "lib" is assumed. 
  1591.  
  1592.  options_1 
  1593.       is a list of valid options.  Options may be specified in any order.  If 
  1594.       you are using a DOS, OS/2 or Windows-hosted version of the Watcom Library 
  1595.       Manager, options are preceded by a "/" or "-" character.  If you are 
  1596.       using a QNX-hosted version of the Watcom Library Manager, options are 
  1597.       preceded by a "-" character. 
  1598.  
  1599.  options_2 
  1600.       is a list of valid options.  These options are only permitted if you are 
  1601.       running a DOS, OS/2 or Windows-hosted version of the Watcom Library 
  1602.       Manager and must be preceded by a "/" character.  The "-" character 
  1603.       cannot be used as an option delimiter for options following the library 
  1604.       file name since it will be interpreted as a delete command. 
  1605.  
  1606.  cmd_list 
  1607.       is a list of commands to the Watcom Library Manager specifying what 
  1608.       operations are to be performed.  Each command in cmd_list is separated by 
  1609.       a space. 
  1610.  
  1611.  The following is a summary of valid options.  Items enclosed in square 
  1612.  brackets "[]" are optional.  Items separated by an or-bar "|" and enclosed in 
  1613.  parentheses "()" indicate that one of the items must be specified.  Items 
  1614.  enclosed in angle brackets "<>" are to be replaced with a user-supplied name 
  1615.  or value (the "<>" are not included in what you specify). 
  1616.  
  1617.  ? 
  1618.       display the usage message 
  1619.  
  1620.  b 
  1621.       suppress creation of backup file 
  1622.  
  1623.  c 
  1624.       perform case sensitive comparison 
  1625.  
  1626.  d=<output_directory> 
  1627.       directory in which extracted object modules will be placed 
  1628.  
  1629.  fa 
  1630.       output AR format library 
  1631.  
  1632.  fm 
  1633.       output MLIB format library 
  1634.  
  1635.  fo 
  1636.       output OMF format library 
  1637.  
  1638.  h 
  1639.       display the usage message 
  1640.  
  1641.  ia 
  1642.       generate AXP import records 
  1643.  
  1644.  ii 
  1645.       generate X86 import records 
  1646.  
  1647.  ip 
  1648.       generate PPC import records 
  1649.  
  1650.  ie 
  1651.       generate ELF import records 
  1652.  
  1653.  ic 
  1654.       generate COFF import records 
  1655.  
  1656.  io 
  1657.       generate OMF import records 
  1658.  
  1659.  i(r|n)(n|o) 
  1660.       imports for the resident/non-resident names table are to be imported by 
  1661.       name/ordinal. 
  1662.  
  1663.  l[=<list_file>] 
  1664.       create a listing file 
  1665.  
  1666.  m 
  1667.       display C++ mangled names 
  1668.  
  1669.  n 
  1670.       always create a new library 
  1671.  
  1672.  o=<output_file> 
  1673.       set output file name for library 
  1674.  
  1675.  p=<record_size> 
  1676.       set library page size (supported for "OMF" library format only) 
  1677.  
  1678.  q 
  1679.       suppress identification banner 
  1680.  
  1681.  s 
  1682.       strip line number records from object files (supported for "OMF" library 
  1683.       format only) 
  1684.  
  1685.  t 
  1686.       remove path information from module name specified in THEADR records 
  1687.       (supported for "OMF" library format only) 
  1688.  
  1689.  v 
  1690.       do not suppress identification banner 
  1691.  
  1692.  x 
  1693.       extract all object modules from library 
  1694.  
  1695.  The following sections describe the operations that can be performed on a 
  1696.  library file.  Note that before making a change to a library file, the Watcom 
  1697.  Library Manager makes a backup copy of the original library file unless the 
  1698.  "o" option is used to specify an output library file whose name is different 
  1699.  than the original library file, or the "b" option is used to suppress the 
  1700.  creation of the backup file.  The backup copy has the same file name as the 
  1701.  original library file but has a file extension of "bak".  Hence, lib_file 
  1702.  should not have a file extension of "bak". 
  1703.  
  1704.  
  1705. ΓòÉΓòÉΓòÉ 3.2. Adding Modules to a Library File ΓòÉΓòÉΓòÉ
  1706.  
  1707.  
  1708. An object file can be added to a library file by specifying a +obj_file command 
  1709. where obj_file is the file specification for an object file.  If you are using 
  1710. a DOS, OS/2 or Windows-hosted version of the Watcom Library Manager, a file 
  1711. extension of "obj" is assumed if none is specified.  If you are using a 
  1712. QNX-hosted version of the Watcom Library Manager, a file extension of "o" is 
  1713. assumed if none is specified.  If the library file does not exist, a warning 
  1714. message will be issued and the library file will be created. 
  1715.  
  1716. Example: 
  1717.  
  1718.    wlib mylib +myobj 
  1719.  
  1720. In the above example, the object file "myobj" is added to the library file 
  1721. "mylib.lib". 
  1722.  
  1723. When a module is added to a library, the Watcom Library Manager will issue a 
  1724. warning if a symbol redefinition occurs.  This will occur if a symbol in the 
  1725. module being added is already defined in another module that already exists in 
  1726. the library file.  Note that the module will be added to the library in any 
  1727. case. 
  1728.  
  1729. It is also possible to combine two library files together.  The following 
  1730. example adds all modules in the library "newlib.lib" to the library 
  1731. "mylib.lib". 
  1732.  
  1733. Example: 
  1734.  
  1735.    wlib mylib +newlib.lib 
  1736.  
  1737. Note that you must specify the "lib" file extension.  Otherwise, the Watcom 
  1738. Library Manager will assume you are adding an object file. 
  1739.  
  1740.  
  1741. ΓòÉΓòÉΓòÉ 3.3. Deleting Modules from a Library File ΓòÉΓòÉΓòÉ
  1742.  
  1743.  
  1744. A module can be deleted from a library file by specifying a -mod_name command 
  1745. where mod_name is the file name of the object file when it was added to the 
  1746. library with the directory and file extension removed. 
  1747.  
  1748. Example: 
  1749.  
  1750.    wlib mylib -myobj 
  1751.  
  1752. In the above example, the Watcom Library Manager is instructed to delete the 
  1753. module "myobj" from the library file "mylib.lib". 
  1754.  
  1755. It is also possible to specify a library file instead of a module name. 
  1756.  
  1757. Example: 
  1758.  
  1759.    wlib mylib -oldlib.lib 
  1760.  
  1761. In the above example, all modules in the library file "oldlib.lib" are removed 
  1762. from the library file "mylib.lib".  Note that you must specify the "lib" file 
  1763. extension.  Otherwise, the Watcom Library Manager will assume you are removing 
  1764. an object module. 
  1765.  
  1766.  
  1767. ΓòÉΓòÉΓòÉ 3.4. Replacing Modules in a Library File ΓòÉΓòÉΓòÉ
  1768.  
  1769.  
  1770. A module can be replaced by specifying a -+mod_name or +-mod_name command.  The 
  1771. module mod_name is deleted from the library.  The object file "mod_name" is 
  1772. then added to the library. 
  1773.  
  1774. Example: 
  1775.  
  1776.    wlib mylib -+myobj 
  1777.  
  1778. In the above example, the module "myobj" is replaced by the object file 
  1779. "myobj". 
  1780.  
  1781. It is also possible to merge two library files. 
  1782.  
  1783. Example: 
  1784.  
  1785.    wlib mylib -+updlib.lib 
  1786.  
  1787. In the above example, all modules in the library file "updlib.lib" replace the 
  1788. corresponding modules in the library file "mylib.lib".  Any module in the 
  1789. library "updlib.lib" not in library "mylib.lib" is added to the library 
  1790. "mylib.lib".  Note that you must specify the "lib" file extension.  Otherwise, 
  1791. the Watcom Library Manager will assume you are replacing an object module. 
  1792.  
  1793.  
  1794. ΓòÉΓòÉΓòÉ 3.5. Extracting a Module from a Library File ΓòÉΓòÉΓòÉ
  1795.  
  1796.  
  1797. A module can be extracted from a library file by specifying a *mod_name command 
  1798. for a DOS, OS/2 or Windows-hosted version of the Watcom Library Manager or a 
  1799. :mod_name command for a QNX-hosted version of the Watcom Library Manager.  The 
  1800. module mod_name is not deleted but is copied to a disk file.  If mod_name is 
  1801. preceded by a path specification, the output file will be placed in the 
  1802. directory identified by the path specification.  If mod_name is followed by a 
  1803. file extension, the output file will contain the specified file extension. 
  1804.  
  1805. Example: 
  1806.  
  1807.    wlib mylib *myobj     DOS, OS/2 or Windows-hosted 
  1808.      or 
  1809.    wlib mylib :myobj     QNX-hosted 
  1810.  
  1811. In the above example, the module "myobj" is copied to a disk file.  The disk 
  1812. file will be an object file with file name "myobj".  If you are running a DOS, 
  1813. OS/2 or Windows-hosted version of the Watcom Library Manager, a file extension 
  1814. of "obj" will be used.  If you are running a QNX-hosted version of the Watcom 
  1815. Library Manager, a file extension of "o" will be used. 
  1816.  
  1817. Example: 
  1818.  
  1819.    wlib mylib *myobj.out   DOS, OS/2 or Windows-hosted 
  1820.      or 
  1821.    wlib mylib :myobj.out   QNX-hosted 
  1822.  
  1823. In the above example, the module "myobj" will be extracted from the library 
  1824. file "mylib.lib" and placed in the file "myobj.out" 
  1825.  
  1826. You can extract a module from a file and have that module deleted from the 
  1827. library file by specifying a *-mod_name command for a DOS, OS/2 or 
  1828. Windows-hosted version of the Watcom Library Manager or a :-mod_name command 
  1829. for a QNX-hosted version of the Watcom Library Manager.  The following example 
  1830. performs the same operations as in the previous example but, in addition, the 
  1831. module is deleted from the library file. 
  1832.  
  1833. Example: 
  1834.  
  1835.    wlib mylib *-myobj.out  DOS, OS/2 or Windows-hosted 
  1836.      or 
  1837.    wlib mylib :-myobj.out  QNX-hosted 
  1838.  
  1839. Note that the same result is achieved if the delete operator precedes the 
  1840. extract operator. 
  1841.  
  1842.  
  1843. ΓòÉΓòÉΓòÉ 3.6. Creating Import Libraries ΓòÉΓòÉΓòÉ
  1844.  
  1845.  
  1846. The Watcom Library Manager can also be used to create import libraries from 
  1847. Dynamic Link Libraries.  Import libraries are used when linking OS/2, Win16 or 
  1848. Win32 applications. 
  1849.  
  1850. Example: 
  1851.  
  1852.    wlib implib +dynamic.dll 
  1853.  
  1854. In the above example, the following actions are performed.  For each external 
  1855. symbol in the specified Dynamic Link Library, a special object module is 
  1856. created that identifies the external symbol and the actual name of the Dynamic 
  1857. Link Library it is defined in.  This object module is then added to the 
  1858. specified library.  The resulting library is called an import library. 
  1859.  
  1860. Note that you must specify the "dll" file extension.  Otherwise, the Watcom 
  1861. Library Manager will assume you are adding an object file. 
  1862.  
  1863.  
  1864. ΓòÉΓòÉΓòÉ 3.7. Creating Import Library Entries ΓòÉΓòÉΓòÉ
  1865.  
  1866.  
  1867. An import library entry can be created and added to a library by specifying a 
  1868. command of the following form. 
  1869.  
  1870.  
  1871.    ++sym.dll_name[.[altsym].export_name][.ordinal] 
  1872.  
  1873.  where 
  1874.       description 
  1875.  
  1876.  sym 
  1877.       is the name of a symbol in a Dynamic Link Library. 
  1878.  
  1879.  dll_name 
  1880.       is the name of the Dynamic Link Library that defines sym. 
  1881.  
  1882.  altsym 
  1883.       is the name of a symbol in a Dynamic Link Library.  When omitted, the 
  1884.       default symbol name is sym. 
  1885.  
  1886.  export_name 
  1887.       is the name that an application that is linking to the Dynamic Link 
  1888.       Library uses to reference sym.  When omitted, the default export name is 
  1889.       sym. 
  1890.  
  1891.  ordinal 
  1892.       is the ordinal value that can be used to identify sym instead of using 
  1893.       the name export_name. 
  1894.  
  1895.  Example: 
  1896.  
  1897.     wlib math ++__sin.trig.sin.1 
  1898.  
  1899.  In the above example, an import library entry will be created for symbol sin 
  1900.  and added to the library "math.lib".  The symbol sin is defined in the Dynamic 
  1901.  Link Library called "trig.dll" as __sin.  When an application is linked with 
  1902.  the library "math.lib", the resulting executable file will contain an import 
  1903.  by ordinal value 1.  If the ordinal value was omitted, the resulting 
  1904.  executable file would contain an import by name sin. 
  1905.  
  1906.  
  1907. ΓòÉΓòÉΓòÉ 3.8. Commands from a File or Environment Variable ΓòÉΓòÉΓòÉ
  1908.  
  1909.  
  1910. The Watcom Library Manager can be instructed to process all commands in a disk 
  1911. file or environment variable by specifying the @name command where name is a 
  1912. file specification for the command file or the name of an environment variable. 
  1913. A file extension of "lbc" is assumed for files if none is specified.  The 
  1914. commands must be one of those previously described. 
  1915.  
  1916. Example: 
  1917.  
  1918.    wlib mylib @mycmd 
  1919.  
  1920. In the above example, all commands in the environment variable "mycmd" or file 
  1921. "mycmd.lbc" are processed by the Watcom Library Manager. 
  1922.  
  1923.  
  1924. ΓòÉΓòÉΓòÉ 3.9. Watcom Library Manager Options ΓòÉΓòÉΓòÉ
  1925.  
  1926.  
  1927. The following sections describe the list of options allowed when invoking the 
  1928. Watcom Library Manager. 
  1929.  
  1930.  
  1931. ΓòÉΓòÉΓòÉ 3.9.1. Suppress Creation of Backup File - "b" Option ΓòÉΓòÉΓòÉ
  1932.  
  1933.  
  1934. The "b" option tells the Watcom Library Manager to not create a backup library 
  1935. file.  In the following example, the object file identified by "new" will be 
  1936. added to the library file "mylib.lib". 
  1937.  
  1938. Example: 
  1939.  
  1940.    wlib -b mylib +new 
  1941.  
  1942. If the library file "mylib.lib" already exits, no backup library file 
  1943. ("mylib.bak") will be created. 
  1944.  
  1945.  
  1946. ΓòÉΓòÉΓòÉ 3.9.2. Case Sensitive Symbol Names - "c" Option ΓòÉΓòÉΓòÉ
  1947.  
  1948.  
  1949. The "c" option tells the Watcom Library Manager to use a case sensitive compare 
  1950. when comparing a symbol to be added to the library to a symbol already in the 
  1951. library file.  This will cause the names "myrtn" and "MYRTN" to be treated as 
  1952. different symbols.  By default, comparisons are case insensitive.  That is the 
  1953. symbol "myrtn" is the same as the symbol "MYRTN". 
  1954.  
  1955.  
  1956. ΓòÉΓòÉΓòÉ 3.9.3. Specify Output Directory - "d" Option ΓòÉΓòÉΓòÉ
  1957.  
  1958.  
  1959. The "d" option tells the Watcom Library Manager the directory in which all 
  1960. extracted modules are to be placed.  The default is to place all extracted 
  1961. modules in the current directory. 
  1962.  
  1963. In the following example, the module "mymod" is extracted from the library 
  1964. "mylib.lib".  If you are running a DOS, OS/2 or Windows-hosted version of the 
  1965. Watcom Library Manager, the module will be placed in the file "\obj\mymod.obj". 
  1966. If you are running a QNX-hosted version of the Watcom Library Manager, the 
  1967. module will be placed in the file "/o/mymod.o". 
  1968.  
  1969. Example: 
  1970.  
  1971.    wlib -d=\obj mymod    DOS, OS/2 or Windows-hosted 
  1972.      or 
  1973.    wlib -d=/o mymod     QNX-hosted 
  1974.  
  1975.  
  1976. ΓòÉΓòÉΓòÉ 3.9.4. Specify Output Format - "f" Option ΓòÉΓòÉΓòÉ
  1977.  
  1978.  
  1979. The "f" option tells the Watcom Library Manager the format of the output 
  1980. library.  The default output format is determined by the type of object files 
  1981. that are added to the library when it is created.  The possible output format 
  1982. options are: 
  1983.  
  1984.  fa 
  1985.       output AR format library 
  1986.  
  1987.  fm 
  1988.       output MLIB format library 
  1989.  
  1990.  fo 
  1991.       output OMF format library 
  1992.  
  1993.  
  1994. ΓòÉΓòÉΓòÉ 3.9.5. Generating Imports - "i" Option ΓòÉΓòÉΓòÉ
  1995.  
  1996.  
  1997. The "i" option can be used to describe type of import library to create. 
  1998.  
  1999.  ia 
  2000.       generate AXP import records 
  2001.  
  2002.  ii 
  2003.       generate X86 import records 
  2004.  
  2005.  ip 
  2006.       generate PPC import records 
  2007.  
  2008.  ie 
  2009.       generate ELF import records 
  2010.  
  2011.  ic 
  2012.       generate COFF import records 
  2013.  
  2014.  io 
  2015.       generate OMF import records 
  2016.  
  2017.  When creating import libraries from Dynamic Link Libraries, import entries for 
  2018.  the names in the resident and non-resident names tables are created.  The "i" 
  2019.  option can be used to describe the method used to import these names. 
  2020.  
  2021.  iro 
  2022.       Specifying "iro" causes imports for names in the resident names table to 
  2023.       be imported by ordinal. 
  2024.  
  2025.  irn 
  2026.       Specifying "irn" causes imports for names in the resident names table to 
  2027.       be imported by name.  This is the default. 
  2028.  
  2029.  ino 
  2030.       Specifying "ino" causes imports for names in the non-resident names table 
  2031.       to be imported by ordinal.  This is the default. 
  2032.  
  2033.  inn 
  2034.       Specifying "inn" causes imports for names in the non-resident names table 
  2035.       to be imported by name. 
  2036.  
  2037.  Example: 
  2038.  
  2039.     wlib -iro -inn implib +dynamic.dll 
  2040.  
  2041.  Note that you must specify the "dll" file extension for the Dynamic Link 
  2042.  Library.  Otherwise an object file will be assumed. 
  2043.  
  2044.  
  2045. ΓòÉΓòÉΓòÉ 3.9.6. Creating a Listing File - "l" Option ΓòÉΓòÉΓòÉ
  2046.  
  2047.  
  2048. The "l" (lower case "L") option instructs the Watcom Library Manager to produce 
  2049. a list of the names of all symbols that can be found in the library file to a 
  2050. listing file.  The file name of the listing file is the same as the file name 
  2051. of the library file.  The file extension of the listing file is "lst". 
  2052.  
  2053. Example: 
  2054.  
  2055.    wlib -l mylib 
  2056.  
  2057. In the above example, the Watcom Library Manager is instructed to list the 
  2058. contents of the library file "mylib.lib" and produce the output to a listing 
  2059. file called "mylib.lst". 
  2060.  
  2061. An alternate form of this option is -l=list_file.  With this form, you can 
  2062. specify the name of the listing file.  When specifying a listing file name, a 
  2063. file extension of "lst" is assumed if none is specified. 
  2064.  
  2065. Example: 
  2066.  
  2067.    wlib -l=mylib.out mylib 
  2068.  
  2069. In the above example, the Watcom Library Manager is instructed to list the 
  2070. contents of the library file "mylib.lib" and produce the output to a listing 
  2071. file called "mylib.out". 
  2072.  
  2073. You can get a listing of the contents of a library file to the terminal by 
  2074. specifying only the library name on the command line as demonstrated by the 
  2075. following example. 
  2076.  
  2077. Example: 
  2078.  
  2079.    wlib mylib 
  2080.  
  2081.  
  2082. ΓòÉΓòÉΓòÉ 3.9.7. Display C++ Mangled Names - "m" Option ΓòÉΓòÉΓòÉ
  2083.  
  2084.  
  2085. The "m" option instructs the Watcom Library Manager to display C++ mangled 
  2086. names rather than displaying their demangled form.  The default is to interpret 
  2087. mangled C++ names and display them in a somewhat more intelligible form. 
  2088.  
  2089.  
  2090. ΓòÉΓòÉΓòÉ 3.9.8. Always Create a New Library - "n" Option ΓòÉΓòÉΓòÉ
  2091.  
  2092.  
  2093. The "n" option tells the Watcom Library Manager to always create a new library 
  2094. file.  If the library file already exists, a backup copy is made (unless the 
  2095. "b" option was specified).  The original contents of the library are discarded 
  2096. and a new library is created.  If the "n" option was not specified, the 
  2097. existing library would be updated. 
  2098.  
  2099. Example: 
  2100.  
  2101.    wlib -n mylib +myobj 
  2102.  
  2103. In the above example, a library file called "mylib.lib" is created.  It will 
  2104. contain a single object module, namely "myobj", regardless of the contents of 
  2105. "mylib.lib" prior to issuing the above command.  If "mylib.lib" already exists, 
  2106. it will be renamed to "mylib.bak". 
  2107.  
  2108.  
  2109. ΓòÉΓòÉΓòÉ 3.9.9. Specifying an Output File Name - "o" Option ΓòÉΓòÉΓòÉ
  2110.  
  2111.  
  2112. The "o" option can be used to specify the output library file name if you want 
  2113. the original library to remain unchanged and a new library created. 
  2114.  
  2115. Example: 
  2116.  
  2117.    wlib -o=newlib lib1 +lib2.lib 
  2118.  
  2119. In the above example, the modules from "lib1.lib" and "lib2.lib" are added to 
  2120. the library "newlib.lib".  Note that since the original library remains 
  2121. unchanged, no backup copy is created.  Also, if the "l" option is used to 
  2122. specify a listing file, the listing file will assume the file name of the 
  2123. output library. 
  2124.  
  2125.  
  2126. ΓòÉΓòÉΓòÉ 3.9.10. Specifying a Library Record Size - "p" Option ΓòÉΓòÉΓòÉ
  2127.  
  2128.  
  2129. The "p" option specifies the record size in bytes for each record in the 
  2130. library file.  The record size must be a power of 2 and in the range 16 to 
  2131. 32768.  If the record size is less than 16, it will be rounded up to 16.  If 
  2132. the record size is greater than 16 and not a power of 2, it will be rounded up 
  2133. to the nearest power of 2.  The default record size is 256 bytes. 
  2134.  
  2135. Each entry in the dictionary of a library file contains an offset from the 
  2136. start of the file which points to a module.  The offset is 16 bits and is a 
  2137. multiple of the record size.  Since the default record size is 256, the maximum 
  2138. size of a library file for a record size of 256 is 256*64K.  If the size of the 
  2139. library file increases beyond this size, you must increase the record size. 
  2140.  
  2141. Example: 
  2142.  
  2143.    wlib -p=512 lib1 +lib2.lib 
  2144.  
  2145. In the above example, the Watcom Library Manager is instructed to create/update 
  2146. the library file "lib1.lib" by adding the modules from the library file 
  2147. "lib2.lib".  The record size of the resulting library file is 512 bytes. 
  2148.  
  2149.  
  2150. ΓòÉΓòÉΓòÉ 3.9.11. Operate Quietly - "q" Option ΓòÉΓòÉΓòÉ
  2151.  
  2152.  
  2153. The "q" option suppressing the banner and copyright notice that is normally 
  2154. displayed when the Watcom Library Manager is invoked. 
  2155.  
  2156. Example: 
  2157.  
  2158.    wlib -q -l mylib 
  2159.  
  2160.  
  2161. ΓòÉΓòÉΓòÉ 3.9.12. Strip Line Number Records - "s" Option ΓòÉΓòÉΓòÉ
  2162.  
  2163.  
  2164. The "s" option tells the Watcom Library Manager to remove line number records 
  2165. from object files that are being added to a library.  Line number records are 
  2166. generated in the object file if the "d1" option is specified when compiling the 
  2167. source code. 
  2168.  
  2169. Example: 
  2170.  
  2171.    wlib -s mylib +myobj 
  2172.  
  2173.  
  2174. ΓòÉΓòÉΓòÉ 3.9.13. Trim Module Name - "t" Option ΓòÉΓòÉΓòÉ
  2175.  
  2176.  
  2177. The "t" option tells the Watcom Library Manager to remove path information from 
  2178. the module name specified in THEADR records in object files that are being 
  2179. added to a library.  The module name is created from the file name by the 
  2180. compiler and placed in the THEADR record of the object file.  The module name 
  2181. will contain path information if the file name given to the compiler contains 
  2182. path information. 
  2183.  
  2184. Example: 
  2185.  
  2186.    wlib -t mylib +myobj 
  2187.  
  2188.  
  2189. ΓòÉΓòÉΓòÉ 3.9.14. Operate Verbosely - "v" Option ΓòÉΓòÉΓòÉ
  2190.  
  2191.  
  2192. The "v" option enables the display of the banner and copyright notice when the 
  2193. Watcom Library Manager is invoked. 
  2194.  
  2195. Example: 
  2196.  
  2197.    wlib -v -l mylib 
  2198.  
  2199.  
  2200. ΓòÉΓòÉΓòÉ 3.9.15. Explode Library File - "x" Option ΓòÉΓòÉΓòÉ
  2201.  
  2202.  
  2203. The "x" option tells the Watcom Library Manager to extract all modules from the 
  2204. library.  Note that the modules are not deleted from the library.  Object 
  2205. modules will be placed in the current directory unless the "d" option is used 
  2206. to specify an alternate directory. 
  2207.  
  2208. In the following example all modules will be extracted from the library 
  2209. "mylib.lib" and placed in the current directory. 
  2210.  
  2211. Example: 
  2212.  
  2213.    wlib -x mylib 
  2214.  
  2215. In the following example, all modules will be extracted from the library 
  2216. "mylib.lib".  If you are running a DOS, OS/2 or Windows-hosted version of the 
  2217. Watcom Library Manager, the module will be placed in the "\obj" directory.  If 
  2218. you are running a QNX-hosted version of the Watcom Library Manager, the module 
  2219. will be placed in the file "/o" directory. 
  2220.  
  2221. Example: 
  2222.  
  2223.    wlib -x -d=\obj mylib   DOS, OS/2 or Windows-hosted 
  2224.      or 
  2225.    wlib -x -d=/o mylib    QNX-hosted 
  2226.  
  2227.  
  2228. ΓòÉΓòÉΓòÉ 3.10. Librarian Error Messages ΓòÉΓòÉΓòÉ
  2229.  
  2230.  
  2231. The following messages may be issued by the Watcom Library Manager. 
  2232.  
  2233.  Error!  Could not open object file '%s'. 
  2234.       Object file '%s' could not be found.  This message is usually issued when 
  2235.       an attempt is made to add a non-existent object file to the library. 
  2236.  
  2237.  Error!  Could not open library file '%s'. 
  2238.       The specified library file could not be found.  This is usually issued 
  2239.       for input library files.  For example, if you are combining two library 
  2240.       files, the library file you are adding is an input library file and the 
  2241.       library file you are adding to or creating is an output library file. 
  2242.  
  2243.  Error!  Invalid object module in file '%s' not added. 
  2244.       The specified file contains an invalid object module. 
  2245.  
  2246.  Error!  Dictionary too large.  Recommend split library into two libraries. 
  2247.       The size of the dictionary in a library file cannot exceed 64K.  You must 
  2248.       split the library file into two separate library files. 
  2249.  
  2250.  Error!  Redefinition of module '%s' in file '%s'. 
  2251.       This message is usually issued when an attempt is made to add a module to 
  2252.       a library that already contains a module by that name. 
  2253.  
  2254.  Warning!  Redefinition of symbol '%s' in file '%s' ignored. 
  2255.       This message is issued if a symbol defined by a module already in the 
  2256.       library is also defined by a module being added to the library. 
  2257.  
  2258.  Error!  Library too large.  Recommend split library into two libraries or try 
  2259.  a larger page_bound than %xH. 
  2260.       The record size of the library file does not allow the library file to 
  2261.       increase beyond its current size.  The record size of the library file 
  2262.       must be increased using the "p" option. 
  2263.  
  2264.  Error!  Expected '%s' in '%s' but found '%s'. 
  2265.       An error occurred while scanning command input. 
  2266.  
  2267.  Warning!  Could not find module '%s' for deletion. 
  2268.       This message is issued if an attempt is made to delete a module that does 
  2269.       not exist in the library. 
  2270.  
  2271.  Error!  Could not find module '%s' for extraction. 
  2272.       This message is issued if an attempt is made to extract a module that 
  2273.       does not exist in the library. 
  2274.  
  2275.  Error!  Could not rename old library for backup. 
  2276.       The Watcom Library Manager creates a backup copy before making any 
  2277.       changes (unless the "b" option is specified).  This message is issued if 
  2278.       an error occurred while trying to rename the original library file to the 
  2279.       backup file name. 
  2280.  
  2281.  Warning!  Could not open library '%s' :  will be created. 
  2282.       The specified library does not exist.  It is usually issued when you are 
  2283.       adding to a non-existent library.  The Watcom Library Manager will create 
  2284.       the library. 
  2285.  
  2286.  Warning!  Output library name specification ignored. 
  2287.       This message is issued if the library file specified by the "o" option 
  2288.       could not be opened. 
  2289.  
  2290.  Warning!  Could not open library '%s' and no operations specified:  will not 
  2291.  be created. 
  2292.       This message is issued if the library file specified on the command line 
  2293.       does not exist and no operations were specified.  For example, asking for 
  2294.       a listing file of a non-existent library will cause this message to be 
  2295.       issued. 
  2296.  
  2297.  Warning!  Could not open listing file '%s'. 
  2298.       The listing file could not be opened.  For example, this message will be 
  2299.       issued when a "disk full" condition is present. 
  2300.  
  2301.  Error!  Could not open output library. 
  2302.       The output library could not be opened. 
  2303.  
  2304.  Error!  Unable to write to output library. 
  2305.       An error occurred while writing to the output library. 
  2306.  
  2307.  Error!  Unable to write to extraction file '%s'. 
  2308.       This message is issued when extracting an object module from a library 
  2309.       file and an error occurs while writing to the output file. 
  2310.  
  2311.  Error!  Out of Memory. 
  2312.       There was not enough memory to process the library file. 
  2313.  
  2314.  Error!  Could not open file '%s'. 
  2315.       This message is issued if the output file for a module that is being 
  2316.       extracted from a library could not be opened. 
  2317.  
  2318.  Error!  Library '%s' is invalid.  Contents ignored. 
  2319.       The library file does not contain the correct header information. 
  2320.  
  2321.  Error!  Library '%s' has an invalid page size.  Contents ignored. 
  2322.       The library file has an invalid record size.  The record size is 
  2323.       contained in the library header and must be a power of 2. 
  2324.  
  2325.  Error!  Invalid object record found in file '%s'. 
  2326.       The specified file contains an invalid object record. 
  2327.  
  2328.  Error!  No library specified on command line. 
  2329.       This message is issued if a library file name is not specified on the 
  2330.       command line. 
  2331.  
  2332.  Error!  Expecting library name. 
  2333.       This message is issued if the location of the library file name on the 
  2334.       command line is incorrect. 
  2335.  
  2336.  Warning!  Invalid file name '%s'. 
  2337.       This message is issued if an invalid file name is specified.  For 
  2338.       example, a file name longer that 127 characters is not allowed. 
  2339.  
  2340.  Error!  Could not open command file '%s'. 
  2341.       The specified command file could not be opened. 
  2342.  
  2343.  Error!  Could not read from file '%s'.  Contents ignored as command input. 
  2344.       An error occurred while reading a command file. 
  2345.  
  2346.  
  2347. ΓòÉΓòÉΓòÉ 4. The Object File Disassembler ΓòÉΓòÉΓòÉ
  2348.  
  2349.  
  2350. This chapter describes the Watcom Disassembler.  It takes as input an object 
  2351. file (a file with extension ".obj") and produces, as output, the Intel assembly 
  2352. language equivalent.  The Watcom compilers do not produce an assembly language 
  2353. listing directly from a source program.  Instead, the Watcom Disassembler can 
  2354. be used to generate an assembly language listing from the object file generated 
  2355. by the compiler. 
  2356.  
  2357. The Watcom Disassembler command line syntax is the following. 
  2358.  
  2359.  
  2360.    WDIS [options] [d:][path]filename[.ext] [options] 
  2361.  
  2362. The square brackets [ ] denote items which are optional. 
  2363.  
  2364.  WDIS 
  2365.       is the name of the Watcom Disassembler. 
  2366.  
  2367.  d: 
  2368.       is an optional drive specification such as "A:", "B:", etc.  If not 
  2369.       specified, the default drive is assumed. 
  2370.  
  2371.  path 
  2372.       is an optional path specification such as "\PROGRAMS\OBJ\".  If not 
  2373.       specified, the current directory is assumed. 
  2374.  
  2375.  filename 
  2376.       is the file name of the object file to disassemble. 
  2377.  
  2378.  ext 
  2379.       is the file extension of the object file to disassemble.  If omitted, a 
  2380.       file extension of ".obj" is assumed.  If the period "." is specified but 
  2381.       not the extension, the file is assumed to have no file extension. 
  2382.  
  2383.  options 
  2384.       is a list of valid options, each preceded by a slash ("/") or a dash 
  2385.       ("-").  Options may be specified in any order. 
  2386.  
  2387.  The options supported by the Watcom Disassembler are: 
  2388.  
  2389.  a 
  2390.       write assembly instructions only to the listing file 
  2391.  
  2392.  e 
  2393.       include list of external names 
  2394.  
  2395.  fp 
  2396.       do not use instruction name pseudonyms 
  2397.  
  2398.  fr 
  2399.       do not use register name pseudonyms [Alpha only] 
  2400.  
  2401.  fi 
  2402.       use alternate indexing format [80(x)86 only] 
  2403.  
  2404.  fu 
  2405.       instructions/registers in upper case 
  2406.  
  2407.  i=<char> 
  2408.       redefine the initial character of internal labels (default:  L) 
  2409.  
  2410.  l[=<list_file>] 
  2411.       create a listing file 
  2412.  
  2413.  m 
  2414.       leave C++ names mangled 
  2415.  
  2416.  o 
  2417.       print list of operands beside instructions 
  2418.  
  2419.  p 
  2420.       include list of public names 
  2421.  
  2422.  s[=<source_file>] 
  2423.       using object file source line information, imbed original source lines 
  2424.       into the output file 
  2425.  
  2426.  The following sections describe the list of options. 
  2427.  
  2428.  
  2429. ΓòÉΓòÉΓòÉ 4.1. Changing the Internal Label Character - "i=<char>" ΓòÉΓòÉΓòÉ
  2430.  
  2431.  
  2432. The "i" option permits you to specify the first character to be used for 
  2433. internal labels.  Internal labels take the form "Ln" where "n" is one or more 
  2434. digits.  The default character "L" can be changed using the "i" option.  The 
  2435. replacement character must be a letter (a-z, A-Z).  A lowercase letter is 
  2436. converted to uppercase. 
  2437.  
  2438. Example: 
  2439.  
  2440.    C>wdis calendar /i=x 
  2441.  
  2442.  
  2443. ΓòÉΓòÉΓòÉ 4.2. The Assembly Format Option - "a" ΓòÉΓòÉΓòÉ
  2444.  
  2445.  
  2446. The "a" option controls the format of the output produced to the listing file. 
  2447. When specified, the Watcom Disassembler will produce a listing file that can be 
  2448. used as input to an assembler. 
  2449.  
  2450. Example: 
  2451.  
  2452.    C>wdis calendar /a /l=calendar.asm 
  2453.  
  2454. In the above example, the Watcom Disassembler is instructed to disassemble the 
  2455. contents of the file CALENDAR.OBJ and produce the output to the file 
  2456. CALENDAR.ASM so that it can be assembled by an assembler. 
  2457.  
  2458.  
  2459. ΓòÉΓòÉΓòÉ 4.3. The External Symbols Option - "e" ΓòÉΓòÉΓòÉ
  2460.  
  2461.  
  2462. The "e" option controls the amount of information produced in the listing file. 
  2463. When specified, a list of all externally defined symbols is produced in the 
  2464. listing file. 
  2465.  
  2466. Example: 
  2467.  
  2468.    C>wdis calendar /e 
  2469.  
  2470. In the above example, the Watcom Disassembler is instructed to disassemble the 
  2471. contents of the file CALENDAR.OBJ and produce the output, with a list of all 
  2472. external symbols, on the screen.  A sample list of external symbols is shown 
  2473. below. 
  2474.  
  2475.  
  2476.    List of external symbols 
  2477.  
  2478.    Symbol 
  2479.    ---------------- 
  2480.    ___iob      0000032f 00000210 000001f4 00000158 00000139 
  2481.    __CHK       00000381 00000343 000002eb 00000237 000000cb 00000006 
  2482.    Box_       000000f2 
  2483.    Calendar_     000000a7 00000079 00000049 
  2484.    ClearScreen_   00000016 
  2485.    fflush_      00000334 00000215 000001f9 0000015d 0000013e 
  2486.    int386_      000003af 00000372 
  2487.    Line_       000002db 000002b5 00000293 00000274 0000025a 
  2488.    localtime_    00000028 
  2489.    memset_      00000308 
  2490.    PosCursor_    0000031e 000001e1 00000148 00000123 000000b6 
  2491.    printf_      00000327 00000208 000001ec 00000150 00000131 
  2492.    strlen_      00000108 
  2493.    time_       0000001d 
  2494.    ------------------------------------------------------------ 
  2495.  
  2496. Each externally defined symbol is followed by a list of location counter values 
  2497. indicating where the symbol is referenced. 
  2498.  
  2499. The "e" option is ignored when the "a" option is specified. 
  2500.  
  2501.  
  2502. ΓòÉΓòÉΓòÉ 4.4. The No Instruction Name Pseudonyms Option - "fp" ΓòÉΓòÉΓòÉ
  2503.  
  2504.  
  2505. By default, AXP instruction name pseudonyms are emitted in place of actual 
  2506. instruction names.  The Watcom AXP Assembler accepts instruction name 
  2507. pseudonyms.  The "fp" option instructs the Watcom Disassembler to emit the 
  2508. actual instruction names instead. 
  2509.  
  2510.  
  2511. ΓòÉΓòÉΓòÉ 4.5. The No Register Name Pseudonyms Option - "fr" ΓòÉΓòÉΓòÉ
  2512.  
  2513.  
  2514. By default, AXP register names are emitted in pseudonym form.  The Watcom AXP 
  2515. Assembler accepts register pseudonyms.  The "fr" option instructs the Watcom 
  2516. Disassembler to display register names in their non-pseudonym form. 
  2517.  
  2518.  
  2519. ΓòÉΓòÉΓòÉ 4.6. The Alternate Addressing Form Option - "fi" ΓòÉΓòÉΓòÉ
  2520.  
  2521.  
  2522. The "fi" option causes an alternate syntactical form of the based or indexed 
  2523. addressing mode of the 80x86 to be used in an instruction.  For example, the 
  2524. following form is used by default for Intel instructions. 
  2525.  
  2526.  
  2527.    mov ax,-2[bp] 
  2528.  
  2529. If the "fi" option is specified, the following form is used. 
  2530.  
  2531.  
  2532.    mov ax,[bp-2] 
  2533.  
  2534.  
  2535. ΓòÉΓòÉΓòÉ 4.7. The Uppercase Instructions/Registers Option - "fu" ΓòÉΓòÉΓòÉ
  2536.  
  2537.  
  2538. The "fu" option instructs the Watcom Disassembler to display instruction and 
  2539. register names in uppercase characters.  The default is to display them in 
  2540. lowercase characters. 
  2541.  
  2542.  
  2543. ΓòÉΓòÉΓòÉ 4.8. The Listing Option - "l[=<list_file>]" ΓòÉΓòÉΓòÉ
  2544.  
  2545.  
  2546. By default, the Watcom Disassembler produces its output to the terminal.  The 
  2547. "l" (lowercase L) option instructs the Watcom Disassembler to produce the 
  2548. output to a listing file.  The default file name of the listing file is the 
  2549. same as the file name of the object file.  The default file extension of the 
  2550. listing file is .LST. 
  2551.  
  2552. Example: 
  2553.  
  2554.    C>wdis calendar /l 
  2555.  
  2556. In the above example, the Watcom Disassembler is instructed to disassemble the 
  2557. contents of the file CALENDAR.OBJ and produce the output to a listing file 
  2558. called CALENDAR.LST. 
  2559.  
  2560. An alternate form of this option is "l=<list_file>".  With this form, you can 
  2561. specify the name of the listing file.  When specifying a listing file, a file 
  2562. extension of .LST is assumed if none is specified. 
  2563.  
  2564. Example: 
  2565.  
  2566.    C>wdis calendar /l=calendar.lis 
  2567.  
  2568. In the above example, the Watcom Disassembler is instructed to disassemble the 
  2569. contents of the file CALENDAR.OBJ and produce the output to a listing file 
  2570. called CALENDAR.LIS. 
  2571.  
  2572.  
  2573. ΓòÉΓòÉΓòÉ 4.9. The Public Symbols Option - "p" ΓòÉΓòÉΓòÉ
  2574.  
  2575.  
  2576. The "p" option controls the amount of information produced in the listing file. 
  2577. When specified, a list of all public symbols is produced in the listing file. 
  2578.  
  2579. Example: 
  2580.  
  2581.    C>wdis calendar /p 
  2582.  
  2583. In the above example, the Watcom Disassembler is instructed to disassemble the 
  2584. contents of the file CALENDAR.OBJ and produce the output, with a list of all 
  2585. exported symbols, to the screen.  A sample list of public symbols is shown 
  2586. below. 
  2587.  
  2588. The following is a list of public symbols in 80x86 code. 
  2589.  
  2590.  
  2591.    List of public symbols 
  2592.  
  2593.    SYMBOL          SECTION         OFFSET 
  2594.    -------------------------------------------------------- 
  2595.    main_          _TEXT          000002C0 
  2596.    void near Box( int, int, int, int ) 
  2597.                _TEXT          00000093 
  2598.    void near Calendar( int, int, int, int, int, char near * ) 
  2599.                _TEXT          0000014A 
  2600.    void near ClearScreen() _TEXT          00000000 
  2601.    void near Line( int, int, int, char, char, char ) 
  2602.                _TEXT          00000036 
  2603.    void near PosCursor( int, int ) 
  2604.                _TEXT          0000001A 
  2605.  
  2606. The following is a list of public symbols in Alpha AXP code. 
  2607.  
  2608.  
  2609.    List of public symbols 
  2610.  
  2611.    SYMBOL          SECTION         OFFSET 
  2612.    -------------------------------------------------------- 
  2613.    main           .text          000004F0 
  2614.    void near Box( int, int, int, int ) 
  2615.                .text          00000148 
  2616.    void near Calendar( int, int, int, int, int, char near * ) 
  2617.                .text          00000260 
  2618.    void near ClearScreen() .text          00000000 
  2619.    void near Line( int, int, int, char, char, char ) 
  2620.                .text          00000060 
  2621.    void near PosCursor( int, int ) 
  2622.                .text          00000028 
  2623.  
  2624. The "p" option is ignored when the "a" option is specified. 
  2625.  
  2626.  
  2627. ΓòÉΓòÉΓòÉ 4.10. Retain C++ Mangled Names - "m" ΓòÉΓòÉΓòÉ
  2628.  
  2629.  
  2630. The "m" option instructs the Watcom Disassembler to retain C++ mangled names 
  2631. rather than displaying their demangled form.  The default is to interpret 
  2632. mangled C++ names and display them in a somewhat more intelligible form. 
  2633.  
  2634.  
  2635. ΓòÉΓòÉΓòÉ 4.11. The Source Option - "s[=<source_file>]" ΓòÉΓòÉΓòÉ
  2636.  
  2637.  
  2638. The "s" option causes the source lines corresponding to the assembly language 
  2639. instructions to be produced in the listing file.  The object file must contain 
  2640. line numbering information.  That is, the "d1" or "d2" option must have been 
  2641. specified when the source file was compiled.  If no line numbering information 
  2642. is present in the object file, the "s" option is ignored. 
  2643.  
  2644. The following defines the order in which the source file name is determined 
  2645. when the "s" option is specified. 
  2646.  
  2647.    1. If present, the source file name specified on the command line. 
  2648.  
  2649.    2. The name from the module header record. 
  2650.  
  2651.    3. The object file name. 
  2652.  
  2653.  In the following example, we have compiled the source file MYSRC.C with "d1" 
  2654.  debugging information.  We then disassemble it as follows: 
  2655.  
  2656.  Example: 
  2657.  
  2658.     C>wdis mysrc /s /l 
  2659.  
  2660.  In the above example, the Watcom Disassembler is instructed to disassemble the 
  2661.  contents of the file MYSRC.OBJ and produce the output to the listing file 
  2662.  MYSRC.LST.  The source lines are extracted from the file MYSRC.C. 
  2663.  
  2664.  An alternate form of this option is "s=<source_file>".  With this form, you 
  2665.  can specify the name of the source file. 
  2666.  
  2667.  Example: 
  2668.  
  2669.     C>wdis mysrc /s=myprog.c /l 
  2670.  
  2671.  The above example produces the same result as in the previous example except 
  2672.  the source lines are extracted from the file MYPROG.C. 
  2673.  
  2674.  
  2675. ΓòÉΓòÉΓòÉ 4.12. An Example ΓòÉΓòÉΓòÉ
  2676.  
  2677.  
  2678. Consider the following program contained in the file HELLO.C. 
  2679.  
  2680. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2681.  
  2682.    #include <stdio.h> 
  2683.  
  2684.    void main() 
  2685.    { 
  2686.      printf( "Hello world\n" ); 
  2687.    } 
  2688.  
  2689. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  2690.  
  2691. Compile it with the "d1" option.  An object file called HELLO.OBJ will be 
  2692. produced.  The "d1" option causes line numbering information to be generated in 
  2693. the object file.  We can use the Watcom Disassembler to disassemble the 
  2694. contents of the object file by issuing the following command. 
  2695.  
  2696.  
  2697.    C>wdis hello /l /e /p /s /fu 
  2698.  
  2699. The output will be written to a listing file called HELLO.LST (the "l" option 
  2700. was specified").  It will contain a list of external symbols (the "e" option 
  2701. was specified), a list of public symbols (the "p" option was specified) and the 
  2702. source lines corresponding to the assembly language instructions (the "s" 
  2703. option was specified).  The source input file is called HELLO.C.  The register 
  2704. names will be displayed in upper case (the "fu" option was specified).  The 
  2705. output, shown below, is the result of using the Watcom C++ compiler. 
  2706.  
  2707. The following is a disassembly of 80x86 code. 
  2708.  
  2709.  
  2710.    Module: HELLO.C 
  2711.    GROUP: 'DGROUP' CONST,CONST2,_DATA,_BSS 
  2712.  
  2713.    Segment: _TEXT DWORD USE32 0000001A bytes 
  2714.  
  2715.    #include <stdio.h> 
  2716.  
  2717.    void main() 
  2718.    0000           main_: 
  2719.    0000   68 08 00 00 00    PUSH    0x00000008 
  2720.    0005   E8 00 00 00 00    CALL    __CHK 
  2721.  
  2722.    { 
  2723.      printf( "Hello world\n" ); 
  2724.    000A   68 00 00 00 00    PUSH    offset L$1 
  2725.    000F   E8 00 00 00 00    CALL    printf_ 
  2726.    0014   83 C4 04       ADD    ESP,0x00000004 
  2727.  
  2728.    } 
  2729.    0017   31 C0        XOR    EAX,EAX 
  2730.    0019   C3          RET 
  2731.  
  2732.    Routine Size: 26 bytes,   Routine Base: _TEXT + 0000 
  2733.  
  2734.    No disassembly errors 
  2735.  
  2736.    List of external references 
  2737.  
  2738.    SYMBOL 
  2739.    ------- 
  2740.    __CHK          0006 
  2741.    printf_         0010 
  2742.  
  2743.    Segment: CONST DWORD USE32 0000000D bytes 
  2744.    0000           L$1: 
  2745.    0000   48 65 6C 6C 6F 20 77 6F 72 6C 64 0A 00      Hello world.. 
  2746.  
  2747.    BSS Size: 0 bytes 
  2748.  
  2749.    List of public symbols 
  2750.  
  2751.    SYMBOL          SECTION         OFFSET 
  2752.    -------------------------------------------------------- 
  2753.    main_          _TEXT          00000000 
  2754.  
  2755. The following is a disassembly of Alpha AXP code. 
  2756.  
  2757.  
  2758.                    .new_section .text, "crx4" 
  2759.  
  2760.    #include <stdio.h> 
  2761.  
  2762.    void main() 
  2763.    0000           main: 
  2764.    0000   23DEFFF0       LDA      SP,-0x10(SP) 
  2765.    0004   B75E0000       STQ      RA,(SP) 
  2766.  
  2767.    { 
  2768.      printf( "Hello world\n" ); 
  2769.    0008   261F0000       LDAH      A0,h^L$0(R31) 
  2770.    000C   22100000       LDA      A0,l^L$0(A0) 
  2771.    0010   43F00010       SEXTL     A0,A0 
  2772.    0014   D3400000       BSR      RA,j^printf 
  2773.  
  2774.    } 
  2775.    0018   201F0000       MOV      0x00000000,V0 
  2776.    001C   A75E0000       LDQ      RA,(SP) 
  2777.    0020   23DE0010       LDA      SP,0x10(SP) 
  2778.    0024   6BFA8001       RET      (RA) 
  2779.  
  2780.    Routine Size: 40 bytes,   Routine Base: .text + 0000 
  2781.  
  2782.    No disassembly errors 
  2783.  
  2784.    List of external references 
  2785.  
  2786.    SYMBOL 
  2787.    ------- 
  2788.    printf          0014 
  2789.  
  2790.                    .new_section .const, "drw4" 
  2791.    0000           L$0: 
  2792.    0000   48 65 6C 6C 6F 20 77 6F 72 6C 64 0A 00 00 00 00 Hello world..... 
  2793.  
  2794.                    .new_section .const2, "drw4" 
  2795.  
  2796.                    .new_section .data, "drw4" 
  2797.  
  2798.                    .new_section .bss, "urw4" 
  2799.    0000           .bss: 
  2800.  
  2801.    BSS Size: 0 bytes 
  2802.  
  2803.                    .new_section .pdata, "dr2" 
  2804.  
  2805.    0000           //  Procedure descriptor for main 
  2806.        main                   //  BeginAddress    : 0 
  2807.        main+0x28                //  EndAddress     : 40 
  2808.        00000000                 //  ExceptionHandler  : 0 
  2809.        00000000                 //  HandlerData    : 0 
  2810.        main+0x8                 //  PrologEnd     : 8 
  2811.  
  2812.                    .new_section .drectve, "iRr0" 
  2813.    0000   2D 64 65 66 61 75 6C 74 6C 69 62 3A 63 6C 69 62 -defaultlib:clib 
  2814.    0010   20 2D 64 65 66 61 75 6C 74 6C 69 62 3A 70 6C 69  -defaultlib:pli 
  2815.    0020   62 20 2D 64 65 66 61 75 6C 74 6C 69 62 3A 6D 61 b -defaultlib:ma 
  2816.    0030   74 68 20 00                   th . 
  2817.  
  2818.    List of public symbols 
  2819.  
  2820.    SYMBOL          SECTION         OFFSET 
  2821.    -------------------------------------------------------- 
  2822.    main           .text          00000000 
  2823.  
  2824. Let us create a form of the listing file that can be used as input to an 
  2825. assembler. 
  2826.  
  2827.  
  2828.    C>wdis hello /l=hello.asm /r /a 
  2829.  
  2830. The output will be produced in the file HELLO.ASM.  The output, shown below, is 
  2831. the result of using the Watcom C++ compiler. 
  2832.  
  2833. The following is a disassembly of 80x86 code. 
  2834.  
  2835.  
  2836.    .387 
  2837.    .386p 
  2838.            PUBLIC  main_ 
  2839.            EXTRN  __CHK:BYTE 
  2840.            EXTRN  printf_:BYTE 
  2841.            EXTRN  ___wcpp_3_data_init_fs_root_:BYTE 
  2842.            EXTRN  _cstart_:BYTE 
  2843.    DGROUP      GROUP  CONST,CONST2,_DATA,_BSS 
  2844.    _TEXT      SEGMENT DWORD PUBLIC USE32 'CODE' 
  2845.            ASSUME CS:_TEXT, DS:DGROUP, SS:DGROUP 
  2846.    main_: 
  2847.      PUSH    0x00000008 
  2848.      CALL    near ptr __CHK 
  2849.      PUSH    offset L$1 
  2850.      CALL    near ptr printf_ 
  2851.      ADD    ESP,0x00000004 
  2852.      XOR    EAX,EAX 
  2853.      RET 
  2854.    _TEXT      ENDS 
  2855.  
  2856.    CONST      SEGMENT DWORD PUBLIC USE32 'DATA' 
  2857.    L$1: 
  2858.            DB    0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0x77, 0x6f 
  2859.            DB    0x72, 0x6c, 0x64, 0x0a, 0x00 
  2860.  
  2861.    CONST      ENDS 
  2862.    CONST2      SEGMENT DWORD PUBLIC USE32 'DATA' 
  2863.    CONST2      ENDS 
  2864.    _DATA      SEGMENT DWORD PUBLIC USE32 'DATA' 
  2865.    _DATA      ENDS 
  2866.    _BSS       SEGMENT DWORD PUBLIC USE32 'BSS' 
  2867.    _BSS       ENDS 
  2868.  
  2869.            END 
  2870.  
  2871. The following is a disassembly of Alpha AXP code. 
  2872.  
  2873.    .globl      main 
  2874.    .extrn      printf 
  2875.    .extrn      _cstart_ 
  2876.    .new_section .text, "crx4" 
  2877.    main: 
  2878.      LDA      $SP,-0x10($SP) 
  2879.      STQ      $RA,($SP) 
  2880.      LDAH      $A0,h^`L$0`($ZERO) 
  2881.      LDA      $A0,l^`L$0`($A0) 
  2882.      SEXTL     $A0,$A0 
  2883.      BSR      $RA,j^printf 
  2884.      MOV      0x00000000,$V0 
  2885.      LDQ      $RA,($SP) 
  2886.      LDA      $SP,0x10($SP) 
  2887.      RET      $ZERO,($RA),0x00000001 
  2888.  
  2889.    .new_section .const, "drw4" 
  2890.    `L$0`: 
  2891.            .asciiz "Hello world\n" 
  2892.            .byte  0x00, 0x00, 0x00 
  2893.  
  2894.    .new_section .pdata, "dr2" 
  2895.  
  2896.            //  0000         Procedure descriptor for main 
  2897.            .long  main           //  BeginAddress    : 0 
  2898.            .long  main+0x28        //  EndAddress     : 40 
  2899.            .long  00000000         //  ExceptionHandler  : 0 
  2900.            .long  00000000         //  HandlerData    : 0 
  2901.            .long  main+0x8         //  PrologEnd     : 8 
  2902.  
  2903.    .new_section .drectve, "iRr0" 
  2904.            .asciiz "-defaultlib:clib -defaultlib:plib -defaultlib:math " 
  2905.  
  2906.  
  2907. ΓòÉΓòÉΓòÉ 5. Optimization of Far Calls ΓòÉΓòÉΓòÉ
  2908.  
  2909.  
  2910. Optimization of far calls can result in smaller executable files and improved 
  2911. performance.  It is most useful when the automatic grouping of logical segments 
  2912. into physical segments takes place.  Note that, by default, automatic grouping 
  2913. is performed by the Watcom Linker. 
  2914.  
  2915. The Watcom C, C++ and FORTRAN 77 compilers automatically enable the far call 
  2916. optimization.  The Watcom Linker will optimize far calls to procedures that 
  2917. reside in the same physical segment as the caller.  For example, a large code 
  2918. model program will probably contain many far calls to procedures in the same 
  2919. physical segment.  Since the segment address of the caller is the same as the 
  2920. segment address of the called procedure, only a near call is necessary.  A near 
  2921. call does not require a relocation entry in the relocation table of the 
  2922. executable file whereas a far call does.  Thus, the far call optimization will 
  2923. result in smaller executable files that will load faster.  Furthermore, a near 
  2924. call will generally execute faster than a far call, particularly on 286 and 
  2925. 386-based machines where, for applications running in protected mode, segment 
  2926. switching is fairly expensive. 
  2927.  
  2928. The following describes the far call optimization.  The call far label 
  2929. instruction is converted to one of the following sequences of code. 
  2930.  
  2931.  
  2932.    push  cs         seg   ss 
  2933.    call  near label     push  cs 
  2934.    nop            call  near label 
  2935.  
  2936. Notes: 
  2937.  
  2938.    1. The nop or seg ss instruction is present since a call far label 
  2939.       instruction is five bytes.  The push cs instruction is one byte and the 
  2940.       call near label instruction is three bytes.  The seg ss instruction is 
  2941.       used because it is faster than the nop instruction. 
  2942.  
  2943.    2. The called procedure will still use a retf instruction but since the code 
  2944.       segment and the near address are pushed on the stack, the far return will 
  2945.       execute correctly. 
  2946.  
  2947.    3. The position of the padding instruction is chosen so that the return 
  2948.       address is word aligned.  A word aligned return address improves 
  2949.       performance. 
  2950.  
  2951.    4. When two consecutive call far label instructions are optimized and the 
  2952.       first call far label instruction is word aligned, the following sequence 
  2953.       replaces both call far label instructions. 
  2954.  
  2955.  
  2956.          push   cs 
  2957.          call   near label1 
  2958.          seg   ss 
  2959.          push   cs 
  2960.          seg   cs 
  2961.          call   near label2 
  2962.  
  2963.    5. If your program contains only near calls, this optimization will have no 
  2964.       effect. 
  2965.  
  2966.  A far jump optimization is also performed by the Watcom Linker.  This has the 
  2967.  same benefits as the far call optimization.  A jmp far label instruction to a 
  2968.  location in the same segment will be replaced by the following sequence of 
  2969.  code. 
  2970.  
  2971.  
  2972.     jmp   near label 
  2973.     mov   ax,ax 
  2974.  
  2975.  Note that for 32-bit segments, this instruction becomes mov eax,eax. 
  2976.  
  2977.  
  2978. ΓòÉΓòÉΓòÉ 5.1. Far Call Optimizations for Non-Watcom Object Modules ΓòÉΓòÉΓòÉ
  2979.  
  2980.  
  2981. The far call optimization is automatically enabled when object modules created 
  2982. by the Watcom C, C++, or FORTRAN 77 compilers are linked.  These compilers mark 
  2983. those segments in which this optimization can be performed.  The following 
  2984. utility can be used to enable this optimization for object modules that have 
  2985. been created by other compilers or assemblers. 
  2986.  
  2987.  
  2988. ΓòÉΓòÉΓòÉ 5.1.1. The Watcom Far Call Optimization Enabling Utility ΓòÉΓòÉΓòÉ
  2989.  
  2990.  
  2991. Only DOS, OS/2 and Windows-hosted versions of the Watcom Far Call Optimization 
  2992. Enabling Utility are available.  A QNX-hosted version is not necessary since 
  2993. QNX-hosted development tools that generate object files, generate the necessary 
  2994. information that enables the far call optimization. 
  2995.  
  2996. The format of the Watcom Far Call Optimization Enabling Utility is as follows. 
  2997. Items enclosed in square brackets are optional; items enclosed in braces may be 
  2998. repeated zero or more times. 
  2999.  
  3000.  
  3001.    FCENABLE { [option] [file] } 
  3002.  
  3003.  where 
  3004.       description 
  3005.  
  3006.  option 
  3007.       is an option and must be preceded by a dash ('-') or slash ('/'). 
  3008.  
  3009.  file 
  3010.       is a file specification for an object file or library file.  If no file 
  3011.       extension is specified, a file extension of "obj" is assumed.  Wild card 
  3012.       specifiers may be used. 
  3013.  
  3014.  The following describes the command line options. 
  3015.  
  3016.  b 
  3017.       Do not create a backup file.  By default, a backup file will be created. 
  3018.       The backup file name will have the same file name as the input file and a 
  3019.       file extension of "bob" for object files and "bak" for library files. 
  3020.  
  3021.  c 
  3022.       Specify a list of class names, each separated by a comma.  This enables 
  3023.       the far call optimization for all segments belonging to the specified 
  3024.       classes. 
  3025.  
  3026.  s 
  3027.       Specify a list of segment names, each separated by a comma.  This enables 
  3028.       the far call optimization for all specified segments. 
  3029.  
  3030.  x 
  3031.       Specify a list of ranges, each separated by a comma, for which no far 
  3032.       call optimizations are to be made.  A range has the following format. 
  3033.  
  3034.  
  3035.          seg_name start-end 
  3036.              or 
  3037.          seg_name start:length 
  3038.  
  3039.       seg_name is the name of a segment.  start is an offset into the specified 
  3040.       segment defining the start of the range.  end is an offset into the 
  3041.       specified segment defining the end of the range.  length is the number of 
  3042.       bytes from start to be included in the range.  All values are assumed to 
  3043.       be hexadecimal. 
  3044.  
  3045.  Notes: 
  3046.  
  3047.    1. If more than one class list or segment list is specified, only the last 
  3048.       one is used.  A class or segment list applies to all object and library 
  3049.       files regardless of their position relative to the class or segment list. 
  3050.  
  3051.    2. A range list applies only to the first object file following the range 
  3052.       specification.  If the object file contains more than one module, the 
  3053.       range list will only apply to the first module in the object file. 
  3054.  
  3055.  The following examples illustrate the use of the Watcom Far Call Optimization 
  3056.  Enabling Utility. 
  3057.  
  3058.  Example: 
  3059.  
  3060.     fcenable /c code *.obj 
  3061.  
  3062.  In the above example, the far call optimization will be enabled for all 
  3063.  segments belonging to the "code" class. 
  3064.  
  3065.  Example: 
  3066.  
  3067.     fcenable /s _text *.obj 
  3068.  
  3069.  In the above example, the far call optimization will be enabled for all 
  3070.  segments with name "_text". 
  3071.  
  3072.  Example: 
  3073.  
  3074.     fcenable /x special 0:400 asmfile.obj 
  3075.  
  3076.  In the above example, the far call optimization will be disabled for the first 
  3077.  1k bytes of the segment named "special" in the object file "asmfile". 
  3078.  
  3079.  Example: 
  3080.  
  3081.     fcenable /x special 0-ffffffff asmfile.obj 
  3082.  
  3083.  In the above example, the far call optimization will be disabled for the 
  3084.  entire segment named "special" in the object file "asmfile". 
  3085.  
  3086.  
  3087. ΓòÉΓòÉΓòÉ 6. The Watcom Patch Utility ΓòÉΓòÉΓòÉ
  3088.  
  3089.  
  3090.  
  3091. The Watcom Patch Utility is a utility program which may be used to apply 
  3092. patches or bug fixes to Watcom's compilers and its associated tools.  As 
  3093. problems are reported and fixed, patches are created and made available on 
  3094. Watcom's BBS, Watcom's FTP site, or CompuServe for users to download and apply 
  3095. to their copy of the tools. 
  3096.  
  3097.  
  3098. ΓòÉΓòÉΓòÉ 6.1. Applying a Patch ΓòÉΓòÉΓòÉ
  3099.  
  3100.  
  3101. The format of the BPATCH command line is: 
  3102.  
  3103.  
  3104.    BPATCH [options] patch_file 
  3105.  
  3106. The square brackets [ ] denote items which are optional. 
  3107.  
  3108.  where 
  3109.       description 
  3110.  
  3111.  options 
  3112.       is a list of valid Watcom Patch Utility options, each preceded by a dash 
  3113.       ("-").  Options may be specified in any order.  The possible options are: 
  3114.  
  3115.       -p 
  3116.                 Do not prompt for confirmation 
  3117.  
  3118.       -b 
  3119.                 Do not create a .BAK file 
  3120.  
  3121.       -q 
  3122.                 Print current patch level of file 
  3123.  
  3124.  patch_file 
  3125.       is the file specification for a patch file provided by Watcom. 
  3126.  
  3127.  Suppose a patch file called "wlink.a" is supplied by Watcom to fix a bug in 
  3128.  the file "WLINK.EXE".  The patch may be applied by typing the command: 
  3129.  
  3130.  
  3131.     bpatch wlink.a 
  3132.  
  3133.  The Watcom Patch Utility locates the file C:\WATCOM\BINW\WLINK.EXE using the 
  3134.  PATH environment variable.  The actual name of the executable file is 
  3135.  extracted from the file WLINK.A.  It then verifies that the file to be patched 
  3136.  is the correct one by comparing the size of the file to be patched to the 
  3137.  expected size.  If the file sizes match, the program responds with: 
  3138.  
  3139.  
  3140.     Ok to modify 'C:\WATCOM\BINW\WLINK.EXE'? [y|n] 
  3141.  
  3142.  If you respond with "yes", BPATCH will modify the indicated file.  If you 
  3143.  respond with "no", BPATCH aborts.  Once the patch has been applied the 
  3144.  resulting file is verified.  First the file size is checked to make sure it 
  3145.  matches the expected file size.  If the file size matches, a check-sum is 
  3146.  computed and compared to the expected check-sum. 
  3147.  
  3148.  Notes: 
  3149.  
  3150.    1. If an error message is issued during the patch process, the file that you 
  3151.       specified to be patched will remain unchanged. 
  3152.  
  3153.    2. If a sequence of patch files exist, such as "wlink.a", "wlink.b" and 
  3154.       "wlink.c", the patches must be applied in order.  That is, "wlink.a" must 
  3155.       be applied first followed by "wlink.b" and finally "wlink.c". 
  3156.  
  3157.  
  3158. ΓòÉΓòÉΓòÉ 6.2. Diagnostic Messages ΓòÉΓòÉΓòÉ
  3159.  
  3160.  
  3161. If the patch cannot be successfully applied, one of the following error 
  3162. messages will be displayed. 
  3163.  
  3164.  Usage:  BPATCH {-p} {-q} {-b} <file> 
  3165.        -p = Do not prompt for confirmation 
  3166.  
  3167.       -b = Do not create a .BAK file 
  3168.       -q = Print current patch level of file 
  3169.       The command line was entered with no arguments. 
  3170.  
  3171.  File '%s' has not been patched 
  3172.       This message is issued when the "-q" option is used and the file has not 
  3173.       been patched. 
  3174.  
  3175.  File '%s' has been patched to level '%s' 
  3176.       This message is issued when the "-q" option is used and the file has been 
  3177.       patched to the indicated level. 
  3178.  
  3179.  File '%s' has already been patched to level '%s' - skipping 
  3180.       This message is issued when the file has already been patched to the same 
  3181.       level or higher. 
  3182.  
  3183.  Command line may only contain one file name 
  3184.       More than one file name is specified on the command line.  Make sure that 
  3185.       "/" is not used as an option delimiter. 
  3186.  
  3187.  Command line must specify a file name 
  3188.       No file name has been specified on the command line. 
  3189.  
  3190.  '%s' is not a Watcom patch file 
  3191.       The patch file is not of the required format.  The required header 
  3192.       information is not present. 
  3193.  
  3194.  '%s' is not a valid Watcom patch file 
  3195.       The patch file is not of the required format.  The required header 
  3196.       information is present but the remaining contents of the file have been 
  3197.       corrupted. 
  3198.  
  3199.  '%s' is the wrong size (%lu1).  Should be (%lu2) 
  3200.       The size of the file to be patched (%lu1) is not the same as the expected 
  3201.       size (%lu2). 
  3202.  
  3203.  Cannot find '%s' 
  3204.       Cannot find the executable to be patched. 
  3205.  
  3206.  Cannot open '%s' 
  3207.       An error occurred while trying to open the patch file, the file to be 
  3208.       patched or the resulting file. 
  3209.  
  3210.  Cannot read '%s' 
  3211.       An input error occurred while reading the old version of the file being 
  3212.       patched. 
  3213.  
  3214.  Cannot rename '%s' to '%s' 
  3215.       The file to be patched could not be renamed to the backup file name or 
  3216.       the resulting file could not be renamed to the name of the file that was 
  3217.       patched. 
  3218.  
  3219.  Cannot write to '%s' 
  3220.       An output error occurred while writing to the new version of the file to 
  3221.       be patched. 
  3222.  
  3223.  I/O error processing file '%s' 
  3224.       An error occurred while seeking in the specified file. 
  3225.  
  3226.  No memory for %s 
  3227.       An attempt to allocate memory dynamically failed. 
  3228.  
  3229.  Patch program aborted! 
  3230.       This message is issued if you answered no to the "OK to modify" prompt. 
  3231.  
  3232.  Resulting file has wrong checksum (%lu) - Should be (%lu2) 
  3233.       The check-sum of the resulting file (%lu) does not match the expected 
  3234.       check-sum (%lu2).  This message is issued if you have patched the wrong 
  3235.       version. 
  3236.  
  3237.  Resulting file has wrong size (%lu1) - Should be (%lu2) 
  3238.       The size of the resulting file (%lu1) does not match the expected size 
  3239.       (%lu2).  This message is issued if you have patched the wrong version. 
  3240.  
  3241.  
  3242. ΓòÉΓòÉΓòÉ 7. The Watcom Strip Utility ΓòÉΓòÉΓòÉ
  3243.  
  3244.  
  3245. The Watcom Strip Utility may be used to manipulate information that is appended 
  3246. to the end of an executable file.  The information can be either one of two 
  3247. things: 
  3248.  
  3249.    1. Symbolic debugging information 
  3250.  
  3251.    2. Resource information 
  3252.  
  3253.  This information can be added or removed from the executable file.  Symbolic 
  3254.  debugging information is placed at the end of an executable file by the Watcom 
  3255.  Linker or the Watcom Strip Utility.  Resource information is placed at the end 
  3256.  of an executable by a resource compiler or the Watcom Strip Utility. 
  3257.  
  3258.  Once a program has been debugged, the Watcom Strip Utility allows you to 
  3259.  remove the debugging information from the executable file so that you do not 
  3260.  have to remove the debugging directives from the linker directive file and 
  3261.  link your program again.  Removal of the debugging information reduces the 
  3262.  size of the executable image. 
  3263.  
  3264.  All executable files generated by the Watcom Linker can be specified as input 
  3265.  to the Watcom Strip Utility.  Note that for executable files created for 
  3266.  Novell's NetWare 386 operating system, debugging information created using the 
  3267.  "NOVELL" option in the "DEBUG" directive cannot be removed from the executable 
  3268.  file.  You must remove the "DEBUG" directive from the directive file and 
  3269.  re-link your application. 
  3270.  
  3271.  The Watcom Strip Utility currently runs under the following operating systems. 
  3272.  
  3273.      DOS 
  3274.      OS/2 
  3275.      QNX 
  3276.      Windows NT 
  3277.      Windows 95 
  3278.  
  3279.  
  3280. ΓòÉΓòÉΓòÉ 7.1. The Watcom Strip Utility Command Line ΓòÉΓòÉΓòÉ
  3281.  
  3282.  
  3283. The Watcom Strip Utility command line syntax is: 
  3284.  
  3285.  
  3286.    WSTRIP [options] input_file [output_file] [info_file] 
  3287.  
  3288.  where: 
  3289.  
  3290.  [] 
  3291.       The square brackets denote items which are optional. 
  3292.  
  3293.  options 
  3294.  
  3295.       /n 
  3296.                 (noerrors) Do not issue any diagnostic message. 
  3297.  
  3298.       /q 
  3299.                 (quiet) Do not print any informational messages. 
  3300.  
  3301.       /r 
  3302.                 (resources) Process resource information rather than debugging 
  3303.                 information. 
  3304.  
  3305.       /a 
  3306.                 (add) Add information rather than remove information. 
  3307.  
  3308.  input_file 
  3309.       is a file specification for the name of an executable file.  If no file 
  3310.       extension is specified, the Watcom Strip Utility will assume one of the 
  3311.       following extensions:  "exe", "dll", "exp", "rex", "nlm", "dsk", "lan", 
  3312.       "nam", "qnx" or no file extension.  Note that the order specified in the 
  3313.       list of file extensions is the order in which the Watcom Strip Utility 
  3314.       will select file extensions. 
  3315.  
  3316.  output_file 
  3317.       is an optional file specification for the output file.  If no file 
  3318.       extension is specified, the file extension specified in the input file 
  3319.       name will be used for the output file name.  If "." is specified, the 
  3320.       input file name will be used. 
  3321.  
  3322.  info_file 
  3323.       is an optional file specification for the file in which the debugging or 
  3324.       resource information is to be stored (when removing information) or read 
  3325.       (when adding information).  If no file extension is specified, a file 
  3326.       extension of "sym" is assumed for debugging information and "res" for 
  3327.       resource information.  To specify the name of the information file but 
  3328.       not the name of an output file, a "." may be specified in place of 
  3329.       output_file. 
  3330.  
  3331.  Description: 
  3332.  
  3333.    1. If the "r" (resource) option is not specified then the default action is 
  3334.       to add/remove symbolic debugging information. 
  3335.  
  3336.    2. If the "a" (add) option is not specified then the default action is to 
  3337.       remove information. 
  3338.  
  3339.    3. If output_file is not specified, the debugging or resource information is 
  3340.       added to or removed from input_file. 
  3341.  
  3342.    4. If output_file is specified, input_file is copied to output_file and the 
  3343.       debugging or resource information is added to or removed from 
  3344.       output_file.  input_file remains unchanged. 
  3345.  
  3346.    5. If info_file is specified then the debugging or resource information that 
  3347.       is added to or removed from the executable file is read from or written 
  3348.       to this file.  The debugging or resource information may be appended to 
  3349.       the executable by specifying the "a" (add) option.  Also, the debugging 
  3350.       information may be appended to the executable by concatenating the 
  3351.       debugging information file to the end of the executable file (the files 
  3352.       must be treated as binary files). 
  3353.  
  3354.    6. During processing, the Watcom Strip Utility will create a temporary file, 
  3355.       ensuring that a file by the chosen name does not already exist. 
  3356.  
  3357.  
  3358. ΓòÉΓòÉΓòÉ 7.2. Strip Utility Messages ΓòÉΓòÉΓòÉ
  3359.  
  3360.  
  3361. The following messages may be issued by the Watcom Strip Utility. 
  3362.  
  3363.  Usage:  WSTRIP [options] input_file [output_file] [info_file] 
  3364.        options:  (-option is also accepted) 
  3365.  
  3366.          /n   don't print warning messages 
  3367.          /q   don't print informational messages 
  3368.          /r   process resource information rather than debugging information 
  3369.          /a   add information rather than delete information 
  3370.       input_file:  executable file 
  3371.       output_file:  optional output executable or '.' 
  3372.       info_file:  optional output debugging or resource information file 
  3373.              or input debugging or resource informational file 
  3374.       The command line was entered with no arguments. 
  3375.  
  3376.  Too low on memory 
  3377.       There is not enough free memory to allocate file buffers. 
  3378.  
  3379.  Unable to find '%s' 
  3380.       The specified file could not be located. 
  3381.  
  3382.  Cannot create temporary file 
  3383.       All the temporary file names are in use. 
  3384.  
  3385.  Unable to open '%s' to read 
  3386.       The input executable file cannot be opened for reading. 
  3387.  
  3388.  '%s' is not a valid executable file 
  3389.       The input file has invalid executable file header information. 
  3390.  
  3391.  '%s' does not contain debugging information 
  3392.       There is nothing to strip from the specified executable file. 
  3393.  
  3394.  Seek error on '%s' 
  3395.       An error occurred during a seek operation on the specified file. 
  3396.  
  3397.  Unable to create output file '%s' 
  3398.       The output file could not be created.  Check that the output disk is not 
  3399.       write-protected or that the specified output file is not marked 
  3400.       "read-only". 
  3401.  
  3402.  Unable to create symbol file '%s' 
  3403.       The symbol file could not be created. 
  3404.  
  3405.  Error reading '%s' 
  3406.       An error occurred while reading the input executable file. 
  3407.  
  3408.  Error writing to '%s' 
  3409.       An error occurred while writing the output executable file or the symbol 
  3410.       file.  Check the amount of free space on the output disk.  If the input 
  3411.       and output files reside on the same disk, there might not be enough room 
  3412.       for a second copy of the executable file during processing. 
  3413.  
  3414.  Cannot erase file '%s' 
  3415.       The input executable file is probably marked "read-only" and therefore 
  3416.       could not be erased (the input file is erased whenever the output file 
  3417.       has the same name). 
  3418.  
  3419.  Cannot rename file '%s' 
  3420.       The output executable file could not be renamed.  Ordinarily, this should 
  3421.       never occur. 
  3422.  
  3423.  
  3424. ΓòÉΓòÉΓòÉ 8. The Watcom Make Utility ΓòÉΓòÉΓòÉ
  3425.  
  3426.  
  3427. The Watcom Make utility is useful in the development of programs and text 
  3428. processing but is general enough to be used in many different applications. 
  3429. Make uses the fact that each file has a time-stamp associated with it that 
  3430. indicates the last time the file was updated.  Make uses this time-stamp to 
  3431. decide which files are out of date with respect to each other.  For instance, 
  3432. if we have an input data file and an output report file we would like the 
  3433. output report file to accurately reflect the contents of the input data file. 
  3434. In terms of time-stamps, we would like the output report to have a more recent 
  3435. time-stamp than the input data file (we will say that the output report file 
  3436. should be "younger" than the input data file).  If the input file had been 
  3437. modified then we would know from the younger time-stamp (in comparison to the 
  3438. report file) that the report file was out of date and should be updated.  Make 
  3439. may be used in this and many other situations to ensure that files are kept up 
  3440. to date. 
  3441.  
  3442. Some readers will be quite familiar with the concepts of the Make file 
  3443. maintenance tool.  Watcom Make is patterned after the Make utility found on 
  3444. UNIX systems.  The next major section is simply intended to summarize, for 
  3445. reference purposes only, the syntax and options of Make's command line and 
  3446. special macros.  Subsequent sections go into the philosophy and capabilities of 
  3447. Watcom Make.  If you are not familiar with the capabilities of the Make 
  3448. utility, we recommend that you skip to the next major section entitled 
  3449. "Dependency Declarations" and read on. 
  3450.  
  3451.  
  3452. ΓòÉΓòÉΓòÉ 8.1. Watcom Make Reference ΓòÉΓòÉΓòÉ
  3453.  
  3454.  
  3455. The following sub-sections serve as a reference guide to the Watcom Make 
  3456. utility. 
  3457.  
  3458.  
  3459. ΓòÉΓòÉΓòÉ 8.1.1. Watcom Make Command Line Format ΓòÉΓòÉΓòÉ
  3460.  
  3461.  
  3462. The formal Watcom Make command line syntax is shown below. 
  3463.  
  3464.  
  3465.    WMAKE [options] [macro_defs] [targets] 
  3466.  
  3467. As indicated by the square brackets [ ], all items are optional. 
  3468.  
  3469.  options 
  3470.       is a list of valid Watcom Make options, each preceded by a slash ("/") or 
  3471.       a dash ("-").  Options may be specified in any order. 
  3472.  
  3473.  macro_defs 
  3474.       is a list of valid Watcom Make macro definitions.  Macro definitions are 
  3475.       of the form: 
  3476.  
  3477.  
  3478.          A=B 
  3479.  
  3480.       and are readily identified by the presence of the "=" (the "#" character 
  3481.       may be used instead of the "=" character if necessary).  Surround the 
  3482.       definition with quotes (") if it contains blanks (e.g., "debug_opt=debug 
  3483.       all").  The macro definitions specified on the command line supersede any 
  3484.       macro definitions defined in makefiles. 
  3485.  
  3486.  targets 
  3487.       is one or more targets described in the makefile. 
  3488.  
  3489.  
  3490. ΓòÉΓòÉΓòÉ 8.1.2. Watcom Make Options Summary ΓòÉΓòÉΓòÉ
  3491.  
  3492.  
  3493. In this section, we present a terse summary of the Watcom Make options.  This 
  3494. summary is displayed on the screen by simply entering "WMAKE ?" on the command 
  3495. line. 
  3496.  
  3497. Example: 
  3498.  
  3499.    C>wmake ? 
  3500.  
  3501.  /a 
  3502.       make all targets by ignoring time-stamps 
  3503.  
  3504.  /b 
  3505.       block/ignore all implicit rules 
  3506.  
  3507.  /c 
  3508.       do not verify the existence of files made 
  3509.  
  3510.  /d 
  3511.       debug mode - echo all work as it progresses 
  3512.  
  3513.  /e 
  3514.       always erase target after error/interrupt (disables prompting) 
  3515.  
  3516.  /f 
  3517.       the next parameter is a name of dependency description file 
  3518.  
  3519.  /h 
  3520.       do not print out Make identification lines (no header) 
  3521.  
  3522.  /i 
  3523.       ignore return status of all commands executed 
  3524.  
  3525.  /k 
  3526.       on error/interrupt:  continue on next target 
  3527.  
  3528.  /l 
  3529.       the next parameter is the name of a output log file 
  3530.  
  3531.  /m 
  3532.       do not search for MAKEINIT file 
  3533.  
  3534.  /ms 
  3535.       Microsoft NMAKE mode 
  3536.  
  3537.  /n 
  3538.       no execute mode - print commands without executing 
  3539.  
  3540.  /o 
  3541.       use circular implicit rule path 
  3542.  
  3543.  /p 
  3544.       print the dependency tree as understood from the file 
  3545.  
  3546.  /q 
  3547.       query mode - check targets without updating them 
  3548.  
  3549.  /r 
  3550.       do not use default definitions 
  3551.  
  3552.  /s 
  3553.       silent mode - do not print commands before execution 
  3554.  
  3555.  /t 
  3556.       touch files instead of executing commands 
  3557.  
  3558.  /u 
  3559.       UNIX compatibility mode 
  3560.  
  3561.  /z 
  3562.       do not erase target after error/interrupt (disables prompting) 
  3563.  
  3564.  
  3565. ΓòÉΓòÉΓòÉ 8.1.3. Command Line Options ΓòÉΓòÉΓòÉ
  3566.  
  3567.  
  3568. Command line options, available with Watcom Make, allow you to control the 
  3569. processing of the makefile. 
  3570.  
  3571.  
  3572. ΓòÉΓòÉΓòÉ 8.1.3.1. a ΓòÉΓòÉΓòÉ
  3573.  
  3574.  
  3575. make all targets by ignoring time-stamps 
  3576. The "a" option is a safe way to update every target.  For program maintenance, 
  3577. it is the preferred method over deleting object files or touching source files. 
  3578.  
  3579.  
  3580. ΓòÉΓòÉΓòÉ 8.1.3.2. b ΓòÉΓòÉΓòÉ
  3581.  
  3582.  
  3583. block/ignore all implicit rules 
  3584. The "b" option will indicate to Make that you do not want any implicit rule 
  3585. checking done.  The "b" option is useful in makefiles containing double colon 
  3586. "::" explicit rules because an implicit rule search is conducted after a double 
  3587. colon "::" target is updated.  Including the directive .BLOCK in a makefile 
  3588. also will disable implicit rule checking. 
  3589.  
  3590.  
  3591. ΓòÉΓòÉΓòÉ 8.1.3.3. c ΓòÉΓòÉΓòÉ
  3592.  
  3593.  
  3594. do not verify the existence of files made 
  3595. Make will check to ensure that a target exists after the associated command 
  3596. list is executed.  The target existence checking may be disabled with the "c" 
  3597. option.  The "c" option is useful in processing makefiles that were developed 
  3598. with other Make utilities.  The .NOCHECK directive may be used to disable 
  3599. target existence in a makefile. 
  3600.  
  3601.  
  3602. ΓòÉΓòÉΓòÉ 8.1.3.4. d ΓòÉΓòÉΓòÉ
  3603.  
  3604.  
  3605. debug mode - echo all work as it progresses 
  3606. The "d" option will print out information about the time-stamp of files and 
  3607. indicate how the makefile processing is proceeding. 
  3608.  
  3609.  
  3610. ΓòÉΓòÉΓòÉ 8.1.3.5. e ΓòÉΓòÉΓòÉ
  3611.  
  3612.  
  3613. always erase target after error/interrupt (disables prompting) 
  3614. The "e" option will indicate to Make that, if an error or interrupt occurs 
  3615. during makefile processing, the current target being made may be deleted 
  3616. without prompting.  The .ERASE directive may be used as an equivalent option in 
  3617. a makefile. 
  3618.  
  3619.  
  3620. ΓòÉΓòÉΓòÉ 8.1.3.6. f ΓòÉΓòÉΓòÉ
  3621.  
  3622.  
  3623. the next parameter is a name of dependency description file 
  3624. The "f" option specifies that the next parameter on the command line is the 
  3625. name of a makefile which must be processed.  If the "f" option is specified 
  3626. then the search for the default makefile named "MAKEFILE" is not done.  Any 
  3627. number of makefiles may be processed with the "f" option. 
  3628.  
  3629. Example: 
  3630.  
  3631.    wmake /f myfile 
  3632.    wmake /f myfile1 /f myfile2 
  3633.  
  3634.  
  3635. ΓòÉΓòÉΓòÉ 8.1.3.7. h ΓòÉΓòÉΓòÉ
  3636.  
  3637.  
  3638. do not print out Make identification lines (no header) 
  3639. The "h" option is useful for less verbose output.  Combined with the "q" 
  3640. option, this allows a batch file to silently query if an application is up to 
  3641. date.  Combined with the "n" option, a batch file could be produced containing 
  3642. the commands necessary to update the application. 
  3643.  
  3644.  
  3645. ΓòÉΓòÉΓòÉ 8.1.3.8. i ΓòÉΓòÉΓòÉ
  3646.  
  3647.  
  3648. ignore return status of all commands executed 
  3649. The "i" option is equivalent to the .IGNORE directive. 
  3650.  
  3651.  
  3652. ΓòÉΓòÉΓòÉ 8.1.3.9. k ΓòÉΓòÉΓòÉ
  3653.  
  3654.  
  3655. on error/interrupt:  continue on next target 
  3656. Make will stop updating targets when a non-zero status is returned by a 
  3657. command.  The "k" option will continue processing targets that do not depend on 
  3658. the target that caused the error.  The .CONTINUE directive in a makefile will 
  3659. enable this error handling capability. 
  3660.  
  3661.  
  3662. ΓòÉΓòÉΓòÉ 8.1.3.10. l ΓòÉΓòÉΓòÉ
  3663.  
  3664.  
  3665. the next parameter is the name of a output log file 
  3666. Make will output an error message when a non-zero status is returned by a 
  3667. command.  The "l" option specifies a file that will record all error messages 
  3668. output by Make during the processing of the makefile. 
  3669.  
  3670.  
  3671. ΓòÉΓòÉΓòÉ 8.1.3.11. m ΓòÉΓòÉΓòÉ
  3672.  
  3673.  
  3674. do not search for the MAKEINIT file 
  3675. The default action for Make is to search for an initialization file called 
  3676. "MAKEINIT".  The "m" option will indicate to Make that processing of the 
  3677. MAKEINIT file is not desired. 
  3678.  
  3679.  
  3680. ΓòÉΓòÉΓòÉ 8.1.3.12. ms ΓòÉΓòÉΓòÉ
  3681.  
  3682.  
  3683. Microsoft NMAKE mode 
  3684. The default action for Make is to process makefiles using Watcom syntax rules. 
  3685. The "ms" option will indicate to Make that it should process makefiles using 
  3686. Microsoft syntax rules.  For example, the line continuation in NMAKE is a 
  3687. backslash ("\") at the end of the line. 
  3688.  
  3689.  
  3690. ΓòÉΓòÉΓòÉ 8.1.3.13. n ΓòÉΓòÉΓòÉ
  3691.  
  3692.  
  3693. no execute mode - print commands without executing 
  3694. The "n" option will print out what commands should be executed to update the 
  3695. application without actually executing them.  Combined with the "h" option, a 
  3696. batch file could be produced which would contain the commands necessary to 
  3697. update the application. 
  3698.  
  3699. Example: 
  3700.  
  3701.    wmake /h /n >update.bat 
  3702.    update 
  3703.  
  3704. This is useful for applications which require all available resources (memory 
  3705. and devices) for executing the updating commands. 
  3706.  
  3707.  
  3708. ΓòÉΓòÉΓòÉ 8.1.3.14. o ΓòÉΓòÉΓòÉ
  3709.  
  3710.  
  3711. use circular implicit rule path 
  3712. When this option is specified, Make will use a circular path specification 
  3713. search which may save on disk activity for large makefiles.  The "o" option is 
  3714. equivalent to the .OPTIMIZE directive. 
  3715.  
  3716.  
  3717. ΓòÉΓòÉΓòÉ 8.1.3.15. p ΓòÉΓòÉΓòÉ
  3718.  
  3719.  
  3720. print out makefile information 
  3721. The "p" option will cause Make to print out information about all the explicit 
  3722. rules, implicit rules, and macro definitions. 
  3723.  
  3724.  
  3725. ΓòÉΓòÉΓòÉ 8.1.3.16. q ΓòÉΓòÉΓòÉ
  3726.  
  3727.  
  3728. query mode - check targets without updating them 
  3729. The "q" option will cause Make to return a status of 1 if the application 
  3730. requires updating; it will return a status of 0 otherwise.  Here is a example 
  3731. batch file using the "q" option: 
  3732.  
  3733. Example: 
  3734.  
  3735.    wmake /q 
  3736.    if errorstatus 0 goto noupdate 
  3737.    wmake /q /h /n >\tmp\update.bat 
  3738.    call \tmp\update.bat 
  3739.    :noupdate 
  3740.  
  3741.  
  3742. ΓòÉΓòÉΓòÉ 8.1.3.17. r ΓòÉΓòÉΓòÉ
  3743.  
  3744.  
  3745. do not use default definitions 
  3746. The default definitions are: 
  3747.  
  3748.  
  3749.    __MAKEOPTS__ = <options passed to WMAKE> 
  3750.    __MAKEFILES__ = <list of makefiles> 
  3751.    __VERSION__ = <version number> 
  3752.    __LOADDLL__= defined if DLL loading supported 
  3753.    __MSDOS__ =  defined if MS/DOS version 
  3754.    __WINDOWS__ = defined if Windows version 
  3755.    __NT__ = defined if Windows NT version 
  3756.    __NT386__ = defined if 32-bit Windows NT version 
  3757.    __OS2__ = defined if OS/2 version 
  3758.    __QNX__ = defined if QNX version 
  3759.    #endif 
  3760.    # clear .EXTENSIONS list 
  3761.    .EXTENSIONS: 
  3762.  
  3763.    # In general, 
  3764.    # set .EXTENSIONS list as follows 
  3765.    .EXTENSIONS: .exe .nlm .dsk .lan .exp & 
  3766.          .lib .obj & 
  3767.          .i & 
  3768.          .asm .c .cpp .cxx .cc .for .pas .cob & 
  3769.          .h .hpp .hxx .hh .fi .mif .inc 
  3770.  
  3771. For Microsoft NMAKE compatibility (when you use the "ms" option), the following 
  3772. default definitions are established. 
  3773.  
  3774.  
  3775.    # For Microsoft NMAKE compatibility switch, 
  3776.    # set .EXTENSIONS list as follows 
  3777.    .EXTENSIONS: .exe .obj .asm .c .cpp .cxx & 
  3778.          .bas .cbl .for .f .f90 .pas .res .rc 
  3779.  
  3780.    AS=ml 
  3781.    BC=bc 
  3782.    CC=cl 
  3783.    COBOL=cobol 
  3784.    CPP=cl 
  3785.    CXX=cl 
  3786.    FOR=fl 
  3787.    PASCAL=pl 
  3788.    RC=rc 
  3789.    .asm.exe: 
  3790.      $(AS) $(AFLAGS) $*.asm 
  3791.    .asm.obj: 
  3792.      $(AS) $(AFLAGS) /c $*.asm 
  3793.    .c.exe: 
  3794.      $(CC) $(CFLAGS) $*.c 
  3795.    .c.obj: 
  3796.      $(CC) $(CFLAGS) /c $*.c 
  3797.    .cpp.exe: 
  3798.      $(CPP) $(CPPFLAGS) $*.cpp 
  3799.    .cpp.obj: 
  3800.      $(CPP) $(CPPFLAGS) /c $*.cpp 
  3801.    .cxx.exe: 
  3802.      $(CXX) $(CXXFLAGS) $*.cxx 
  3803.    .cxx.obj: 
  3804.      $(CXX) $(CXXFLAGS) $*.cxx 
  3805.    .bas.obj: 
  3806.      $(BC) $(BFLAGS) $*.bas 
  3807.    .cbl.exe: 
  3808.      $(COBOL) $(COBFLAGS) $*.cbl, $*.exe; 
  3809.    .cbl.obj: 
  3810.      $(COBOL) $(COBFLAGS) $*.cbl; 
  3811.    .f.exe: 
  3812.      $(FOR) $(FFLAGS) $*.f 
  3813.    .f.obj: 
  3814.      $(FOR) /c $(FFLAGS) $*.f 
  3815.    .f90.exe: 
  3816.      $(FOR) $(FFLAGS) $*.f90 
  3817.    .f90.obj: 
  3818.      $(FOR) /c $(FFLAGS) $*.f90 
  3819.    .for.exe: 
  3820.      $(FOR) $(FFLAGS) $*.for 
  3821.    .for.obj: 
  3822.      $(FOR) /c $(FFLAGS) $*.for 
  3823.    .pas.exe: 
  3824.      $(PASCAL) $(PFLAGS) $*.pas 
  3825.    .pas.obj: 
  3826.      $(PASCAL) /c $(PFLAGS) $*.pas 
  3827.    .rc.res: 
  3828.      $(RC) $(RFLAGS) /r $* 
  3829.  
  3830. For OS/2, the __MSDOS__ macro will be replaced by __OS2__ and for Windows NT, 
  3831. the __MSDOS__ macro will be replaced by __NT__.  The "r" option will disable 
  3832. these definitions before processing any makefiles. 
  3833.  
  3834.  
  3835. ΓòÉΓòÉΓòÉ 8.1.3.18. s ΓòÉΓòÉΓòÉ
  3836.  
  3837.  
  3838. silent mode - do not print commands before execution 
  3839. The "s" option is equivalent to the .SILENT directive. 
  3840.  
  3841.  
  3842. ΓòÉΓòÉΓòÉ 8.1.3.19. t ΓòÉΓòÉΓòÉ
  3843.  
  3844.  
  3845. touch files instead of executing commands 
  3846. Sometimes there are changes which are purely cosmetic (adding a comment to a 
  3847. source file) that will cause targets to be updated needlessly thus wasting 
  3848. computer resources.  The "t" option will make files appear younger without 
  3849. altering their contents.  The "t" option is useful but should be used with 
  3850. caution. 
  3851.  
  3852.  
  3853. ΓòÉΓòÉΓòÉ 8.1.3.20. u ΓòÉΓòÉΓòÉ
  3854.  
  3855.  
  3856. UNIX compatibility mode 
  3857. The "u" option will indicate to Make that the line continuation character 
  3858. should be a backslash "\" rather than an ampersand "&". 
  3859.  
  3860.  
  3861. ΓòÉΓòÉΓòÉ 8.1.3.21. z ΓòÉΓòÉΓòÉ
  3862.  
  3863.  
  3864. do not erase target after error/interrupt (disables prompting) 
  3865. The "z" option will indicate to Make that if an error or interrupt occurs 
  3866. during makefile processing then the current target being made should not be 
  3867. deleted.  The .HOLD directive in a makefile has the same effect as the "z" 
  3868. option. 
  3869.  
  3870.  
  3871. ΓòÉΓòÉΓòÉ 8.1.4. Special Macros ΓòÉΓòÉΓòÉ
  3872.  
  3873.  
  3874. Watcom Make has many different special macros.  Here are some of the simpler 
  3875. ones. 
  3876.  
  3877.  $$ 
  3878.       represents the character "$" 
  3879.  
  3880.  $# 
  3881.       represents the character "#" 
  3882.  
  3883.  $@ 
  3884.       full file name of the target 
  3885.  
  3886.  $* 
  3887.       target with the extension removed 
  3888.  
  3889.  $< 
  3890.       list of all dependents 
  3891.  
  3892.  $? 
  3893.       list of dependents that are younger than the target 
  3894.  
  3895.  The following macros are for more sophisticated makefiles. 
  3896.  
  3897.  __MSDOS__ 
  3898.       This macro is defined in the MS/DOS environment. 
  3899.  
  3900.  __NT__ 
  3901.       This macro is defined in the Windows NT environment. 
  3902.  
  3903.  __OS2__ 
  3904.       This macro is defined in the OS/2 environment. 
  3905.  
  3906.  __MAKEOPTS__ 
  3907.       contains all of the command line options that WMAKE was invoked with 
  3908.       except for the "f" options 
  3909.  
  3910.  __MAKEFILES__ 
  3911.       contains the names of all of the makefiles processed at the time of 
  3912.       expansion (includes the file currently being processed) 
  3913.  
  3914.  The next three tables contain macros that are valid during execution of 
  3915.  command lists for explicit rules, implicit rules, and the .ERROR directive. 
  3916.  The expansion is presented for the following example: 
  3917.  
  3918.  Example: 
  3919.  
  3920.     a:\dir\target.ext : b:\dir1\dep1.ex1 c:\dir2\dep2.ex2 
  3921.  
  3922.  $^@ 
  3923.       a:\dir\target.ext 
  3924.  
  3925.  $^* 
  3926.       a:\dir\target 
  3927.  
  3928.  $^& 
  3929.       target 
  3930.  
  3931.  $^. 
  3932.       target.ext 
  3933.  
  3934.  $^: 
  3935.       a:\dir\ 
  3936.  
  3937.  $[@ 
  3938.       b:\dir1\dep1.ex1 
  3939.  
  3940.  $[* 
  3941.       b:\dir1\dep1 
  3942.  
  3943.  $[& 
  3944.       dep1 
  3945.  
  3946.  $[. 
  3947.       dep1.ex1 
  3948.  
  3949.  $[: 
  3950.       b:\dir1\ 
  3951.  
  3952.  $]@ 
  3953.       c:\dir2\dep2.ex2 
  3954.  
  3955.  $]* 
  3956.       c:\dir2\dep2 
  3957.  
  3958.  $]& 
  3959.       dep2 
  3960.  
  3961.  $]. 
  3962.       dep2.ex2 
  3963.  
  3964.  $]: 
  3965.       c:\dir2\ 
  3966.  
  3967.  
  3968. ΓòÉΓòÉΓòÉ 8.2. Dependency Declarations ΓòÉΓòÉΓòÉ
  3969.  
  3970.  
  3971. In order for Watcom Make to be effective, a list of file dependencies must be 
  3972. declared.  The declarations may be entered into a text file of any name but 
  3973. Make will read a file called "MAKEFILE" by default if it is invoked as follows: 
  3974.  
  3975. Example: 
  3976.  
  3977.    C>wmake 
  3978.  
  3979. If you want to use a file that is not called "MAKEFILE" then the command line 
  3980. option "f" will cause Make to read the specified file instead of the default 
  3981. "MAKEFILE". 
  3982.  
  3983. Example: 
  3984.  
  3985.    C>wmake /f myfile 
  3986.  
  3987. We will now go through an example to illustrate how Make may be used for a 
  3988. simple application.  Suppose we have an input file, a report file, and a report 
  3989. generator program then we may declare a dependency as follows: 
  3990.  
  3991.  
  3992.    # 
  3993.    # (a comment in a makefile starts with a "#") 
  3994.    # simple dependency declaration 
  3995.    # 
  3996.    balance.lst : ledger.dat 
  3997.        doreport 
  3998.  
  3999. Note that the dependency declaration starts at the beginning of a line while 
  4000. commands always have at least one blank or tab before them.  This form of a 
  4001. dependency declaration is called an explicit rule.  The file "BALANCE.LST" is 
  4002. called the target of the rule.  The dependent of the rule is the file 
  4003. "LEDGER.DAT" while "DOREPORT" forms one line of the rule command list.  The 
  4004. dependent is separated from the target by a colon. 
  4005.  
  4006. Hint:  A good habit to develop is to always put spaces around the colon so that 
  4007. it will not be confused with drive specifications (e.g., a:). 
  4008.  
  4009. The explicit rule declaration indicates to Make that the program "DOREPORT" 
  4010. should be executed if "LEDGER.DAT" is younger than "BALANCE.LST" or if 
  4011. "BALANCE.LST" does not yet exist.  In general, if the dependent file has a more 
  4012. recent modification date and time than the target file then Watcom Make will 
  4013. execute the specified command. 
  4014.  
  4015. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4016.  
  4017.  Note:  The terminology employed here is used by S.I.Feldman of Bell 
  4018. Laboratories in Make - A Program for Maintaining Computer Programs.  Confusion 
  4019. often arises from the use of the word "dependent".  In this context, it means 
  4020. "a subordinate part".  In the example, "LEDGER.DAT" is a subordinate part of 
  4021. the report "BALANCE.LST". 
  4022.  
  4023. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  4024.  
  4025.  
  4026. ΓòÉΓòÉΓòÉ 8.3. Multiple Dependents ΓòÉΓòÉΓòÉ
  4027.  
  4028.  
  4029. Suppose that our report "BALANCE.LST" becomes out-of-date if any of the files 
  4030. "LEDGER.DAT", "SALES.DAT" or "PURCHASE.DAT" are modified.  We may modify the 
  4031. dependency rule as follows: 
  4032.  
  4033.  
  4034.    # 
  4035.    # multiple dependents rule 
  4036.    # 
  4037.    balance.lst : ledger.dat sales.dat purchase.dat 
  4038.        doreport 
  4039.  
  4040. This is an example of a rule with multiple dependents.  In this situation, the 
  4041. program "DOREPORT" should be executed if any of "LEDGER.DAT", "SALES.DAT" or 
  4042. "PURCHASE.DAT" are younger than "BALANCE.LST" or if "BALANCE.LST" does not yet 
  4043. exist.  In cases where there are multiple dependents, if any of the dependent 
  4044. files has a more recent modification date and time than the target file then 
  4045. Watcom Make will execute the specified command. 
  4046.  
  4047.  
  4048. ΓòÉΓòÉΓòÉ 8.4. Multiple Targets ΓòÉΓòÉΓòÉ
  4049.  
  4050.  
  4051. Suppose that the "DOREPORT" program produces two reports.  If both of these 
  4052. reports require updating as a result of modification to the dependent files, we 
  4053. could change the rule as follows: 
  4054.  
  4055.  
  4056.    # 
  4057.    # multiple targets and multiple dependents rule 
  4058.    # 
  4059.    balance.lst summary.lst : ledger.dat sales.dat purchase.dat 
  4060.        doreport 
  4061.  
  4062. Suppose that you entered the command: 
  4063.  
  4064.  
  4065.    wmake 
  4066.  
  4067. which causes Make to start processing the rules described in "MAKEFILE".  In 
  4068. the case where multiple targets are listed in the makefile, Make will, by 
  4069. default, process only the first target it encounters.  In the example, Make 
  4070. will check the date and time of "BALANCE.LST" against its dependents since this 
  4071. is the first target listed. 
  4072.  
  4073. To indicate that some other target should be processed, the target is specified 
  4074. as an argument to the Make command. 
  4075.  
  4076. Example: 
  4077.  
  4078.    wmake summary.lst 
  4079.  
  4080. There are a number of interesting points to consider: 
  4081.  
  4082.    1. By default, Make will only check that the target file exists after the 
  4083.       command ("DOREPORT" in this example) is executed.  It does not check that 
  4084.       the target's time-stamp shows it to be younger.  If the target file does 
  4085.       not exist after the command has been executed, an error is reported. 
  4086.  
  4087.    2. There is no guarantee that the command you have specified does update the 
  4088.       target file.  In other words, simply because you have stated a dependency 
  4089.       does not mean that one exists. 
  4090.  
  4091.    3. Furthermore, it is not implied that other targets in our list will not be 
  4092.       updated.  In the case of our example, you can assume that we have 
  4093.       designed the "doreport" command to update both targets. 
  4094.  
  4095.  
  4096. ΓòÉΓòÉΓòÉ 8.5. Multiple Rules ΓòÉΓòÉΓòÉ
  4097.  
  4098.  
  4099. A makefile may consist of any number of rules.  Note that the following: 
  4100.  
  4101.  
  4102.    target1 target2 : dependent1 dependent2 dependent3 
  4103.        command list 
  4104.  
  4105. is equivalent to: 
  4106.  
  4107.  
  4108.    target1 : dependent1 dependent2 dependent3 
  4109.        command list 
  4110.  
  4111.    target2 : dependent1 dependent2 dependent3 
  4112.        command list 
  4113.  
  4114. Also, the rules may depend on the targets of other rules. 
  4115.  
  4116.  
  4117.    # 
  4118.    # rule 1: this rule uses rule 2 
  4119.    # 
  4120.    balance.lst summary.lst : ledger.dat sales.dat purchase.dat 
  4121.        doreport 
  4122.  
  4123.    # 
  4124.    # rule 2: used by rules 1 and 3 
  4125.    # 
  4126.    sales.dat : canada.dat england.dat usa.dat 
  4127.        dosales 
  4128.  
  4129.    # 
  4130.    # rule 3: this rule uses rule 2 
  4131.    # 
  4132.    year.lst : ledger.dat sales.dat purchase.dat 
  4133.        doyearly 
  4134.  
  4135. The dependents are checked to see if they are the targets of any other rules in 
  4136. the makefile in which case they are updated.  This process of updating 
  4137. dependents that are targets in other rules continues until a rule is reached 
  4138. that has only simple dependents that are not targets of rules.  At this point, 
  4139. if the target does not exist or if any of the dependents is younger than the 
  4140. target then the command list associated with the rule is executed. 
  4141.  
  4142. Hint:  The term "updating", in this context, refers to the process of checking 
  4143. the time-stamps of dependents and running the specified command list whenever 
  4144. they are out-of-date.  Whenever a dependent is the target of some other rule, 
  4145. the dependent must be brought up-to-date first.  Stated another way, if "A" 
  4146. depends on "B" and "B" depends on "C" and "C" is younger than "B" then we must 
  4147. update "B" before we update "A". 
  4148.  
  4149. Make will check to ensure that the target exists after its associated command 
  4150. list is executed.  The target existence checking may be disabled in two ways: 
  4151.  
  4152.    1. use the command line option "c" 
  4153.  
  4154.    2. use the .NOCHECK directive. 
  4155.  
  4156.  The rule checking returns to the previous rule that had the target as a 
  4157.  dependent.  Upon returning to the rule, the command list is executed if the 
  4158.  target does not exist or if any of the updated dependents are now younger than 
  4159.  the target.  If you were to type: 
  4160.  
  4161.  
  4162.     wmake 
  4163.  
  4164.  here are the steps that would occur with the previous makefile: 
  4165.  
  4166.  
  4167.     update(balance.lst) (rule 1) 
  4168.  
  4169.      update(ledger.dat)       (not a target) 
  4170.      update(sales.dat)       (found rule 2) 
  4171.  
  4172.       update(canada.dat)      (not a target) 
  4173.       update(england.dat)     (not a target) 
  4174.       update(usa.dat)       (not a target) 
  4175.       IF sales.dat does not exist            OR 
  4176.        any of (canada.dat,england.dat,usa.dat) 
  4177.         is younger than sales.dat 
  4178.       THEN execute "dosales" 
  4179.  
  4180.      update(purchase.dat)      (not a target) 
  4181.      IF balance.lst does not exist            OR 
  4182.       any of (ledger.dat,sales.dat,purchase.dat) 
  4183.        is younger than (balance.lst) 
  4184.      THEN execute "doreport" 
  4185.  
  4186.  The third rule in the makefile will not be included in this update sequence of 
  4187.  steps.  Recall that the default target that is "updated" is the first target 
  4188.  in the first rule encountered in the makefile.  This is the default action 
  4189.  taken by Make when no target is specified on the command line.  If you were to 
  4190.  type: 
  4191.  
  4192.  
  4193.     wmake year.lst 
  4194.  
  4195.  then the file "YEAR.LST" would be updated.  As Make reads the rules in 
  4196.  "MAKEFILE", it discovers that updating "YEAR.LST" involves updating 
  4197.  "SALES.DAT".  The update sequence is similar to the previous example. 
  4198.  
  4199.  
  4200. ΓòÉΓòÉΓòÉ 8.6. Automatic Dependency Detection (.AUTODEPEND) ΓòÉΓòÉΓòÉ
  4201.  
  4202.  
  4203. Explicit listing of dependencies in a makefile can often be tedious in the 
  4204. development and maintenance phases of a project.  The Watcom C/C++ compiler 
  4205. will insert dependency information into the object file as it processes source 
  4206. files so that a complete snapshot of the files necessary to build the object 
  4207. file are recorded.  Since all files do not have dependency information 
  4208. contained within them in a standard form, it is necessary to indicate to Make 
  4209. when dependencies are present. 
  4210.  
  4211. To illustrate the use of the .AUTODEPEND directive, we will show its use in an 
  4212. implicit rule and in an explicit rule. 
  4213.  
  4214.  
  4215.    # 
  4216.    # .AUTODEPEND example 
  4217.    # 
  4218.    .c.obj: .AUTODEPEND 
  4219.        wcc386 $[* $(compile_options) 
  4220.  
  4221.    test.exe : a.obj b.obj c.obj test.res 
  4222.        wlink FILE a.obj, b.obj, c.obj 
  4223.        wrc /q /bt=windows test.res test.exe 
  4224.  
  4225.    test.res : test.rc test.ico .AUTODEPEND 
  4226.        wrc /ad /q /bt=windows /r $[@ $^@ 
  4227.  
  4228. In the above example, Make will use the contents of the object file to 
  4229. determine whether the object file has to be built during processing.  The 
  4230. Watcom Resource Compiler can also insert dependency information into a resource 
  4231. file that can be used by Make. 
  4232.  
  4233.  
  4234. ΓòÉΓòÉΓòÉ 8.7. Targets Without Any Dependents (.SYMBOLIC) ΓòÉΓòÉΓòÉ
  4235.  
  4236.  
  4237. There must always be at least one target in a rule but it is not necessary to 
  4238. have any dependents.  If a target does not have any dependents, the command 
  4239. list associated with the rule will always be executed if the target is updated. 
  4240.  
  4241. You might ask, "What may a rule with no dependents be used for?".  A rule with 
  4242. no dependents may be used to describe actions that are useful for the group of 
  4243. files being maintained.  Possible uses include backing up files, cleaning up 
  4244. files, or printing files. 
  4245.  
  4246. To illustrate the use of the .SYMBOLIC directive, we will add two new rules to 
  4247. the previous example.  First, we will omit the .SYMBOLIC directive and observe 
  4248. what will happen when it is not present. 
  4249.  
  4250.  
  4251.    # 
  4252.    # rule 4: backup the data files 
  4253.    # 
  4254.    backup : 
  4255.        echo "insert backup disk" 
  4256.        pause 
  4257.        copy *.dat a: 
  4258.        echo "backup complete" 
  4259.  
  4260.    # 
  4261.    # rule 5: cleanup temporary files 
  4262.    # 
  4263.    cleanup : 
  4264.        del *.tmp 
  4265.        del \tmp\*.* 
  4266.  
  4267. and then execute the command: 
  4268.  
  4269.  
  4270.    wmake backup 
  4271.  
  4272. Make will execute the command list associated with the "backup" target and 
  4273. issue an error message indicating that the file "BACKUP" does not exist after 
  4274. the command list was executed.  The same thing would happen if we typed: 
  4275.  
  4276.  
  4277.    wmake cleanup 
  4278.  
  4279. In this makefile we are using "backup" and "cleanup" to represent actions we 
  4280. want performed.  The names are not real files but rather they are symbolic 
  4281. names.  This special type of target may be declared with the .SYMBOLIC 
  4282. directive.  This time, we show rules 4 and 5 with the appropriate addition of 
  4283. .SYMBOLIC directives. 
  4284.  
  4285.  
  4286.    # 
  4287.    # rule 4: backup the data files 
  4288.    # 
  4289.    backup : .SYMBOLIC 
  4290.        echo "insert backup disk" 
  4291.        pause 
  4292.        copy *.dat a: 
  4293.        echo "backup complete" 
  4294.  
  4295.    # 
  4296.    # rule 5: cleanup temporary files 
  4297.    # 
  4298.    cleanup : .SYMBOLIC 
  4299.        del *.tmp 
  4300.        del \tmp\*.* 
  4301.  
  4302. The use of the .SYMBOLIC directive indicates to Make that the target should 
  4303. always be updated internally after the command list associated with the rule 
  4304. has been executed.  A short form for the common idiom of singular .SYMBOLIC 
  4305. targets like: 
  4306.  
  4307.  
  4308.    target : .SYMBOLIC 
  4309.        commands 
  4310.  
  4311. is: 
  4312.  
  4313.  
  4314.    target 
  4315.        commands 
  4316.  
  4317. This kind of target definition is useful for many types of management tasks 
  4318. that can be described in a makefile. 
  4319.  
  4320.  
  4321. ΓòÉΓòÉΓòÉ 8.8. Preserving Targets (.PRECIOUS) ΓòÉΓòÉΓòÉ
  4322.  
  4323.  
  4324. Most operating system utilities and programs have special return codes that 
  4325. indicate error conditions.  Watcom Make will check the return code for every 
  4326. command executed.  If the return code is non-zero, Make will stop processing 
  4327. the current rule and optionally delete the current target being updated.  If a 
  4328. file is precious enough that this treatment of return codes is not wanted then 
  4329. the .PRECIOUS directive may be used.  The .PRECIOUS directive indicates to Make 
  4330. that the target should not be deleted if an error occurs during the execution 
  4331. of the associated command list.  Here is an example of the .PRECIOUS directive: 
  4332.  
  4333.  
  4334.    # 
  4335.    # .PRECIOUS example 
  4336.    # 
  4337.    balance.lst summary.lst : ledger.dat sales.dat purchase.dat .PRECIOUS 
  4338.        doreport 
  4339.  
  4340. If the program "DOREPORT" executes and its return code is non-zero then Make 
  4341. will not attempt to delete "BALANCE.LST" or "SUMMARY.LST".  If only one of the 
  4342. files is precious then the makefile could be coded as follows: 
  4343.  
  4344.  
  4345.    # 
  4346.    # .PRECIOUS example 
  4347.    # 
  4348.    balance.lst : .PRECIOUS 
  4349.    balance.lst summary.lst : ledger.dat sales.dat purchase.dat 
  4350.        doreport 
  4351.  
  4352. The file "BALANCE.LST" will not be deleted if an error occurs while the program 
  4353. "DOREPORT" is executing. 
  4354.  
  4355.  
  4356. ΓòÉΓòÉΓòÉ 8.9. Ignoring Return Codes (.IGNORE) ΓòÉΓòÉΓòÉ
  4357.  
  4358.  
  4359. Some programs do not have meaningful return codes so for these programs we want 
  4360. to ignore the return code completely.  There are different ways to ignore 
  4361. return codes namely, 
  4362.  
  4363.    1. use the command line option "i" 
  4364.  
  4365.    2. put a "-" in front of specific commands, or 
  4366.  
  4367.    3. use the .IGNORE directive. 
  4368.  
  4369.  In the following example, the rule: 
  4370.  
  4371.  
  4372.     # 
  4373.     # ignore return code example 
  4374.     # 
  4375.     balance.lst summary.lst : ledger.dat sales.dat purchase.dat 
  4376.         -doreport 
  4377.  
  4378.  will ignore the return status from the program "DOREPORT".  Using the dash in 
  4379.  front of the command is the preferred method for ignoring return codes because 
  4380.  it allows Make to check all the other return codes. 
  4381.  
  4382.  The .IGNORE directive is used as follows: 
  4383.  
  4384.  
  4385.     # 
  4386.     # .IGNORE example 
  4387.     # 
  4388.     .IGNORE 
  4389.     balance.lst summary.lst : ledger.dat sales.dat purchase.dat 
  4390.         doreport 
  4391.  
  4392.  Using the .IGNORE directive will cause Make to ignore the return code for 
  4393.  every command.  The "i" command line option and the .IGNORE directive prohibit 
  4394.  Make from performing any error checking on the commands executed and, as such, 
  4395.  should be used with caution. 
  4396.  
  4397.  Another way to handle non-zero return codes is to continue processing targets 
  4398.  which do not depend on the target that had a non-zero return code during 
  4399.  execution of its associated command list.  There are two ways of indicating to 
  4400.  Make that processing should continue after a non-zero return code: 
  4401.  
  4402.    1. use the command line option "k" 
  4403.  
  4404.    2. use the .CONTINUE directive. 
  4405.  
  4406.  
  4407. ΓòÉΓòÉΓòÉ 8.10. Erasing Targets After Error (.ERASE) ΓòÉΓòÉΓòÉ
  4408.  
  4409.  
  4410. Most operating system utilities and programs have special return codes that 
  4411. indicate error conditions.  Watcom Make will check the return code for every 
  4412. command executed.  If the return code is non-zero, Make will stop processing 
  4413. the current rule and optionally delete the current target being updated.  By 
  4414. default, Make will prompt for deletion of the current target.  The .ERASE 
  4415. directive indicates to Make that the target should be deleted if an error 
  4416. occurs during the execution of the associated command list.  No prompt is 
  4417. issued in this case.  Here is an example of the .ERASE directive: 
  4418.  
  4419.  
  4420.    # 
  4421.    # .ERASE example 
  4422.    # 
  4423.    .ERASE 
  4424.    balance.lst summary.lst : ledger.dat sales.dat purchase.dat 
  4425.        doreport 
  4426.  
  4427. If the program "DOREPORT" executes and its return code is non-zero then Make 
  4428. will attempt to delete "BALANCE.LST" or "SUMMARY.LST" depending on which it was 
  4429. updating. 
  4430.  
  4431.  
  4432. ΓòÉΓòÉΓòÉ 8.11. Preserving Targets After Error (.HOLD) ΓòÉΓòÉΓòÉ
  4433.  
  4434.  
  4435. Most operating system utilities and programs have special return codes that 
  4436. indicate error conditions.  Watcom Make will check the return code for every 
  4437. command executed.  If the return code is non-zero, Make will stop processing 
  4438. the current rule and optionally delete the current target being updated.  By 
  4439. default, Make will prompt for deletion of the current target.  The .HOLD 
  4440. directive indicates to Make that the target should not be deleted if an error 
  4441. occurs during the execution of the associated command list.  No prompt is 
  4442. issued in this case.  The .HOLD directive is similar to .PRECIOUS but applies 
  4443. to all targets listed in the makefile.  Here is an example of the .HOLD 
  4444. directive: 
  4445.  
  4446.  
  4447.    # 
  4448.    # .HOLD example 
  4449.    # 
  4450.    .HOLD 
  4451.    balance.lst summary.lst : ledger.dat sales.dat purchase.dat 
  4452.        doreport 
  4453.  
  4454. If the program "DOREPORT" executes and its return code is non-zero then Make 
  4455. will not delete "BALANCE.LST" or "SUMMARY.LST". 
  4456.  
  4457.  
  4458. ΓòÉΓòÉΓòÉ 8.12. Suppressing Terminal Output (.SILENT) ΓòÉΓòÉΓòÉ
  4459.  
  4460.  
  4461. As commands are executed, Watcom Make will print out the current command before 
  4462. it is executed.  It is possible to execute the makefile without having the 
  4463. commands printed.  There are three ways to inhibit the printing of the commands 
  4464. before they are executed, namely: 
  4465.  
  4466.    1. use the command line option "s" 
  4467.  
  4468.    2. put an "@" in front of specific commands, or 
  4469.  
  4470.    3. use the .SILENT directive. 
  4471.  
  4472.  In the following example, the rule: 
  4473.  
  4474.  
  4475.     # 
  4476.     # silent command example 
  4477.     # 
  4478.     balance.lst summary.lst : ledger.dat sales.dat purchase.dat 
  4479.         @doreport 
  4480.  
  4481.  will prevent the string "doreport" from being printed on the screen before the 
  4482.  command is executed. 
  4483.  
  4484.  The .SILENT directive is used as follows: 
  4485.  
  4486.  
  4487.     # 
  4488.     # .SILENT example 
  4489.     # 
  4490.     .SILENT 
  4491.     balance.lst summary.lst : ledger.dat sales.dat purchase.dat 
  4492.         doreport 
  4493.  
  4494.  Using the .SILENT directive or the "s" command line option will inhibit the 
  4495.  printing of all commands before they are executed. 
  4496.  
  4497.  At this point, most of the capability of Make may be realized.  Methods for 
  4498.  making makefiles more succinct will be discussed. 
  4499.  
  4500.  
  4501. ΓòÉΓòÉΓòÉ 8.13. Macros ΓòÉΓòÉΓòÉ
  4502.  
  4503.  
  4504. Watcom Make has a simple macro facility that may be used to improve makefiles 
  4505. by making them easier to read and maintain.  A macro identifier may be composed 
  4506. from a string of alphabetic characters and numeric characters.  The underscore 
  4507. character is also allowed in a macro identifier.  If the macro identifier 
  4508. starts with a "%" character, the macro identifier represents an environment 
  4509. variable.  For instance, the macro identifier "%path" represents the 
  4510. environment variable "path". 
  4511.  
  4512.  2morrow 
  4513.       yes 
  4514.  
  4515.  stitch_in_9 
  4516.       yes 
  4517.  
  4518.  invalid~id 
  4519.       no 
  4520.  
  4521.  2b_or_not_2b 
  4522.       yes 
  4523.  
  4524.  %path 
  4525.       yes 
  4526.  
  4527.  reports 
  4528.       yes 
  4529.  
  4530.  !@#*% 
  4531.       no 
  4532.  
  4533.  We will use a programming example to show how macros are used.  The 
  4534.  programming example involves four C/C++ source files and two header files. 
  4535.  Here is the initial makefile (before macros): 
  4536.  
  4537.  
  4538.     # 
  4539.     # programming example 
  4540.     # (before macros) 
  4541.     # 
  4542.     plot.exe : main.obj input.obj calc.obj output.obj 
  4543.         wlink @plot 
  4544.  
  4545.     main.obj : main.c defs.h globals.h 
  4546.         wcc386 main /mf /d1 /w3 
  4547.  
  4548.     calc.obj : calc.c defs.h globals.h 
  4549.         wcc386 calc /mf /d1 /w3 
  4550.  
  4551.     input.obj : input.c defs.h globals.h 
  4552.         wcc386 input /mf /d1 /w3 
  4553.  
  4554.     output.obj : output.c defs.h globals.h 
  4555.         wcc386 output /mf /d1 /w3 
  4556.  
  4557.  Macros become useful when changes must be made to makefiles.  If the 
  4558.  programmer wanted to change the compiler options for the different compiles, 
  4559.  the programmer would have to make a global change to the makefile.  With this 
  4560.  simple example, it is quite easy to make the change but try to imagine a more 
  4561.  complex example with different programs having similar options.  The global 
  4562.  change made by the editor could cause problems by changing the options for 
  4563.  other programs. A good habit to develop is to define macros for any programs 
  4564.  that have command line options.  In our example, we would change the makefile 
  4565.  to be: 
  4566.  
  4567.  
  4568.     # 
  4569.     # programming example 
  4570.     # (after macros) 
  4571.     # 
  4572.     link_options = 
  4573.     compiler = wcc386 
  4574.     compile_options = /mf /d1 /w3 
  4575.  
  4576.     plot.exe : main.obj input.obj calc.obj output.obj 
  4577.         wlink $(link_options) @plot 
  4578.  
  4579.     main.obj : main.c defs.h globals.h 
  4580.         $(compiler) main $(compile_options) 
  4581.  
  4582.     calc.obj : calc.c defs.h globals.h 
  4583.         $(compiler) calc $(compile_options) 
  4584.  
  4585.     input.obj : input.c defs.h globals.h 
  4586.         $(compiler) input $(compile_options) 
  4587.  
  4588.     output.obj : output.c defs.h globals.h 
  4589.         $(compiler) output $(compile_options) 
  4590.  
  4591.  A macro definition consists of a macro identifier starting on the beginning of 
  4592.  the line followed by an "=" which in turn is followed by the text to be 
  4593.  replaced.  A macro may be redefined, with the latest declaration being used 
  4594.  for subsequent expansions (no warning is given upon redefinition of a macro). 
  4595.  The replacement text may contain macro references. 
  4596.  
  4597.  A macro reference may occur in two forms.  The previous example illustrates 
  4598.  one way to reference macros whereby the macro identifier is delimited by "$(" 
  4599.  and ")".  The parentheses are optional so the macros "compiler" and 
  4600.  "compile_options" could be referenced by: 
  4601.  
  4602.  
  4603.     main.obj : main.c defs.h globals.h 
  4604.         $compiler main $compile_options 
  4605.  
  4606.  Certain ambiguities may arise with this form of macro reference.  For 
  4607.  instance, examine this makefile fragment: 
  4608.  
  4609.  Example: 
  4610.  
  4611.     temporary_dir = \tmp\ 
  4612.     temporary_file = $temporary_dirtmp000.tmp 
  4613.  
  4614.  The intention of the declarations is to have a macro that will expand into a 
  4615.  file specification for a temporary file.  Make will collect the largest 
  4616.  identifier possible before macro expansion occurs.  The macro reference is 
  4617.  followed by text that looks like part of the macro identifier ("tmp000") so 
  4618.  the macro identifier that will be referenced will be "temporary_dirtmp000". 
  4619.  The incorrect macro identifier will not be defined so an error message will be 
  4620.  issued. 
  4621.  
  4622.  If the makefile fragment was: 
  4623.  
  4624.  
  4625.     temporary_dir = \tmp\ 
  4626.     temporary_file = $(temporary_dir)tmp000.tmp 
  4627.  
  4628.  there would be no ambiguity.  The preferred way to reference macros is to 
  4629.  enclose the macro identifier by "$(" and ")". 
  4630.  
  4631.  Macro references are expanded immediately on dependency lines (and thus may 
  4632.  not contain references to macros that have not been defined) but other macro 
  4633.  references have their expansion deferred until they are used in a command.  In 
  4634.  the previous example, the macros "link_options", "compiler", and 
  4635.  "compile_options" will not be expanded until the commands that reference them 
  4636.  are executed. 
  4637.  
  4638.  Another use for macros is to replace large amounts of text with a much smaller 
  4639.  macro reference.  In our example, we only have two header files but suppose we 
  4640.  had very many header files.  Each explicit rule would be very large and 
  4641.  difficult to read and maintain.  We will use the previous example makefile to 
  4642.  illustrate this use of macros. 
  4643.  
  4644.  
  4645.     # 
  4646.     # programming example 
  4647.     # (with more macros) 
  4648.     # 
  4649.     link_options = 
  4650.     compiler = wcc386 
  4651.     compile_options = /mf /d1 /w3 
  4652.  
  4653.     header_files = defs.h globals.h 
  4654.     object_files = main.obj input.obj calc.obj & 
  4655.            output.obj 
  4656.  
  4657.     plot.exe : $(object_files) 
  4658.         wlink $(link_options) @plot 
  4659.  
  4660.     main.obj : main.c $(header_files) 
  4661.         $(compiler) main $(compile_options) 
  4662.  
  4663.     calc.obj : calc.c $(header_files) 
  4664.         $(compiler) calc $(compile_options) 
  4665.  
  4666.     input.obj : input.c $(header_files) 
  4667.         $(compiler) input $(compile_options) 
  4668.  
  4669.     output.obj : output.c $(header_files) 
  4670.         $(compiler) output $(compile_options) 
  4671.  
  4672.  Notice the ampersand ("&") at the end of the macro definition for 
  4673.  "object_files".  The ampersand indicates that the macro definition continues 
  4674.  on the next line.  In general, if you want to continue a line in a makefile, 
  4675.  use an ampersand ("&") at the end of the line. 
  4676.  
  4677.  There are special macros provided by Make to access environment variable 
  4678.  names.  To access the PATH environment variable in a makefile, we use the 
  4679.  macro identifier "%path".  For example, if we have the following line in a 
  4680.  command list: 
  4681.  
  4682.  Example: 
  4683.  
  4684.        echo $(%path) 
  4685.  
  4686.  it will print out the current value of the PATH environment variable when it 
  4687.  is executed. 
  4688.  
  4689.  There are two other special environment macros that are predefined by Make. 
  4690.  The macro identifier "%cdrive" will expand into one letter representing the 
  4691.  current drive.  The macro identifier "%cwd" will expand into the current 
  4692.  working directory.  These macro identifiers are not very useful unless we can 
  4693.  specify that they be expanded immediately.  The complementary macros "$+" and 
  4694.  "$-" respectively turn on and turn off immediate expansion of macros.  The 
  4695.  scope of the "$+" macro is the current line after which the default macro 
  4696.  expansion behaviour is resumed.  A possible use of these macros is illustrated 
  4697.  by the following example makefile. 
  4698.  
  4699.  
  4700.     # 
  4701.     # $(%cdrive), $(%cwd), $+, and $- example 
  4702.     # 
  4703.     dir1 = $(%cdrive):$(%cwd) 
  4704.     dir2 = $+ $(dir1) $- 
  4705.     example : .SYMBOLIC 
  4706.         cd .. 
  4707.         echo $(dir1) 
  4708.         echo $(dir2) 
  4709.  
  4710.  Which would produce the following output if the current working directory is 
  4711.  C:\WATCOM\SOURCE\EXAMPLE: 
  4712.  
  4713.  Example: 
  4714.  
  4715.     (command output only) 
  4716.     C:\WATCOM\SOURCE 
  4717.     C:\WATCOM\SOURCE\EXAMPLE 
  4718.  
  4719.  The macro definition for "dir2" forces immediate expansion of the "%cdrive" 
  4720.  and "%cwd" macros thus defining "dir2" to be the current directory that Make 
  4721.  was invoked in.  The macro "dir1" is not expanded until execution time when 
  4722.  the current directory has changed from the initial directory. 
  4723.  
  4724.  Combining the $+ and $- special macros with the special macro identifiers 
  4725.  "%cdrive" and "%cwd" is a useful makefile technique.  The $+ and $- special 
  4726.  macros are general enough to be used in many different ways. 
  4727.  
  4728.  Constructing other macros is another use for the $+ and $- special macros. 
  4729.  Make allows macros to be redefined and combining this with the $+ and $- 
  4730.  special macros, similar looking macros may be constructed. 
  4731.  
  4732.  
  4733.     # 
  4734.     # macro construction with $+ and $- 
  4735.     # 
  4736.     template = file1.$(ext) file2.$(ext) file3.$(ext) file4.$(ext) 
  4737.     ext = dat 
  4738.     data_files = $+ $(template) $- 
  4739.     ext = lst 
  4740.     listing_files = $+ $(template) $- 
  4741.  
  4742.     example : .SYMBOLIC 
  4743.         echo $(data_files) 
  4744.         echo $(listing_files) 
  4745.  
  4746.  This makefile would produce the following output: 
  4747.  
  4748.  Example: 
  4749.  
  4750.     file1.dat file2.dat file3.dat file4.dat 
  4751.     file1.lst file2.lst file3.lst file4.lst 
  4752.  
  4753.  Adding more text to a macro can also be done with the $+ and $- special 
  4754.  macros. 
  4755.  
  4756.     # 
  4757.     # macro addition with $+ and $- 
  4758.     # 
  4759.     objs = file1.obj file2.obj file3.obj 
  4760.     objs = $+$(objs)$- file4.obj 
  4761.     objs = $+$(objs)$- file5.obj 
  4762.  
  4763.     example : .SYMBOLIC 
  4764.         echo $(objs) 
  4765.  
  4766.  This makefile would produce the following output: 
  4767.  
  4768.  Example: 
  4769.  
  4770.     file1.obj file2.obj file3.obj file4.obj file5.obj 
  4771.  
  4772.  Make provides a shorthand notation for this type of macro operation.  Text can 
  4773.  be added to a macro by using the "+=" macro assignment.  The previous makefile 
  4774.  can be written as: 
  4775.  
  4776.  
  4777.     # 
  4778.     # macro addition with += 
  4779.     # 
  4780.     objs  = file1.obj file2.obj file3.obj 
  4781.     objs += file4.obj 
  4782.     objs += file5.obj 
  4783.  
  4784.     example : .SYMBOLIC 
  4785.         echo $(objs) 
  4786.  
  4787.  and still produce the same results.  The shorthand notation "+=" supported by 
  4788.  Make provides a quick way to add more text to macros. 
  4789.  
  4790.  There are instances when it is useful to have macro identifiers that have 
  4791.  macro references contained in them.  If you wanted to print out an informative 
  4792.  message before linking the executable that was different between the debugging 
  4793.  and production version, we would express it as follows: 
  4794.  
  4795.  
  4796.     # 
  4797.     # programming example 
  4798.     # (macro selection) 
  4799.     # 
  4800.     version = debugging      # debugging version 
  4801.  
  4802.     msg_production = linking production version ... 
  4803.     msg_debugging = linking debug version ... 
  4804.  
  4805.     link_options_production = 
  4806.     link_options_debugging = debug all 
  4807.     link_options = $(link_options_$(version)) 
  4808.  
  4809.     compiler = wcc386 
  4810.     compile_options_production = /mf /w3 
  4811.     compile_options_debugging = /mf /d1 /w3 
  4812.     compile_options = $(compile_options_$(version)) 
  4813.  
  4814.     header_files = defs.h globals.h 
  4815.     object_files = main.obj input.obj calc.obj & 
  4816.            output.obj 
  4817.  
  4818.     plot.exe : $(object_files) 
  4819.         echo $(msg_$(version)) 
  4820.         wlink $(link_options) @plot 
  4821.  
  4822.     main.obj : main.c $(header_files) 
  4823.         $(compiler) main $(compile_options) 
  4824.  
  4825.     calc.obj : calc.c $(header_files) 
  4826.         $(compiler) calc $(compile_options) 
  4827.  
  4828.     input.obj : input.c $(header_files) 
  4829.         $(compiler) input $(compile_options) 
  4830.  
  4831.     output.obj : output.c $(header_files) 
  4832.         $(compiler) output $(compile_options) 
  4833.  
  4834.  Take notice of the macro references that are of the form: 
  4835.  
  4836.  
  4837.     $(<partial_macro_identifier>$(version)) 
  4838.  
  4839.  The expansion of a macro reference begins by expanding any macros seen until a 
  4840.  matching right parenthesis is found.  The macro identifier that is present 
  4841.  after the matching parenthesis is found will be expanded.  The other form of 
  4842.  macro reference namely: 
  4843.  
  4844.  
  4845.     $<macro_identifier> 
  4846.  
  4847.  may be used in a similar fashion.  The previous example would be of the form: 
  4848.  
  4849.  
  4850.     $<partial_macro_identifier>$version 
  4851.  
  4852.  Macro expansion occurs until a character that cannot be in a macro identifier 
  4853.  is found (on the same line as the "$") after which the resultant macro 
  4854.  identifier is expanded.  If you want two macros to be concatenated then the 
  4855.  line would have to be coded: 
  4856.  
  4857.  
  4858.     $(macro1)$(macro2) 
  4859.  
  4860.  The use of parentheses is the preferred method for macro references because it 
  4861.  completely specifies the order of expansion. 
  4862.  
  4863.  In the previous example, we can see that the four command lines that invoke 
  4864.  the compiler are very similar in form.  We may make use of these similarities 
  4865.  by denoting the command by a macro reference.  We need to be able to define a 
  4866.  macro that will expand into the correct command when processed.  Fortunately, 
  4867.  Make can reference the first member of the dependent list, the last member of 
  4868.  the dependent list, and the current target being updated with the use of some 
  4869.  special macros.  These special macros have the form: 
  4870.  
  4871.  
  4872.     $<file_specifier><form_qualifier> 
  4873.  
  4874.  where <file_specifier> is one of: 
  4875.  
  4876.  "^" 
  4877.       represents the current target being updated 
  4878.  
  4879.  "[" 
  4880.       represents the first member of the dependent list 
  4881.  
  4882.  "]" 
  4883.       represents the last member of the dependent list 
  4884.  
  4885.  and <form_qualifier> is one of: 
  4886.  
  4887.  "@" 
  4888.       full file name 
  4889.  
  4890.  "*" 
  4891.       file name with extension removed 
  4892.  
  4893.  "&" 
  4894.       file name with path and extension removed 
  4895.  
  4896.  "." 
  4897.       file name with path removed 
  4898.  
  4899.  ":" 
  4900.       path of file name 
  4901.  
  4902.  If the file "D:\DIR1\DIR2\NAME.EXT" is the current target being updated then 
  4903.  the following example will show how the form qualifiers are used. 
  4904.  
  4905.  $^@ 
  4906.        D:\DIR1\DIR2\NAME.EXT 
  4907.  
  4908.  $^* 
  4909.        D:\DIR1\DIR2\NAME 
  4910.  
  4911.  $^& 
  4912.        NAME 
  4913.  
  4914.  $^. 
  4915.        NAME.EXT 
  4916.  
  4917.  $^: 
  4918.        D:\DIR1\DIR2\ 
  4919.  
  4920.  These special macros provide the capability to reference targets and 
  4921.  dependents in a variety of ways. 
  4922.  
  4923.  
  4924.     # 
  4925.     # programming example 
  4926.     # (more macros) 
  4927.     # 
  4928.     version = debugging      # debugging version 
  4929.  
  4930.     msg_production = linking production version ... 
  4931.     msg_debugging = linking debug version ... 
  4932.  
  4933.     link_options_production = 
  4934.     link_options_debugging = debug all 
  4935.     link_options = $(link_options_$(version)) 
  4936.  
  4937.     compile_options_production = /mf /w3 
  4938.     compile_options_debugging = /mf /d1 /w3 
  4939.     compile_options = $(compile_options_$(version)) 
  4940.  
  4941.     compiler_command = wcc386 $[* $(compile_options) 
  4942.  
  4943.     header_files = defs.h globals.h 
  4944.     object_files = main.obj input.obj calc.obj & 
  4945.            output.obj 
  4946.  
  4947.     plot.exe : $(object_files) 
  4948.         echo $(msg_$(version)) 
  4949.         wlink $(link_options) @$^* 
  4950.  
  4951.     main.obj : main.c $(header_files) 
  4952.         $(compiler_command) 
  4953.  
  4954.     calc.obj : calc.c $(header_files) 
  4955.         $(compiler_command) 
  4956.  
  4957.     input.obj : input.c $(header_files) 
  4958.         $(compiler_command) 
  4959.  
  4960.     output.obj : output.c $(header_files) 
  4961.         $(compiler_command) 
  4962.  
  4963.  This example illustrates the use of the special dependency macros.  Notice the 
  4964.  use of "$^*" in the linker command.  The macro expands into the string "plot" 
  4965.  since "plot.exe" is the target when the command is processed.  The use of the 
  4966.  special dependency macros is recommended because they make use of information 
  4967.  that is already contained in the dependency rule. 
  4968.  At this point, we know that macro references begin with a "$" and that 
  4969.  comments begin with a "#".  What happens if we want to use these characters 
  4970.  without their special meaning?  Make has two special macros that provide these 
  4971.  characters to you.  The special macro "$$" will result in a "$" when expanded 
  4972.  and "$#" will expand into a "#".  These special macros are provided so that 
  4973.  you are not forced to work around the special meanings of the "$" and "#" 
  4974.  characters. 
  4975.  
  4976.  
  4977. ΓòÉΓòÉΓòÉ 8.14. Implicit Rules ΓòÉΓòÉΓòÉ
  4978.  
  4979.  
  4980. Watcom Make is capable of accepting declarations of commonly used dependencies. 
  4981. These declarations are called "implicit rules" as opposed to "explicit rules" 
  4982. which were discussed previously.  Implicit rules may be applied only in 
  4983. instances where you are able to describe a dependency in terms of file 
  4984. extensions. 
  4985.  
  4986. Hint:  Recall that a file extension is the portion of the file name which 
  4987. follows the period.  In the file specification: 
  4988.  
  4989. C:\DOS\ANSI.SYS 
  4990.  
  4991. the file extension is "SYS". 
  4992.  
  4993. An implicit rule provides a command list for a dependency between files with 
  4994. certain extensions.  The form of an implicit rule is as follows: 
  4995.  
  4996.  
  4997.    .<dependent_extension>.<target_extension>: 
  4998.        <command_list> 
  4999.  
  5000. Implicit rules are used if a file has not been declared as a target in any 
  5001. explicit rule or the file has been declared as a target in an explicit rule 
  5002. with no command list.  For a given target file, a search is conducted to see if 
  5003. there are any implicit rules defined for the target file's extension in which 
  5004. case Make will then check if the file with the dependent extension in the 
  5005. implicit rule exists.  If the file with the dependent extension exists then the 
  5006. command list associated with the implicit rule is executed and processing of 
  5007. the makefile continues. 
  5008.  
  5009. Other implicit rules for the target extension are searched in a similar 
  5010. fashion.  The order in which the dependent extensions are checked becomes 
  5011. important if there is more than one implicit rule declaration for a target 
  5012. extension.  If we have the following makefile fragment: 
  5013.  
  5014. Example: 
  5015.  
  5016.    .pas.obj: 
  5017.        (command list) 
  5018.    .c.obj: 
  5019.        (command list) 
  5020.  
  5021. an ambiguity arises.  If we have a target file "TEST.OBJ" then which do we 
  5022. check for first, "TEST.PAS" or "TEST.C"?  Make handles this with the 
  5023. .EXTENSIONS directive.  The .EXTENSIONS directive declares which extensions are 
  5024. allowed to be used in implicit rules and how these extensions are ordered.  The 
  5025. default .EXTENSIONS declaration is: 
  5026.  
  5027.  
  5028.    .EXTENSIONS: 
  5029.    .EXTENSIONS: .exe .exp .lib .obj .asm .c .for .pas .cob .h .fi .mif 
  5030.  
  5031. A .EXTENSIONS directive with an empty list will clear the .EXTENSIONS list and 
  5032. any previously defined implicit rules.  Any subsequent .EXTENSIONS directives 
  5033. will add extensions to the end of the list. 
  5034.  
  5035. Hint:  The default .EXTENSIONS declaration could have been coded as: 
  5036.  
  5037. .EXTENSIONS: 
  5038.  
  5039. .EXTENSIONS:  .exe 
  5040. .EXTENSIONS:  .exp 
  5041. .EXTENSIONS:  .lib 
  5042. .EXTENSIONS:  .obj 
  5043. .EXTENSIONS:  .asm .c .for .pas .cob .h .fi .mif 
  5044. with identical results. 
  5045.  
  5046. Make will not allow any implicit rule declarations that use extensions that are 
  5047. not in the current .EXTENSIONS list.  Returning to our makefile fragment: 
  5048.  
  5049.  
  5050.    .pas.obj: 
  5051.        (command list) 
  5052.    .c.obj: 
  5053.        (command list) 
  5054.  
  5055. and our target file "TEST.OBJ", we now know that the .EXTENSIONS list 
  5056. determines in what order the dependents "TEST.PAS" and "TEST.C" will be tried. 
  5057. If the .EXTENSIONS declaration is: 
  5058.  
  5059. Example: 
  5060.  
  5061.    .EXTENSIONS: 
  5062.    .EXTENSIONS: .exe .obj .asm .pas .c .cpp .for .cob 
  5063.  
  5064. we can see that the dependent file "TEST.PAS" will be tried first as a possible 
  5065. dependent with "TEST.C" being tried next. 
  5066.  
  5067. One apparent problem with implicit rules and their associated command lists is 
  5068. that they are used for many different targets and dependents during the 
  5069. processing of a makefile.  The same problem occurs with commands constructed 
  5070. from macros.  Recall that there is a set of special macros that start with 
  5071. "$^", "$[", or "$]" that reference the target, first dependent, or last 
  5072. dependent of an explicit dependency rule.  In an implicit rule there may be 
  5073. only one dependent or many dependents depending on whether the rule is being 
  5074. executed for a target with a single colon ":" or double colon "::" dependency. 
  5075. If the target has a single colon or double colon dependency, the "$^", "$[", 
  5076. and "$]" special macros will reflect the values in the rule that caused the 
  5077. implicit rule to be invoked.  Otherwise, if the target does not have a 
  5078. dependency rule then the "$[" and "$]" special macros will be set to the same 
  5079. value, namely, the file found in the implicit rule search. 
  5080.  
  5081. We will use the last programming example to illustrate a possible use of 
  5082. implicit rules. 
  5083.  
  5084.  
  5085.    # 
  5086.    # programming example 
  5087.    # (implicit rules) 
  5088.    # 
  5089.    version = debugging      # debugging version 
  5090.  
  5091.    msg_production = linking production version ... 
  5092.    msg_debugging = linking debug version ... 
  5093.  
  5094.    link_options_production = 
  5095.    link_options_debugging = debug all 
  5096.    link_options = $(link_options_$(version)) 
  5097.  
  5098.    compiler = wcc386 
  5099.    compile_options_production = /mf /w3 
  5100.    compile_options_debugging = /mf /d1 /w3 
  5101.    compile_options = $(compile_options_$(version)) 
  5102.  
  5103.    header_files = defs.h globals.h 
  5104.    object_files = main.obj input.obj calc.obj & 
  5105.           output.obj 
  5106.  
  5107.    plot.exe : $(object_files) 
  5108.        echo $(msg_$(version)) 
  5109.        wlink $(link_options) @$^* 
  5110.  
  5111.    .c.obj: 
  5112.        $(compiler) $[* $(compile_options) 
  5113.  
  5114.    main.obj : main.c $(header_files) 
  5115.  
  5116.    calc.obj : calc.c $(header_files) 
  5117.  
  5118.    input.obj : input.c $(header_files) 
  5119.  
  5120.    output.obj : output.c $(header_files) 
  5121.  
  5122. As this makefile is processed, any time an object file is found to be older 
  5123. than its associated source file or header files then Make will attempt to 
  5124. execute the command list associated with the explicit rule.  Since there are no 
  5125. command lists associated with the four object file targets, an implicit rule 
  5126. search is conducted.  Suppose "CALC.OBJ" was older than "CALC.C".  The lack of 
  5127. a command list in the explicit rule with "CALC.OBJ" as a target causes the 
  5128. ".c.obj" implicit rule to be invoked for "CALC.OBJ".  The file "CALC.C" is 
  5129. found to exist so the commands 
  5130.  
  5131.  
  5132.        wcc386 calc /mf /d1 /w3 
  5133.        echo linking debug version ... 
  5134.        wlink debug all @plot 
  5135.  
  5136. are executed.  The last two commands are a result of the compilation of 
  5137. "CALC.C" producing a "CALC.OBJ" file that is younger than the "PLOT.EXE" file 
  5138. that in turn must be generated again. 
  5139.  
  5140. The use of implicit rules is straightforward when all the files that the 
  5141. makefile deals with are in the current directory.  Larger applications may have 
  5142. files that are in many different directories.  Suppose we moved the programming 
  5143. example files to three sub-directories. 
  5144.  
  5145.  *.H 
  5146.        \EXAMPLE\H 
  5147.  
  5148.  *.C 
  5149.        \EXAMPLE\C 
  5150.  
  5151.  rest 
  5152.        \EXAMPLE\O 
  5153.  
  5154.  Now the previous makefile (located in the \EXAMPLE\O sub-directory) would look 
  5155.  like this: 
  5156.  
  5157.  
  5158.     # 
  5159.     # programming example 
  5160.     # (implicit rules) 
  5161.     # 
  5162.     h_dir  = \example\h\ #sub-directory containing header files 
  5163.     c_dir  = \example\c\ #sub-directory containing C/C++ files 
  5164.     version = debugging  # debugging version 
  5165.  
  5166.     msg_production = linking production version ... 
  5167.     msg_debugging = linking debug version ... 
  5168.  
  5169.     link_options_production = 
  5170.     link_options_debugging = debug all 
  5171.     link_options = $(link_options_$(version)) 
  5172.  
  5173.     compiler = wcc386 
  5174.     compile_options_production = /mf /w3 
  5175.     compile_options_debugging = /mf /d1 /w3 
  5176.     compile_options = $(compile_options_$(version)) 
  5177.  
  5178.     header_files = $(h_dir)defs.h $(h_dir)globals.h 
  5179.     object_files = main.obj input.obj calc.obj & 
  5180.            output.obj 
  5181.  
  5182.     plot.exe : $(object_files) 
  5183.         echo $(msg_$(version)) 
  5184.         wlink $(link_options) @$^* 
  5185.  
  5186.     .c.obj: 
  5187.         $(compiler) $[* $(compile_options) 
  5188.  
  5189.     main.obj : $(c_dir)main.c $(header_files) 
  5190.  
  5191.     calc.obj : $(c_dir)calc.c $(header_files) 
  5192.  
  5193.     input.obj : $(c_dir)input.c $(header_files) 
  5194.  
  5195.     output.obj : $(c_dir)output.c $(header_files) 
  5196.  
  5197.  Suppose "\EXAMPLE\O\CALC.OBJ" was older than "\EXAMPLE\C\CALC.C".  The lack of 
  5198.  a command list in the explicit rule with "CALC.OBJ" as a target causes the 
  5199.  ".c.obj" implicit rule to be invoked for "CALC.OBJ".  At this time, the file 
  5200.  "\EXAMPLE\O\CALC.C" is not found so an error is reported indicating that 
  5201.  "CALC.OBJ" could not be updated.  How may implicit rules be useful in larger 
  5202.  applications if they will only search the current directory for the dependent 
  5203.  file?  We must specify more information about the dependent extension (in this 
  5204.  case ".C").  We do this by associating a path with the dependent extension as 
  5205.  follows: 
  5206.  
  5207.  
  5208.     .<dependent_extension> : <path_specification> 
  5209.  
  5210.  This allows the implicit rule search to find the files with the dependent 
  5211.  extension. 
  5212.  
  5213.  Hint:  A valid path specification is made up of directory specifications 
  5214.  separated by semicolons (";").  Here are some path specifications: 
  5215.  
  5216.  D:;C:\DOS;C:\UTILS;C:\WC 
  5217.  C:\SYS 
  5218.  A:\BIN;D: 
  5219.  Notice that these path specifications are identical to the form required by 
  5220.  the operating system shell's "PATH" command. 
  5221.  
  5222.  Our makefile will be correct now if we add the new declaration as follows: 
  5223.  
  5224.     # 
  5225.     # programming example 
  5226.     # (implicit rules) 
  5227.     # 
  5228.     h_dir  = \example\h\ #sub-directory containing header files 
  5229.     c_dir  = \example\c\ #sub-directory containing C/C++ files 
  5230.     version = debugging   # debugging version 
  5231.  
  5232.     msg_production = linking production version ... 
  5233.     msg_debugging = linking debug version ... 
  5234.  
  5235.     link_options_production = 
  5236.     link_options_debugging = debug all 
  5237.     link_options = $(link_options_$(version)) 
  5238.  
  5239.     compiler = wcc386 
  5240.     compile_options_production = /mf /w3 
  5241.     compile_options_debugging = /mf /d1 /w3 
  5242.     compile_options = $(compile_options_$(version)) 
  5243.  
  5244.     header_files = $(h_dir)defs.h $(h_dir)globals.h 
  5245.     object_files = main.obj input.obj calc.obj & 
  5246.            output.obj 
  5247.  
  5248.     plot.exe : $(object_files) 
  5249.         echo $(msg_$(version)) 
  5250.         wlink $(link_options) @$^* 
  5251.  
  5252.     .c:   $(c_dir) 
  5253.     .c.obj: 
  5254.         $(compiler) $[* $(compile_options) 
  5255.  
  5256.     main.obj : $(c_dir)main.c $(header_files) 
  5257.  
  5258.     calc.obj : $(c_dir)calc.c $(header_files) 
  5259.  
  5260.     input.obj : $(c_dir)input.c $(header_files) 
  5261.  
  5262.     output.obj : $(c_dir)output.c $(header_files) 
  5263.  
  5264.  Suppose "\EXAMPLE\O\CALC.OBJ" is older than "\EXAMPLE\C\CALC.C".  The lack of 
  5265.  a command list in the explicit rule with "CALC.OBJ" as a target will cause the 
  5266.  ".c.obj" implicit rule to be invoked for "CALC.OBJ".  The dependent extension 
  5267.  ".C" has a path associated with it so the file "\EXAMPLE\C\CALC.C" is found to 
  5268.  exist.  The commands 
  5269.  
  5270.  
  5271.         wcc386 \EXAMPLE\C\CALC /mf /d1 /w3 
  5272.         echo linking debug version ... 
  5273.         wlink debug all @plot 
  5274.  
  5275.  are executed to update the necessary files. 
  5276.  
  5277.  If the application requires many source files in different directories Make 
  5278.  will search for the files using their associated path specifications.  For 
  5279.  instance, if the current example files were setup as follows: 
  5280.  
  5281.  \EXAMPLE\H 
  5282.        DEFS.H, GLOBALS.H 
  5283.  
  5284.  \EXAMPLE\C\PROGRAM 
  5285.        MAIN.C, CALC.C 
  5286.  
  5287.  \EXAMPLE\C\SCREEN 
  5288.        INPUT.C, OUTPUT.C 
  5289.  
  5290.  \EXAMPLE\O 
  5291.        PLOT.EXE, MAKEFILE, MAIN.OBJ, CALC.OBJ, INPUT.OBJ, OUTPUT.OBJ 
  5292.  
  5293.  the makefile would be changed to: 
  5294.  
  5295.  
  5296.     # 
  5297.     # programming example 
  5298.     # (implicit rules) 
  5299.     # 
  5300.     h_dir     = ..\h\   # sub-directory with header files 
  5301.                 # sub-directories with C/C++ source files 
  5302.     program_dir  = ..\c\program\ # - MAIN.C, CALC.C 
  5303.     screen_dir  = ..\c\screen\  # - INPUT.C, OUTPUT.C 
  5304.     version    = debugging   # debugging version 
  5305.  
  5306.     msg_production = linking production version ... 
  5307.     msg_debugging = linking debug version ... 
  5308.  
  5309.     link_options_production = 
  5310.     link_options_debugging = debug all 
  5311.     link_options = $(link_options_$(version)) 
  5312.  
  5313.     compiler = wcc386 
  5314.     compile_options_production = /mf /w3 
  5315.     compile_options_debugging = /mf /d1 /w3 
  5316.     compile_options = $(compile_options_$(version)) 
  5317.  
  5318.     header_files = $(h_dir)defs.h $(h_dir)globals.h 
  5319.     object_files = main.obj input.obj calc.obj & 
  5320.            output.obj 
  5321.  
  5322.     plot.exe : $(object_files) 
  5323.         echo $(msg_$(version)) 
  5324.         wlink $(link_options) @$^* 
  5325.  
  5326.     .c:   $(program_dir);$(screen_dir) 
  5327.     .c.obj: 
  5328.         $(compiler) $[* $(compile_options) 
  5329.  
  5330.     main.obj : $(program_dir)main.c $(header_files) 
  5331.  
  5332.     calc.obj : $(program_dir)calc.c $(header_files) 
  5333.  
  5334.     input.obj : $(screen_dir)input.c $(header_files) 
  5335.  
  5336.     output.obj : $(screen_dir)output.c $(header_files) 
  5337.  
  5338.  Suppose that there is a change in the "DEFS.H" file which causes all the 
  5339.  source files to be recompiled. The implicit rule ".c.obj" is invoked for every 
  5340.  object file so the corresponding ".C" file must be found for each ".OBJ" file. 
  5341.  We will show where Make searches for the C/C++ source files. 
  5342.  
  5343.  
  5344.     update   main.obj 
  5345.      test   ..\c\program\main.c       (it does exist) 
  5346.      execute wcc386 ..\c\program\main /mf /d1 /w3 
  5347.  
  5348.     update   calc.obj 
  5349.      test   ..\c\program\calc.c       (it does exist) 
  5350.      execute wcc386 ..\c\program\calc /mf /d1 /w3 
  5351.  
  5352.     update   input.obj 
  5353.      test   ..\c\program\input.c    (it does not exist) 
  5354.      test   ..\c\screen\input.c       (it does exist) 
  5355.      execute wcc386 ..\c\screen\input /mf /d1 /w3 
  5356.  
  5357.     update   output.obj 
  5358.      test   ..\c\program\output.c    (it does not exist) 
  5359.      test   ..\c\screen\output.c      (it does exist) 
  5360.      execute wcc386 ..\c\screen\output /mf /d1 /w3 
  5361.  
  5362.     etc. 
  5363.  
  5364.  Notice that Make checked the sub-directory "..\C\PRORGAM" for the files 
  5365.  "INPUT.C" and "OUTPUT.C".  Make optionally may use a circular path 
  5366.  specification search which may save on disk activity for large makefiles.  The 
  5367.  circular path searching may be used in two different ways: 
  5368.  
  5369.    1. use the command line option "o" 
  5370.  
  5371.    2. use the .OPTIMIZE directive. 
  5372.  
  5373.  Make will retain (for each suffix) what sub-directory yielded the last 
  5374.  successful search for a file.  The search for a file is resumed at this 
  5375.  directory in the hope that wasted disk activity will be minimized.  If the 
  5376.  file cannot be found in the sub-directory then Make will search the next 
  5377.  sub-directory in the path specification (cycling to the first sub-directory in 
  5378.  the path specification after an unsuccessful search in the last 
  5379.  sub-directory). 
  5380.  
  5381.  Changing the previous example to include this feature, results in the 
  5382.  following: 
  5383.  
  5384.  
  5385.     # 
  5386.     # programming example 
  5387.     # (optimized path searching) 
  5388.     # 
  5389.     .OPTIMIZE 
  5390.  
  5391.     h_dir     = ..\h\   # sub-directory with header files 
  5392.                 # sub-directories with C/C++ source files 
  5393.     program_dir  = ..\c\program\ # - MAIN.C, CALC.C 
  5394.     screen_dir  = ..\c\screen\  # - INPUT.C, OUTPUT.C 
  5395.     version    = debugging   # debugging version 
  5396.  
  5397.     msg_production = linking production version ... 
  5398.     msg_debugging = linking debug version ... 
  5399.  
  5400.     link_options_production = 
  5401.     link_options_debugging = debug all 
  5402.     link_options = $(link_options_$(version)) 
  5403.  
  5404.     compiler = wcc386 
  5405.     compile_options_production = /mf /w3 
  5406.     compile_options_debugging = /mf /d1 /w3 
  5407.     compile_options = $(compile_options_$(version)) 
  5408.  
  5409.     header_files = $(h_dir)defs.h $(h_dir)globals.h 
  5410.     object_files = main.obj input.obj calc.obj & 
  5411.            output.obj 
  5412.  
  5413.     plot.exe : $(object_files) 
  5414.         echo $(msg_$(version)) 
  5415.         wlink $(link_options) @$^* 
  5416.  
  5417.     .c:   $(program_dir);$(screen_dir) 
  5418.     .c.obj: 
  5419.         $(compiler) $[* $(compile_options) 
  5420.     main.obj : $(program_dir)main.c $(header_files) 
  5421.  
  5422.     calc.obj : $(program_dir)calc.c $(header_files) 
  5423.  
  5424.     input.obj : $(screen_dir)input.c $(header_files) 
  5425.  
  5426.     output.obj : $(screen_dir)output.c $(header_files) 
  5427.  
  5428.  Suppose again that there is a change in the "DEFS.H" file which causes all the 
  5429.  source files to be recompiled.  We will show where Make searches for the C/C++ 
  5430.  source files using the optimized path specification searching. 
  5431.  
  5432.  
  5433.     update   main.obj 
  5434.      test   ..\c\program\main.c       (it does exist) 
  5435.      execute wcc386 ..\c\program\main /mf /d1 /w3 
  5436.  
  5437.     update   calc.obj 
  5438.      test   ..\c\program\calc.c       (it does exist) 
  5439.      execute wcc386 ..\c\program\calc /mf /d1 /w3 
  5440.  
  5441.     update   input.obj 
  5442.      test   ..\c\program\input.c    (it does not exist) 
  5443.      test   ..\c\screen\input.c       (it does exist) 
  5444.      execute wcc386 ..\c\screen\input /mf /d1 /w3 
  5445.  
  5446.     update   output.obj 
  5447.      test   ..\c\screen\output.c      (it does exist) 
  5448.      execute wcc386 ..\c\screen\output /mf /d1 /w3 
  5449.  
  5450.     etc. 
  5451.  
  5452.  Make did not check the sub-directory "..\C\PROGRAM" for the file "OUTPUT.C" 
  5453.  because the last successful attempt to find a ".C" file occurred in the 
  5454.  "..\C\SCREEN" sub-directory.  In this small example, the amount of disk 
  5455.  activity saved by Make is not substantial but the savings become much more 
  5456.  pronounced in larger makefiles. 
  5457.  
  5458.  Hint:  The simple heuristic method that Make uses for optimizing path 
  5459.  specification searches namely, keeping track of the last successful 
  5460.  sub-directory, is very effective in reducing the amount of disk activity 
  5461.  during the processing of a makefile.  A pitfall to avoid is having two files 
  5462.  with the same name in the path.  The version of the file that is used to 
  5463.  update the target depends on the previous searches.  Care should be taken when 
  5464.  using files that have the same name with path specifications. 
  5465.  
  5466.  Large makefiles for projects written in C/C++ may become difficult to maintain 
  5467.  with all the header file dependencies.  Ignoring header file dependencies and 
  5468.  using implicit rules may reduce the size of the makefile while keeping most of 
  5469.  the functionality intact.  The previous example may be made smaller by using 
  5470.  this idea. 
  5471.  
  5472.  
  5473.     # 
  5474.     # programming example 
  5475.     # (no header dependencies) 
  5476.     # 
  5477.     .OPTIMIZE 
  5478.  
  5479.     h_dir     = ..\h\   # sub-directory with header files 
  5480.                 # sub-directories with C/C++ source files 
  5481.     program_dir  = ..\c\program\ # - MAIN.C, CALC.C 
  5482.     screen_dir  = ..\c\screen\  # - INPUT.C, OUTPUT.C 
  5483.     version    = debugging   # debugging version 
  5484.  
  5485.     msg_production = linking production version ... 
  5486.     msg_debugging = linking debug version ... 
  5487.  
  5488.     link_options_production = 
  5489.     link_options_debugging = debug all 
  5490.     link_options = $(link_options_$(version)) 
  5491.  
  5492.     compiler = wcc386 
  5493.     compile_options_production = /mf /w3 
  5494.     compile_options_debugging = /mf /d1 /w3 
  5495.     compile_options = $(compile_options_$(version)) 
  5496.  
  5497.     object_files = main.obj input.obj calc.obj & 
  5498.            output.obj 
  5499.  
  5500.     plot.exe : $(object_files) 
  5501.         echo $(msg_$(version)) 
  5502.         wlink $(link_options) @$^* 
  5503.  
  5504.     .c:   $(program_dir);$(screen_dir) 
  5505.     .c.obj: 
  5506.         $(compiler) $[* $(compile_options) 
  5507.  
  5508.  Implicit rules are very useful in this regard providing you are aware that you 
  5509.  have to make up for the information that is missing from the makefile.  In the 
  5510.  case of C/C++ programs, you must ensure that you force Make to compile any 
  5511.  programs affected by changes in header files.  Forcing Make to compile 
  5512.  programs may be done by touching source files (not recommended), deleting 
  5513.  object files, or using the "a" option and targets on the command line.  Here 
  5514.  is how the files "INPUT.OBJ" and "MAIN.OBJ" may be recompiled if a change in 
  5515.  some header file affects both files. 
  5516.  
  5517.  Example: 
  5518.  
  5519.     del input.obj 
  5520.     del main.obj 
  5521.     wmake 
  5522.  
  5523.  or using the "a" option 
  5524.  
  5525.  Example: 
  5526.  
  5527.     wmake /a input.obj main.obj 
  5528.  
  5529.  The possibility of introducing bugs into programs is present when using this 
  5530.  makefile technique because it does not protect the programmer completely from 
  5531.  object modules becoming out-of-date.  The use of implicit rules without header 
  5532.  file dependencies is a viable makefile technique but it is not without its 
  5533.  pitfalls. 
  5534.  
  5535.  
  5536. ΓòÉΓòÉΓòÉ 8.15. Double Colon Explicit Rules ΓòÉΓòÉΓòÉ
  5537.  
  5538.  
  5539. Single colon ":" explicit rules are useful in many makefile applications. 
  5540. However, the single colon rule has certain restrictions that make it difficult 
  5541. to express more complex dependency relationships.  The restrictions imposed on 
  5542. single colon ":" explicit rules are: 
  5543.  
  5544.    1. only one command list is allowed for each target 
  5545.  
  5546.    2. after the command list is executed, the target is considered up to date 
  5547.  
  5548.  The first restriction becomes evident when you want to update a target in 
  5549.  different ways (i.e., when the target is out of date with respect to different 
  5550.  dependents).  The double colon explicit rule removes this restriction. 
  5551.  
  5552.  
  5553.     # 
  5554.     # multiple command lists 
  5555.     # 
  5556.     target1 :: dependent1 dependent2 
  5557.         command1 
  5558.  
  5559.     target1 :: dependent3 dependent4 
  5560.         command2 
  5561.  
  5562.  Notice that if "target1" is out of date with respect to either "dependent1" or 
  5563.  "dependent2" then "command1" will be executed.  The double colon "::" explicit 
  5564.  rule does not consider the target (in this case "target1") up to date after 
  5565.  the command list is executed.  Make will continue to attempt to update 
  5566.  "target1".  Afterwards "command2" will be executed if "target1" is out of date 
  5567.  with respect to either "dependent3" or "dependent4".  It is possible that both 
  5568.  "command1" and "command2" will be executed.  As a result of the target not 
  5569.  being considered up to date, an implicit rule search will be conducted on 
  5570.  "target1" also.  Make will process the double colon "::" explicit rules in the 
  5571.  order that they are encountered in the makefile.  A useful application of the 
  5572.  double colon "::" explicit rule involves maintaining and using prototype 
  5573.  information generated by a compiler. 
  5574.  
  5575.  
  5576.     # 
  5577.     # double colon "::" example 
  5578.     # 
  5579.     compiler = wcc386 
  5580.     options = /w3 
  5581.  
  5582.     # generate macros for the .OBJ and .DEF files 
  5583.     template = module1.$(ext) module2.$(ext) module3.$(ext) 
  5584.     ext = obj 
  5585.     objs = $+ $(template) $- 
  5586.     ext = def 
  5587.     defs = $+ $(template) $- 
  5588.  
  5589.     # add .DEF to the extensions list 
  5590.     .EXTENSIONS: 
  5591.     .EXTENSIONS: .exe .obj .def .c 
  5592.  
  5593.     # implicit rules for the .OBJ and .DEF files 
  5594.     .c.obj: 
  5595.         $(compiler) $[* $(options) 
  5596.  
  5597.     # generate the prototype file (only do a syntax check) 
  5598.     .c.def: 
  5599.         $(compiler) $[* $(options) /v/zs 
  5600.  
  5601.     program.exe :: $(defs) 
  5602.         erase *.err 
  5603.  
  5604.     program.exe :: $(objs) 
  5605.         wlink @$^* 
  5606.  
  5607.  The ".OBJ" files are updated to complete the update of the file "PROGRAM.EXE". 
  5608.  It is important to keep in mind that Make does not consider the file 
  5609.  "PROGRAM.EXE" up to date until it has conducted a final implicit rule search. 
  5610.  The double colon "::" explicit rule is useful when describing complex update 
  5611.  actions. 
  5612.  
  5613.  
  5614. ΓòÉΓòÉΓòÉ 8.16. Preprocessing Directives ΓòÉΓòÉΓòÉ
  5615.  
  5616.  
  5617. One of the primary objectives in using a make utility is to improve the 
  5618. development and maintenance of projects.  A programming project consisting of 
  5619. many makefiles in different sub-directories may become unwieldy to maintain. 
  5620. The maintenance problem stems from the amount of duplicated information 
  5621. scattered throughout the project makefiles.  Make provides a method to reduce 
  5622. the amount of duplicated information present in makefiles.  Preprocessing 
  5623. directives provide the capability for different makefiles to make use of common 
  5624. information. 
  5625.  
  5626.  
  5627. ΓòÉΓòÉΓòÉ 8.16.1. File Inclusion ΓòÉΓòÉΓòÉ
  5628.  
  5629.  
  5630. A common solution to the "duplicated information" problem involves referencing 
  5631. text contained in one file from many different files.  Make supports file 
  5632. inclusion with the !include preprocessing directive.  The development of object 
  5633. libraries, using 16-bit Watcom C/C++, for the different 80x86 16-bit memory 
  5634. models provides an ideal example to illustrate the use of the !include 
  5635. preprocessing directive. 
  5636.  
  5637.  \WINDOW 
  5638.        WINDOW.CMD, WINDOW.MIF 
  5639.  
  5640.  \WINDOW\H 
  5641.        PROTO.H, GLOBALS.H, BIOS_DEF.H 
  5642.  
  5643.  \WINDOW\C 
  5644.        WINDOW.C, KEYBOARD.C, MOUSE.C, BIOS.C 
  5645.  
  5646.  \WINDOW\SCSD 
  5647.       small model object files, MAKEFILE, WINDOW_S.LIB 
  5648.  
  5649.  \WINDOW\SCBD 
  5650.       compact model object files, MAKEFILE, WINDOW_C.LIB 
  5651.  
  5652.  \WINDOW\BCSD 
  5653.       medium model object files, MAKEFILE, WINDOW_M.LIB 
  5654.  
  5655.  \WINDOW\BCBD 
  5656.       large model object files, MAKEFILE, WINDOW_L.LIB 
  5657.  
  5658.  \WINDOW\BCHD 
  5659.       huge model object files, MAKEFILE, WINDOW_L.LIB 
  5660.  
  5661.  The WLIB command file "WINDOW.CMD" contains the list of library operations 
  5662.  required to build the libraries. The contents of "WINDOW.CMD" are: 
  5663.  
  5664.  
  5665.     -+window 
  5666.     -+bios 
  5667.     -+keyboard 
  5668.     -+mouse 
  5669.  
  5670.  The "-+" library manager command indicates to WLIB that the object file should 
  5671.  be replaced in the library. 
  5672.  
  5673.  The file "WINDOW.MIF" contains the makefile declarations that are common to 
  5674.  every memory model.  The ".MIF" extension will be used for all the Make 
  5675.  Include Files discussed in this manual.  This extension is also in the default 
  5676.  extension list so it is a recommended extension for Make include files.  The 
  5677.  contents of the "WINDOW.MIF" file is as follows: 
  5678.  
  5679.  
  5680.     # 
  5681.     # example of a Make Include File 
  5682.     # 
  5683.     common = /d1 /w3      # common options 
  5684.     objs = window.obj bios.obj keyboard.obj mouse.obj 
  5685.  
  5686.     .c: ..\c 
  5687.     .c.obj: 
  5688.         wcc $[* $(common) $(local) /m$(model) 
  5689.  
  5690.     window_$(model).lib : $(objs) 
  5691.         wlib window_$(model) @..\window 
  5692.  
  5693.  The macros "model" and "local" are defined by the file "MAKEFILE" in each 
  5694.  object directory.  An example of the file "MAKEFILE" in the medium memory 
  5695.  model object directory is: 
  5696.  
  5697.  
  5698.     # 
  5699.     # !include example 
  5700.     # 
  5701.     model = m     # memory model required 
  5702.     local =      # memory model specific options 
  5703.     !include ..\window.mif 
  5704.  
  5705.  Notice that changes that affect all the memory models may be made in one file, 
  5706.  namely "WINDOW.MIF".  Any changes that are specific to a memory model may be 
  5707.  made to the "MAKEFILE" in the object directory.  To update the medium memory 
  5708.  model library, the following commands may be executed: 
  5709.  
  5710.  Example: 
  5711.  
  5712.     C>cd \window\bcsd 
  5713.     C>wmake 
  5714.  
  5715.  A DOS ".BAT" or OS/2 ".CMD" file may be used to update all the different 
  5716.  memory models.  If the following DOS "MAKEALL.BAT" (OS/2 "MAKEALL.CMD") file 
  5717.  is located somewhere in the "PATH", we may update all the libraries. 
  5718.  
  5719.  
  5720.     cd \window\scsd 
  5721.     wmake %1 %2 %3 %4 %5 %6 %7 %8 %9 
  5722.     cd \window\scbd 
  5723.     wmake %1 %2 %3 %4 %5 %6 %7 %8 %9 
  5724.     cd \window\bcsd 
  5725.     wmake %1 %2 %3 %4 %5 %6 %7 %8 %9 
  5726.     cd \window\bcbd 
  5727.     wmake %1 %2 %3 %4 %5 %6 %7 %8 %9 
  5728.     cd \window\bchd 
  5729.     wmake %1 %2 %3 %4 %5 %6 %7 %8 %9 
  5730.  
  5731.  The batch file parameters are useful if you want to specify options to Make. 
  5732.  For instance, a global recompile may be done by executing: 
  5733.  
  5734.  Example: 
  5735.  
  5736.     C>makeall /a 
  5737.  
  5738.  The !include preprocessing directive is a good way to partition common 
  5739.  information so that it may be maintained easily. 
  5740.  
  5741.  Another use of the !include involves program generated makefile information. 
  5742.  For instance, if we have a program called "WMKMK" that will search through 
  5743.  source files and generate a file called "WMKMK.MIF" that contains: 
  5744.  
  5745.  
  5746.     # 
  5747.     # program generated makefile information 
  5748.     # 
  5749.     C_to_OBJ = $(compiler) $[* $(compile_options) 
  5750.  
  5751.     OBJECTS = WINDOW.OBJ BIOS.OBJ KEYBOARD.OBJ MOUSE.OBJ 
  5752.  
  5753.     WINDOW.OBJ : ..\C\WINDOW.C ..\H\PROTO.H ..\H\GLOBALS.H 
  5754.       $(C_to_OBJ) 
  5755.     BIOS.OBJ : ..\C\BIOS.C ..\H\BIOS_DEF.H ..\H\GLOBALS.H 
  5756.       $(C_to_OBJ) 
  5757.     KEYBOARD.OBJ : ..\C\KEYBOARD.C ..\H\PROTO.H ..\H\GLOBALS.H 
  5758.       $(C_to_OBJ) 
  5759.     MOUSE.OBJ : ..\C\MOUSE.C ..\H\PROTO.H ..\H\GLOBALS.H 
  5760.       $(C_to_OBJ) 
  5761.  
  5762.  In order to use this program generated makefile information, we use a 
  5763.  "MAKEFILE" containing: 
  5764.  
  5765.  
  5766.     # 
  5767.     # makefile that makes use of generated makefile information 
  5768.     # 
  5769.     compile_options = /mf /d1 /w3 
  5770.  
  5771.     first_target : window.lib .SYMBOLIC 
  5772.         echo done 
  5773.  
  5774.     !include wmkmk.mif 
  5775.  
  5776.     window.lib : $(OBJECTS) 
  5777.         wlib window $(OBJECTS) 
  5778.  
  5779.     make : .SYMBOLIC 
  5780.         wmkmk /r ..\c\*.c+..\c\*.cpp+..\h 
  5781.  
  5782.  Notice that there is a symbolic target "first_target" that is used as a "place 
  5783.  holder".  The default behaviour for Make is to "make" the first target 
  5784.  encountered in the makefile.  The symbolic target "first_target" ensures that 
  5785.  we have control over what file will be updated first (in this case 
  5786.  "WINDOW.LIB").  The use of the !include preprocessing directive simplifies the 
  5787.  use of program generated makefile information because any changes are 
  5788.  localized to the file "MAKEFILE".  As program development continues, the file 
  5789.  "WMKMK.MIF" may be regenerated so that subsequent invocations of WMAKE benefit 
  5790.  from the new makefile information.  The file "MAKEFILE" even contains the 
  5791.  command to regenerate the file "WMKMK.MIF".  The symbolic target "make" has an 
  5792.  associated command list that will regenerate the file "WMKMK.MIF".  The 
  5793.  command list can be executed by typing the following command: 
  5794.  
  5795.  Example: 
  5796.  
  5797.     C>wmake make 
  5798.  
  5799.  The use of the !include preprocessing directive is a simple way to reduce 
  5800.  maintenance of related makefiles. 
  5801.  
  5802.  Hint:  Macros are expanded on !include preprocessor control lines.  This 
  5803.  allows many benefits like: 
  5804.  
  5805.  !include $(%env_var) 
  5806.  
  5807.  so that the files that Make will process can be controlled through many 
  5808.  different avenues like internal macros, command line macros, and environment 
  5809.  variables. 
  5810.  
  5811.  Another way to access files is through the suffix path feature of Make.  A 
  5812.  definition like 
  5813.  
  5814.  .mif :  c:\mymifs;d:\some\more\mifs 
  5815.  
  5816.  will cause Make to search different paths for any make include files. 
  5817.  
  5818.  
  5819. ΓòÉΓòÉΓòÉ 8.16.2. Conditional Processing ΓòÉΓòÉΓòÉ
  5820.  
  5821.  
  5822. Watcom Make has conditional preprocessing directives available that allow 
  5823. different declarations to be processed.  The conditional preprocessing 
  5824. directives allow the makefile to 
  5825.  
  5826.    1. check whether a macro is defined, and 
  5827.  
  5828.    2. check whether a macro has a certain value. 
  5829.  
  5830.  The macros that can be checked include 
  5831.  
  5832.    1. normal macros "$(<macro_identifier>)" 
  5833.  
  5834.    2. environment macros "$(%<environment_var>)" 
  5835.  
  5836.  The conditional preprocessing directives allow a makefile to adapt to 
  5837.  different external conditions based on the values of macros or environment 
  5838.  variables.  We can define macros on the WMAKE command line as shown in the 
  5839.  following example. 
  5840.  
  5841.  Example: 
  5842.  
  5843.     C>wmake "macro=some text with spaces in it" 
  5844.  
  5845.  Alternatively, we can include a makefile that defines the macros if all the 
  5846.  macros cannot fit on the command line.  This is shown in the following 
  5847.  example: 
  5848.  
  5849.  Example: 
  5850.  
  5851.     C>wmake /f macdef.mif /f makefile 
  5852.  
  5853.  Also, environment variables can be set before WMAKE is invoked.  This is shown 
  5854.  in the following example: 
  5855.  
  5856.  Example: 
  5857.  
  5858.     C>set macro=some text with spaces in it 
  5859.     C>wmake 
  5860.  
  5861.  Now that we know how to convey information to Make through either macros or 
  5862.  environment variables, we will look at how this information can be used to 
  5863.  influence makefile processing. 
  5864.  
  5865.  Make has conditional preprocessing directives that are similar to the C 
  5866.  preprocessor directives.  Make supports these preprocessor directives: 
  5867.  
  5868.  
  5869.     !ifeq 
  5870.     !ifneq 
  5871.     !ifeqi 
  5872.     !ifneqi 
  5873.     !ifdef 
  5874.     !ifndef 
  5875.  
  5876.  along with 
  5877.  
  5878.  
  5879.     !else 
  5880.     !endif 
  5881.  
  5882.  Together these preprocessor directives allow selection of makefile 
  5883.  declarations to be based on either the value or the existence of a macro. 
  5884.  
  5885.  Environment variables can be checked by using an environment variable name 
  5886.  prefixed with a "%".  A common use of a conditional preprocessing directive 
  5887.  involves setting environment variables. 
  5888.  
  5889.  
  5890.     # 
  5891.     # setting an environment variable 
  5892.     # 
  5893.     !ifndef %lib 
  5894.  
  5895.     .BEFORE 
  5896.         set lib=c:\watcom\lib386;c:\watcom\lib386\dos 
  5897.     !endif 
  5898.  
  5899.  If you are writing portable applications, you might want to have: 
  5900.  
  5901.  
  5902.     # 
  5903.     # checking a macro 
  5904.     # 
  5905.     !include version.mif 
  5906.  
  5907.     !ifdef OS2 
  5908.     machine = /2      # compile for 286 
  5909.     !else 
  5910.     machine = /0      # default: 8086 
  5911.     !endif 
  5912.  
  5913.  The !ifdef ("if defined") and !ifndef ("if not defined") conditional 
  5914.  preprocessing directives are useful for checking boolean conditions.  In other 
  5915.  words, the !ifdef and !ifndef are useful for "yes-no" conditions.  There are 
  5916.  instances where it would be useful to check a macro against a value.  In order 
  5917.  to use the value checking preprocessor directives, we must know the exact 
  5918.  value of a macro.  A macro definition is of the form: 
  5919.  
  5920.  
  5921.     <macro_identifier> = <text> <comment> 
  5922.  
  5923.  Make will first strip any comment off the line.  The macro definition will 
  5924.  then be the text following the equal "=" sign with leading and trailing blanks 
  5925.  removed.  Initially this might not seem like a sensible way to define a macro 
  5926.  but it does lend itself well to defining macros that are common in makefiles. 
  5927.  For instance, it allows definitions like: 
  5928.  
  5929.  
  5930.     # 
  5931.     # sample macro definitions 
  5932.     # 
  5933.     link_options   = debug line  # line number debugging 
  5934.     compile_options = /d1 /s    # line numbers, no stack checking 
  5935.  
  5936.  These definitions are both readable and useful.  A makefile can handle 
  5937.  differences between compilers with the !ifeq, !ifneq, !ifeqi and !ifneqi 
  5938.  conditional preprocessing directives.  The first two perform case sensitive 
  5939.  comparisons while the last two perform case insensitive comparisons.  One way 
  5940.  of setting up adaptive makefiles is: 
  5941.  
  5942.  
  5943.     # 
  5944.     # options made simple 
  5945.     # 
  5946.     compiler     = wcc386 
  5947.  
  5948.     stack_overflow  = No  # yes -> check for stack overflow 
  5949.     line_info    = Yes  # yes -> generate line numbers 
  5950.  
  5951.     !ifeq compiler wcc386 
  5952.     !ifneqi stack_overflow  yes 
  5953.     stack_option   =    /s 
  5954.     !endif 
  5955.     !ifeqi line_info     yes 
  5956.     line_option   =    /d1 
  5957.     !endif 
  5958.     !endif 
  5959.  
  5960.     !ifeq compiler tcc 
  5961.     !ifeqi stack_overflow   yes 
  5962.     stack_option   =    -N 
  5963.     !endif 
  5964.     !ifeqi line_info     yes 
  5965.     line_option   =    -y 
  5966.     !endif 
  5967.     !endif 
  5968.  
  5969.     # 
  5970.     # make sure the macros are defined 
  5971.     # 
  5972.     !ifndef stack_option 
  5973.     stack_option   = 
  5974.     !endif 
  5975.     !ifndef line_option 
  5976.     line_option   = 
  5977.     !endif 
  5978.  
  5979.     example : .SYMBOLIC 
  5980.         echo $(compiler) $(stack_option) $(line_option) 
  5981.  
  5982.  The conditional preprocessing directives can be very useful to hide 
  5983.  differences, exploit similarities, and organize declarations for applications 
  5984.  that use many different programs. 
  5985.  
  5986.  Another directive is the !define directive.  This directive is equivalent to 
  5987.  the normal type of macro definition (i.e., macro = text) but will make C 
  5988.  programmers feel more at home.  One important distinction is that the !define 
  5989.  preprocessor directive may be used to reflect the logical structure of macro 
  5990.  definitions in conditional processing. For instance, the previous makefile 
  5991.  could have been written in this style: 
  5992.  
  5993.  
  5994.     !ifndef stack_option 
  5995.     !  define stack_option 
  5996.     !endif 
  5997.     !ifndef line_option 
  5998.     !  define line_option 
  5999.     !endif 
  6000.  
  6001.  The "!" character must be in the first column but the directive keyword can be 
  6002.  indented.  This freedom applies to all of the preprocessing directives.  The 
  6003.  !else preprocessing directive benefits from this type of style because !else 
  6004.  can also check conditions like: 
  6005.  
  6006.  
  6007.     !else ifeq 
  6008.     !else ifneq 
  6009.     !else ifeqi 
  6010.     !else ifneqi 
  6011.     !else ifdef 
  6012.     !else ifndef 
  6013.  
  6014.  so that logical structures like: 
  6015.  
  6016.  
  6017.     !ifdef %version 
  6018.     !  ifeq %version debugging 
  6019.     !   define option = debug all 
  6020.     !  else ifeq %version beta 
  6021.     !   define option = debug line 
  6022.     !  else ifeq %version production 
  6023.     !   define option = debug 
  6024.     !  else 
  6025.     !   error invalid value in VERSION 
  6026.     !  endif 
  6027.     !endif 
  6028.  
  6029.  can be used.  The above example checks the environment variable "VERSION" for 
  6030.  three possible values and acts accordingly. 
  6031.  
  6032.  Another derivative from the C language preprocessor is the !error directive 
  6033.  which has the form of 
  6034.  
  6035.  
  6036.     !error <text> 
  6037.  
  6038.  in Make.  This directive will print out the text and terminate processing of 
  6039.  the makefile.  It is very useful in preventing errors from macros that are not 
  6040.  defined properly.  Here is an example of the !error preprocessing directive. 
  6041.  
  6042.  
  6043.     !ifndef stack_option 
  6044.     !  error stack_option is not defined 
  6045.     !endif 
  6046.     !ifndef line_option 
  6047.     !  error line_option is not defined 
  6048.     !endif 
  6049.  
  6050.  There is one more directive that can be used in a makefile.  The !undef 
  6051.  preprocessing directive will clear a macro definition.  The !undef 
  6052.  preprocessing directive has the form: 
  6053.  
  6054.     !undef <macro_identifier> 
  6055.  
  6056.  The macro identifier can represent a normal macro or an environment variable. 
  6057.  A macro can be cleared after it is no longer needed.  Clearing a macro will 
  6058.  reduce the memory requirements for a makefile.  If the macro identifier 
  6059.  represents an environment variable (i.e., the identifier has a "%" prefix) 
  6060.  then the environment variable will be deleted from the current environment. 
  6061.  The !undef preprocessing directive is useful for deleting environment 
  6062.  variables and reducing the amount of internal memory required during makefile 
  6063.  processing. 
  6064.  
  6065.  
  6066. ΓòÉΓòÉΓòÉ 8.16.3. Loading Dynamic Link Libraries ΓòÉΓòÉΓòÉ
  6067.  
  6068.  
  6069. Watcom Make supports loading of Dynamic Link Library (DLL) versions of Watcom 
  6070. software through the use of the !loaddll preprocessing directive.  This support 
  6071. is available on Win32 and 32-bit OS/2 platforms.  Performance is greatly 
  6072. improved by avoiding a reload of the software for each file to be processed. 
  6073. The syntax of the !loaddll preprocessing directive is: 
  6074.  
  6075.  
  6076.    !loaddll $(exename) $(dllname) 
  6077.  
  6078. where $(exename) is the command name used in the makefile and $(dllname) is the 
  6079. name of the DLL to be loaded and executed in its place.  For example, consider 
  6080. the following makefile which contains a list of commands and their 
  6081. corresponding DLL versions. 
  6082.  
  6083.  
  6084.    # Default compilation macros for sample programs 
  6085.    # 
  6086.    # Compile switches that are enabled 
  6087.  
  6088.    CFLAGS  = -d1 
  6089.    CC    = wpp386 $(CFLAGS) 
  6090.  
  6091.    LFLAGS  = DEBUG ALL 
  6092.    LINK   = wlink  $(LFLAGS) 
  6093.  
  6094.    !ifdef __LOADDLL__ 
  6095.    !  loaddll wcc    wccd 
  6096.    !  loaddll wccaxp  wccdaxp 
  6097.    !  loaddll wcc386  wccd386 
  6098.    !  loaddll wpp    wppdi86 
  6099.    !  loaddll wppaxp  wppdaxp 
  6100.    !  loaddll wpp386  wppd386 
  6101.    !  loaddll wlink   wlink 
  6102.    !  loaddll wlib   wlibd 
  6103.    !endif 
  6104.  
  6105.    .c.obj: 
  6106.        $(CC) $*.c 
  6107.  
  6108. The __LOADDLL__ symbol is defined for versions of Watcom Make that support the 
  6109. !loaddll preprocessing directive.  The !ifdef __LOADDLL__ construct ensures 
  6110. that the makefile can be processed by an older version of Watcom Make. 
  6111.  
  6112. Make will look up the wpp386 command in its DLL load table and find a match. 
  6113. It will then attempt to load the corresponding DLL (i.e., wppd386.dll) and pass 
  6114. it the command line for processing.  The lookup is case insensitive but must 
  6115. match in all other respects.  For example, if a path is included with the 
  6116. command name then the same path must be specified in the !loaddll preprocessing 
  6117. directive.  This problem can be avoided through the use of macros as 
  6118. illustrated below. 
  6119.  
  6120.  
  6121.    # Default compilation macros for sample programs 
  6122.    # 
  6123.    # Compile switches  that are enabled 
  6124.    # 
  6125.    cc286  = wpp 
  6126.    cc286d  = wppdi86 
  6127.    cc386  = wpp386 
  6128.    cc386d  = wppd386 
  6129.    linker  = wlink 
  6130.    linkerd = wlink 
  6131.  
  6132.    CFLAGS  = -d1 
  6133.    CC    = $(cc386) $(CFLAGS) 
  6134.  
  6135.    LFLAGS  = DEBUG ALL 
  6136.    LINK   = wlink  $(LFLAGS) 
  6137.  
  6138.    !ifdef __LOADDLL__ 
  6139.    !loaddll $(cc286)  $(cc286d) 
  6140.    !loaddll $(cc386)  $(cc386d) 
  6141.    !loaddll $(linker)  $(linkerd) 
  6142.    !endif 
  6143.  
  6144.    .c.obj: 
  6145.        $(CC) $*.c 
  6146.  
  6147. A path and/or extension may be specified with the DLL name if desired. 
  6148.  
  6149.  
  6150. ΓòÉΓòÉΓòÉ 8.17. Command List Directives ΓòÉΓòÉΓòÉ
  6151.  
  6152.  
  6153. Watcom Make supports special directives that provide command lists for 
  6154. different purposes.  If a command list cannot be found while updating a target 
  6155. then the directive .DEFAULT may be used to provide one.  A simple .DEFAULT 
  6156. command list which makes the target appear to be updated is: 
  6157.  
  6158.  
  6159.    .DEFAULT 
  6160.        wtouch $^@ 
  6161.  
  6162. The Watcom Touch utility sets the time-stamp on the file to the current time. 
  6163. The effect of the above rule will be to "update" the file without altering its 
  6164. contents. 
  6165.  
  6166. In some applications it is necessary to execute some commands before any other 
  6167. commands are executed and likewise it is useful to be able to execute some 
  6168. commands after all other commands are executed.  Make supports this capability 
  6169. by checking to see if the .BEFORE and .AFTER directives have been used.  If the 
  6170. .BEFORE directive has been used, the .BEFORE command list is executed before 
  6171. any commands are executed.  Similarly the .AFTER command list is executed after 
  6172. processing is finished.  It is important to note that if all the files are up 
  6173. to date and no commands must be executed, the .BEFORE and .AFTER command lists 
  6174. are never executed.  If some commands are executed to update targets and errors 
  6175. are detected (non-zero return status, macro expansion errors), the .AFTER 
  6176. command list is not executed (the .ERROR directive supplies a command list for 
  6177. error conditions and is discussed in this section).  These two directives may 
  6178. be used for maintenance as illustrated in the following example: 
  6179.  
  6180.  
  6181.    # 
  6182.    # .BEFORE and .AFTER example 
  6183.    # 
  6184.    .BEFORE 
  6185.        echo .BEFORE command list executed 
  6186.    .AFTER 
  6187.        echo .AFTER command list executed 
  6188.    # 
  6189.    # rest of makefile follows 
  6190.    # 
  6191.        . 
  6192.        . 
  6193.        . 
  6194.  
  6195. If all the targets in the makefile are up to date then neither the .BEFORE nor 
  6196. the .AFTER command lists will be executed.  If any of the targets are not up to 
  6197. date then before any commands to update the target are executed, the .BEFORE 
  6198. command list will be executed.  The .AFTER command list will be executed only 
  6199. if there were no errors detected during the updating of the targets.  The 
  6200. .BEFORE, .DEFAULT, and .AFTER command list directives provide the capability to 
  6201. execute commands before, during, and after the makefile processing. 
  6202.  
  6203. Make also supports the .ERROR directive.  The .ERROR directive supplies a 
  6204. command list to be executed if an error occurs during the updating of a target. 
  6205.  
  6206.  
  6207.    # 
  6208.    # .ERROR example 
  6209.    # 
  6210.    .ERROR 
  6211.        beep 
  6212.    # 
  6213.    # rest of makefile follows 
  6214.    # 
  6215.        . 
  6216.        . 
  6217.        . 
  6218.  
  6219. The above makefile will audibly signal you that an error has occurred during 
  6220. the makefile processing.  If any errors occur during the .ERROR command list 
  6221. execution, makefile processing is terminated. 
  6222.  
  6223.  
  6224. ΓòÉΓòÉΓòÉ 8.18. MAKEINIT File ΓòÉΓòÉΓòÉ
  6225.  
  6226.  
  6227. As you become proficient at using Watcom Make, you will probably want to 
  6228. isolate common makefile declarations so that there is less duplication among 
  6229. different makefiles.  Make will search for a file called "MAKEINIT" and process 
  6230. it before any other makefiles.  The search for the "MAKEINIT" file will occur 
  6231. along the current "PATH".  If the file "MAKEINIT" is not found, processing 
  6232. continues without any errors.  The only default declaration that Make provides 
  6233. is equivalent to a "MAKEINIT" file containing: 
  6234.  
  6235.  
  6236.    __MAKEOPTS__ = <options passed to WMAKE> 
  6237.    __MAKEFILES__ = <list of makefiles> 
  6238.    __MSDOS__ = 
  6239.    # clear .EXTENSIONS list 
  6240.    .EXTENSIONS: 
  6241.  
  6242.    # set .EXTENSIONS list 
  6243.    .EXTENSIONS: .exe .exp .lib .obj .asm .c .for .pas .cob .h .fi .mif 
  6244.  
  6245. For OS/2, the __MSDOS__ macro will be replaced by __OS2__ and for Windows NT, 
  6246. the __MSDOS__ macro will be replaced by __NT__.  The use of a "MAKEINIT" file 
  6247. will allow you to reuse common declarations and will result in simpler, more 
  6248. maintainable makefiles. 
  6249.  
  6250.  
  6251. ΓòÉΓòÉΓòÉ 8.19. Command List Execution ΓòÉΓòÉΓòÉ
  6252.  
  6253.  
  6254. Watcom Make is a program which must execute other programs and operating system 
  6255. shell commands.  There are three basic types of executable files in DOS. 
  6256.  
  6257.    1. .COM files 
  6258.  
  6259.    2. .EXE files 
  6260.  
  6261.    3. .BAT files 
  6262.  
  6263.  There are two basic types of executable files in Windows NT. 
  6264.  
  6265.    1. .EXE files 
  6266.  
  6267.    2. .BAT files 
  6268.  
  6269.  There are two basic types of executable files in OS/2. 
  6270.  
  6271.    1. .EXE files 
  6272.  
  6273.    2. .CMD files 
  6274.  
  6275.  The .COM and .EXE files may be loaded into memory and executed.  The .BAT 
  6276.  files must be executed by the DOS command processor or shell, "COMMAND.COM". 
  6277.  The .CMD files must be executed by the OS/2 command processor or shell, 
  6278.  "CMD.EXE" Make will search along the "PATH" for the command and depending on 
  6279.  the file extension the file will be executed in the proper manner. 
  6280.  
  6281.  If Make detects any input or output redirection characters (these are ">", 
  6282.  "<", and "|") in the command, it will be executed by the shell. 
  6283.  
  6284.  Under DOS, an asterisk prefix (*) will cause Make to examine the length of the 
  6285.  command argument.  If it is too long (> 126 characters), it will take the 
  6286.  command argument and stuff it into a temporary environment variable and then 
  6287.  execute the command with "@env_var" as its argument.  Suppose the following 
  6288.  sample makefile fragment contained a very long command line argument. 
  6289.  
  6290.  
  6291.     # 
  6292.     # Asterisk example 
  6293.     # 
  6294.       *foo myfile /a /b /c ... /x /y /z 
  6295.  
  6296.  Make will perform something logically similar to the following steps. 
  6297.  
  6298.  
  6299.       set TEMPVAR001=myfile /a /b /c ... /x /y /z 
  6300.       foo @TEMPVAR001 
  6301.  
  6302.  The command must, of course, support the "@env_var" syntax.  Typically, DOS 
  6303.  commands do not support this syntax but many of the Watcom tools do. 
  6304.  
  6305.  The exclamation mark prefix (!) will force a command to be executed by the 
  6306.  shell.  Also, the command will be executed by the shell if the command is an 
  6307.  internal shell command from the following list: 
  6308.  
  6309.  break 
  6310.       (check for Ctrl+Break) 
  6311.  
  6312.  call 
  6313.       (nest batch files) 
  6314.  
  6315.  chdir 
  6316.       (change current directory) 
  6317.  
  6318.  cd 
  6319.       (change current directory) 
  6320.  
  6321.  cls 
  6322.       (clear the screen) 
  6323.  
  6324.  cmd 
  6325.       (start NT or OS/2 command processor) 
  6326.  
  6327.  command 
  6328.       (start DOS command processor) 
  6329.  
  6330.  copy 
  6331.       (copy or combine files) 
  6332.  
  6333.  ctty 
  6334.       (DOS redirect input/output to COM port) 
  6335.  
  6336.  d: 
  6337.       (change drive where "d" represents a drive specifier) 
  6338.  
  6339.  date 
  6340.       (set system date) 
  6341.  
  6342.  del 
  6343.       (erase files) 
  6344.  
  6345.  dir 
  6346.       (display contents in a directory) 
  6347.  
  6348.  echo 
  6349.       (display commands as they are processed) 
  6350.  
  6351.  erase 
  6352.       (erase files) 
  6353.  
  6354.  for 
  6355.       (repetitively process commands, intercepted by WMAKE) 
  6356.  
  6357.  if 
  6358.       (allow conditional processing of commands) 
  6359.  
  6360.  md 
  6361.       (make directory) 
  6362.  
  6363.  mkdir 
  6364.       (make directory) 
  6365.  
  6366.  path 
  6367.       (set search path) 
  6368.  
  6369.  pause 
  6370.       (suspend batch operations) 
  6371.  
  6372.  prompt 
  6373.       (change command prompt) 
  6374.  
  6375.  ren 
  6376.       (rename files) 
  6377.  
  6378.  rename 
  6379.       (rename files) 
  6380.  
  6381.  rmdir 
  6382.       (remove directory) 
  6383.  
  6384.  rd 
  6385.       (remove directory) 
  6386.  
  6387.  set 
  6388.       (set environment variables, intercepted by WMAKE) 
  6389.  
  6390.  time 
  6391.       (set system time) 
  6392.  
  6393.  type 
  6394.       (display contents of a file) 
  6395.  
  6396.  ver 
  6397.       (display the operating system version number) 
  6398.  
  6399.  verify 
  6400.       (set data verification) 
  6401.  
  6402.  vol 
  6403.       (display disk volume label) 
  6404.  
  6405.  The operating system shell "SET" command is intercepted by Make.  The "SET" 
  6406.  command may be used to set environment variables to values required during 
  6407.  makefile processing.  The environment variable changes are only valid during 
  6408.  makefile processing and do not affect the values that were in effect before 
  6409.  Make was invoked.  The "SET" command may be used to initialize environment 
  6410.  variables necessary for the makefile commands to execute properly.  The 
  6411.  setting of environment variables in makefiles reduces the number of "SET" 
  6412.  commands required in the system initialization file.  Here is an example with 
  6413.  the Watcom C/C++ compiler. 
  6414.  
  6415.  
  6416.     # 
  6417.     # SET example 
  6418.     # 
  6419.     .BEFORE 
  6420.         set include=c:\special\h;$(%include) 
  6421.         set lib=c:\watcom\lib386;c:\watcom\lib386\dos 
  6422.     # 
  6423.     # rest of makefile follows 
  6424.     # 
  6425.         . 
  6426.         . 
  6427.         . 
  6428.  
  6429.  The first "SET" command will set up the INCLUDE environment variable so that 
  6430.  the Watcom C/C++ compiler may find header files.  Notice that the old value of 
  6431.  the INCLUDE environment variable is used in setting the new value. 
  6432.  
  6433.  The second "SET" command indicates to the Watcom Linker that libraries may be 
  6434.  found in the indicated directories. 
  6435.  
  6436.  Environment variables may be used also as dynamic variables that may 
  6437.  communicate information between different parts of the makefile.  An example 
  6438.  of communication within a makefile is illustrated in the following example. 
  6439.  
  6440.  
  6441.     # 
  6442.     # internal makefile communication 
  6443.     # 
  6444.     .BEFORE 
  6445.         set message=message text 1 
  6446.         echo *$(%message)* 
  6447.         set message= 
  6448.         echo *$(%message)* 
  6449.  
  6450.     .example : another_target .SYMBOLIC 
  6451.         echo *$(%message)* 
  6452.  
  6453.     another_target : .SYMBOLIC 
  6454.         set message=message text 2 
  6455.  
  6456.  The output of the previous makefile would be: 
  6457.  
  6458.  
  6459.     (command output only) 
  6460.     *message text 1* 
  6461.     ** 
  6462.     *message text 2* 
  6463.  
  6464.  Make handles the "SET" command so that it appears to work in an intuitive 
  6465.  manner similar to the operating system shell's "SET" command.  The "SET" 
  6466.  command also may be used to allow commands to relay information to commands 
  6467.  that are executed afterwards. 
  6468.  
  6469.  The DOS "FOR" command is intercepted by Make.  The reason for this is that DOS 
  6470.  has a fixed limit for the size of a command thus making it unusable for large 
  6471.  makefile applications.  One such application that can be done easily with Make 
  6472.  is the construction of a WLINK command file from a makefile.  The idea behind 
  6473.  the next example is to have one file that contains the list of object files. 
  6474.  Anytime this file is changed, say, after a new module has been added, a new 
  6475.  linker command file will be generated which in turn, will cause the linker to 
  6476.  relink the executable.  First we need the makefile to define the list of 
  6477.  object files, this file is "OBJDEF.MIF" and it declares a macro "objs" which 
  6478.  has as its value the list of object files in the application.  The content of 
  6479.  the "OBJDEF.MIF" file is: 
  6480.  
  6481.     # 
  6482.     # list of object files 
  6483.     # 
  6484.     objs = & 
  6485.       window.obj & 
  6486.       bios.obj & 
  6487.       keyboard.obj & 
  6488.       mouse.obj 
  6489.  
  6490.  The main makefile ("MAKEFILE") is: 
  6491.  
  6492.  
  6493.     # 
  6494.     # FOR command example 
  6495.     # 
  6496.     !include objdef.mif 
  6497.  
  6498.     plot.exe : $(objs) plot.lnk 
  6499.         wlink @plot 
  6500.  
  6501.     plot.lnk : objdef.mif 
  6502.         echo NAME $^& >$^@ 
  6503.         echo DEBUG all >>$^@ 
  6504.         for %i in ($(objs)) do echo FILE %i >>$^@ 
  6505.  
  6506.  This makefile would produce a file "PLOT.LNK" automatically whenever the list 
  6507.  of object files is changed (anytime "OBJDEF.MIF" is changed).  For the above 
  6508.  example, the file "PLOT.LNK" would contain: 
  6509.  
  6510.  
  6511.     NAME plot 
  6512.     DEBUG all 
  6513.     FILE window.obj 
  6514.     FILE bios.obj 
  6515.     FILE keyboard.obj 
  6516.     FILE mouse.obj 
  6517.  
  6518.  Make supports eight internal commands: 
  6519.  
  6520.    1. %null 
  6521.  
  6522.    2. %stop 
  6523.  
  6524.    3. %quit 
  6525.  
  6526.    4. %abort 
  6527.  
  6528.    5. %create 
  6529.  
  6530.    6. %write 
  6531.  
  6532.    7. %append 
  6533.  
  6534.    8. %make 
  6535.  
  6536.  The %null internal command does absolutely nothing.  It is useful because Make 
  6537.  demands that a command list be present whenever a target is updated. 
  6538.  
  6539.  
  6540.     # 
  6541.     # %null example 
  6542.     # 
  6543.     all : application1 application2 .SYMBOLIC 
  6544.         %null 
  6545.  
  6546.     application1 : appl1.exe .SYMBOLIC 
  6547.         %null 
  6548.  
  6549.     application2 : appl2.exe .SYMBOLIC 
  6550.         %null 
  6551.  
  6552.     appl1.exe : (dependents ...) 
  6553.         (commands) 
  6554.  
  6555.     appl2.exe : (dependents ...) 
  6556.         (commands) 
  6557.  
  6558.  Through the use of the %null internal command, multiple application makefiles 
  6559.  may be produced that are quite readable and maintainable.  The %stop internal 
  6560.  command will temporarily suspend makefile processing and print out a message 
  6561.  asking whether the Makefile processing should continue.  Make will wait for 
  6562.  either the "y" key (indicating that the Makefile processing should continue) 
  6563.  or the "n" key.  If the "n" key is pressed, makefile processing will stop. 
  6564.  The %stop internal command is very useful for debugging makefiles but it may 
  6565.  be used also to develop interactive makefiles.  The %quit internal command 
  6566.  will terminate execution of Make and return to the operating system shell with 
  6567.  an exit code of zero.  The %abort internal command is identical to %quit 
  6568.  except that a non-zero exit code is returned by WMAKE. 
  6569.  
  6570.  The %create, %write, and %append internal commands allow WMAKE to generate 
  6571.  files under makefile control.  This is useful for files that have contents 
  6572.  that depend on makefile contents.  Through the use of macros and the "for" 
  6573.  command, Make becomes a very powerful tool in maintaining lists of files for 
  6574.  other programs.  The %create internal command will create or truncate a file 
  6575.  so that the file does not contain any text.  The %create internal command has 
  6576.  the form: 
  6577.  
  6578.  
  6579.     %create <file> 
  6580.  
  6581.  where <file> is a file specification.  The %write internal command will create 
  6582.  or truncate a file and write one line of text into it.  The %append internal 
  6583.  command will append a text line to the end of a file (which will be created if 
  6584.  it does not exist).  The %write and %append internal commands have the same 
  6585.  form, namely: 
  6586.  
  6587.  
  6588.     %write <file> <text> 
  6589.     %append <file> <text> 
  6590.  
  6591.  where <file> is a file specification and <text> is arbitrary text.  Full macro 
  6592.  processing is performed on these internal commands so the full power of WMAKE 
  6593.  can be used.  The following example illustrates a common use of these internal 
  6594.  commands. 
  6595.  
  6596.  
  6597.     # 
  6598.     # %create %append example 
  6599.     # 
  6600.     !include objdef.mif 
  6601.  
  6602.     plot.exe : $(objs) plot.lnk 
  6603.         wlink @plot 
  6604.  
  6605.     plot.lnk : objdef.mif 
  6606.         %create $^@ 
  6607.         %append $^@ NAME $^& 
  6608.         %append $^@ DEBUG all 
  6609.         for %i in ($(objs)) do %append $^@ FILE %i 
  6610.  
  6611.  The above code demonstrates a valuable technique that can generate directive 
  6612.  files for WLINK, WLIB, and other utilities. 
  6613.  
  6614.  The %make internal command permits the updating of a specific target.  The 
  6615.  %make internal command has the form: 
  6616.  
  6617.  
  6618.     %make <target> 
  6619.  
  6620.  where <target> is a target in the makefile. 
  6621.  
  6622.  
  6623.     # 
  6624.     # %make example 
  6625.     # 
  6626.     !include objdef.mif 
  6627.  
  6628.     plot.exe : $(objs) 
  6629.         %make plot.lnk 
  6630.         wlink @plot 
  6631.  
  6632.     plot.lnk : objdef.mif 
  6633.         %create $^@ 
  6634.         %append $^@ NAME $^& 
  6635.         %append $^@ DEBUG all 
  6636.         for %i in ($(objs)) do %append $^@ FILE %i 
  6637.  
  6638.  
  6639. ΓòÉΓòÉΓòÉ 8.20. Compatibility Between Watcom Make and UNIX Make ΓòÉΓòÉΓòÉ
  6640.  
  6641.  
  6642. Watcom Make was originally based on the UNIX Make utility.  The PC's operating 
  6643. environment presents a base of users which may or may not be familiar with the 
  6644. UNIX operating system.  Make is designed to be a PC product with some UNIX 
  6645. compatibility.  The line continuation in UNIX Make is a backslash ("\") at the 
  6646. end of the line.  The backslash ("\") is used by the operating system for 
  6647. directory specifications and as such will be confused with line continuation. 
  6648. For example, you could type: 
  6649.  
  6650.  
  6651.    cd \ 
  6652.  
  6653. along with other commands ...  and get unexpected results.  However, if your 
  6654. makefile does not contain path separator characters ("\") and you wish to use 
  6655. "\" as a line continuation indicator then you can use the Make "u" (UNIX 
  6656. compatibility mode) option. 
  6657.  
  6658. Also, in the UNIX operating system there is no concept of file extensions, only 
  6659. the concept of a file suffix.  Make will accept the UNIX Make directive 
  6660. .SUFFIXES for compatibility with UNIX makefiles.  The UNIX compatible special 
  6661. macros supported are: 
  6662.  
  6663.  $@ 
  6664.       full name of the target 
  6665.  
  6666.  $* 
  6667.       target with the extension removed 
  6668.  
  6669.  $< 
  6670.       list of all dependents 
  6671.  
  6672.  $? 
  6673.       list of dependents that are younger than the target 
  6674.  
  6675.  The extra checking of makefiles done by Make will require modifications to 
  6676.  UNIX makefiles.  The UNIX Make utility does not check for the existence of 
  6677.  targets after the associated command list is executed so the "c" or the 
  6678.  .NOCHECK directive should be used to disable this checking.  The lack of a 
  6679.  command list to update a target is ignored by the UNIX Make utility but Watcom 
  6680.  Make requires the special internal command %null to specify a null command 
  6681.  list.  In summary, Make supports many of the features of the UNIX Make utility 
  6682.  but is not 100% compatible. 
  6683.  
  6684.  
  6685. ΓòÉΓòÉΓòÉ 8.21. Watcom Make Diagnostic Messages ΓòÉΓòÉΓòÉ
  6686.  
  6687.  
  6688. This section lists the various warning and error messages that may be issued by 
  6689. the Watcom Make.  In the messages below, %?  character sequences indicate 
  6690. places in the message that are replaced with some other string. 
  6691.  
  6692.  1 Out of memory 
  6693.  
  6694.  2 Make execution terminated 
  6695.  
  6696.  3 Option %c%c invalid 
  6697.  
  6698.  4 %c%c must be followed by a filename 
  6699.  
  6700.  5 No targets specified 
  6701.  
  6702.  6 Ignoring first target in MAKEINIT 
  6703.  
  6704.  7 Expecting a %M 
  6705.  
  6706.  8 Invalid macro name %E 
  6707.  
  6708.  9 Ignoring out of place %M 
  6709.  
  6710.  10 Macros nested too deep 
  6711.  
  6712.  11 Unknown internal command 
  6713.  
  6714.  12 Program name is too long 
  6715.  
  6716.  13 No control characters allowed in options 
  6717.  
  6718.  14 Cannot execute %E:  %Z 
  6719.  
  6720.  15 Syntax error in %s command 
  6721.  
  6722.  16 Nested %s loops not allowed 
  6723.  
  6724.  17 Token too long, maximum size is %d chars 
  6725.  
  6726.  18 Unrecognized or out of place character '%C' 
  6727.  
  6728.  19 Target %E already declared %M 
  6729.  
  6730.  20 Command list does not belong to any target 
  6731.  
  6732.  21 Extension(s) %E not defined 
  6733.  
  6734.  22 No existing file matches %E 
  6735.  
  6736.  23 Extensions reversed in implicit rule 
  6737.  
  6738.  24 More than one command list found for %E 
  6739.  
  6740.  25 Extension %E declared more than once 
  6741.  
  6742.  26 Unknown preprocessor directive:  %s 
  6743.  
  6744.  27 Macro %E is undefined 
  6745.  
  6746.  28 !If statements nested too deep 
  6747.  
  6748.  29 !%s has no matching !if 
  6749.  
  6750.  30 Skipping !%1 block after !%2 
  6751.  
  6752.  31 %1 not allowed after !%2 
  6753.  
  6754.  32 Opening file %E:  %Z 
  6755.  
  6756.  34 !%s pending at end of file 
  6757.  
  6758.  35 Trying to !%s an undefined macro 
  6759.  
  6760.  36 Illegal attempt to update special target %E 
  6761.  
  6762.  37 Target %E is defined recursively 
  6763.  
  6764.  38 %E does not exist and cannot be made from existing files 
  6765.  
  6766.  39 Target %E not mentioned in any makefile 
  6767.  
  6768.  40 Could not touch %E 
  6769.  
  6770.  41 No %s commands for making %E 
  6771.  
  6772.  42 Last command making (%L) returned a bad status 
  6773.  
  6774.  43 Deleting %E:  %Z 
  6775.  
  6776.  44 %s command returned a bad status 
  6777.  
  6778.  45 Maximum string length exceeded 
  6779.  
  6780.  46 Illegal character value %xH in file 
  6781.  
  6782.  47 Assuming target(s) are .%s 
  6783.  
  6784.  48 Maximum %%make depth exceeded 
  6785.  
  6786.  49 Opening (%s) for write:  %Z 
  6787.  
  6788.  50 Unable to write:  %Z 
  6789.  
  6790.  51 CD'ing to %E:  %Z 
  6791.  
  6792.  52 Changing to drive %C: 
  6793.  
  6794.  53 DOS memory inconsistency detected!  System may halt ... 
  6795.  
  6796.  53 OS corruption detected 
  6797.  
  6798.  54 While reading (%s):  %Z 
  6799.  
  6800.  59 !IF Parse Error 
  6801.  
  6802.  60 TMP Path /File Too Long 
  6803.  
  6804.  61 Unexpected End of File 
  6805.  
  6806.  62 Only NO(KEEP) allowed here 
  6807.  
  6808.  63 Non-matching " 
  6809.  
  6810.  64 Invalid String Macro Substitution 
  6811.  
  6812.  65 File Name Length Exceeded 
  6813.  
  6814.  66 Redefinition of .DEFAULT Command List 
  6815.  
  6816.  67 Non-matching { In Implicit Rule 
  6817.  
  6818.  68 Invalid Implicit Rule Definition 
  6819.  
  6820.  69 Path Too Long 
  6821.  
  6822.  70 Cannot Load/Unload DLL %E 
  6823.  
  6824.  71 Initialization of DLL %E returned a bad status 
  6825.  
  6826.  72 DLL %E returned a bad status 
  6827.  
  6828.  73 Illegal Character %C in macro name 
  6829.  
  6830.  74 in closing file %E 
  6831.  
  6832.  75 in opening file %E 
  6833.  
  6834.  76 in writing file %E 
  6835.  
  6836.  77 User Break Encountered 
  6837.  
  6838.  78 Error in Memory Tracking Encountered 
  6839.  
  6840.  79 Makefile may be Microsoft 
  6841.       try /ms switch 
  6842.  
  6843.  
  6844. ΓòÉΓòÉΓòÉ 9. The Touch Utility ΓòÉΓòÉΓòÉ
  6845.  
  6846.  
  6847. This chapter describes the Watcom Touch utility.  Watcom Touch will set the 
  6848. time-stamp (i.e., the modification date and time) of one or more files.  The 
  6849. new modification date and time may be the current date and time, the 
  6850. modification date and time of another file, or a date and time specified on the 
  6851. command line.  This utility is normally used in conjunction with the Watcom 
  6852. Make utility.  The rationale for bringing a file up-to-date without altering 
  6853. its contents is best understood by reading the chapter which describes the Make 
  6854. utility. 
  6855.  
  6856. The Watcom Touch command line syntax is: 
  6857.  
  6858.  
  6859.    WTOUCH [options] file_spec [file_spec...] 
  6860.  
  6861. The square brackets [ ] denote items which are optional. 
  6862.  
  6863.  options 
  6864.       is a list of valid options, each preceded by a slash ("/") or a dash 
  6865.       ("-").  Options may be specified in any order. 
  6866.  
  6867.  file_spec 
  6868.       is the file specification for the file to be touched.  Any number of file 
  6869.       specifications may be listed.  The wild card characters "*" and "?" may 
  6870.       be used. 
  6871.  
  6872.  The following is a description of the options available. 
  6873.  
  6874.  c 
  6875.       do not create an empty file if the specified file does not exist 
  6876.  
  6877.  d <date> 
  6878.       specify the date for the file time-stamp in "mm-dd-yy" format 
  6879.  
  6880.  f <file> 
  6881.       use the time-stamp from the specified file 
  6882.  
  6883.  i 
  6884.       increment time-stamp before touching the file 
  6885.  
  6886.  q 
  6887.       suppress informational messages 
  6888.  
  6889.  r 
  6890.       touch file even if it is marked read-only 
  6891.  
  6892.  t <time> 
  6893.       specify the time for the file time-stamp in "hh:mm:ss" format 
  6894.  
  6895.  u 
  6896.       use USA date/time format regardless of country 
  6897.  
  6898.  ? 
  6899.       display help screen 
  6900.  
  6901.  
  6902. ΓòÉΓòÉΓòÉ 9.1. WTOUCH Operation ΓòÉΓòÉΓòÉ
  6903.  
  6904.  
  6905. WTOUCH is used to set the time-stamp (i.e., the modification date and time) of 
  6906. a file.  The contents of the file are not affected by this operation.  If the 
  6907. specified file does not exist, it will be created as an empty file.  This 
  6908. behaviour may be altered with the "c" option so that if the file is not 
  6909. present, a new empty file will not be created. 
  6910.  
  6911. Example: 
  6912.  
  6913.    (will not create myfile.dat) 
  6914.    C>wtouch /c myfile.dat 
  6915.  
  6916. If a wild card file specification is used and no files match the pattern, no 
  6917. files will have their time-stamps altered.  The date and time that all the 
  6918. specified files are set to is determined as follows: 
  6919.  
  6920.    1. The current date and time is used as a default value. 
  6921.  
  6922.    2. A time-stamp from an "age file" may replace the current date and time. 
  6923.       The "f" option is used to specify the file that will supply the 
  6924.       time-stamp. 
  6925.  
  6926.       Example: 
  6927.  
  6928.          (use the date and time from file "last.tim") 
  6929.          C>wtouch /f last.tim file*.dat 
  6930.  
  6931.    3. The date and/or time may be specified from the command line to override a 
  6932.       part of the time-stamp that will be used.  The "d" and "t" options are 
  6933.       used to override the date and time respectively. 
  6934.  
  6935.       Example: 
  6936.  
  6937.          (use current date but use different time) 
  6938.          C>wtouch /t 2:00p file*.dat 
  6939.          (completely specify date and time) 
  6940.          C>wtouch /d 10-31-90 /t 8:00:00 file*.dat 
  6941.          (use date from file "last.tim" but set time) 
  6942.          C>wtouch /f last.tim /t 12:00 file*.dat 
  6943.  
  6944.       The format of the date and time on the command line depends on the 
  6945.       country information provided by the host operating system.  Watcom Touch 
  6946.       should accept dates and times in a similar format to any operating system 
  6947.       utilities (i.e., the DATE and TIME utilities provided by DOS).  The "a" 
  6948.       and "p" suffix is an extension to the time syntax for specifying whether 
  6949.       the time is A.M.  or P.M., but this is only available if the operating 
  6950.       system is not configured for military or 24-hour time. 
  6951.