home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / elvis184.zip / doc / makefile.ms < prev    next >
Makefile  |  1994-01-17  |  11KB  |  255 lines
  1. .Go 10 "MAKEFILE"
  2. .PP
  3. On most Operating Systems, and with most compilers, the "Makefile.mix"
  4. file is used to control compilation and installation of \*E.
  5. This section of the manual describes the overall structure of "Makefile.mix",
  6. and the various configuration options in it.
  7. .NH 2
  8. Configuring the Makefile
  9. .PP
  10. Begin by copying "Makefile.mix" to "Makefile".
  11. Never alter the original "Makefile.mix".
  12. .PP
  13. Most of the configuration options are controlled via a group of macros.
  14. Makefile.mix begins with several pre-configured sets of macro definitions \-
  15. one group for each of the most common supported systems.
  16. As shipped, all of these macro definitions are commented out;
  17. you must either uncomment out one of the groups, or
  18. (for less common systems) construct an entirely new group.
  19. .NH 2
  20. Using the Makefile
  21. .PP
  22. After configuring the Makefile, you can run "make" to compile the programs.
  23. There are also some other useful things that the Makefile can do...
  24. .LD
  25. .ta 0.5i 2.1i
  26.  
  27.     COMMAND    RESULT
  28.     make    compile all programs
  29.     make install    copy the programs to the BIN directory
  30.     make clean    remove all object files
  31.     make clobber    remove everything except source & documentation
  32. .DE
  33. .PP
  34. Note that the last two will probably work only under UNIX.
  35. .NH 2
  36. What "make install" does
  37. .PP
  38. To install elvis, we should copy all of the executables into a directory
  39. where users can find them;
  40. copy the documentation into a directory where the on-line manual program
  41. can find them;
  42. and arrange for edit buffers to be preserved after a system crash.
  43. The "make install" command tries to do this automatically,
  44. but there are problems.
  45. .PP
  46. Practically all operating systems allow programs to be installed different
  47. directories.
  48. As shipped, Makefile.mix contains somebody's best guess as to where you'd
  49. like them to go.
  50. You should double check it, though.
  51. The BIN macro controls where the programs will be installed.
  52. .PP
  53. On UNIX systems the "elvprsv" and "elvrec" programs need to be
  54. installed as SUID-root programs.
  55. Consequently, you must run "make install" as root;
  56. then they will automatically be installed as SUID-root.
  57. .PP
  58. For text to be recovered after a crash, you need to arrange for the
  59. "elvprsv" program to be run before the /tmp file is cleaned.
  60. This means that the /etc/rc file (or whatever) needs to be edited.
  61. If you have a SysV UNIX system which uses a /etc/rc2.d directory for storing
  62. start-up commands, then you're lucky.
  63. "make install" will detect that /etc/rc2.d exists and attempt to
  64. automatically create a file called "/etc/rc2.d/S03elvis" which runs elvprsv.
  65. However, for non-UNIX systems, or UNIX systems which don't have a /etc/rc2.d
  66. directory, you'll need to do this by hand.
  67. See the "Versions" section of the manual for hints about doing this on
  68. your particular system.
  69. .PP
  70. Non-UNIX systems don't have a standard place where UNIX-style man-pages
  71. go, so "make install" doesn't attempt to install documentation on those
  72. systems.
  73. .PP
  74. On UNIX systems, there is no standard place either, but you can be
  75. pretty sure that your system has a non-standard one.
  76. There is a shell script called "instman.sh" which attempts to figure
  77. out where the man-pages belong on your system, and then copies them there.
  78. You might need to edit "instman.sh" to make it work, but try it as-is first.
  79. "instman.sh" is automatically run by "make install".
  80. .PP
  81. Note: It is safe to run "make install" more than once.
  82. .NH 2
  83. Summary of Macros
  84. .PP
  85. The following describes the configuration macros.
  86. With most versions of make, a blank macro can simply be left undefined.
  87. .IP OBJ
  88. This is the filename extension for unlinked object files
  89. \- usually .o, but MS-DOS uses .obj.
  90. .IP EXE
  91. This is the filename extension for elvis executable file
  92. \- usually nothing, but MS-DOS uses .exe,
  93. and other operating systems may use something else.
  94. .IP COM
  95. This is the filename extension for the executables of elvis' support programs
  96. \- usually the same as the EXE macro, but since the support programs are all
  97. much smaller that elvis, MS-DOS can use the .com format.
  98. .IP EXTRA
  99. This is a space-delimited list of version-specific object files to be linked
  100. into elvis.
  101. Typically, this list will contain at least one object file which was written
  102. specifically for a given operating system.
  103. It may also contain "tinytcap$(OBJ)" or "tinyprnt$(OBJ)".
  104. .IP EXTRA2
  105. This is a space-delimited list of version-specific object files used in elvis
  106. and a few of the support programs.
  107. For UNIX-like systems, this is typically an empty list.
  108. For non-UNIX systems, it will usually either be empty, or it will contain
  109. the name of an object file which contains functions which emulate certain
  110. UNIX system calls.
  111. (Not all non-UNIX systems need any special emulation functions, because
  112. all C libraries try to emulate UNIX.  You only need an EXTRA2 list if
  113. the library doesn't emulate UNIX well enough.)
  114. .IP LIBS
  115. This is a list of library flags used while linking elvis.
  116. UNIX systems need "-ltermcap" or something similar, unless the EXTRA
  117. macro includes "tinytcap$(OBJ)".
  118. Most other operating systems use "tinytcap$(OBJ)" and don't need anything else,
  119. so they leave the LIBS list empty.
  120. .IP BIN
  121. This is the directory where executables should be installed by "make install".
  122. .IP CC
  123. This is the C compiler command, possibly with "memory model" flags.
  124. .IP CFLAGS
  125. This lists the compiler flags used to select compile-time options.
  126. The "CFLAGS" section of this manual describes this in detail.
  127. .IP LNK
  128. This is the name of the linker.
  129. If you want to use $(CC) as your linker, then you can leave LNK undefined.
  130. .IP LFLAGS
  131. This is a list of linker flags used to select link-time options.
  132. It is almost always blank.
  133. .IP SMALL
  134. The flag for special small memory model compilation \- usually blank.
  135. .IP OF
  136. The link flag to control the output file's name \- usually -o<space>.
  137. The Sun version of "make" strips off trailing whitespace, so a pair
  138. of empty quotes has been added after the space, to protect it.
  139. On non-Suns, this isn't necessary.
  140. .IP RF
  141. The flag used to denote "compile but don't link" \- usually -c
  142. .IP PROGS
  143. This is a space-delimited list of all programs.
  144. This list always includes elvis, ctags, ref, elvrec, and elvprsv.
  145. Also, everybody gets fmt except for BSD UNIX; it already has its own
  146. version of fmt as standard equipment.
  147. .IP
  148. Most non-UNIX systems also include the vi, ex, and view aliases.
  149. (UNIX doesn't need those aliases in the PROGS list because it creates
  150. them via file links during installation.)
  151. OS-9 doesn't include the ex alias, because there is already a command
  152. by that name built into its standard shell.
  153. .IP
  154. Note: some MS-DOS configurations break this list into two smaller lists,
  155. to compensate for MS-DOS's limitations on command line length.
  156. .IP CHMEM
  157. This is either blank, or a command to be run immediately after linking elvis.
  158. Under Minix and Coherent, elvis needs to have extra space assigned for the
  159. stack & heap after it has been linked,
  160. so their commands to do that are placed here.
  161. Most other operating systems generally either don't need to have their stacks
  162. enlarged, or they enlarge it during linking.
  163. .IP SORT
  164. This should be defined to be -DSORT if you want your tags list to be sorted,
  165. or blank if you want it unsorted.
  166. The real vi requires a sorted tags file, so for the sake of compatibility
  167. all of the UNIX configurations use -DSORT.
  168. Elvis doesn't need a sorted tags file, though, so on non-UNIX systems you
  169. can leave this macro blank.
  170. .IP RM
  171. This is the name of a program that deletes files unconditionally.
  172. It is used during "make clean".
  173. RM is defined as "rm -f" for UNIX systems, or "del" for most others.
  174. .IP CP
  175. This is the name of a program that copies files.
  176. \- usually "cp" or "copy".
  177. It is used during "make install".
  178. .IP SYS
  179. This is the type of system.
  180. It is used to select an appropriate style of linking and installation
  181. that are used by "make" and "make install", respectively.
  182. The available types are:
  183. .LD
  184. .ta 2i 3i
  185.     unx    UNIX and UNIX-like systems
  186.     dos    MS-DOS
  187.     ami    AmigaDos
  188.     tos    Atari TOS
  189.     os9    OS-9/68k
  190.     vms    VAX/VMS
  191.     xdos    cross-compiled on SCO for MS-DOS
  192. .DE
  193. .IP DUMMY
  194. This is used as the "source" filename in the dependency list of
  195. targets which are supposed to be unconditionally compiled.
  196. It is usually nothing since most versions of "make" treat an
  197. empty source file list as a special case,
  198. but OS-9 needs it defined as "dummy" and further requires that
  199. there be no actual file named dummy.
  200. .IP CFG
  201. The is the name of the compiler configuration file \- usually blank,
  202. since most compilers don't need a configuration file.
  203. Some MS-DOS compilers need it, though.
  204. .NH 2
  205. Structure of Makefile.mix
  206. .PP
  207. Makefile.mix begins with several sets of commented out configuration
  208. macro definitions, as described above.
  209. A comment saying "The rest of this Makefile contains no user-serviceable parts"
  210. marks the end of this section.
  211. Most people won't need to edit anything after that.
  212. .PP
  213. This is followed by macro definitions which are identical,
  214. regardless of your operating system.
  215. The OBJS macros list the object files that form the portable parts of
  216. elvis, and are used together with the EXTRA and EXTRA2 configuration macros
  217. during linking.
  218. .PP
  219. The SRC macros list all of the files mentioned in the "MANIFEST" file.
  220. These are used to bundle the source code via "make uue" or "make sh".
  221. .PP
  222. This is followed by a target named "all" which depends on all of the
  223. programs listed in the PROGS configuration macro.
  224. This is followed by detailed instructions describing how each file is
  225. compiled and linked.
  226. The only exceptions are the "elvis" program, and the various forms of the
  227. "alias" program.
  228. .PP
  229. Linking a big program like elvis is non-standard on some systems.
  230. To support this, we just say that elvis depends on "linkelv.$(SYS)",
  231. where "$(SYS)" is replaced by whatever you defined the SYS configuration
  232. macro to be.
  233. The various link styles are listed after that.
  234. The only really tricky one is for DOS.
  235. Since the list of files to be linked is too long to fit on a DOS command line,
  236. a customized response file is created, and the name of the response file
  237. is passed instead.
  238. The exact format of the response file depends on the compiler you're using.
  239. .PP
  240. This is followed by system-dependent ways of linking the "alias" object
  241. file to create multiple executables.
  242. For most systems, we only really link it once to form the "ex" executable,
  243. and then copy that executable to form the "vi", "view", and "input" executables.
  244. OS-9, though, doesn't need an "ex" executable and it requires actual
  245. linking for each alias.
  246. .PP
  247. Next comes installation, in all its system dependent forms.
  248. This uses the now-familiar trick of saying that the "install" target
  249. depends on a bogus file named "inst.$(SYS)" and then listing each
  250. installation technique after that.
  251. There should be no surprises here.
  252. .PP
  253. The rest of Makefile.mix contains a few handy pseudo-targets,
  254. such as "make clean".
  255.