[clang,flang] Add help text for -fsyntax-only

[alexiprof]

Summary

Fix for the problem with displaying options -fsyntax-only in clang and flang-new in help
Fix https://github.com/llvm/llvm-project/issues/57033

Before:

$ clang  -help | grep syntax
 -objcmt-migrate-property-dot-syntax
        Enable migration of setter/getter messages to property-dot syntax

After:

$ clang -help | grep syntax
 -fsyntax-only           Run the preprocessor, parser and semantic analysis stages
 -objcmt-migrate-property-dot-syntax
        Enable migration of setter/getter messages to property-dot syntax

[vzakhari]

LGTM.

[peixin]

The CI failed since the test cases in flang driver have new output.

[alexiprof]

This is commit fix flang unit tests in using help command

[alexiprof]

Fix revision

Differential Revision: https://reviews.llvm.org/D131808

[awarzynski]

This is primarily a Clang change, so added some Clang reviewers. I will review shortly - thanks for taking this on!

[awarzynski]

Thanks, mostly makes sense! https://github.com/llvm/llvm-project/issues/57033 mentions -O{n} as well :) Could you fix that too? More comments inline.

CI is still failing :( Are you able to re-produce that? (I'm traveling atm, so can't check).

clang/include/clang/Driver/Options.td

2803–2805

Note that:

$ gcc --help=common | grep syntax
  -fsyntax-only               Check for syntax errors, then stop.

and (from Clang docs

Run the preprocessor, parser and type checking stages.

For consistency sake, I would replace "Syntax-check only"" with "Run the preprocessor, parser and type checking stages.". Technically, there's no separate preprocessor in Flang, but that's IMO tangential to this.

3219–3220

Unrelated change?

[alexiprof]

fix tests

[alexiprof]

In D131808#3720910, @awarzynski wrote:

Thanks, mostly makes sense! https://github.com/llvm/llvm-project/issues/57033 mentions -O{n} as well :) Could you fix that too? More comments inline.

CI is still failing :( Are you able to re-produce that? (I'm traveling atm, so can't check).

@awarzynski thanks for the feedback
Yes, if is valid phrase for flang and clang "Run the preprocessor, parser and type checking stages", I'll put it on.

in gcc optimization level displayed:

-O<number>                  Set optimization level to <number>.

I can add this to the list, but I think it's better to make it a separate revision

[alexiprof]

Set new text hint for option fsyntax-only

[alexiprof]

clang/include/clang/Driver/Options.td

2803–2805

Yes, i am replace text

3219–3220

yes, mini fix format.
If it bothers you, I can remove it

[alexiprof]

this pull request contains a fix for the problem with displaying options -fsyntax_only in clang and fland-new in help
https://github.com/llvm/llvm-project/issues/57033

Before:

$ clang  -help | grep syntax
 -objcmt-migrate-property-dot-syntax
        Enable migration of setter/getter messages to property-dot syntax

After:

$ clang -help | grep syntax
 -fsyntax-only           Run the preprocessor, parser and type checking stages
 -objcmt-migrate-property-dot-syntax
        Enable migration of setter/getter messages to property-dot syntax

Differential Revision: https://reviews.llvm.org/D131808

[alexiprof]

remove Unrelated change

[MaskRay]

Subject: [clang,flang] Add missing options fsyntax-only in help

Prefer -fsyntax-only to fsyntax-only since the former is what a user writes.

this pull request contains a fix for the problem with displaying options -fsyntax_only in clang and fland-new in help

typo: -fsyntax-only

"this pull request contains a fix" is verbose. Just use an imperative sentence: "Fix ..."

clang/include/clang/Driver/Options.td

2803–2805

semantic analysis is probably better than "type checking".

[MaskRay]

https://github.com/llvm/llvm-project/issues/57033

Use Fix https://github.com/llvm/llvm-project/issues/57033 or Fixes https://github.com/llvm/llvm-project/issues/57033 or (I usually prefer this for non-bugs but still some issues worth addressing) Close ..., then the issue will be automatically closed when you push the commit to origin/main

[alexiprof]

I do not have commit access, i do not have merge :-(

[MaskRay]

To be clear, some issues should be addressed before someone lands this.

[alexiprof]

replace text hint

[alexiprof]

I can't merge the changes((

[alexiprof]

Could someone land this patch please?
Alexander Malkov <[e-mail]>

[awarzynski]

LGTM, thanks for the fix!

You may want to update to title to better reflect the contents (e.g. “Add help text for -fsyntax-only”). While the fact that it fixes https://github.com/llvm/llvm-project/issues/57033 motivated this change, the actual implementation does a bit more than just fixing that.

I can land this for you once I can access stable internet. Sorry for the delay.

[alexiprof]

ping
@awarzynski @MaskRay @vzakhari

[kiranchandramohan]

I can land this.

[kiranchandramohan]

In D131808#3722809, @alexiprof wrote:

Could someone land this patch please?
Alexander Malkov <[e-mail]>

Was landed with the email id contained in the patch (Author: Alexander Malkov <[e-mail]>). Hope that is OK. May be you can update to the gmail id if that is what you prefer in your phabricator account.

clang/docs/ClangCommandLineReference.rst

 Extract API information
 
 .. option:: -fdriver-only
 
 Only run the driver.
 
 .. option:: -fsyntax-only
 
+Run the preprocessor, parser and semantic analysis stages
+
 .. option:: -module-file-info
 
 Provide information about a particular module file
 
 .. option:: --precompile
 
 Only precompile the input
 

clang/docs/CommandGuide/clang.rst

 ~~~~~~~~~~~~~~~~~~~~~~~
 
 .. option:: -E
 
  Run the preprocessor stage.
 
 .. option:: -fsyntax-only
 
- Run the preprocessor, parser and type checking stages.
+ Run the preprocessor, parser and semantic analysis stages.
 
 .. option:: -S
 
  Run the previous stages as well as LLVM generation and optimization stages
  and target-specific code generation, producing an assembly file.
 
 .. option:: -c
 

clang/docs/UsersManual.rst

CL.EXE COMPATIBILITY OPTIONS:
       /Zc:trigraphs-          Disable trigraphs (default)
       /Zc:trigraphs           Enable trigraphs
       /Zc:twoPhase-           Disable two-phase name lookup in templates
       /Zc:twoPhase            Enable two-phase name lookup in templates
       /Zi                     Alias for /Z7. Does not produce PDBs.
       /Zl                     Don't mention any default libraries in the object file
       /Zp                     Set the default maximum struct packing alignment to 1
       /Zp<value>              Specify the default maximum struct packing alignment
-      /Zs                     Syntax-check only
+      /Zs                     Run the preprocessor, parser and semantic analysis stages
 
     OPTIONS:
       -###                    Print (but do not run) the commands to run for this compilation
       --analyze               Run the static analyzer
       -faddrsig               Emit an address-significance table
       -fansi-escape-codes     Use ANSI escape codes for diagnostics
       -fblocks                Enable the 'blocks' language feature
       -fcf-protection=<value> Instrument control-flow architecture protection. Options: return, branch, full, none.
OPTIONS:
                               Enable memory access instrumentation in ThreadSanitizer (default)
       -fsanitize-trap=<value> Enable trapping for specified sanitizers
       -fsanitize-undefined-strip-path-components=<number>
                               Strip (or keep only, if negative) a given number of path components when emitting check metadata.
       -fsanitize=<check>      Turn on runtime checks for various forms of undefined or suspicious
                               behavior. See user manual for available checks
       -fsplit-lto-unit        Enables splitting of the LTO unit.
       -fstandalone-debug      Emit full debug info for all types used by the program
+      -fsyntax-only           Run the preprocessor, parser and semantic analysis stages
       -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto
       -gcodeview-ghash        Emit type record hashes in a .debug$H section
       -gcodeview              Generate CodeView debug information
       -gline-directives-only  Emit debug line info directives only
       -gline-tables-only      Emit debug line number tables only
       -miamcu                 Use Intel MCU ABI
       -mllvm <value>          Additional arguments to forward to LLVM's option processing
       -nobuiltininc           Disable builtin #include directories

clang/include/clang/Driver/Options.td

defm strict_vtable_pointers : BoolFOption<"strict-vtable-pointers",
   CodeGenOpts<"StrictVTablePointers">, DefaultFalse,
   PosFlag<SetTrue, [CC1Option], "Enable optimizations based on the strict rules for"
             " overwriting polymorphic C++ objects">,
   NegFlag<SetFalse>>;
 def fstrict_overflow : Flag<["-"], "fstrict-overflow">, Group<f_Group>;
 def fdriver_only : Flag<["-"], "fdriver-only">, Flags<[NoXarchOption, CoreOption]>,
   Group<Action_Group>, HelpText<"Only run the driver.">;
 def fsyntax_only : Flag<["-"], "fsyntax-only">,
-  Flags<[NoXarchOption,CoreOption,CC1Option,FC1Option]>, Group<Action_Group>;
+  Flags<[NoXarchOption,CoreOption,CC1Option,FC1Option,FlangOption]>, Group<Action_Group>,
+  HelpText<"Run the preprocessor, parser and semantic analysis stages">;
 def ftabstop_EQ : Joined<["-"], "ftabstop=">, Group<f_Group>;
 def ftemplate_depth_EQ : Joined<["-"], "ftemplate-depth=">, Group<f_Group>;
 def ftemplate_depth_ : Joined<["-"], "ftemplate-depth-">, Group<f_Group>;
 def ftemplate_backtrace_limit_EQ : Joined<["-"], "ftemplate-backtrace-limit=">,
                                    Group<f_Group>;
 def foperator_arrow_depth_EQ : Joined<["-"], "foperator-arrow-depth=">,
                                Group<f_Group>;
 
 def fsave_optimization_record : Flag<["-"], "fsave-optimization-record">,

 def gembed_source : Flag<["-"], "gembed-source">, Group<g_flags_Group>, Flags<[CC1Option]>,
     HelpText<"Embed source text in DWARF debug sections">,
     MarshallingInfoFlag<CodeGenOpts<"EmbedSource">>;
 def gno_embed_source : Flag<["-"], "gno-embed-source">, Group<g_flags_Group>,
     Flags<[NoXarchOption]>,
     HelpText<"Restore the default behavior of not embedding source text in DWARF debug sections">;
 def headerpad__max__install__names : Joined<["-"], "headerpad_max_install_names">;
 def help : Flag<["-", "--"], "help">, Flags<[CC1Option,CC1AsOption, FC1Option,
     FlangOption]>, HelpText<"Display available options">,
     MarshallingInfoFlag<FrontendOpts<"ShowHelp">>;
 def ibuiltininc : Flag<["-"], "ibuiltininc">,
   HelpText<"Enable builtin #include directories even when -nostdinc is used "
            "before or after -ibuiltininc. "
            "Using -nobuiltininc after the option disables it">;
 def index_header_map : Flag<["-"], "index-header-map">, Flags<[CC1Option]>,
   HelpText<"Make the next included directory (-I or -F) an indexer header map">;
 def idirafter : JoinedOrSeparate<["-"], "idirafter">, Group<clang_i_Group>, Flags<[CC1Option]>,
   HelpText<"Add directory to AFTER include search path">;

 def _SLASH_Zi : CLFlag<"Zi">, Alias<_SLASH_Z7>,
   HelpText<"Like /Z7">;
 def _SLASH_Zp : CLJoined<"Zp">,
   HelpText<"Set default maximum struct packing alignment">,
   Alias<fpack_struct_EQ>;
 def _SLASH_Zp_flag : CLFlag<"Zp">,
   HelpText<"Set default maximum struct packing alignment to 1">,
   Alias<fpack_struct_EQ>, AliasArgs<["1"]>;
-def _SLASH_Zs : CLFlag<"Zs">, HelpText<"Syntax-check only">,
+def _SLASH_Zs : CLFlag<"Zs">, HelpText<"Run the preprocessor, parser and semantic analysis stages">,
   Alias<fsyntax_only>;
 def _SLASH_openmp_ : CLFlag<"openmp-">,
   HelpText<"Disable OpenMP support">, Alias<fno_openmp>;
 def _SLASH_openmp : CLFlag<"openmp">, HelpText<"Enable OpenMP support">,
   Alias<fopenmp>;
 def _SLASH_openmp_experimental : CLFlag<"openmp:experimental">,
   HelpText<"Enable OpenMP support with experimental SIMD support">,
   Alias<fopenmp>;

flang/test/Driver/driver-help-hidden.f90

 ! CHECK-NEXT:                        Enable support for generating executables (experimental)
 ! CHECK-NEXT: -flarge-sizes          Use INTEGER(KIND=8) for the result type in size-related intrinsics
 ! CHECK-NEXT: -flogical-abbreviations Enable logical abbreviations
 ! CHECK-NEXT: -fno-automatic         Implies the SAVE attribute for non-automatic local objects in subprograms unless RECURSIVE
 ! CHECK-NEXT: -fno-color-diagnostics  Disable colors in diagnostics
 ! CHECK-NEXT: -fno-integrated-as     Disable the integrated assembler
 ! CHECK-NEXT: -fopenacc              Enable OpenACC
 ! CHECK-NEXT: -fopenmp               Parse OpenMP pragmas and generate parallel code.
+! CHECK-NEXT: -fsyntax-only          Run the preprocessor, parser and semantic analysis stages
 ! CHECK-NEXT: -fxor-operator         Enable .XOR. as a synonym of .NEQV.
 ! CHECK-NEXT: -help     Display available options
 ! CHECK-NEXT: -I <dir>               Add directory to the end of the list of include search paths
 ! CHECK-NEXT: -mllvm <value>         Additional arguments to forward to LLVM's option processing
 ! CHECK-NEXT: -mmlir <value>         Additional arguments to forward to MLIR's option processing
 ! CHECK-NEXT: -module-dir <dir>      Put MODULE files in <dir>
 ! CHECK-NEXT: -nocpp                 Disable predefined and command line preprocessor macros
 ! CHECK-NEXT: -o <file> Write output to <file>

flang/test/Driver/driver-help.f90

 ! HELP-NEXT:                        Specify where to find the compiled intrinsic modules
 ! HELP-NEXT: -flarge-sizes          Use INTEGER(KIND=8) for the result type in size-related intrinsics
 ! HELP-NEXT: -flogical-abbreviations Enable logical abbreviations
 ! HELP-NEXT: -fno-automatic         Implies the SAVE attribute for non-automatic local objects in subprograms unless RECURSIVE
 ! HELP-NEXT: -fno-color-diagnostics  Disable colors in diagnostics
 ! HELP-NEXT: -fno-integrated-as      Disable the integrated assembler
 ! HELP-NEXT: -fopenacc              Enable OpenACC
 ! HELP-NEXT: -fopenmp               Parse OpenMP pragmas and generate parallel code.
+! HELP-NEXT: -fsyntax-only          Run the preprocessor, parser and semantic analysis stages
 ! HELP-NEXT: -fxor-operator         Enable .XOR. as a synonym of .NEQV.
 ! HELP-NEXT: -help                  Display available options
 ! HELP-NEXT: -I <dir>               Add directory to the end of the list of include search paths
 ! HELP-NEXT: -mllvm <value>         Additional arguments to forward to LLVM's option processing
 ! HELP-NEXT: -mmlir <value>         Additional arguments to forward to MLIR's option processing
 ! HELP-NEXT: -module-dir <dir>      Put MODULE files in <dir>
 ! HELP-NEXT: -nocpp                 Disable predefined and command line preprocessor macros
 ! HELP-NEXT: -o <file>              Write output to <file>

 ! HELP-FC1-NEXT: -flogical-abbreviations Enable logical abbreviations
 ! HELP-FC1-NEXT: -fno-analyzed-objects-for-unparse
 ! HELP-FC1-NEXT:                        Do not use the analyzed objects when unparsing
 ! HELP-FC1-NEXT: -fno-automatic         Implies the SAVE attribute for non-automatic local objects in subprograms unless RECURSIVE
 ! HELP-FC1-NEXT: -fno-debug-pass-manager Disables debug printing for the new pass manager
 ! HELP-FC1-NEXT: -fno-reformat          Dump the cooked character stream in -E mode
 ! HELP-FC1-NEXT: -fopenacc              Enable OpenACC
 ! HELP-FC1-NEXT: -fopenmp               Parse OpenMP pragmas and generate parallel code.
+! HELP-FC1-NEXT: -fsyntax-only          Run the preprocessor, parser and semantic analysis stages
 ! HELP-FC1-NEXT: -fxor-operator         Enable .XOR. as a synonym of .NEQV.
 ! HELP-FC1-NEXT: -help                  Display available options
 ! HELP-FC1-NEXT: -init-only             Only execute frontend initialization
 ! HELP-FC1-NEXT: -I <dir>               Add directory to the end of the list of include search paths
 ! HELP-FC1-NEXT: -load <dsopath>        Load the named plugin (dynamic shared object)
 ! HELP-FC1-NEXT: -mllvm <value>         Additional arguments to forward to LLVM's option processing
 ! HELP-FC1-NEXT: -mmlir <value>         Additional arguments to forward to MLIR's option processing
 ! HELP-FC1-NEXT: -module-dir <dir>      Put MODULE files in <dir>