CDT Man Pages

[BenjaminGormanPMP]

CDT is missing a manpage.

Suggestion:

• Write the manpage source in markdown and use pandoc to convert to manpage format.
• Update CMake to:
  • automate creating the manpage from source
  • install the generated manpage into the package

[BenjaminGormanPMP]

From 3/28/23 Stand-up meeting:

• Action item – @ScottBailey to add description to GitHub issue CDT Man Pages #121.

[larryk85]

The list of applications to document:

• cdt-cpp
• cdt-cc
• cdt-ld
• cdt-abidiff
• cdt-objdump

[jolly-fellow]

@larryk85 Questions about options of cdt-cpp:

As I understand these options are obsolete and not supported or deprecated now:

  --fquery                                  - Produce binaries for wasmql
  --fquery-client                           - Produce binaries for wasmql
  --fquery-server                           - Produce binaries for wasmql

How is better to describe them to don't confuse the users?

Do I understand correctly that the following options do the same as these options in gcc?

  --MD                                      - Write depfile containing user and system headers
  --MF=<string>                             - Write depfile output
  --MMD                                     - Write depfile containing user
  --MT=<string>                             - Specify name of main file output in depfile

Would it be OK to describe them with reference to GCC documentation like https://gcc.gnu.org/onlinedocs/cpp/Invocation.html ?

Does

--fnative - Compile and link for x86-64

work rather as gcc -march=native or gcc -march=x86-64 ?

Do I understand correctly that
-W=<string> - Enable the specified warning
supports all warnings of GCC/clang and I can refer to this document: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html

Do I understand correctly that:

  --help                                    - Display available options (--help-hidden for more)
  --help-list                               - Display list of available options (--help-list-hidden for more)

and

  --help-hidden                             - Display all available options
  --help-list-hidden                        - Display list of all available options

do the same and I can describe them as duplicates?
Does it make sense to mark duplicates as deprecated options which will be removed?

What means options with such descriptions:

  -g                                        - debug build <ignored>
  -x=<string>                               - <ignored>
  --fpch-preprocess                         - <ignored>

Does it make sense to describe them as disabled options which will be removed?

IMHO it would be nice to describe default values and ranges of possible values for the following options:

  --non-global-value-max-name-size=<uint>   - Maximum size for the name of non-global values.
  --opt-bisect-limit=<int>                  - Maximum optimization to perform
  --rng-seed=<seed>                         - Seed for the random number generator
  --time-trace-granularity=<uint>           - Minimum time granularity (in microseconds) traced by time profiler

I compared man pages of gcc and clang and found that description of the same options for gcc is much more user friendly than for clang. For example:

man gcc

       -C  Do not discard comments.  All comments are passed through to the output file, except for comments in processed directives, which are deleted along with the directive.

           You should be prepared for side effects when using -C; it causes the preprocessor to treat comments as tokens in their own right.  For example, comments appearing at the start of what would be a directive line have the effect of turning that line into an ordinary
           source line, since the first token on the line is no longer a #.

       -CC Do not discard comments, including during macro expansion.  This is like -C, except that comments contained within macros are also passed through to the output file where the macro is expanded.

           In addition to the side effects of the -C option, the -CC option causes all C++-style comments inside a macro to be converted to C-style comments.  This is to prevent later use of that macro from inadvertently commenting out the remainder of the source line.

           The -CC option is generally used to support lint comments.

-------------------------------------
clang

-C, --comments

Include comments in preprocessed output

-CC, --comments-in-macros

Include comments from within macros in preprocessed output

Does it make sense to follow example of gcc man page and make the descriptions more user friendly?

[larryk85]

As I understand these options are obsolete and not supported or deprecated now:

  --fquery                                  - Produce binaries for wasmql
  --fquery-client                           - Produce binaries for wasmql
  --fquery-server                           - Produce binaries for wasmql

How is better to describe them to don't confuse the users?

We can ignore any 'fquery' stuff as it will be removed in the next version.

[larryk85]

Do I understand correctly that the following options do the same as these options in gcc?

  --MD                                      - Write depfile containing user and system headers
  --MF=<string>                             - Write depfile output
  --MMD                                     - Write depfile containing user
  --MT=<string>                             - Specify name of main file output in depfile

Would it be OK to describe them with reference to GCC documentation like https://gcc.gnu.org/onlinedocs/cpp/Invocation.html ?

That would be fine.

[larryk85]

Do I understand correctly that:

  --help                                    - Display available options (--help-hidden for more)
  --help-list                               - Display list of available options (--help-list-hidden for more)

and

  --help-hidden                             - Display all available options
  --help-list-hidden                        - Display list of all available options

do the same and I can describe them as duplicates? Does it make sense to mark duplicates as deprecated options which will be removed?

I'm not sure what you mean, these all display different options and presentations of options.

[larryk85]

What means options with such descriptions:

  -g                                        - debug build <ignored>
  -x=<string>                               - <ignored>
  --fpch-preprocess                         - <ignored>

Does it make sense to describe them as disabled options which will be removed?

For these you can simply state that they are there for compatibility with CMake and other build tools.

[larryk85]

IMHO it would be nice to describe default values and ranges of possible values for the following options:

  --non-global-value-max-name-size=<uint>   - Maximum size for the name of non-global values.
  --opt-bisect-limit=<int>                  - Maximum optimization to perform
  --rng-seed=<seed>                         - Seed for the random number generator
  --time-trace-granularity=<uint>           - Minimum time granularity (in microseconds) traced by time profiler

I compared man pages of gcc and clang and found that description of the same options for gcc is much more user friendly than for clang. For example:

man gcc

       -C  Do not discard comments.  All comments are passed through to the output file, except for comments in processed directives, which are deleted along with the directive.

           You should be prepared for side effects when using -C; it causes the preprocessor to treat comments as tokens in their own right.  For example, comments appearing at the start of what would be a directive line have the effect of turning that line into an ordinary
           source line, since the first token on the line is no longer a #.

       -CC Do not discard comments, including during macro expansion.  This is like -C, except that comments contained within macros are also passed through to the output file where the macro is expanded.

           In addition to the side effects of the -C option, the -CC option causes all C++-style comments inside a macro to be converted to C-style comments.  This is to prevent later use of that macro from inadvertently commenting out the remainder of the source line.

           The -CC option is generally used to support lint comments.

-------------------------------------
clang

-C, --comments

Include comments in preprocessed output

-CC, --comments-in-macros

Include comments from within macros in preprocessed output

Does it make sense to follow example of gcc man page and make the descriptions more user friendly?

I would be more inclined to have the more user friendly yes.

[jolly-fellow]

Need to clarify how exactly option -D works.

It is described as

-D=<string> Define <macro> to <value> (or 1 if <value> omitted)

I don't understand how to declare a macro and a value from this description.

In GCC it is described as:

-D name=definition
    Predefine name as a macro, with definition definition. There are no restrictions on the contents of definition, but if you are invoking the preprocessor from a shell or shell-like program you may need to use the shell's quoting syntax to protect characters such as spaces that have a meaning in the shell syntax.

    If you wish to define a function-like macro on the command line, write its argument list with surrounding parentheses before the equals sign (if any). Parentheses are meaningful to most shells, so you will need to quote the option. With sh and csh, -D'name(args...)=definition' works.

    -D and -U options are processed in the order they are given on the command line. All -imacros file and -include file options are processed after all -D and -U options. 

I tried define a name and print it:

./cdt-cpp -E -D="ASDDD 123" -dM asd.cpp | grep ASDDD

with empty result

But GCC with the same command line works well

 gcc -E -D="ASDDD 123" -dM asd.cpp | grep ASDDD
#define ASDDD 123

[jolly-fellow]

I'd be glad to know what does option --as-secure-log-file-name=<value> do.

[jolly-fellow]

@larryk85 After my learning about how CDT tools work and a long discussion with @dimas1185 I believe that the plan of man pages writing should be corrected. Here are my thoughts and proposal:

At the beginning I had a plan to take excellent documentation from GCC tools, correct it corresponding to CDT specific and use it as a base for the CDT man pages. Most of the options of CDT tools have the same names as options of GCC. I assumed that they have the same behavior. But after I checked how some options of cdt-cpp actually work and consultation with @dimas1185 about internals of CDT tools I understood that behavior of options with the same names in CDT and GCC may be very different, some options don't work, may have bugs and unexpected behavior, some options were developed years ago and the best way to understand how they work is learning of their source code. After I got this information I realized that my task goes far beyond simply adapting GCC documentation to CDT specifics.
So I propose to divide this task into the following:

1. I will make the man pages with the text which CDT utilities print with option --help (IMHO this help in its current state is almost useless because the descriptions of the options look like --as-secure-log-file-name= - As secure log file name) in order to get man pages for all utilities.
2. I will test and research how the options actually work (it may takes time)
3. I will make issues for all bugs which I find during the test.
4. I will update the option descriptions in man pages and --help text.

[jolly-fellow]

cdt-cpp.1.md
Hello @larryk85. I have created all required man pages with simple descriptions of the options. Now we should decide do we need to make the descriptions more correct, beautiful and user friendly. Like in man page for GCC.
The problem is that I can't predict how much time may takes the inspection and testing of the compiler and the linker options to understand how they work exactly, because some of them don't work, some have bugs and some work different than the same options of GCC.
So if you think it make sense to inspect the options and update their descriptions I will start this task, if you have another tasks for me with higher priority I will switch to them. I have attached to this comment partially written man page for the compiler to show how it may look after updating.

[larryk85]

Let's get this one merged first. And then make a new follow on issue to "fix" the man pages and to also get devrel input on it.