Missing documentation

Missing documentation

[Mark Mitchell]

Gentlemen --

  PR761 refers to various undocumented compiler options.  Those of you
on the CC list are there because you either seem to have written some
of the code in question, maintain that portion of the compiler, or
seem knowledgable.

  Surely you want people do know that your labors have born fruit in
the form of compiler options!  Here are the ones that need invoke.texi
documentation, along with names for people who seem like good
candidates to add the missing information.  All invoke.texi patches
you might make as a result of this mail are preapproved.

  ???
  
     -fbounded-pointers
     -fbounds-check

     Do these actually work?  If not, we should just remove the
     options for GCC 3.0.  Does anyone know?

  Alexandre:

     -print-multi-lib
     -print-multi-directory
     -aux-info

  Bernd:

     -fsched-verbose
     -fsched-interblock
     -fsched-spec
     -fsched-spec-load
     -fsched-spec-load-dangerous
     -fbranch-count-reg

  Richard:

     -fnon-call-exceptions
     -fpeephole2

  Zack, Neil:

     -fpreprocessed
 
  Jason E.:

     -freorder-blocks

  Jason M.: 

     -feliminate-dwarf2-dups

--
Mark Mitchell                   mark@codesourcery.com
CodeSourcery, LLC               http://www.codesourcery.com

Re: Missing documentation

[Toon Moene]

Mark Mitchell wrote:

>   PR761 refers to various undocumented compiler options.

>      -fbounded-pointers
>      -fbounds-check

I recall a discussion in '99 (i.e., before the 2.95 release) that it
would be a good idea to get uniformity in "bounds checking options". 
The reason discussing this at that time was that Craig Burley just
finished the implementation of array bound checking in Fortran, and it
would be there in the 2.95 series.

So for other languages they are probably doing nothing *at the moment*
but act as a sort of reserved keywords.

Hope this helps (I can try to find this discussion on the mailing list
archives if there's interest).

-- 
Toon Moene - mailto:toon@moene.indiv.nluug.nl - phoneto: +31 346 214290
Saturnushof 14, 3738 XG  Maartensdijk, The Netherlands
Maintainer, GNU Fortran 77: http://gcc.gnu.org/onlinedocs/g77_news.html
Join GNU Fortran 95: http://g95.sourceforge.net/ (under construction)

Re: Missing documentation

[Robert Bernecky]

The -fbounded-pointers and -fbounds-check options
were introduced by Greg McGary
(See http://gcc.gnu.org/projects/bp/main.html );
I have taken over that work as the Secure Pointers
Project, at John Gilmore's request,
but it is certainly not ready for prime time,
as I'm still fighting glibc wars at present, to the tune
of about 100 outstanding "make check" errors, which I suspect
are largely due to problems with recent improvements to
locale support in glibc.

I'd suggest removing the options from GCC 3.0.
Greg's and John's opinions should drive this decision.

Bob

On Sat, 9 Jun 2001, Mark
Mitchell wrote:

> Date: Sat, 09 Jun 2001 12:54:43 -0700
> From: Mark Mitchell <mark@codesourcery.com>
> To: gcc@gcc.gnu.org
> Cc: Jason Eckhardt <jle@cygnus.com>, Bernd Schmidt <bernds@cygnus.co.uk>,
>      Jason Merrill <jason@cygnus.com>, Alexandre Oliva <aoliva@cygnus.com>,
>      Richard Henderson <rth@cygnus.com>, Zack Weinberg <weinberg@cygnus.com>,
>      Neil Booth <neil@daikokuya.demon.co.uk>
> Subject: Missing documentation
>
>
> Gentlemen --
>
>   PR761 refers to various undocumented compiler options.  Those of you
> on the CC list are there because you either seem to have written some
> of the code in question, maintain that portion of the compiler, or
> seem knowledgable.
>
>   Surely you want people do know that your labors have born fruit in
> the form of compiler options!  Here are the ones that need invoke.texi
> documentation, along with names for people who seem like good
> candidates to add the missing information.  All invoke.texi patches
> you might make as a result of this mail are preapproved.
>
>   ???
>
>      -fbounded-pointers
>      -fbounds-check
>
>      Do these actually work?  If not, we should just remove the
>      options for GCC 3.0.  Does anyone know?
>
>   Alexandre:
>
>      -print-multi-lib
>      -print-multi-directory
>      -aux-info
>
>   Bernd:
>
>      -fsched-verbose
>      -fsched-interblock
>      -fsched-spec
>      -fsched-spec-load
>      -fsched-spec-load-dangerous
>      -fbranch-count-reg
>
>   Richard:
>
>      -fnon-call-exceptions
>      -fpeephole2
>
>   Zack, Neil:
>
>      -fpreprocessed
>
>   Jason E.:
>
>      -freorder-blocks
>
>   Jason M.:
>
>      -feliminate-dwarf2-dups
>
> --
> Mark Mitchell                   mark@codesourcery.com
> CodeSourcery, LLC               http://www.codesourcery.com
>

Robert Bernecky                  Snake Island Research Inc.
bernecky@acm.org                 18 Fifth Street, Ward's Island
+1 416 203 0854                  Toronto, Ontario M5J 2B9 Canada
http://www.snakeisland.com

Re: Missing documentation

[Zack Weinberg]

On Sat, Jun 09, 2001 at 12:54:43PM -0700, Mark Mitchell wrote:

[undocumented options: ...]
>
>      -print-multi-lib
>      -print-multi-directory

I believe these are only used for arcane purposes during the build of
GCC itself.  That doesn't mean they shouldn't be documented, but
perhaps invoke.texi is not the best place.

I could of course be mistaken about this.

>      -aux-info

This dumps information about function prototypes to a file argument.
I believe its primary use is while setting up fixproto.  It could be
useful outside GCC, but the format of the output should be documented
as well as the option itself.

I think it's C specific.

>      -fpreprocessed

This is for internal use, mostly; the driver passes it to cc1 when
it's fed an .i file.  It'll be mentioned in cpp.texi after I check in
the rewrite (today, I hope).  Should it also appear in invoke.texi?

-- 
zw   The beginning of almost every story is actually a bone, something with
     which to court the dog, which may bring you closer to the lady.
     	-- Amos Oz, _The Story Begins_

Re: Missing documentation

[Mark Mitchell]

>>>>> "Zack" == Zack Weinberg <zackw@stanford.edu> writes:

    >>  -print-multi-lib -print-multi-directory

    Zack> I believe these are only used for arcane purposes during the
    Zack> build of GCC itself.  That doesn't mean they shouldn't be
    Zack> documented, but perhaps invoke.texi is not the best place.

I agree -- but our current policy is to document all options in
invoke.texi.  We all agree that we eventually want to separate the
manual into user documentation and maintainer documentation, and some
of these options should probably move at that point.  (And, in fact,
when build for production use the options should maybe just not be
present in the compiler at all.)

So, for now, if you're willing to add information to invoke.texi about
any of the options you mentioned, that would be great.

    >> -fpreprocessed

    Zack> This is for internal use, mostly; the driver passes it to
    Zack> cc1 when it's fed an .i file.  It'll be mentioned in
    Zack> cpp.texi after I check in the rewrite (today, I hope).
    Zack> Should it also appear in invoke.texi?

Yes, please -- but you can make it just be a cross-reference if you
want, like:

  Users should not have to use this option; it is for internal use
  only.  For more information, see <link to cpp.texi>.

Thanks!

--
Mark Mitchell                   mark@codesourcery.com
CodeSourcery, LLC               http://www.codesourcery.com

Re: Missing documentation

[Alexandre Oliva]

On Jun  9, 2001, Mark Mitchell <mark@codesourcery.com> wrote:

> So, for now, if you're willing to add information to invoke.texi about
> any of the options you mentioned, that would be great.

Don't worry about these, my patch to add them is almost finished.

-- 
Alexandre Oliva   Enjoy Guarana', see http://www.ic.unicamp.br/~oliva/
Red Hat GCC Developer                  aoliva@{cygnus.com, redhat.com}
CS PhD student at IC-Unicamp        oliva@{lsd.ic.unicamp.br, gnu.org}
Free Software Evangelist    *Please* write to mailing lists, not to me

Re: Missing documentation

[Alexandre Oliva]

On Jun  9, 2001, Mark Mitchell <mark@codesourcery.com> wrote:

>   Alexandre:

>      -print-multi-lib
>      -print-multi-directory
>      -aux-info

Documented as follows.

I didn't know about -aux-info, and ended up finding a bug in its
implementation.  -aux-info=foo.X would create =foo.X, not foo.X as one
would expect.  -aux-info foo.X worked correctly.  I went ahead and
fixed this inconsistency.  Ok for branch and mainline?  Tested on
i686-pc-linux-gnu.

Re: Missing documentation

[Neil Booth]

Zack Weinberg wrote:-

> >      -fpreprocessed
> 
> This is for internal use, mostly; the driver passes it to cc1 when
> it's fed an .i file.  It'll be mentioned in cpp.texi after I check in
> the rewrite (today, I hope).  Should it also appear in invoke.texi?

Zack,

I've got it covered for cppinit.c and invoke.texi (I'll post the patch
now).  You handle it in your rewritten cpp.texi.

Neil.

Re: Missing documentation

[Zack Weinberg]

On Sat, Jun 09, 2001 at 07:25:15PM -0300, Alexandre Oliva wrote:
> On Jun  9, 2001, Mark Mitchell <mark@codesourcery.com> wrote:
> 
> >   Alexandre:
> 
> >      -print-multi-lib
> >      -print-multi-directory
> >      -aux-info
> 
> Documented as follows.

...
> +@item -aux-info @var{filename}
> +@opindex aux-info
> +Output to the given filename declarations for all functions declared
> +and/or defined in a translation unit, including those in header files.
> +This option is silently ignored in any languages other than C.

Grammar nit: 'language other than C' not 'languages ...'

I think there should be more documentation of the format than just
"declarations".  It looks like this:

/* /usr/include/stdio.h:275:NC */ extern int printf (const char *, ...);

You should at least mention that it prefixes each one with a comment
giving the file and line of the declaration.  The code letters after
the line number should also be documented, but this is less important.

- from c-aux-info.c, it seems that the first letter may be 'I' 'N' or
  'O' corresponding to implicit, new (prototyped), and old
  (unprototyped) decl/defn respectively.  The second letter may be 'C'
  or 'F' corresponding to declaration and definition respectively.

  oh, and for function definitions, it appends a comment to the line
  giving an old-style function header for the definition, e.g.

/* dtoa.c:10:NF */ static char *dtoa_c (char *buf, t_uint32 n); 
				/* (buf, n) char *buf; t_uint32 n; */

  all on one line in the original.

You should also mention that this is used during the GCC build, and by
(un)protoize.

zw

Re: Missing documentation

[Neil Booth]

This documents -fpreprocessed (and removes an unnecessary comment
about trigraphs being brain-damaged.  I can't argue with that, but
I don't think it belongs in the manual).

I'll commit to both trees.

Neil.

	* cppinit.c (print_help): Document -fpreprocessed.
	* invoke.texi: Similarly.

Index: cppinit.c
===================================================================
RCS file: /cvs/gcc/gcc/gcc/cppinit.c,v
retrieving revision 1.159
diff -u -p -r1.159 cppinit.c
--- cppinit.c	2001/05/20 06:26:33	1.159
+++ cppinit.c	2001/06/09 22:43:09
@@ -1885,6 +1885,7 @@ Switches:\n\
   -dI                       Include #include directives in the output\n\
 "), stdout);
   fputs (_("\
+  -fpreprocessed            Treat the input file as already preprocessed\n\
   -ftabstop=<number>        Distance between tab stops for column reporting\n\
   -P                        Do not generate #line directives\n\
   -$                        Do not allow '$' in identifiers\n\
Index: doc/invoke.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/invoke.texi,v
retrieving revision 1.5
diff -u -p -r1.5 invoke.texi
--- invoke.texi	2001/06/09 13:32:45	1.5
+++ invoke.texi	2001/06/09 22:43:37
@@ -1023,9 +1023,8 @@ freestanding and hosted environments.
 
 @item -trigraphs
 @opindex trigraphs
-Support ISO C trigraphs.  You don't want to know about this
-brain-damage.  The @option{-ansi} option (and @option{-std} options for
-strict ISO C conformance) implies @option{-trigraphs}.
+Support ISO C trigraphs.  The @option{-ansi} option (and @option{-std}
+options for strict ISO C conformance) implies @option{-trigraphs}.
 
 @cindex traditional C language
 @cindex C language, traditional
@@ -4015,6 +4014,18 @@ Only @samp{#define @var{name}} is includ
 @opindex dI
 Output @samp{#include} directives in addition to the result of
 preprocessing.
+
+@item -fpreprocessed
+@opindex fpreprocessed
+Indicate to the preprocessor that the input file has already been
+preprocessed.  This suppresses things like macro expansion, trigraph
+conversion, escaped newline splicing, and processing of most directives.
+In this mode the integrated preprocessor is little more than a tokenizer
+for the front ends.
+
+@samp{-fpreprocessed} is implicit if the input file has one of the
+extensions @samp{i}, @samp{ii} or @samp{mi} indicating it has already
+been preprocessed.
 
 @item -trigraphs
 @opindex trigraphs

Re: Missing documentation

[Mark Mitchell]

>>>>> "Alexandre" == Alexandre Oliva <aoliva@redhat.com> writes:

    Alexandre> On Jun 9, 2001, Mark Mitchell <mark@codesourcery.com>
    Alexandre> wrote:

    >> So, for now, if you're willing to add information to
    >> invoke.texi about any of the options you mentioned, that would
    >> be great.

    Alexandre> Don't worry about these, my patch to add them is almost
    Alexandre> finished.

Great.

--
Mark Mitchell                   mark@codesourcery.com
CodeSourcery, LLC               http://www.codesourcery.com

Re: Missing documentation

[Mark Mitchell]

>>>>> "Alexandre" == Alexandre Oliva <aoliva@redhat.com> writes:

    Alexandre> unit, including those in header files.  +This option is
    Alexandre> silently ignored in any languages other than C.  +

s/languages/language

Otherwise, OK -- and thanks!  Please update the PR to indicate that
you've fixed these entries.

--
Mark Mitchell                   mark@codesourcery.com
CodeSourcery, LLC               http://www.codesourcery.com

Re: Missing documentation

[Mark Mitchell]

>>>>> "Neil" == Neil Booth <neil@daikokuya.demon.co.uk> writes:

    Neil> This documents -fpreprocessed (and removes an unnecessary
    Neil> comment about trigraphs being brain-damaged.  I can't argue
    Neil> with that, but I don't think it belongs in the manual).

The manual is definitely not a soapbox.

Thank you.

--
Mark Mitchell                   mark@codesourcery.com
CodeSourcery, LLC               http://www.codesourcery.com

Re: Missing documentation

[Alexandre Oliva]

On Jun  9, 2001, Mark Mitchell <mark@codesourcery.com> wrote:

>>>>>> "Alexandre" == Alexandre Oliva <aoliva@redhat.com> writes:
Alexandre> unit, including those in header files.  +This option is
Alexandre> silently ignored in any languages other than C.  +

> s/languages/language

Thanks.

> Otherwise, OK

The changes to toplev.c and gcc.c too?

-- 
Alexandre Oliva   Enjoy Guarana', see http://www.ic.unicamp.br/~oliva/
Red Hat GCC Developer                  aoliva@{cygnus.com, redhat.com}
CS PhD student at IC-Unicamp        oliva@{lsd.ic.unicamp.br, gnu.org}
Free Software Evangelist    *Please* write to mailing lists, not to me

Re: Missing documentation

[Alexandre Oliva]

On Jun  9, 2001, "Zack Weinberg" <zackw@stanford.edu> wrote:

> Grammar nit: 'language other than C' not 'languages ...'

Thanks.

> You should at least mention that it prefixes each one with a comment
> giving the file and line of the declaration.  The code letters after
> the line number should also be documented, but this is less important.

Thanks for the extra information.  How about this paragraph?

        Besides declarations, the file indicates, in comments, the
        origin of each declaration (source file and line), whether the
        declaration was implicit, prototyped or unprototyped
        (@samp{I}, @samp{N} for new or @samp{O} for old, respectively,
        in the first character after the line number and the colon),
        and whether it came from a declaration or a definition
        (@samp{C} or @samp{F}, respectively, in the following
        character).  In the case of function definitions, a K&R-style
        list of arguments followed by their declarations is also
        provided, inside comments, after the declaration.

> You should also mention that this is used during the GCC build, and by
> (un)protoize.

This is already covered elsewhere in the manual.

-- 
Alexandre Oliva   Enjoy Guarana', see http://www.ic.unicamp.br/~oliva/
Red Hat GCC Developer                  aoliva@{cygnus.com, redhat.com}
CS PhD student at IC-Unicamp        oliva@{lsd.ic.unicamp.br, gnu.org}
Free Software Evangelist    *Please* write to mailing lists, not to me

Re: Missing documentation

[Mark Mitchell]

>>>>> "Alexandre" == Alexandre Oliva <aoliva@redhat.com> writes:

    Alexandre> The changes to toplev.c and gcc.c too?

Yup.  Thanks!

--
Mark Mitchell                   mark@codesourcery.com
CodeSourcery, LLC               http://www.codesourcery.com

Re: Missing documentation

[Zack Weinberg]

On Sat, Jun 09, 2001 at 08:39:20PM -0300, Alexandre Oliva wrote:
> 
> Thanks for the extra information.  How about this paragraph?
> 
>         Besides declarations, the file indicates, in comments, the
>         origin of each declaration (source file and line), whether the
>         declaration was implicit, prototyped or unprototyped
>         (@samp{I}, @samp{N} for new or @samp{O} for old, respectively,
>         in the first character after the line number and the colon),
>         and whether it came from a declaration or a definition
>         (@samp{C} or @samp{F}, respectively, in the following
>         character).  In the case of function definitions, a K&R-style
>         list of arguments followed by their declarations is also
>         provided, inside comments, after the declaration.

That looks good.  An example would be helpful:

int foo(int bar) {}
-->
/* file.c:1:NF */ extern int foo (int bar); /* (bar) int bar; */

> > You should also mention that this is used during the GCC build, and by
> > (un)protoize.
> 
> This is already covered elsewhere in the manual.

Didn't know that.  Okay.

-- 
zw    If punishments don't compensate the victims and don't prevent future
      crimes they seem to me to be indistinguishable from random acts of
      sadism.
      	-- Bernard Peek

Re: Missing documentation

[Robert Bernecky]

Re -fbounded-pointers and -fcheck-bounds options:

Contrary to a message I sent earlier, the GCC code is
actually in fairly good shape ( I still think of GCC and GLIBC
as coming in the same box... Sorry.), so here is some
documentation on the options:

The -fbounded-pointers option tells GCC to make pointers
"secure". A "secure" pointer is a triple, containing
the pointer value, as well as the upper and lower bounds
of the memory referred to by the pointer.
This option implies -fcheck-bounds.

The -fcheck-bounds options tells GCC to
emit bounds checking code for the purpose of improved
security. You can turn checking off
explicitly to get secure-pointer interfaces
without having runtime bounds checks.
This could be used for partitioning the debugging task, or for
assessing the performance impact of secure-pointer handling in
isolation from that of runtime checks.

A bounds check is an assertion that, for a secure pointer with
value V, lower bound L, and upper bound H:

   (V >= L) && (V < H)

Both options remain experimental at this date, in the sense that
if you enable them, you'll most likely end up with a non-working
program, as I'm still cleaning up glibc.

The above text is adapted from email I received from
Greg McGary <greg@mcgary.org>, who is the original author of this
work.

Bob

Robert Bernecky                  Snake Island Research Inc.
bernecky@acm.org                 18 Fifth Street, Ward's Island
+1 416 203 0854                  Toronto, Ontario M5J 2B9 Canada
http://www.snakeisland.com

Re: Missing documentation

[Greg McGary]

Robert Bernecky <bernecky@acm.org> writes:

> Contrary to a message I sent earlier, the GCC code is
> actually in fairly good shape

The bounds checking code for GCC is only on the branch
`bounded-pointers-branch', and not in the mainline or any release
branch.  Any vestiges should be removed from 3.0. There isn't much.

Greg

Re: Missing documentation

[Phil Edwards]

On Sat, Jun 09, 2001 at 04:21:26PM -0700, Mark Mitchell wrote:
> >>>>> "Neil" == Neil Booth <neil@daikokuya.demon.co.uk> writes:
> 
>     Neil> This documents -fpreprocessed (and removes an unnecessary
>     Neil> comment about trigraphs being brain-damaged.  I can't argue
>     Neil> with that, but I don't think it belongs in the manual).
> 
> The manual is definitely not a soapbox.

Then we can throw out that annoying "Linux and the GNU Project" chapter?


Phil

-- 
pedwards at disaster dot jaj dot com  |  pme at sources dot redhat dot com
devphil at several other less interesting addresses in various dot domains
The gods do not protect fools.  Fools are protected by more capable fools.

Re: Missing documentation

[Mark Mitchell]

--On Monday, June 11, 2001 06:34:11 AM -0400 Phil Edwards 
<pedwards@disaster.jaj.com> wrote:

> On Sat, Jun 09, 2001 at 04:21:26PM -0700, Mark Mitchell wrote:
>> >>>>> "Neil" == Neil Booth <neil@daikokuya.demon.co.uk> writes:
>>
>>     Neil> This documents -fpreprocessed (and removes an unnecessary
>>     Neil> comment about trigraphs being brain-damaged.  I can't argue
>>     Neil> with that, but I don't think it belongs in the manual).
>>
>> The manual is definitely not a soapbox.
>
> Then we can throw out that annoying "Linux and the GNU Project" chapter?
>

I guess I should say "most of the manual is not a
soapbox".  The FSF definitely considers the manual a reasonable place
to make its views and objectives known.  I think it's OK to talk about
the GNU Project in the manual -- but editorializing on compiler switches
is pretty extreme.

--
Mark Mitchell                   mark@codesourcery.com
CodeSourcery, LLC               http://www.codesourcery.com

Re: Missing documentation

[Jason Merrill]

>>>>> "Mark" == Mark Mitchell <mark@codesourcery.com> writes:

>   Surely you want people do know that your labors have born fruit in
> the form of compiler options!

>      -feliminate-dwarf2-dups

No.  :)

I haven't had time to worry about making this work properly, so I suppose
it should be removed from 3.0.

Jason

Re: Missing documentation

[Joseph S. Myers]

On 11 Jun 2001, Jason Merrill wrote:

> >      -feliminate-dwarf2-dups
> 
> No.  :)
> 
> I haven't had time to worry about making this work properly, so I suppose
> it should be removed from 3.0.

Note that where options are removed on the branch but left on the
mainline, the PR should be left open but downgraded once all the options
left on the branch have been documented.

-- 
Joseph S. Myers
jsm28@cam.ac.uk