1
0

comp.ms 37 KB

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