From mboxrd@z Thu Jan  1 00:00:00 1970
From: Per Bothner <bothner@cygnus.com>
To: egcs@cygnus.com
Subject: Re: prototyping
Date: Sun, 17 Aug 1997 17:52:11 -0000
Message-id: <199708171751.KAA20069@cygnus.com>
In-reply-to: prototyping
X-SW-Source: 1997-08/0039.html

> One of the things we should be doing -- switching to cpplib across
> the board instead of for just the fixing of header files.
> 
> Per, are there any technical reasons why we can't start this soon?

There is no particular reason why we cannot switch from cpp compiled
from cccp.c to one compiled from cpplib.c+cpplib.c.  Just change
CCCP=ccccp to CCCP=cppmain in the Makefile.  However, there are
years of changes to cccp made after cpplib was forked off that have
not been merged into cpplib.  It would great if we could have a volunteer
go through the RCS files for cccp.c and cexp.y, evaluate the changes,
and integrate them into cpplib.c and cppexp.c.  In the case of changes
where it is non-obvious how to make them in cpplib, I'd be happy to
advice or even write the changes.  What I do not have time for is
the tedious task of sifting through the changes, making the easy
patches, and flagging the difficult ones.

There are a few unimplemented features in cpplib.c that are needed before
it can be the default (of a production gcc).  See the TODO list at the
end of cpplib.c.  The most tricky is trigraphs - and maybe also digraphs.

Of course the big pay-off from cpplib is when it is integrated into the
lexers for languages that use it.  The most obvious win is faster
compile times.  Another potential advantage is error messages and debug
information that contain column numbers as well as line numbers.  (This
is impractical with a separate cpp, because you don't know how column
positions were adjusted by comments and macros.)  If you try cppmain
with a macro with the wrong number of arguments, you will see that the
error message contains the column number as well a the line number.

I've made most of the necessary changes to the C and ObjC lexer
(controlled by USE_CPPLIB), but have not done anything with C++.
The main thing still missing is that the gcc.c specs must be modified to
not invoke cpp, and to pass the cpp command-line arguments (such
as -I and -D) to cc1 and cc1plus.  And then toplev.c must be modified
to pass those flags to the language front-end (specifically the lexer).
So we need an API to do that.  Of course this opens the door for
arbitrary front-end specific flags, which RMS does not want.

I wrote a *teeny* bit of docuemntation that is not checked in,
including a very short cpplib.texi, appended below.

	--Per Bothner
Cygnus Solutions     bothner@cygnus.com     http://www.cygnus.com/~bothner

\input texinfo.tex      @c -*-texinfo-*-
@c %**start of header
@setfilename cpplib.info
@settitle The GNU C Pre-Processor Library
@setchapternewpage off
@c %**end of header

@iftex
@finalout
@end iftex
@titlepage
@title The CPP Library
@end titlepage

@ifinfo
@node Top, , (dir), (dir)
@top
@end ifinfo

@menu
* Output Buffer::  The Output Buffer
@end menu

@node Output Buffer
@chapter The Output Buffer

A cpp_reader contains an output buffer.  Each calls to cpp_get_token
appends the resulting text to the output buffer.  The output buffer
is also used for many purposes internally in cpplib.

@deffn Macro CPP_OUT_BUFFER (cppfile)
Returns the beginning of the output buffer (as an (unsigned char*)).
@end deffn

@deffn Macro CPP_WRITTEN (cppfile)
Returns the number of characters in @var{cppfile}'s output buffer.
@end deffn

@deffn Macro CPP_PWRITTEN (cppfile)
A pointer to the next available (unused) character in @var{cppfile}'s
output buffer.
Same as CPP_OUT_BUFFER(@var{cppfile})+CPP_WRITTEN(@var{cppfile}).
@end deffn

@deffn Macro CPP_RESERVE (cppfile, n)
Make sure the output buffer has room for at least @var{n} more characters
(beyond @code{CPP_PWRITTEN(@var{cppfile})}).
This will re-allocate the output buffer if needed.
@end deffn

The following functions append a character or a string to the output
buffer.  CPP_WRITTEN gets increased by the number of characters appended.
The macros ending in _Q do not test that there is sufficient space.
The other macros calls CPP_RESERVE to make sure there is enough space.

@deffn Macro CPP_PUTC (cppfile, ch)
Append character @var{CH} to the output buffer,
making sure there is enough space available in the output buffer.
@end deffn


@deffn Macro CPP_PUTC_Q (cppfile, ch)
Append character @var{CH} to the output buffer.
Assumes there is enough space available.
@end deffn

@deffn Macro CPP_PUTS (cppfile, str, n)
Append the string @var{str} (whose length is @var{n}) to the output buffer,
making sure there is enough space.
@end deffn

@deffn Macro CPP_PUTS_Q (cppfile, str, n)
Append the string @var{str} (whose length is @var{n}) to the output buffer.
Assumes there is enough space available.
@end deffn

The next two functions write a '\0' at the current write position,
but do not adjust CPP_WRITTEN.  This is useful if you want to
pass CPP_OUT_BUFFER to a function that expects a nul-terminated string.

@deffn Macro CPP_NUL_TERMINATE_Q (cppfile)
Same as CPP_RESERVE(@var{cppfile}, 1) followed by
CPP_PWRITTEN(@var{cppfile})='\0'.
@end deffn

@deffn Macro CPP_NUL_TERMINATE_Q (cppfile)
Same as CPP_PWRITTEN(@var{cppfile})='\0'.
Assumes there is space available for the '\0'.
@end deffn

The next two macros are commonly used to truncate the output buffer
or "pop off" text from its end.

@deffn Macro CPP_SET_WRITTEN (cppfile, length)
Set CPP_WRITTEN (@var{cppfile}) to @var{length}.
@end deffn

@deffn Macro CPP_ADJUST_WRITTEN (cppfile, delta)
Adds @var{length} to CPP_WRITTEN (@var{cppfile}).
Usually, @var{length} is negative, but it need not be, as long
as you have reserved enough space.
@end deffn

@bye