decent manual for clang

Hello all,

I'm looking for a *full* user manual for clang.
I can find few things under clang --help
I can find few more here: http://clang.llvm.org/docs/UsersManual.html

But not everything is present.
For instance, the -g, -ggdb and alike are not listed.

Is there a man page for clang, or a web page that I missed?

Thanks,

Ran.

This e-mail message is intended for the recipient only and contains information which is CONFIDENTIAL and which may be proprietary to ECI Telecom. If you have received this transmission in error, please inform us by e-mail, phone or fax, and then delete the original and all copies thereof.

While not the correct way to address your problem, you're quite likely
to find what you need to know in the GCC manual, because many of
CLang's command-line arguments are compatible with GCC. Also look at
GNU's manuals for the compilers for the individual programming
languages - if you use CLang to build C++, then look at the g++
manual, for example, or third-party books, online tutorials, HOWTOs
and the like for g++.

Every software product needs a good manual, but one cannot simply copy
the GNU manuals into CLangs unless the licenses for both manuals are
compatible, which they are not likely to be.

It's necessary that we have a full edition of Clang manual even if Clang is compatible with GCC. Do we have one? If not, anybody working on that?

The idea is that it'll be compatible via driver with as many compilers as we can, just that the gcc support is quite a bit further along. That said the only manuals that exist are on clang.llvm.org. I don't know offhand if anyone is working on it.

-eric

Someone who knows better than I do what all the individual compilers
are that CLang presently emulated, please file a bug report that
points out that that other compiler's support in CLang is either not
completely documented, or not at all documented. Give some estimate
of how well it is documented.

I would suggest one single bug report that gives a brief mention of
every single other compiler, that links to a Related Bug that gives
more detail for each individual compiler.

Even if no one gets to writing a manual sometime soon, a good start
would be to make it more obvious that someone needs to.

There are lots of people who either like to write documentation, or
are good at it, even if they know little or nothing about coding.
People like that are looking to help out Open Source projects all they
time, but it may not be at all obvious to totally new volunteers that
CLang could use some technical writers.

AFAIK, clang doesn't take an upper case 'L' in its name.

-- Jean-Daniel

It's necessary that we have a full edition of Clang manual even if Clang is compatible with GCC.

Yes, we certainly should have a complete Clang manual independent of GCC's manual.

Do we have one? If not, anybody working on that?

We do not have such a manual, and I don't know of anyone actively work on one.

  - Doug

I was strongly considering putting together at least a quick manual for command line flags, optimization levels, and same for passing things into LLVM from the -mllvm option. Unfortunately tracking down the relationship between one of the undocumented flags in the tablegen and what it eventually causes to happen in the rest of the build process became very complicated very fast, and some of the other flags don't seem to do what their names imply due to language standards being followed by Clang which other compilers might have considered optimizations, particularly the aggressive constant folding and command line options that *seem* related to it not doing what one would expect.

-Gordon

For documenting command-line options in particular, there are
essentially two pieces here. One, we want some sort of TableGen
integration so we can track which options are documented and possibly
integrate documentation into clang. Two, we need to actually write
the documentation.

I don't really have much time to spend on this at the moment, but if
you have questions about a specific option, I'll do my best to answer.

On a side note, I don't think we want to document -mllvm beyond "this
exposes internal options; use at your own risk" (except maybe "-mllvm
-disable-llvm-optzs").

-Eli

One would think SQA in Apple and Technical Writing groups would work together and get a LLVM/Clang set of manuals put together and made available under Technical publications via developer.apple.com.

It would aide in everyone’s work using XCode and much, much more.

  • Marc

Clang is an open source project, it should have a great man page and manual, independent of any vendor using it.

-Chris

For documenting command-line options in particular, there are
essentially two pieces here. One, we want some sort of TableGen
integration so we can track which options are documented and possibly
integrate documentation into clang.

Could you expand on that a bit? I don't know what TableGen is yet.

Two, we need to actually write the documentation.

I am willing to devote some time to that cause. I have found that
writing the documentation is a good way to learn about the thing being
documented.

--jkl

For documenting command-line options in particular, there are
essentially two pieces here. One, we want some sort of TableGen
integration so we can track which options are documented and possibly
integrate documentation into clang.

Could you expand on that a bit? I don't know what TableGen is yet.

Basically, we have a list of options in
clang/include/clang/Driver/Options.td, and it's processed by an LLVM
tool called TableGen (see clang/utils/TableGen/). We should be using
that list of options to both generate the appropriate C++ declarations
and generate the appropriate documentation.

Two, we need to actually write the documentation.

I am willing to devote some time to that cause. I have found that
writing the documentation is a good way to learn about the thing being
documented.

Cool. http://clang.llvm.org/docs/UsersManual.html could certainly use
a lot of work, both in terms of missing pieces and reorganizing our
documentation to be more user-friendly. The documentation is part of
the clang source tree, in clang/docs/, so you can submit patches to
that to cfe-commits the same way you would for code patches.

-Eli

James,

After asking my question I understood that there is a work to do.
Me too willing to join this mission, I'm sure together we'll be able to make this manual to happen.

Ran.