OpenCores
URL https://opencores.org/ocsvn/eco32/eco32/trunk

Subversion Repositories eco32

[/] [eco32/] [trunk/] [lcc/] [doc/] [lcc.1] - Blame information for rev 149

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 4 hellwig
.\" $Id: lcc.1,v 1.15 1998/08/24 21:14:33 drh Exp $
2
.TH LCC 1 "local \- $Date: 1998/08/24 21:14:33 $"
3
.SH NAME
4
lcc \- ANSI C compiler
5
.SH SYNOPSIS
6
.B lcc
7
[
8
.I option
9
|
10
.I file
11
]...
12
.br
13
.SH DESCRIPTION
14
.PP
15
.I lcc
16
is an ANSI C compiler for a variety of platforms.
17
.PP
18
Arguments whose names end with `.c' (plus `.C' under Windows) are taken to be
19
C source programs; they are preprocessed, compiled, and
20
each object program is left on the file
21
whose name is that of the source with `.o' (UNIX) or `.obj' (Windows)
22
substituted for the extension.
23
Arguments whose names end with `.i' are treated similarly,
24
except they are not preprocessed.
25
In the same way,
26
arguments ending with `.s' (plus `.S', `.asm', and `.ASM', under Windows)
27
are taken to be assembly source programs
28
and are assembled, producing an object file.
29
If there are no arguments,
30
.I lcc
31
summarizes its options on the standard error.
32
.PP
33
.I lcc
34
deletes an object file if and only if exactly one
35
source file is mentioned and no other file
36
(source, object, library) or
37
.B \-l
38
option is mentioned.
39
.PP
40
If the environment variable
41
.B LCCINPUTS
42
is set,
43
.I lcc
44
assumes it gives a semicolon- or colon-separated list of directories in which to
45
look for source and object files whose names do not begin with `/'.
46
These directories are also added to the list of directories
47
searched for libraries.
48
If
49
.B LCCINPUTS
50
is defined, it must contain `.' in order for the current directory
51
to be searched for input files.
52
.PP
53
.I lcc
54
uses ANSI standard header files (see `FILES' below).
55
Include files not found in the ANSI header files
56
are taken from the normal default include areas,
57
which usually includes
58
.BR /usr/include .
59
Under Windows, if the environment variable
60
.B include
61
is defined, it gives a semicolon-separated list of directories in which to search for
62
header files.
63
.PP
64
.I lcc
65
interprets the following options; unrecognized options are
66
taken as loader options (see
67
.IR ld (1))
68
unless
69
.BR \-c ,
70
.BR \-S ,
71
or
72
.B \-E
73
precedes them.
74
Except for
75
.BR \-l ,
76
all options are processed before any of the files
77
and apply to all of the files.
78
Applicable options are passed to each compilation phase in the order given.
79
.TP
80
.B \-c
81
Suppress the loading phase of the compilation, and force
82
an object file to be produced even if only one program is compiled.
83
.TP
84
.B \-g
85
Produce additional symbol table information for the local debuggers.
86
.I lcc
87
warns when
88
.B \-g
89
is unsupported.
90
.TP
91
.BI \-Wf\-g n , x
92
Set the debugging level to
93
.I n
94
and emit source code as comments into the generated assembly code;
95
.I x
96
must be the assembly language comment character.
97
If
98
.I n
99
is omitted, it defaults to 1, which is similar to
100
.BR \-g .
101
Omitting
102
.BI , x
103
just sets the debugging level to
104
.IR n .
105
.TP
106
.B \-w
107
Suppress warning diagnostics, such as those
108
announcing unreferenced statics, locals, and parameters.
109
The line
110
.I
111
#pragma ref id
112
simulates a reference to the variable
113
.IR id .
114
.TP
115
.BI \-d n
116
Generate jump tables for switches whose density is at least
117
.IR n ,
118
a floating point constant between zero and one.
119
The default is 0.5.
120
.TP
121
.B \-A
122
Warns about
123
declarations and casts of function types without prototypes,
124
assignments between pointers to ints and pointers to enums, and
125
conversions from pointers to smaller integral types.
126
A second
127
.B \-A
128
warns about
129
unrecognized control lines,
130
nonANSI language extensions and source characters in literals,
131
unreferenced variables and static functions,
132
declaring arrays of incomplete types,
133
and exceeding
134
.I some
135
ANSI environmental limits, like more than 257 cases in switches.
136
It also arranges for duplicate global definitions in separately compiled
137
files to cause loader errors.
138
.TP
139
.B \-P
140
Writes declarations for all defined globals on standard error.
141
Function declarations include prototypes;
142
editing this output can simplify conversion to ANSI C.
143
This output may not correspond to the input when
144
there are several typedefs for the same type.
145
.TP
146
.B \-n
147
Arrange for the compiler to produce code
148
that tests for dereferencing zero pointers.
149
The code reports the offending file and line number and calls
150
.IR abort (3).
151
.TP
152
.B \-O
153
is ignored.
154
.TP
155
.B \-S
156
Compile the named C programs, and leave the
157
assembler-language output on corresponding files suffixed `.s' or `.asm'.
158
.TP
159
.B \-E
160
Run only the preprocessor on the named C programs
161
and unsuffixed file arguments,
162
and send the result to the standard output.
163
.TP
164
.BI \-o "  output"
165
Name the output file
166
.IR output .
167
If
168
.B \-c
169
or
170
.B \-S
171
is specified and there is exactly one source file,
172
this option names the object or assembly file, respectively.
173
Otherwise, this option names the final executable
174
file generated by the loader, and `a.out' (UNIX) or `a.exe' (Windows) is left undisturbed.
175
.I lcc
176
warns if
177
.B \-o
178
and
179
.B \-c
180
or
181
.B \-S
182
are given with more than one source file and ignores the
183
.B \-o
184
option.
185
.TP
186
.BI \-D name=def
187
Define the
188
.I name
189
to the preprocessor, as if by `#define'.
190
If
191
.I =def
192
is omitted, the name is defined as "1".
193
.TP
194
.BI \-U name
195
Remove any initial definition of
196
.IR name .
197
.TP
198
.BI \-I dir
199
`#include' files
200
whose names do not begin with `/' are always
201
sought first in the directory of the
202
.I file
203
arguments, then in directories named in
204
.B \-I
205
options, then in directories on a standard list.
206
.TP
207
.B \-N
208
Do not search
209
.I any
210
of the standard directories for `#include' files.
211
Only those directories specified by subsequent explicit
212
.B \-I
213
options will be searched, in the order given.
214
.TP
215
.BI \-B str
216
Use the compiler
217
.BI "" str rcc
218
instead of the default version.
219
Note that
220
.I str
221
often requires a trailing slash.
222
On Sparcs only,
223
.B \-Bstatic
224
and
225
.BI \-Bdynamic
226
are passed to the loader; see
227
.IR ld (1).
228
.TP
229
.BI \-Wo\-lccdir= dir
230
Find the preprocessor, compiler proper, and include directory
231
in the directory
232
.I dir/
233
or
234
.I
235
dir\\.
236
If the environment variable
237
.B LCCDIR
238
is defined, it gives this directory.
239
.I lcc
240
warns when this option is unsupported.
241
.TP
242
.B \-Wf-unsigned_char=1
243
.br
244
.ns
245
.TP
246
.B \-Wf-unsigned_char=0
247
makes plain
248
.B char
249
an unsigned (1) or signed (0) type; by default,
250
.B char
251
is signed.
252
.TP
253
.B \-Wf\-wchar_t=unsigned_char
254
.br
255
.ns
256
.TP
257
.B \-Wf\-wchar_t=unsigned_short
258
.br
259
.ns
260
.TP
261
.B \-Wf\-wchar_t=unsigned_int
262
Makes wide characters the type indicated; by default,
263
wide characters are unsigned short ints, and
264
.B wchar_t
265
is a typedef for unsigned short defined in stddef.h.
266
The definition for
267
.B wchar_t
268
in stddef.h must correspond to the type specified.
269
.TP
270
.B \-v
271
Print commands as they are executed; some of the executed
272
programs are directed to print their version numbers.
273
More than one occurrence of
274
.B \-v
275
causes the commands to be printed, but
276
.I not
277
executed.
278
.TP
279
.BR \-help " or " \-?
280
Print a message on the standard error summarizing
281
.IR lcc 's
282
options and giving the values of the environment variables
283
.B LCCINPUTS
284
and
285
.BR LCCDIR ,
286
if they are defined.
287
Under Windows, the values of
288
.B include
289
and
290
.B lib
291
are also given, if they are defined.
292
.TP
293
.B \-b
294
Produce code that counts the number of times each expression is executed.
295
If loading takes place, arrange for a
296
.B prof.out
297
file to be written when the object program terminates.
298
A listing annotated with execution counts can then be generated with
299
.IR bprint (1).
300
.I lcc
301
warns when
302
.B \-b
303
is unsupported.
304
.B \-Wf\-C
305
is similar, but counts only the number of function calls.
306
.TP
307
.B \-p
308
Produce code that counts the number of times each function is called.
309
If loading takes place, replace the standard startup
310
function by one that automatically calls
311
.IR monitor (3)
312
at the start and arranges to write a
313
.B mon.out
314
file when the object program terminates normally.
315
An execution profile can then be generated with
316
.IR prof (1).
317
.I lcc
318
warns when
319
.B \-p
320
is unsupported.
321
.TP
322
.B \-pg
323
Causes the compiler to produce counting code like
324
.BR \-p ,
325
but invokes a run-time recording mechanism that keeps more
326
extensive statistics and produces a
327
.B gmon.out
328
file at normal termination.
329
Also, a profiling library is searched, in lieu of the standard C library.
330
An execution profile can then be generated with
331
.IR gprof (1).
332
.I lcc
333
warns when
334
.B \-pg
335
is unsupported.
336
.TP
337
.BI \-t name
338
.br
339
.ns
340
.TP
341
.BI \-t
342
Produce code to print the name of the function, an activation number,
343
and the name and value of each argument at function entry.
344
At function exit, produce code to print
345
the name of the function, the activation number, and the return value.
346
By default,
347
.I printf
348
does the printing; if
349
.I name
350
appears, it does.
351
For null
352
.I char*
353
values, "(null)" is printed.
354
.BI \-target
355
.I name
356
is accepted, but ignored.
357
.TP
358
.BI \-tempdir= dir
359
Store temporary files in the directory
360
.I dir/
361
or
362
.I
363
dir\\.
364
The default is usually
365
.BR /tmp .
366
.TP
367
.BI \-W xarg
368
pass argument
369
.I arg
370
to the program indicated by
371
.IR x ;
372
.I x
373
can be one of
374
.BR p ,
375
.BR f ,
376
.BR a ,
377
or
378
.BR l ,
379
which refer, respectively, to the preprocessor, the compiler proper,
380
the assembler, and the loader.
381
.I arg
382
is passed as given; if a
383
.B \-
384
is expected, it must be given explicitly.
385
.BI \-Wo arg
386
specifies a system-specific option,
387
.IR arg .
388
.PP
389
Other arguments
390
are taken to be either loader option arguments, or C-compatible
391
object programs, typically produced by an earlier
392
.I lcc
393
run, or perhaps libraries of C-compatible routines.
394
Duplicate object files are ignored.
395
These programs, together with the results of any
396
compilations specified, are loaded (in the order
397
given) to produce an executable program with name
398
.BR a.out
399
(UNIX) or
400
.BR a.exe
401
(Windows).
402
.PP
403
.I lcc
404
assigns the most frequently referenced scalar parameters and
405
locals to registers whenever possible.
406
For each block,
407
explicit register declarations are obeyed first;
408
remaining registers are assigned to automatic locals if they
409
are `referenced' at least 3 times.
410
Each top-level occurrence of an identifier
411
counts as 1 reference. Occurrences in a loop,
412
either of the then/else arms of an if statement, or a case
413
in a switch statement each count, respectively, as 10, 1/2, or 1/10 references.
414
These values are adjusted accordingly for nested control structures.
415
.B \-Wf\-a
416
causes
417
.I lcc
418
to read a
419
.B prof.out
420
file from a previous execution and to use the data therein
421
to compute reference counts (see
422
.BR \-b ).
423
.PP
424
.I lcc
425
is a cross compiler;
426
.BI \-Wf\-target= target/os
427
causes
428
.I lcc
429
to generate code for
430
.I target
431
running the operating system denoted by
432
.IR os .
433
The supported
434
.I target/os
435
combinations may include
436
.PP
437
.RS
438
.ta \w'sparc/solarisxx'u
439
.nf
440
alpha/osf       ALPHA, OSF 3.2
441
mips/irix       big-endian MIPS, IRIX 5.2
442
mips/ultrix     little-endian MIPS, ULTRIX 4.3
443
sparc/solaris   SPARC, Solaris 2.3
444
x86/win32       x86, Windows NT 4.0/Windows 95/98
445
x86/linux       x86, Linux
446
symbolic        text rendition of the generated code
447
null            no output
448
.fi
449
.RE
450
.PP
451
For
452
.BR \-Wf\-target=symbolic ,
453
the option
454
.B \-Wf-html
455
causes the text rendition to be emitted as HTML.
456
.B
457
.SH LIMITATIONS
458
.PP
459
.I lcc
460
accepts the C programming language
461
as described in the ANSI standard.
462
If
463
.I lcc
464
is used with the GNU C preprocessor, the
465
.B \-Wp\-trigraphs
466
option is required to enable trigraph sequences.
467
.PP
468
Plain int bit fields are signed.
469
Bit fields are aligned like unsigned integers but are otherwise laid out
470
as by most standard C compilers.
471
Some compilers, such as the GNU C compiler,
472
may choose other, incompatible layouts.
473
.PP
474
Likewise, calling conventions are intended to be compatible with
475
the host C compiler,
476
except possibly for passing and returning structures.
477
Specifically,
478
.I lcc
479
passes and returns structures like host ANSI C compilers
480
on most targets, but some older host C compilers use different conventions.
481
Consequently, calls to/from such functions compiled with
482
older C compilers may not work.
483
Calling a function that returns
484
a structure without declaring it as such violates
485
the ANSI standard and may cause a fault.
486
.SH FILES
487
.PP
488
The file names listed below are
489
.IR typical ,
490
but vary among installations; installation-dependent variants
491
can be displayed by running
492
.I lcc
493
with the
494
.B \-v
495
option.
496
.PP
497
.RS
498
.ta \w'$LCCDIR/liblcc.{a,lib}XX'u
499
.nf
500
file.{c,C}      input file
501
file.{s,asm}    assembly-language file
502
file.{o,obj}    object file
503
a.{out,exe}     loaded output
504
/tmp/lcc*       temporary files
505
$LCCDIR/cpp     preprocessor
506
$LCCDIR/rcc     compiler
507
$LCCDIR/liblcc.{a,lib}  \fIlcc\fP-specific library
508
/lib/crt0.o     runtime startup (UNIX)
509
/lib/[gm]crt0.o startups for profiling (UNIX)
510
/lib/libc.a     standard library (UNIX)
511
$LCCDIR/include ANSI standard headers
512
/usr/local/include      local headers
513
/usr/include    traditional headers
514
prof.out        file produced for \fIbprint\fR(1)
515
mon.out file produced for \fIprof\fR(1)
516
gmon.out        file produced for \fIgprof\fR(1)
517
.fi
518
.RE
519
.PP
520
.I lcc
521
predefines the macro
522
.B __LCC__
523
on all systems.
524
It may also predefine some installation-dependent symbols; option
525
.B \-v
526
exposes them.
527
.SH "SEE ALSO"
528
.PP
529
C. W. Fraser and D. R. Hanson,
530
.I A Retargetable C Compiler: Design and Implementation,
531
Addison-Wesley, 1995. ISBN 0-8053-1670-1.
532
.PP
533
The World-Wide Web page at http://www.cs.princeton.edu/software/lcc/.
534
.PP
535
S. P. Harbison and G. L. Steele, Jr.,
536
.I C: A Reference Manual,
537
4th ed., Prentice-Hall, 1995.
538
.PP
539
B. W. Kernighan and D. M. Ritchie,
540
.I The C Programming Language,
541
2nd ed., Prentice-Hall, 1988.
542
.PP
543
American National Standards Inst.,
544
.I American National Standard for Information Systems\(emProgramming
545
.IR Language\(emC ,
546
ANSI X3.159-1989, New York, 1990.
547
.br
548
.SH BUGS
549
Mail bug reports along with the shortest preprocessed program
550
that exposes them and the details reported by
551
.IR lcc 's
552
.B \-v
553
option to lcc-bugs@princeton.edu. The WWW page at
554
URL http://www.cs.princeton.edu/software/lcc/
555
includes detailed instructions for reporting bugs.
556
.PP
557
The ANSI standard headers conform to the specifications in
558
the Standard, which may be too restrictive for some applications,
559
but necessary for portability.
560
Functions given in the ANSI headers may be missing from
561
some local C libraries (e.g., wide-character functions)
562
or may not correspond exactly to the local versions;
563
for example, the ANSI standard
564
stdio.h
565
specifies that
566
.IR printf ,
567
.IR fprintf ,
568
and
569
.I sprintf
570
return the number of characters written to the file or array,
571
but some existing libraries don't implement this convention.
572
.PP
573
On the MIPS and SPARC, old-style variadic functions must use
574
varargs.h
575
from MIPS or Sun. New-style is recommended.
576
.PP
577
With
578
.BR \-b ,
579
files compiled
580
.I without
581
.B \-b
582
may cause
583
.I bprint
584
to print erroneous call graphs.
585
For example, if
586
.B f
587
calls
588
.B g
589
calls
590
.B h
591
and
592
.B f
593
and
594
.B h
595
are compiled with
596
.BR \-b ,
597
but
598
.B g
599
is not,
600
.B bprint
601
will report that
602
.B f
603
called
604
.BR h .
605
The total number of calls is correct, however.

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.