clang manual page?

Discussion:

clang manual page?

(too old to reply)

Steve Kargl

2018-04-05 22:38:52 UTC

Is anyone working on fixing the clang manual to actually
document the available options?

% man clang
(search for -std=)
-std=<language>
Specify the language standard to compile for.

OK, what does <language> mean?

--
Steve

Ian Lepore

2018-04-05 23:30:35 UTC

Permalink

clang --help has more info than the manpage, but it's still light on
details.

-- Ian

Steve Kargl

2018-04-06 00:15:14 UTC

Permalink

This assumes that a gcc(1) is available on the system.

% man gcc
No manual entry for gcc

If the system compiler is clang/clang++, then it ought to be
documented better than it currently is. Ian's suggests for
'clang --help' is even worse

% clang --help | grep -- -std
-cl-std=<value> OpenCL language standard to compile for.
-std=<value> Language standard to compile for
-stdlib=<value> C++ standard library to use

Does <value> == <language>?
--
steve

To a first order approximation, the manual page for clang is gcc(1).
Conrad
On Thu, Apr 5, 2018 at 3:38 PM, Steve Kargl

Post by Steve Kargl
Is anyone working on fixing the clang manual to actually
document the available options?
% man clang
(search for -std=)
-std=<language>
Specify the language standard to compile for.
OK, what does <language> mean?
--
Steve
_______________________________________________
https://lists.freebsd.org/mailman/listinfo/freebsd-current

--
Steve
20170425

20161221

Pete Wright

2018-04-06 00:30:04 UTC

Permalink

Post by Steve Kargl
This assumes that a gcc(1) is available on the system.
% man gcc
No manual entry for gcc
If the system compiler is clang/clang++, then it ought to be
documented better than it currently is. Ian's suggests for
'clang --help' is even worse
% clang --help | grep -- -std
-cl-std=<value> OpenCL language standard to compile for.
-std=<value> Language standard to compile for
-stdlib=<value> C++ standard library to use
Does <value> == <language>?

a quick google search turns up the following additional information:

"clang supports the -std option, which changes what language mode clang
uses. The supported modes for C are c89, gnu89, c99, gnu99, c11, gnu11,
c17, gnu17, and various aliases for those modes. If no -std option is
specified, clang defaults to gnu11 mode. Many C99 and C11 features are
supported in earlier modes as a conforming extension, with a warning.
Use |-pedantic-errors| to request an error if a feature from a later
standard revision is used in an earlier mode."

https://clang.llvm.org/docs/UsersManual.html

-p

--
Pete Wright
***@nomadlogic.org
@nomadlogicLA

Steve Kargl

2018-04-06 00:50:01 UTC

Permalink

Post by Pete Wright

"clang supports the -std option, which changes what language mode clang
uses. The supported modes for C are c89, gnu89, c99, gnu99, c11, gnu11,
c17, gnu17, and various aliases for those modes. If no -std option is
specified, clang defaults to gnu11 mode. Many C99 and C11 features are
supported in earlier modes as a conforming extension, with a warning.
Use |-pedantic-errors| to request an error if a feature from a later
standard revision is used in an earlier mode."
https://clang.llvm.org/docs/UsersManual.html

Yeah, I know how to use google. The above leaves out the clang++
-std=<language>, er, <value> values. One can guess at some of the
<value> from https://clang.llvm.org/cxx_status.html. There is no
mention of any of the gnu C++ <value>. I'll also note that the
above list does include -std=iso9899:1990, which clang appears to
accept (but does clang silently igonore the option like other GCC
options).

An option as fundamental as -std=<value> should be fully documented.
A user should not have to resort to the almighty google to use the tools
supplied by the system.

--
Steve

David Chisnall

2018-04-06 05:20:41 UTC

Permalink

"clang supports the -std option, which changes what language mode clang uses. The supported modes for C are c89, gnu89, c99, gnu99, c11, gnu11, c17, gnu17, and various aliases for those modes. If no -std option is specified, clang defaults to gnu11 mode. Many C99 and C11 features are supported in earlier modes as a conforming extension, with a warning. Use |-pedantic-errors| to request an error if a feature from a later standard revision is used in an earlier mode."
https://clang.llvm.org/docs/UsersManual.html

I believe that the clang user manual referenced here is written in Sphynx, which is able to generate mandoc output as well as HTML. Perhaps we should incorporate the generated file in the next import?

David

Steve Kargl

2018-04-06 06:22:20 UTC

Permalink

Post by David Chisnall

"clang supports the -std option, which changes what language mode clang uses. The supported modes for C are c89, gnu89, c99, gnu99, c11, gnu11, c17, gnu17, and various aliases for those modes. If no -std option is specified, clang defaults to gnu11 mode. Many C99 and C11 features are supported in earlier modes as a conforming extension, with a warning. Use |-pedantic-errors| to request an error if a feature from a later standard revision is used in an earlier mode."
https://clang.llvm.org/docs/UsersManual.html

That would be a good start. But, after cruisng around the
clang webpages, there is no clear set of <value> for
-std=<value> in the User's manuals on the webpages. For
example, "clang -std=iso9899:1990" apparently is valid,
but google find no instances of this construct. A search
of clang.llvm.org does not find this construct. Surprising
doing something complete stupid give`

% cc -std=fubar -c a.c
error: invalid value 'fubar' in '-std=fubar'
note: use 'c89', 'c90', or 'iso9899:1990' for 'ISO C 1990' standard
note: use 'iso9899:199409' for 'ISO C 1990 with amendment 1' standard
note: use 'gnu89' or 'gnu90' for 'ISO C 1990 with GNU extensions' standard
note: use 'c99' or 'iso9899:1999' for 'ISO C 1999' standard
note: use 'gnu99' for 'ISO C 1999 with GNU extensions' standard
note: use 'c11' or 'iso9899:2011' for 'ISO C 2011' standard
note: use 'gnu11' for 'ISO C 2011 with GNU extensions' standard
note: use 'c17' or 'iso9899:2017' for 'ISO C 2017' standard
note: use 'gnu17' for 'ISO C 2017 with GNU extensions' standard

% clang++ -std=fubar a.cxx
error: invalid value 'fubar' in '-std=fubar'
note: use 'c++98' or 'c++03' for 'ISO C++ 1998 with amendments' standard
note: use 'gnu++98' or 'gnu++03' for 'ISO C++ 1998 with amendments and GNU
extensions' standard
note: use 'c++11' for 'ISO C++ 2011 with amendments' standard
note: use 'gnu++11' for 'ISO C++ 2011 with amendments and GNU extensions'
standard
note: use 'c++14' for 'ISO C++ 2014 with amendments' standard
note: use 'gnu++14' for 'ISO C++ 2014 with amendments and GNU extensions'
standard
note: use 'c++17' for 'ISO C++ 2017 with amendments' standard
note: use 'gnu++17' for 'ISO C++ 2017 with amendments and GNU extensions'
standard
note: use 'c++2a' for 'Working draft for ISO C++ 2020' standard
note: use 'gnu++2a' for 'Working draft for ISO C++ 2020 with GNU extensions'
standard

This information belongs in a manpage.

--
Steve

Dimitry Andric

2018-04-06 11:25:54 UTC

Permalink

Post by David Chisnall

"clang supports the -std option, which changes what language mode clang uses. The supported modes for C are c89, gnu89, c99, gnu99, c11, gnu11, c17, gnu17, and various aliases for those modes. If no -std option is specified, clang defaults to gnu11 mode. Many C99 and C11 features are supported in earlier modes as a conforming extension, with a warning. Use |-pedantic-errors| to request an error if a feature from a later standard revision is used in an earlier mode."
https://clang.llvm.org/docs/UsersManual.html

Yes, but that manual is also pretty much incomplete, so with the last
import I decided to stay with the older perl doc based one. Upstream
is pretty bad at writing detailed documentation, certainly in the form
of man pages.

With lld there wasn't even *any* form of command line documentation
yet, which is why Ed slapped together a man page (that could probably
still use more details). It should really be upstreamed, in Sphinx's
RST format, or since they appear to gravitate towards Markdown now,
maybe already in that format.

For a clang man page I'd really prefer working with upstream to get
some more details in there, like an exhaustive list of which -std=
options are supported. But it's quite a lot of effort.

-Dimitry

Steve Kargl

2018-04-06 18:39:42 UTC

Permalink

Post by Dimitry Andric
Yes, but that manual is also pretty much incomplete, so with the last
import I decided to stay with the older perl doc based one. Upstream
is pretty bad at writing detailed documentation, certainly in the form
of man pages.

Index: clang.1
===================================================================
--- clang.1 (revision 332114)
+++ clang.1 (working copy)
@@ -128,15 +128,72 @@
.UNINDENT
.INDENT 0.0
.TP
-.B \-std=<language>
-Specify the language standard to compile for.
+.B \-std=<value>
+Specify the language standard to enforce.
+
+A partial list of validate
+.B <value>
+for the C programming language is
+.INDENT 7.0
+.INDENT 3.5
+\fIc89\fP ISO/IEC 9899:1990
+.sp
+\fIc90\fP ISO/IEC 9899:1990
+.sp
+\fIc99\fP ISO/IEC 9899:1999
+.sp
+\fIc11\fP ISO/IEC 9899:2011
+.sp
+\fIc17\fP Working draft for ISO/EIC 9899:2017
+.sp
+\fIgnu89\fP ISO/IEC 9899:1990 with GNU extensions
+.sp
+\fIgnu90\fP ISO/IEC 9899:1990 with GNU extensions
+.sp
+\fIgnu99\fP ISO/IEC 9899:1999 with GNU extensions
+.sp
+\fIgnu11\fP ISO/IEC 9899:2011 with GNU extensions
+.sp
+\fIgnu17\fP Draft for ISO/EIC 9899:2017 with GNU extensions
.UNINDENT
+.UNINDENT
+
+A partial list of validate
+.B <value>
+for the C++ programming language is
+.INDENT 7.0
+.INDENT 3.5
+\fIc++98\fP ISO/IEC 14882:1998 with amendments
+.sp
+\fIc++03\fP ISO/IEC 14882:2003 with amendments
+.sp
+\fIc++11\fP ISO/IEC 14882:2011 with amendments
+.sp
+\fIc++14\fP ISO/IEC 14882:2014 with amendments
+.sp
+\fIc++17\fP ISO/IEC 14882:2017 with amendments
+.sp
+\fIc++2a\fP Draft ISO/IEC 14882:2020
+.sp
+\fIgnu++98\fP ISO/IEC 14882:1998 with amendments and GNU extensions
+.sp
+\fIgnu++03\fP ISO/IEC 14882:2003 with amendments and GNU extensions
+.sp
+\fIgnu++11\fP ISO/IEC 14882:2011 with amendments and GNU extensions
+.sp
+\fIgnu++14\fP ISO/IEC 14882:2014 with amendments and GNU extensions
+.sp
+\fIgnu++17\fP ISO/IEC 14882:2017 with amendments and GNU extensions
+.sp
+\fIgnu++2a\fP Draft ISO/IEC 14882:2020 with GNU extensions
+.UNINDENT
+.UNINDENT
+.UNINDENT
.INDENT 0.0
.TP
.B \-stdlib=<library>
Specify the C++ standard library to use; supported options are libstdc++ and
libc++. If not specified, platform default will be used.
-.UNINDENT
.INDENT 0.0
.TP
.B \-rtlib=<library>

--
Steve
20170425 http://youtu.be/VWUpyCsUKR4
20161221 http://youtu.be/IbCHE-hONow

Dimitry Andric

2018-04-07 19:00:06 UTC

Permalink

Post by Steve Kargl

Thanks for the diff, but the man page is generated from a .rst source,
so it will have to be changed there instead. I will submit an analogous
patch upstream for the rst file.

-Dimitry

Ed Maste

2018-04-07 20:34:24 UTC

Permalink

Post by Dimitry Andric
With lld there wasn't even *any* form of command line documentation
yet, which is why Ed slapped together a man page (that could probably
still use more details). It should really be upstreamed, in Sphinx's
RST format, or since they appear to gravitate towards Markdown now,
maybe already in that format.

The lld manpage was committed upstream a while ago in fact, and has
had a round of improvements since then from both lld and
OpenBSD/mandoc developers. We'll get these improvements with the next
LLVM update.

Steve Kargl

2018-04-06 00:56:24 UTC

Permalink

I never said that you said it was in base. I'm noting that
referring a user to a non-existent manual page is of little
help. In fact, your 7 word response is an affirmation that
the tools supplied in base should be properly documented.
--
steve

I never said it was in base.
On Thu, Apr 5, 2018 at 5:15 PM, Steve Kargl

To a first order approximation, the manual page for clang is gcc(1).
Conrad
On Thu, Apr 5, 2018 at 3:38 PM, Steve Kargl

--
Steve
20170425 http://youtu.be/VWUpyCsUKR4
20161221 http://youtu.be/IbCHE-hONow

Benjamin Kaduk

2018-04-06 01:11:50 UTC

Permalink

Post by Steve Kargl
I never said that you said it was in base. I'm noting that
referring a user to a non-existent manual page is of little
help. In fact, your 7 word response is an affirmation that
the tools supplied in base should be properly documented.

It would probably be more useful to file explicit bug reports
(or even write a patch) about missing or poor documentation, than
to proffer passive-aggressive inquiries on public mailing lists
that merely suggest but do not explicitly state that the
documentation is deficient.

Thanks,

Ben

Steve Kargl

2018-04-06 03:00:56 UTC

Permalink

Post by Benjamin Kaduk

There is nothing passive nor aggressive in asking about how
to use the tools supplied in base because its accompanying
documentation is substantially lacking in quality.

It should be the responsibility of the individual (or individuals)
who import new software into base to ensure that it has proper
documentation. Of course, the assumption is that this individual
has (or these individuals have) a familiarity with the software,
which should facilitate writing said documentation. This started
8 year 10 months ago when clang pre-2.8 was committed without a
manpage. The initial version of clang.1 appeared 7 year 6 months
ago. FreeBSD is now at clang 6.0.0. I fully anticipate that the
next import of clang will again have poor documentation.

To preempt a retort about "stop complaining and contribute a fix",
I'll note that all of my previous contributions that are in base have
been accompanied by documentation.

--
Steve

Conrad Meyer

2018-04-06 01:01:48 UTC

Permalink

I think we're on the same page about the deficiency of system Clang's
manual page, if little else...

On Thu, Apr 5, 2018 at 5:56 PM, Steve Kargl

I never said it was in base.
On Thu, Apr 5, 2018 at 5:15 PM, Steve Kargl

To a first order approximation, the manual page for clang is gcc(1).
Conrad
On Thu, Apr 5, 2018 at 3:38 PM, Steve Kargl

--
Steve
20170425 http://youtu.be/VWUpyCsUKR4
20161221 http://youtu.be/IbCHE-hONow

Conrad Meyer

2018-04-06 00:42:58 UTC

Permalink

I never said it was in base.

On Thu, Apr 5, 2018 at 5:15 PM, Steve Kargl

To a first order approximation, the manual page for clang is gcc(1).
Conrad
On Thu, Apr 5, 2018 at 3:38 PM, Steve Kargl

--
Steve
20170425 http://youtu.be/VWUpyCsUKR4
20161221 http://youtu.be/IbCHE-hONow

Conrad Meyer

2018-04-05 23:37:38 UTC

Permalink

To a first order approximation, the manual page for clang is gcc(1).

Conrad

On Thu, Apr 5, 2018 at 3:38 PM, Steve Kargl