comp.ms 37 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450
  1. .HTML "How to Use the Plan 9 C Compiler
  2. .TL
  3. How to Use the Plan 9 C Compiler
  4. .AU
  5. Rob Pike
  6. rob@plan9.bell-labs.com
  7. .SH
  8. Introduction
  9. .PP
  10. The C compiler on Plan 9 is a wholly new program; in fact
  11. it was the first piece of software written for what would
  12. eventually become Plan 9 from Bell Labs.
  13. Programmers familiar with existing C compilers will find
  14. a number of differences in both the language the Plan 9 compiler
  15. accepts and in how the compiler is used.
  16. .PP
  17. The compiler is really a set of compilers, one for each
  18. architecture \(em MIPS, SPARC, Motorola 68020, Intel 386, etc. \(em
  19. that accept a dialect of ANSI C and efficiently produce
  20. fairly good code for the target machine.
  21. There is a packaging of the compiler that accepts strict ANSI C for
  22. a POSIX environment, but this document focuses on the
  23. native Plan 9 environment, that in which all the system source and
  24. almost all the utilities are written.
  25. .SH
  26. Source
  27. .PP
  28. The language accepted by the compilers is the core 1989 ANSI C language
  29. with some modest extensions,
  30. a greatly simplified preprocessor,
  31. a smaller library that includes system calls and related facilities,
  32. and a completely different structure for include files.
  33. .PP
  34. Official ANSI C accepts the old (K&R) style of declarations for
  35. functions; the Plan 9 compilers
  36. are more demanding.
  37. Without an explicit run-time flag
  38. .CW -B ) (
  39. whose use is discouraged, the compilers insist
  40. on new-style function declarations, that is, prototypes for
  41. function arguments.
  42. The function declarations in the libraries' include files are
  43. all in the new style so the interfaces are checked at compile time.
  44. For C programmers who have not yet switched to function prototypes
  45. the clumsy syntax may seem repellent but the payoff in stronger typing
  46. is substantial.
  47. Those who wish to import existing software to Plan 9 are urged
  48. to use the opportunity to update their code.
  49. .PP
  50. The compilers include an integrated preprocessor that accepts the familiar
  51. .CW #include ,
  52. .CW #define
  53. for macros both with and without arguments,
  54. .CW #undef ,
  55. .CW #line ,
  56. .CW #ifdef ,
  57. .CW #ifndef ,
  58. and
  59. .CW #endif .
  60. It
  61. supports neither
  62. .CW #if
  63. nor
  64. .CW ## ,
  65. although it does
  66. honor a few
  67. .CW #pragmas .
  68. The
  69. .CW #if
  70. directive was omitted because it greatly complicates the
  71. preprocessor, is never necessary, and is usually abused.
  72. Conditional compilation in general makes code hard to understand;
  73. the Plan 9 source uses it sparingly.
  74. Also, because the compilers remove dead code, regular
  75. .CW if
  76. statements with constant conditions are more readable equivalents to many
  77. .CW #ifs .
  78. To compile imported code ineluctably fouled by
  79. .CW #if
  80. there is a separate command,
  81. .CW /bin/cpp ,
  82. that implements the complete ANSI C preprocessor specification.
  83. .PP
  84. Include files fall into two groups: machine-dependent and machine-independent.
  85. The machine-independent files occupy the directory
  86. .CW /sys/include ;
  87. the others are placed in a directory appropriate to the machine, such as
  88. .CW /mips/include .
  89. The compiler searches for include files
  90. first in the machine-dependent directory and then
  91. in the machine-independent directory.
  92. At the time of writing there are thirty-one machine-independent include
  93. files and two (per machine) machine-dependent ones:
  94. .CW <ureg.h>
  95. and
  96. .CW <u.h> .
  97. The first describes the layout of registers on the system stack,
  98. for use by the debugger.
  99. The second defines some
  100. architecture-dependent types such as
  101. .CW jmp_buf
  102. for
  103. .CW setjmp
  104. and the
  105. .CW va_arg
  106. and
  107. .CW va_list
  108. macros for handling arguments to variadic functions,
  109. as well as a set of
  110. .CW typedef
  111. abbreviations for
  112. .CW unsigned
  113. .CW short
  114. and so on.
  115. .PP
  116. Here is an excerpt from
  117. .CW /68020/include/u.h :
  118. .P1
  119. #define nil ((void*)0)
  120. typedef unsigned short ushort;
  121. typedef unsigned char uchar;
  122. typedef unsigned long ulong;
  123. typedef unsigned int uint;
  124. typedef signed char schar;
  125. typedef long long vlong;
  126. typedef long jmp_buf[2];
  127. #define JMPBUFSP 0
  128. #define JMPBUFPC 1
  129. #define JMPBUFDPC 0
  130. .P2
  131. Plan 9 programs use
  132. .CW nil
  133. for the name of the zero-valued pointer.
  134. The type
  135. .CW vlong
  136. is the largest integer type available; on most architectures it
  137. is a 64-bit value.
  138. A couple of other types in
  139. .CW <u.h>
  140. are
  141. .CW u32int ,
  142. which is guaranteed to have exactly 32 bits (a possibility on all the supported architectures) and
  143. .CW mpdigit ,
  144. which is used by the multiprecision math package
  145. .CW <mp.h> .
  146. The
  147. .CW #define
  148. constants permit an architecture-independent (but compiler-dependent)
  149. implementation of stack-switching using
  150. .CW setjmp
  151. and
  152. .CW longjmp .
  153. .PP
  154. Every Plan 9 C program begins
  155. .P1
  156. #include <u.h>
  157. .P2
  158. because all the other installed header files use the
  159. .CW typedefs
  160. declared in
  161. .CW <u.h> .
  162. .PP
  163. In strict ANSI C, include files are grouped to collect related functions
  164. in a single file: one for string functions, one for memory functions,
  165. one for I/O, and none for system calls.
  166. Each include file is protected by an
  167. .CW #ifdef
  168. to guarantee its contents are seen by the compiler only once.
  169. Plan 9 takes a different approach. Other than a few include
  170. files that define external formats such as archives, the files in
  171. .CW /sys/include
  172. correspond to
  173. .I libraries.
  174. If a program is using a library, it includes the corresponding header.
  175. The default C library comprises string functions, memory functions, and
  176. so on, largely as in ANSI C, some formatted I/O routines,
  177. plus all the system calls and related functions.
  178. To use these functions, one must
  179. .CW #include
  180. the file
  181. .CW <libc.h> ,
  182. which in turn must follow
  183. .CW <u.h> ,
  184. to define their prototypes for the compiler.
  185. Here is the complete source to the traditional first C program:
  186. .P1
  187. #include <u.h>
  188. #include <libc.h>
  189. void
  190. main(void)
  191. {
  192. print("hello world\en");
  193. exits(0);
  194. }
  195. .P2
  196. The
  197. .CW print
  198. routine and its relatives
  199. .CW fprint
  200. and
  201. .CW sprint
  202. resemble the similarly-named functions in Standard I/O but are not
  203. attached to a specific I/O library.
  204. In Plan 9
  205. .CW main
  206. is not integer-valued; it should call
  207. .CW exits ,
  208. which takes a string argument (or null; here ANSI C promotes the 0 to a
  209. .CW char* ).
  210. All these functions are, of course, documented in the Programmer's Manual.
  211. .PP
  212. To use
  213. .CW printf ,
  214. .CW <stdio.h>
  215. must be included to define the function prototype for
  216. .CW printf :
  217. .P1
  218. #include <u.h>
  219. #include <libc.h>
  220. #include <stdio.h>
  221. void
  222. main(int argc, char *argv[])
  223. {
  224. printf("%s: hello world; argc = %d\en", argv[0], argc);
  225. exits(0);
  226. }
  227. .P2
  228. In practice, Standard I/O is not used much in Plan 9. I/O libraries are
  229. discussed in a later section of this document.
  230. .PP
  231. There are libraries for handling regular expressions, raster graphics,
  232. windows, and so on, and each has an associated include file.
  233. The manual for each library states which include files are needed.
  234. The files are not protected against multiple inclusion and themselves
  235. contain no nested
  236. .CW #includes .
  237. Instead the
  238. programmer is expected to sort out the requirements
  239. and to
  240. .CW #include
  241. the necessary files once at the top of each source file. In practice this is
  242. trivial: this way of handling include files is so straightforward
  243. that it is rare for a source file to contain more than half a dozen
  244. .CW #includes .
  245. .PP
  246. The compilers do their own register allocation so the
  247. .CW register
  248. keyword is ignored.
  249. For different reasons,
  250. .CW volatile
  251. and
  252. .CW const
  253. are also ignored.
  254. .PP
  255. To make it easier to share code with other systems, Plan 9 has a version
  256. of the compiler,
  257. .CW pcc ,
  258. that provides the standard ANSI C preprocessor, headers, and libraries
  259. with POSIX extensions.
  260. .CW Pcc
  261. is recommended only
  262. when broad external portability is mandated. It compiles slower,
  263. produces slower code (it takes extra work to simulate POSIX on Plan 9),
  264. eliminates those parts of the Plan 9 interface
  265. not related to POSIX, and illustrates the clumsiness of an environment
  266. designed by committee.
  267. .CW Pcc
  268. is described in more detail in
  269. .I
  270. APE\(emThe ANSI/POSIX Environment,
  271. .R
  272. by Howard Trickey.
  273. .SH
  274. Process
  275. .PP
  276. Each CPU architecture supported by Plan 9 is identified by a single,
  277. arbitrary, alphanumeric character:
  278. .CW k
  279. for SPARC,
  280. .CW q
  281. for Motorola Power PC 630 and 640,
  282. .CW v
  283. for MIPS,
  284. .CW 0
  285. for little-endian MIPS,
  286. .CW 1
  287. for Motorola 68000,
  288. .CW 2
  289. for Motorola 68020 and 68040,
  290. .CW 5
  291. for Acorn ARM 7500,
  292. .CW 6
  293. for AMD 64,
  294. .CW 7
  295. for DEC Alpha,
  296. .CW 8
  297. for Intel 386, and
  298. .CW 9
  299. for AMD 29000.
  300. The character labels the support tools and files for that architecture.
  301. For instance, for the 68020 the compiler is
  302. .CW 2c ,
  303. the assembler is
  304. .CW 2a ,
  305. the link editor/loader is
  306. .CW 2l ,
  307. the object files are suffixed
  308. .CW \&.2 ,
  309. and the default name for an executable file is
  310. .CW 2.out .
  311. Before we can use the compiler we therefore need to know which
  312. machine we are compiling for.
  313. The next section explains how this decision is made; for the moment
  314. assume we are building 68020 binaries and make the mental substitution for
  315. .CW 2
  316. appropriate to the machine you are actually using.
  317. .PP
  318. To convert source to an executable binary is a two-step process.
  319. First run the compiler,
  320. .CW 2c ,
  321. on the source, say
  322. .CW file.c ,
  323. to generate an object file
  324. .CW file.2 .
  325. Then run the loader,
  326. .CW 2l ,
  327. to generate an executable
  328. .CW 2.out
  329. that may be run (on a 680X0 machine):
  330. .P1
  331. 2c file.c
  332. 2l file.2
  333. 2.out
  334. .P2
  335. The loader automatically links with whatever libraries the program
  336. needs, usually including the standard C library as defined by
  337. .CW <libc.h> .
  338. Of course the compiler and loader have lots of options, both familiar and new;
  339. see the manual for details.
  340. The compiler does not generate an executable automatically;
  341. the output of the compiler must be given to the loader.
  342. Since most compilation is done under the control of
  343. .CW mk
  344. (see below), this is rarely an inconvenience.
  345. .PP
  346. The distribution of work between the compiler and loader is unusual.
  347. The compiler integrates preprocessing, parsing, register allocation,
  348. code generation and some assembly.
  349. Combining these tasks in a single program is part of the reason for
  350. the compiler's efficiency.
  351. The loader does instruction selection, branch folding,
  352. instruction scheduling,
  353. and writes the final executable.
  354. There is no separate C preprocessor and no assembler in the usual pipeline.
  355. Instead the intermediate object file
  356. (here a
  357. .CW \&.2
  358. file) is a type of binary assembly language.
  359. The instructions in the intermediate format are not exactly those in
  360. the machine. For example, on the 68020 the object file may specify
  361. a MOVE instruction but the loader will decide just which variant of
  362. the MOVE instruction \(em MOVE immediate, MOVE quick, MOVE address,
  363. etc. \(em is most efficient.
  364. .PP
  365. The assembler,
  366. .CW 2a ,
  367. is just a translator between the textual and binary
  368. representations of the object file format.
  369. It is not an assembler in the traditional sense. It has limited
  370. macro capabilities (the same as the integral C preprocessor in the compiler),
  371. clumsy syntax, and minimal error checking. For instance, the assembler
  372. will accept an instruction (such as memory-to-memory MOVE on the MIPS) that the
  373. machine does not actually support; only when the output of the assembler
  374. is passed to the loader will the error be discovered.
  375. The assembler is intended only for writing things that need access to instructions
  376. invisible from C,
  377. such as the machine-dependent
  378. part of an operating system;
  379. very little code in Plan 9 is in assembly language.
  380. .PP
  381. The compilers take an option
  382. .CW -S
  383. that causes them to print on their standard output the generated code
  384. in a format acceptable as input to the assemblers.
  385. This is of course merely a formatting of the
  386. data in the object file; therefore the assembler is just
  387. an
  388. ASCII-to-binary converter for this format.
  389. Other than the specific instructions, the input to the assemblers
  390. is largely architecture-independent; see
  391. ``A Manual for the Plan 9 Assembler'',
  392. by Rob Pike,
  393. for more information.
  394. .PP
  395. The loader is an integral part of the compilation process.
  396. Each library header file contains a
  397. .CW #pragma
  398. that tells the loader the name of the associated archive; it is
  399. not necessary to tell the loader which libraries a program uses.
  400. The C run-time startup is found, by default, in the C library.
  401. The loader starts with an undefined
  402. symbol,
  403. .CW _main ,
  404. that is resolved by pulling in the run-time startup code from the library.
  405. (The loader undefines
  406. .CW _mainp
  407. when profiling is enabled, to force loading of the profiling start-up
  408. instead.)
  409. .PP
  410. Unlike its counterpart on other systems, the Plan 9 loader rearranges
  411. data to optimize access. This means the order of variables in the
  412. loaded program is unrelated to its order in the source.
  413. Most programs don't care, but some assume that, for example, the
  414. variables declared by
  415. .P1
  416. int a;
  417. int b;
  418. .P2
  419. will appear at adjacent addresses in memory. On Plan 9, they won't.
  420. .SH
  421. Heterogeneity
  422. .PP
  423. When the system starts or a user logs in the environment is configured
  424. so the appropriate binaries are available in
  425. .CW /bin .
  426. The configuration process is controlled by an environment variable,
  427. .CW $cputype ,
  428. with value such as
  429. .CW mips ,
  430. .CW 68020 ,
  431. .CW 386 ,
  432. or
  433. .CW sparc .
  434. For each architecture there is a directory in the root,
  435. with the appropriate name,
  436. that holds the binary and library files for that architecture.
  437. Thus
  438. .CW /mips/lib
  439. contains the object code libraries for MIPS programs,
  440. .CW /mips/include
  441. holds MIPS-specific include files, and
  442. .CW /mips/bin
  443. has the MIPS binaries.
  444. These binaries are attached to
  445. .CW /bin
  446. at boot time by binding
  447. .CW /$cputype/bin
  448. to
  449. .CW /bin ,
  450. so
  451. .CW /bin
  452. always contains the correct files.
  453. .PP
  454. The MIPS compiler,
  455. .CW vc ,
  456. by definition
  457. produces object files for the MIPS architecture,
  458. regardless of the architecture of the machine on which the compiler is running.
  459. There is a version of
  460. .CW vc
  461. compiled for each architecture:
  462. .CW /mips/bin/vc ,
  463. .CW /68020/bin/vc ,
  464. .CW /sparc/bin/vc ,
  465. and so on,
  466. each capable of producing MIPS object files regardless of the native
  467. instruction set.
  468. If one is running on a SPARC,
  469. .CW /sparc/bin/vc
  470. will compile programs for the MIPS;
  471. if one is running on machine
  472. .CW $cputype ,
  473. .CW /$cputype/bin/vc
  474. will compile programs for the MIPS.
  475. .PP
  476. Because of the bindings that assemble
  477. .CW /bin ,
  478. the shell always looks for a command, say
  479. .CW date ,
  480. in
  481. .CW /bin
  482. and automatically finds the file
  483. .CW /$cputype/bin/date .
  484. Therefore the MIPS compiler is known as just
  485. .CW vc ;
  486. the shell will invoke
  487. .CW /bin/vc
  488. and that is guaranteed to be the version of the MIPS compiler
  489. appropriate for the machine running the command.
  490. Regardless of the architecture of the compiling machine,
  491. .CW /bin/vc
  492. is
  493. .I always
  494. the MIPS compiler.
  495. .PP
  496. Also, the output of
  497. .CW vc
  498. and
  499. .CW vl
  500. is completely independent of the machine type on which they are executed:
  501. .CW \&.v
  502. files compiled (with
  503. .CW vc )
  504. on a SPARC may be linked (with
  505. .CW vl )
  506. on a 386.
  507. (The resulting
  508. .CW v.out
  509. will run, of course, only on a MIPS.)
  510. Similarly, the MIPS libraries in
  511. .CW /mips/lib
  512. are suitable for loading with
  513. .CW vl
  514. on any machine; there is only one set of MIPS libraries, not one
  515. set for each architecture that supports the MIPS compiler.
  516. .SH
  517. Heterogeneity and \f(CWmk\fP
  518. .PP
  519. Most software on Plan 9 is compiled under the control of
  520. .CW mk ,
  521. a descendant of
  522. .CW make
  523. that is documented in the Programmer's Manual.
  524. A convention used throughout the
  525. .CW mkfiles
  526. makes it easy to compile the source into binary suitable for any architecture.
  527. .PP
  528. The variable
  529. .CW $cputype
  530. is advisory: it reports the architecture of the current environment, and should
  531. not be modified. A second variable,
  532. .CW $objtype ,
  533. is used to set which architecture is being
  534. .I compiled
  535. for.
  536. The value of
  537. .CW $objtype
  538. can be used by a
  539. .CW mkfile
  540. to configure the compilation environment.
  541. .PP
  542. In each machine's root directory there is a short
  543. .CW mkfile
  544. that defines a set of macros for the compiler, loader, etc.
  545. Here is
  546. .CW /mips/mkfile :
  547. .P1
  548. </sys/src/mkfile.proto
  549. CC=vc
  550. LD=vl
  551. O=v
  552. AS=va
  553. .P2
  554. The line
  555. .P1
  556. </sys/src/mkfile.proto
  557. .P2
  558. causes
  559. .CW mk
  560. to include the file
  561. .CW /sys/src/mkfile.proto ,
  562. which contains general definitions:
  563. .P1
  564. #
  565. # common mkfile parameters shared by all architectures
  566. #
  567. OS=v486xq7
  568. CPUS=mips 386 power alpha
  569. CFLAGS=-FVw
  570. LEX=lex
  571. YACC=yacc
  572. MK=/bin/mk
  573. .P2
  574. .CW CC
  575. is obviously the compiler,
  576. .CW AS
  577. the assembler, and
  578. .CW LD
  579. the loader.
  580. .CW O
  581. is the suffix for the object files and
  582. .CW CPUS
  583. and
  584. .CW OS
  585. are used in special rules described below.
  586. .PP
  587. Here is a
  588. .CW mkfile
  589. to build the installed source for
  590. .CW sam :
  591. .P1
  592. </$objtype/mkfile
  593. OBJ=sam.$O address.$O buffer.$O cmd.$O disc.$O error.$O \e
  594. file.$O io.$O list.$O mesg.$O moveto.$O multi.$O \e
  595. plan9.$O rasp.$O regexp.$O string.$O sys.$O xec.$O
  596. $O.out: $OBJ
  597. $LD $OBJ
  598. install: $O.out
  599. cp $O.out /$objtype/bin/sam
  600. installall:
  601. for(objtype in $CPUS) mk install
  602. %.$O: %.c
  603. $CC $CFLAGS $stem.c
  604. $OBJ: sam.h errors.h mesg.h
  605. address.$O cmd.$O parse.$O xec.$O unix.$O: parse.h
  606. clean:V:
  607. rm -f [$OS].out *.[$OS] y.tab.?
  608. .P2
  609. (The actual
  610. .CW mkfile
  611. imports most of its rules from other secondary files, but
  612. this example works and is not misleading.)
  613. The first line causes
  614. .CW mk
  615. to include the contents of
  616. .CW /$objtype/mkfile
  617. in the current
  618. .CW mkfile .
  619. If
  620. .CW $objtype
  621. is
  622. .CW mips ,
  623. this inserts the MIPS macro definitions into the
  624. .CW mkfile .
  625. In this case the rule for
  626. .CW $O.out
  627. uses the MIPS tools to build
  628. .CW v.out .
  629. The
  630. .CW %.$O
  631. rule in the file uses
  632. .CW mk 's
  633. pattern matching facilities to convert the source files to the object
  634. files through the compiler.
  635. (The text of the rules is passed directly to the shell,
  636. .CW rc ,
  637. without further translation.
  638. See the
  639. .CW mk
  640. manual if any of this is unfamiliar.)
  641. Because the default rule builds
  642. .CW $O.out
  643. rather than
  644. .CW sam ,
  645. it is possible to maintain binaries for multiple machines in the
  646. same source directory without conflict.
  647. This is also, of course, why the output files from the various
  648. compilers and loaders
  649. have distinct names.
  650. .PP
  651. The rest of the
  652. .CW mkfile
  653. should be easy to follow; notice how the rules for
  654. .CW clean
  655. and
  656. .CW installall
  657. (that is, install versions for all architectures) use other macros
  658. defined in
  659. .CW /$objtype/mkfile .
  660. In Plan 9,
  661. .CW mkfiles
  662. for commands conventionally contain rules to
  663. .CW install
  664. (compile and install the version for
  665. .CW $objtype ),
  666. .CW installall
  667. (compile and install for all
  668. .CW $objtypes ),
  669. and
  670. .CW clean
  671. (remove all object files, binaries, etc.).
  672. .PP
  673. The
  674. .CW mkfile
  675. is easy to use. To build a MIPS binary,
  676. .CW v.out :
  677. .P1
  678. % objtype=mips
  679. % mk
  680. .P2
  681. To build and install a MIPS binary:
  682. .P1
  683. % objtype=mips
  684. % mk install
  685. .P2
  686. To build and install all versions:
  687. .P1
  688. % mk installall
  689. .P2
  690. These conventions make cross-compilation as easy to manage
  691. as traditional native compilation.
  692. Plan 9 programs compile and run without change on machines from
  693. large multiprocessors to laptops. For more information about this process, see
  694. ``Plan 9 Mkfiles'',
  695. by Bob Flandrena.
  696. .SH
  697. Portability
  698. .PP
  699. Within Plan 9, it is painless to write portable programs, programs whose
  700. source is independent of the machine on which they execute.
  701. The operating system is fixed and the compiler, headers and libraries
  702. are constant so most of the stumbling blocks to portability are removed.
  703. Attention to a few details can avoid those that remain.
  704. .PP
  705. Plan 9 is a heterogeneous environment, so programs must
  706. .I expect
  707. that external files will be written by programs on machines of different
  708. architectures.
  709. The compilers, for instance, must handle without confusion
  710. object files written by other machines.
  711. The traditional approach to this problem is to pepper the source with
  712. .CW #ifdefs
  713. to turn byte-swapping on and off.
  714. Plan 9 takes a different approach: of the handful of machine-dependent
  715. .CW #ifdefs
  716. in all the source, almost all are deep in the libraries.
  717. Instead programs read and write files in a defined format,
  718. either (for low volume applications) as formatted text, or
  719. (for high volume applications) as binary in a known byte order.
  720. If the external data were written with the most significant
  721. byte first, the following code reads a 4-byte integer correctly
  722. regardless of the architecture of the executing machine (assuming
  723. an unsigned long holds 4 bytes):
  724. .P1
  725. ulong
  726. getlong(void)
  727. {
  728. ulong l;
  729. l = (getchar()&0xFF)<<24;
  730. l |= (getchar()&0xFF)<<16;
  731. l |= (getchar()&0xFF)<<8;
  732. l |= (getchar()&0xFF)<<0;
  733. return l;
  734. }
  735. .P2
  736. Note that this code does not `swap' the bytes; instead it just reads
  737. them in the correct order.
  738. Variations of this code will handle any binary format
  739. and also avoid problems
  740. involving how structures are padded, how words are aligned,
  741. and other impediments to portability.
  742. Be aware, though, that extra care is needed to handle floating point data.
  743. .PP
  744. Efficiency hounds will argue that this method is unnecessarily slow and clumsy
  745. when the executing machine has the same byte order (and padding and alignment)
  746. as the data.
  747. The CPU cost of I/O processing
  748. is rarely the bottleneck for an application, however,
  749. and the gain in simplicity of porting and maintaining the code greatly outweighs
  750. the minor speed loss from handling data in this general way.
  751. This method is how the Plan 9 compilers, the window system, and even the file
  752. servers transmit data between programs.
  753. .PP
  754. To port programs beyond Plan 9, where the system interface is more variable,
  755. it is probably necessary to use
  756. .CW pcc
  757. and hope that the target machine supports ANSI C and POSIX.
  758. .SH
  759. I/O
  760. .PP
  761. The default C library, defined by the include file
  762. .CW <libc.h> ,
  763. contains no buffered I/O package.
  764. It does have several entry points for printing formatted text:
  765. .CW print
  766. outputs text to the standard output,
  767. .CW fprint
  768. outputs text to a specified integer file descriptor, and
  769. .CW sprint
  770. places text in a character array.
  771. To access library routines for buffered I/O, a program must
  772. explicitly include the header file associated with an appropriate library.
  773. .PP
  774. The recommended I/O library, used by most Plan 9 utilities, is
  775. .CW bio
  776. (buffered I/O), defined by
  777. .CW <bio.h> .
  778. There also exists an implementation of ANSI Standard I/O,
  779. .CW stdio .
  780. .PP
  781. .CW Bio
  782. is small and efficient, particularly for buffer-at-a-time or
  783. line-at-a-time I/O.
  784. Even for character-at-a-time I/O, however, it is significantly faster than
  785. the Standard I/O library,
  786. .CW stdio .
  787. Its interface is compact and regular, although it lacks a few conveniences.
  788. The most noticeable is that one must explicitly define buffers for standard
  789. input and output;
  790. .CW bio
  791. does not predefine them. Here is a program to copy input to output a byte
  792. at a time using
  793. .CW bio :
  794. .P1
  795. #include <u.h>
  796. #include <libc.h>
  797. #include <bio.h>
  798. Biobuf bin;
  799. Biobuf bout;
  800. main(void)
  801. {
  802. int c;
  803. Binit(&bin, 0, OREAD);
  804. Binit(&bout, 1, OWRITE);
  805. while((c=Bgetc(&bin)) != Beof)
  806. Bputc(&bout, c);
  807. exits(0);
  808. }
  809. .P2
  810. For peak performance, we could replace
  811. .CW Bgetc
  812. and
  813. .CW Bputc
  814. by their equivalent in-line macros
  815. .CW BGETC
  816. and
  817. .CW BPUTC
  818. but
  819. the performance gain would be modest.
  820. For more information on
  821. .CW bio ,
  822. see the Programmer's Manual.
  823. .PP
  824. Perhaps the most dramatic difference in the I/O interface of Plan 9 from other
  825. systems' is that text is not ASCII.
  826. The format for
  827. text in Plan 9 is a byte-stream encoding of 16-bit characters.
  828. The character set is based on the Unicode Standard and is backward compatible with
  829. ASCII:
  830. characters with value 0 through 127 are the same in both sets.
  831. The 16-bit characters, called
  832. .I runes
  833. in Plan 9, are encoded using a representation called
  834. UTF,
  835. an encoding that is becoming accepted as a standard.
  836. (ISO calls it UTF-8;
  837. throughout Plan 9 it's just called
  838. UTF.)
  839. UTF
  840. defines multibyte sequences to
  841. represent character values from 0 to 65535.
  842. In
  843. UTF,
  844. character values up to 127 decimal, 7F hexadecimal, represent themselves,
  845. so straight
  846. ASCII
  847. files are also valid
  848. UTF.
  849. Also,
  850. UTF
  851. guarantees that bytes with values 0 to 127 (NUL to DEL, inclusive)
  852. will appear only when they represent themselves, so programs that read bytes
  853. looking for plain ASCII characters will continue to work.
  854. Any program that expects a one-to-one correspondence between bytes and
  855. characters will, however, need to be modified.
  856. An example is parsing file names.
  857. File names, like all text, are in
  858. UTF,
  859. so it is incorrect to search for a character in a string by
  860. .CW strchr(filename,
  861. .CW c)
  862. because the character might have a multi-byte encoding.
  863. The correct method is to call
  864. .CW utfrune(filename,
  865. .CW c) ,
  866. defined in
  867. .I rune (2),
  868. which interprets the file name as a sequence of encoded characters
  869. rather than bytes.
  870. In fact, even when you know the character is a single byte
  871. that can represent only itself,
  872. it is safer to use
  873. .CW utfrune
  874. because that assumes nothing about the character set
  875. and its representation.
  876. .PP
  877. The library defines several symbols relevant to the representation of characters.
  878. Any byte with unsigned value less than
  879. .CW Runesync
  880. will not appear in any multi-byte encoding of a character.
  881. .CW Utfrune
  882. compares the character being searched against
  883. .CW Runesync
  884. to see if it is sufficient to call
  885. .CW strchr
  886. or if the byte stream must be interpreted.
  887. Any byte with unsigned value less than
  888. .CW Runeself
  889. is represented by a single byte with the same value.
  890. Finally, when errors are encountered converting
  891. to runes from a byte stream, the library returns the rune value
  892. .CW Runeerror
  893. and advances a single byte. This permits programs to find runes
  894. embedded in binary data.
  895. .PP
  896. .CW Bio
  897. includes routines
  898. .CW Bgetrune
  899. and
  900. .CW Bputrune
  901. to transform the external byte stream
  902. UTF
  903. format to and from
  904. internal 16-bit runes.
  905. Also, the
  906. .CW %s
  907. format to
  908. .CW print
  909. accepts
  910. UTF;
  911. .CW %c
  912. prints a character after narrowing it to 8 bits.
  913. The
  914. .CW %S
  915. format prints a null-terminated sequence of runes;
  916. .CW %C
  917. prints a character after narrowing it to 16 bits.
  918. For more information, see the Programmer's Manual, in particular
  919. .I utf (6)
  920. and
  921. .I rune (2),
  922. and the paper,
  923. ``Hello world, or
  924. Καλημέρα κόσμε, or\
  925. \f(Jpこんにちは 世界\f1'',
  926. by Rob Pike and
  927. Ken Thompson;
  928. there is not room for the full story here.
  929. .PP
  930. These issues affect the compiler in several ways.
  931. First, the C source is in
  932. UTF.
  933. ANSI says C variables are formed from
  934. ASCII
  935. alphanumerics, but comments and literal strings may contain any characters
  936. encoded in the native encoding, here
  937. UTF.
  938. The declaration
  939. .P1
  940. char *cp = "abcÿ";
  941. .P2
  942. initializes the variable
  943. .CW cp
  944. to point to an array of bytes holding the
  945. UTF
  946. representation of the characters
  947. .CW abcÿ.
  948. The type
  949. .CW Rune
  950. is defined in
  951. .CW <u.h>
  952. to be
  953. .CW ushort ,
  954. which is also the `wide character' type in the compiler.
  955. Therefore the declaration
  956. .P1
  957. Rune *rp = L"abcÿ";
  958. .P2
  959. initializes the variable
  960. .CW rp
  961. to point to an array of unsigned short integers holding the 16-bit
  962. values of the characters
  963. .CW abcÿ .
  964. Note that in both these declarations the characters in the source
  965. that represent
  966. .CW "abcÿ"
  967. are the same; what changes is how those characters are represented
  968. in memory in the program.
  969. The following two lines:
  970. .P1
  971. print("%s\en", "abcÿ");
  972. print("%S\en", L"abcÿ");
  973. .P2
  974. produce the same
  975. UTF
  976. string on their output, the first by copying the bytes, the second
  977. by converting from runes to bytes.
  978. .PP
  979. In C, character constants are integers but narrowed through the
  980. .CW char
  981. type.
  982. The Unicode character
  983. .CW ÿ
  984. has value 255, so if the
  985. .CW char
  986. type is signed,
  987. the constant
  988. .CW 'ÿ'
  989. has value \-1 (which is equal to EOF).
  990. On the other hand,
  991. .CW L'ÿ'
  992. narrows through the wide character type,
  993. .CW ushort ,
  994. and therefore has value 255.
  995. .PP
  996. Finally, although it's not ANSI C, the Plan 9 C compilers
  997. assume any character with value above
  998. .CW Runeself
  999. is an alphanumeric,
  1000. so α is a legal, if non-portable, variable name.
  1001. .SH
  1002. Arguments
  1003. .PP
  1004. Some macros are defined
  1005. in
  1006. .CW <libc.h>
  1007. for parsing the arguments to
  1008. .CW main() .
  1009. They are described in
  1010. .I ARG (2)
  1011. but are fairly self-explanatory.
  1012. There are four macros:
  1013. .CW ARGBEGIN
  1014. and
  1015. .CW ARGEND
  1016. are used to bracket a hidden
  1017. .CW switch
  1018. statement within which
  1019. .CW ARGC
  1020. returns the current option character (rune) being processed and
  1021. .CW ARGF
  1022. returns the argument to the option, as in the loader option
  1023. .CW -o
  1024. .CW file .
  1025. Here, for example, is the code at the beginning of
  1026. .CW main()
  1027. in
  1028. .CW ramfs.c
  1029. (see
  1030. .I ramfs (1))
  1031. that cracks its arguments:
  1032. .P1
  1033. void
  1034. main(int argc, char *argv[])
  1035. {
  1036. char *defmnt;
  1037. int p[2];
  1038. int mfd[2];
  1039. int stdio = 0;
  1040. defmnt = "/tmp";
  1041. ARGBEGIN{
  1042. case 'i':
  1043. defmnt = 0;
  1044. stdio = 1;
  1045. mfd[0] = 0;
  1046. mfd[1] = 1;
  1047. break;
  1048. case 's':
  1049. defmnt = 0;
  1050. break;
  1051. case 'm':
  1052. defmnt = ARGF();
  1053. break;
  1054. default:
  1055. usage();
  1056. }ARGEND
  1057. .P2
  1058. .SH
  1059. Extensions
  1060. .PP
  1061. The compiler has several extensions to 1989 ANSI C, all of which are used
  1062. extensively in the system source.
  1063. Some of these have been adopted in later ANSI C standards.
  1064. First,
  1065. .I structure
  1066. .I displays
  1067. permit
  1068. .CW struct
  1069. expressions to be formed dynamically.
  1070. Given these declarations:
  1071. .P1
  1072. typedef struct Point Point;
  1073. typedef struct Rectangle Rectangle;
  1074. struct Point
  1075. {
  1076. int x, y;
  1077. };
  1078. struct Rectangle
  1079. {
  1080. Point min, max;
  1081. };
  1082. Point p, q, add(Point, Point);
  1083. Rectangle r;
  1084. int x, y;
  1085. .P2
  1086. this assignment may appear anywhere an assignment is legal:
  1087. .P1
  1088. r = (Rectangle){add(p, q), (Point){x, y+3}};
  1089. .P2
  1090. The syntax is the same as for initializing a structure but with
  1091. a leading cast.
  1092. .PP
  1093. If an
  1094. .I anonymous
  1095. .I structure
  1096. or
  1097. .I union
  1098. is declared within another structure or union, the members of the internal
  1099. structure or union are addressable without prefix in the outer structure.
  1100. This feature eliminates the clumsy naming of nested structures and,
  1101. particularly, unions.
  1102. For example, after these declarations,
  1103. .P1
  1104. struct Lock
  1105. {
  1106. int locked;
  1107. };
  1108. struct Node
  1109. {
  1110. int type;
  1111. union{
  1112. double dval;
  1113. double fval;
  1114. long lval;
  1115. }; /* anonymous union */
  1116. struct Lock; /* anonymous structure */
  1117. } *node;
  1118. void lock(struct Lock*);
  1119. .P2
  1120. one may refer to
  1121. .CW node->type ,
  1122. .CW node->dval ,
  1123. .CW node->fval ,
  1124. .CW node->lval ,
  1125. and
  1126. .CW node->locked .
  1127. Moreover, the address of a
  1128. .CW struct
  1129. .CW Node
  1130. may be used without a cast anywhere that the address of a
  1131. .CW struct
  1132. .CW Lock
  1133. is used, such as in argument lists.
  1134. The compiler automatically promotes the type and adjusts the address.
  1135. Thus one may invoke
  1136. .CW lock(node) .
  1137. .PP
  1138. Anonymous structures and unions may be accessed by type name
  1139. if (and only if) they are declared using a
  1140. .CW typedef
  1141. name.
  1142. For example, using the above declaration for
  1143. .CW Point ,
  1144. one may declare
  1145. .P1
  1146. struct
  1147. {
  1148. int type;
  1149. Point;
  1150. } p;
  1151. .P2
  1152. and refer to
  1153. .CW p.Point .
  1154. .PP
  1155. In the initialization of arrays, a number in square brackets before an
  1156. element sets the index for the initialization. For example, to initialize
  1157. some elements in
  1158. a table of function pointers indexed by
  1159. ASCII
  1160. character,
  1161. .P1
  1162. void percent(void), slash(void);
  1163. void (*func[128])(void) =
  1164. {
  1165. ['%'] percent,
  1166. ['/'] slash,
  1167. };
  1168. .P2
  1169. .LP
  1170. A similar syntax allows one to initialize structure elements:
  1171. .P1
  1172. Point p =
  1173. {
  1174. .y 100,
  1175. .x 200
  1176. };
  1177. .P2
  1178. These initialization syntaxes were later added to ANSI C, with the addition of an
  1179. equals sign between the index or tag and the value.
  1180. The Plan 9 compiler accepts either form.
  1181. .PP
  1182. Finally, the declaration
  1183. .P1
  1184. extern register reg;
  1185. .P2
  1186. .I this "" (
  1187. appearance of the register keyword is not ignored)
  1188. allocates a global register to hold the variable
  1189. .CW reg .
  1190. External registers must be used carefully: they need to be declared in
  1191. .I all
  1192. source files and libraries in the program to guarantee the register
  1193. is not allocated temporarily for other purposes.
  1194. Especially on machines with few registers, such as the i386,
  1195. it is easy to link accidentally with code that has already usurped
  1196. the global registers and there is no diagnostic when this happens.
  1197. Used wisely, though, external registers are powerful.
  1198. The Plan 9 operating system uses them to access per-process and
  1199. per-machine data structures on a multiprocessor. The storage class they provide
  1200. is hard to create in other ways.
  1201. .SH
  1202. The compile-time environment
  1203. .PP
  1204. The code generated by the compilers is `optimized' by default:
  1205. variables are placed in registers and peephole optimizations are
  1206. performed.
  1207. The compiler flag
  1208. .CW -N
  1209. disables these optimizations.
  1210. Registerization is done locally rather than throughout a function:
  1211. whether a variable occupies a register or
  1212. the memory location identified in the symbol
  1213. table depends on the activity of the variable and may change
  1214. throughout the life of the variable.
  1215. The
  1216. .CW -N
  1217. flag is rarely needed;
  1218. its main use is to simplify debugging.
  1219. There is no information in the symbol table to identify the
  1220. registerization of a variable, so
  1221. .CW -N
  1222. guarantees the variable is always where the symbol table says it is.
  1223. .PP
  1224. Another flag,
  1225. .CW -w ,
  1226. turns
  1227. .I on
  1228. warnings about portability and problems detected in flow analysis.
  1229. Most code in Plan 9 is compiled with warnings enabled;
  1230. these warnings plus the type checking offered by function prototypes
  1231. provide most of the support of the Unix tool
  1232. .CW lint
  1233. more accurately and with less chatter.
  1234. Two of the warnings,
  1235. `used and not set' and `set and not used', are almost always accurate but
  1236. may be triggered spuriously by code with invisible control flow,
  1237. such as in routines that call
  1238. .CW longjmp .
  1239. The compiler statements
  1240. .P1
  1241. SET(v1);
  1242. USED(v2);
  1243. .P2
  1244. decorate the flow graph to silence the compiler.
  1245. Either statement accepts a comma-separated list of variables.
  1246. Use them carefully: they may silence real errors.
  1247. For the common case of unused parameters to a function,
  1248. leaving the name off the declaration silences the warnings.
  1249. That is, listing the type of a parameter but giving it no
  1250. associated variable name does the trick.
  1251. .SH
  1252. Debugging
  1253. .PP
  1254. There are two debuggers available on Plan 9.
  1255. The first, and older, is
  1256. .CW db ,
  1257. a revision of Unix
  1258. .CW adb .
  1259. The other,
  1260. .CW acid ,
  1261. is a source-level debugger whose commands are statements in
  1262. a true programming language.
  1263. .CW Acid
  1264. is the preferred debugger, but since it
  1265. borrows some elements of
  1266. .CW db ,
  1267. notably the formats for displaying values, it is worth knowing a little bit about
  1268. .CW db .
  1269. .PP
  1270. Both debuggers support multiple architectures in a single program; that is,
  1271. the programs are
  1272. .CW db
  1273. and
  1274. .CW acid ,
  1275. not for example
  1276. .CW vdb
  1277. and
  1278. .CW vacid .
  1279. They also support cross-architecture debugging comfortably:
  1280. one may debug a 68020 binary on a MIPS.
  1281. .PP
  1282. Imagine a program has crashed mysteriously:
  1283. .P1
  1284. % X11/X
  1285. Fatal server bug!
  1286. failed to create default stipple
  1287. X 106: suicide: sys: trap: fault read addr=0x0 pc=0x00105fb8
  1288. %
  1289. .P2
  1290. When a process dies on Plan 9 it hangs in the `broken' state
  1291. for debugging.
  1292. Attach a debugger to the process by naming its process id:
  1293. .P1
  1294. % acid 106
  1295. /proc/106/text:mips plan 9 executable
  1296. /sys/lib/acid/port
  1297. /sys/lib/acid/mips
  1298. acid:
  1299. .P2
  1300. The
  1301. .CW acid
  1302. function
  1303. .CW stk()
  1304. reports the stack traceback:
  1305. .P1
  1306. acid: stk()
  1307. At pc:0x105fb8:abort+0x24 /sys/src/ape/lib/ap/stdio/abort.c:6
  1308. abort() /sys/src/ape/lib/ap/stdio/abort.c:4
  1309. called from FatalError+#4e
  1310. /sys/src/X/mit/server/dix/misc.c:421
  1311. FatalError(s9=#e02, s8=#4901d200, s7=#2, s6=#72701, s5=#1,
  1312. s4=#7270d, s3=#6, s2=#12, s1=#ff37f1c, s0=#6, f=#7270f)
  1313. /sys/src/X/mit/server/dix/misc.c:416
  1314. called from gnotscreeninit+#4ce
  1315. /sys/src/X/mit/server/ddx/gnot/gnot.c:792
  1316. gnotscreeninit(snum=#0, sc=#80db0)
  1317. /sys/src/X/mit/server/ddx/gnot/gnot.c:766
  1318. called from AddScreen+#16e
  1319. /n/bootes/sys/src/X/mit/server/dix/main.c:610
  1320. AddScreen(pfnInit=0x0000129c,argc=0x00000001,argv=0x7fffffe4)
  1321. /sys/src/X/mit/server/dix/main.c:530
  1322. called from InitOutput+0x80
  1323. /sys/src/X/mit/server/ddx/brazil/brddx.c:522
  1324. InitOutput(argc=0x00000001,argv=0x7fffffe4)
  1325. /sys/src/X/mit/server/ddx/brazil/brddx.c:511
  1326. called from main+0x294
  1327. /sys/src/X/mit/server/dix/main.c:225
  1328. main(argc=0x00000001,argv=0x7fffffe4)
  1329. /sys/src/X/mit/server/dix/main.c:136
  1330. called from _main+0x24
  1331. /sys/src/ape/lib/ap/mips/main9.s:8
  1332. .P2
  1333. The function
  1334. .CW lstk()
  1335. is similar but
  1336. also reports the values of local variables.
  1337. Note that the traceback includes full file names; this is a boon to debugging,
  1338. although it makes the output much noisier.
  1339. .PP
  1340. To use
  1341. .CW acid
  1342. well you will need to learn its input language; see the
  1343. ``Acid Manual'',
  1344. by Phil Winterbottom,
  1345. for details. For simple debugging, however, the information in the manual page is
  1346. sufficient. In particular, it describes the most useful functions
  1347. for examining a process.
  1348. .PP
  1349. The compiler does not place
  1350. information describing the types of variables in the executable,
  1351. but a compile-time flag provides crude support for symbolic debugging.
  1352. The
  1353. .CW -a
  1354. flag to the compiler suppresses code generation
  1355. and instead emits source text in the
  1356. .CW acid
  1357. language to format and display data structure types defined in the program.
  1358. The easiest way to use this feature is to put a rule in the
  1359. .CW mkfile :
  1360. .P1
  1361. syms: main.$O
  1362. $CC -a main.c > syms
  1363. .P2
  1364. Then from within
  1365. .CW acid ,
  1366. .P1
  1367. acid: include("sourcedirectory/syms")
  1368. .P2
  1369. to read in the relevant definitions.
  1370. (For multi-file source, you need to be a little fancier;
  1371. see
  1372. .I 2c (1)).
  1373. This text includes, for each defined compound
  1374. type, a function with that name that may be called with the address of a structure
  1375. of that type to display its contents.
  1376. For example, if
  1377. .CW rect
  1378. is a global variable of type
  1379. .CW Rectangle ,
  1380. one may execute
  1381. .P1
  1382. Rectangle(*rect)
  1383. .P2
  1384. to display it.
  1385. The
  1386. .CW *
  1387. (indirection) operator is necessary because
  1388. of the way
  1389. .CW acid
  1390. works: each global symbol in the program is defined as a variable by
  1391. .CW acid ,
  1392. with value equal to the
  1393. .I address
  1394. of the symbol.
  1395. .PP
  1396. Another common technique is to write by hand special
  1397. .CW acid
  1398. code to define functions to aid debugging, initialize the debugger, and so on.
  1399. Conventionally, this is placed in a file called
  1400. .CW acid
  1401. in the source directory; it has a line
  1402. .P1
  1403. include("sourcedirectory/syms");
  1404. .P2
  1405. to load the compiler-produced symbols. One may edit the compiler output directly but
  1406. it is wiser to keep the hand-generated
  1407. .CW acid
  1408. separate from the machine-generated.
  1409. .PP
  1410. To make things simple, the default rules in the system
  1411. .CW mkfiles
  1412. include entries to make
  1413. .CW foo.acid
  1414. from
  1415. .CW foo.c ,
  1416. so one may use
  1417. .CW mk
  1418. to automate the production of
  1419. .CW acid
  1420. definitions for a given C source file.
  1421. .PP
  1422. There is much more to say here. See
  1423. .CW acid
  1424. manual page, the reference manual, or the paper
  1425. ``Acid: A Debugger Built From A Language'',
  1426. also by Phil Winterbottom.