mirrors/llvm-project
0
0
Fork 0
mirror of https://github.com/llvm/llvm-project.git synced 2025-04-25 21:16:05 +00:00
Code Issues Projects Releases Wiki Activity
llvm-project/flang/docs/FlangOptionsDocs.td

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

34 lines
1.0 KiB
TableGen
Raw Normal View History

[Flang] Generate documentation for compiler flags This patch aims to create a webpage to document Flang's command line options on https://flang.llvm.org/docs/ in a similar way to Clang's https://clang.llvm.org/docs/ClangCommandLineReference.html This is done by using clang_tablegen to generate an .rst file from Options.td (which is current shared with Clang) For this to work, ClangOptionDocEmitter.cpp was updated to allow specific Flang flags to be included, rather than bulk excluding clang flags. Note: Some headings in the generated documentation will incorrectly contain references to Clang, e.g. "Flags controlling the behaviour of Clang during compilation" This is because Options.td (Which is shared between both Clang and Flang) contains hard-coded DocBrief sections. I couldn't find a non-intrusive way to make this target-dependant, as such I've left this as is, and it will need revisiting later. Reviewed By: awarzynski Differential Revision: https://reviews.llvm.org/D129864
2022-07-22 16:40:50 +00:00
//==--- FlangOptionDocs.td - Option documentation -------------------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
def GlobalDocumentation {
code Intro =[{..
-------------------------------------------------------------------
NOTE: This file is automatically generated by running clang-tblgen
-gen-opt-docs. Do not edit this file by hand!!
-------------------------------------------------------------------
=====================================
Flang command line argument reference
=====================================
.. contents::
:local:
Introduction
============
}];
[clang][flang][driver] Correct program names in option group descriptions (#81726) Currently https://flang.llvm.org/docs/FlangCommandLineReference.html refers to "Clang" in several of the group descriptions for example: ``` Compilation options Flags controlling the behavior of Clang during compilation... ``` This is pretty confusing. I'm fixing this by making use of `Program` from the existing GlobalDocumentation object to substitute in the program name to these descriptions. This `Program` has been changed to a proper noun given that it's easier to lower case a string than capitalise one character (syntax wise). The tablegen backend has been changed to lower it so that links in the RST/HTML remain the same as they were before. To make sure the file is valid when not generating docs, I'm checking a #define and providing a default GlobalDocumentation if it's not defined. (I looked for a way to check if a def exists, but tablegen doesn't seem to have one) This means that if the DocBrief are used outside of documentation, they'll say "Clang", which is the same as it always was. This change does not aim fix option descriptions that refer to clang. Though we can use parts of this for that, there is only one driver library so it needs a different approach. This change also fixes the warning: ``` /home/buildbot/as-worker-4/publish-sphinx-docs/build/tools/flang/docs/Source/FlangCommandLineReference.rst:194: WARNING: unknown document: 'DiagnosticsReference' ``` Which is due to flang docs trying to link to clang docs. Now it will just tell the reader to go to Clang's page, which is not ideal but it is easy to find with Google at least.
2024-02-15 10:27:43 +00:00
string Program = "Flang";
[Driver] Refactor to use llvm Option's new Visibility flags This is a big refactor of the clang driver's option handling to use the Visibility flags introduced in https://reviews.llvm.org/D157149. There are a few distinct parts, but they can't really be split into separate commits and still be made to compile. 1. We split out some of the flags in ClangFlags to ClangVisibility. Note that this does not include any subtractive flags. 2. We update the Flag definitions and OptIn/OptOut constructs in Options.td by hand. 3. We introduce and use a script, update_options_td_flags, to ease migration of flag definitions in Options.td, and we run that on Options.td. I intend to remove this later, but I'm committing it so that downstream forks can use the script to simplify merging. 4. We update calls to OptTable in the clang driver, cc1as, flang, and clangd to use the visibility APIs instead of Include/Exclude flags. 5. We deprecate the Include/Exclude APIs and add a release note. *if you are running into conflicts with this change:* Note that https://reviews.llvm.org/D157150 may also be the culprit and if so it should be handled first. The script in `clang/utils/update_options_td_flags.py` can help. Take the downstream side of all conflicts and then run the following: ``` % cd clang/include/clang/Driver % ../../../utils/update_options_td_flags.py Options.td > Options.td.new % mv Options.td.new Options.td ``` This will hopefully be sufficient, please take a look at the diff. Differential Revision: https://reviews.llvm.org/D157151
2023-08-02 16:04:28 -07:00
list<string> VisibilityMask = ["FlangOption"];
list<string> IgnoreFlags = ["HelpHidden", "Unsupported", "Ignored"];
[Flang] Generate documentation for compiler flags This patch aims to create a webpage to document Flang's command line options on https://flang.llvm.org/docs/ in a similar way to Clang's https://clang.llvm.org/docs/ClangCommandLineReference.html This is done by using clang_tablegen to generate an .rst file from Options.td (which is current shared with Clang) For this to work, ClangOptionDocEmitter.cpp was updated to allow specific Flang flags to be included, rather than bulk excluding clang flags. Note: Some headings in the generated documentation will incorrectly contain references to Clang, e.g. "Flags controlling the behaviour of Clang during compilation" This is because Options.td (Which is shared between both Clang and Flang) contains hard-coded DocBrief sections. I couldn't find a non-intrusive way to make this target-dependant, as such I've left this as is, and it will need revisiting later. Reviewed By: awarzynski Differential Revision: https://reviews.llvm.org/D129864
2022-07-22 16:40:50 +00:00
}
[clang][flang][driver] Correct program names in option group descriptions (#81726) Currently https://flang.llvm.org/docs/FlangCommandLineReference.html refers to "Clang" in several of the group descriptions for example: ``` Compilation options Flags controlling the behavior of Clang during compilation... ``` This is pretty confusing. I'm fixing this by making use of `Program` from the existing GlobalDocumentation object to substitute in the program name to these descriptions. This `Program` has been changed to a proper noun given that it's easier to lower case a string than capitalise one character (syntax wise). The tablegen backend has been changed to lower it so that links in the RST/HTML remain the same as they were before. To make sure the file is valid when not generating docs, I'm checking a #define and providing a default GlobalDocumentation if it's not defined. (I looked for a way to check if a def exists, but tablegen doesn't seem to have one) This means that if the DocBrief are used outside of documentation, they'll say "Clang", which is the same as it always was. This change does not aim fix option descriptions that refer to clang. Though we can use parts of this for that, there is only one driver library so it needs a different approach. This change also fixes the warning: ``` /home/buildbot/as-worker-4/publish-sphinx-docs/build/tools/flang/docs/Source/FlangCommandLineReference.rst:194: WARNING: unknown document: 'DiagnosticsReference' ``` Which is due to flang docs trying to link to clang docs. Now it will just tell the reader to go to Clang's page, which is not ideal but it is easy to find with Google at least.
2024-02-15 10:27:43 +00:00
#define GENERATING_DOCS
[flang][docs][nfc] Refine FlangOptionsDocs.td Currently, FlangOptionsDocs.td doesn't specify `ExcludedFlags` which means that in the generated documentation file we expose flags that: * we don't necessarily won't to advertise to our users (e.g. hidden flags), or * are not supported altogether (e.g. CL options). This patch defines `ExcludeFlags` to fix that. The definition of `ExcludeFlags` was copied from Clang so that LLVM frontends have consistent documentation. It might be a bit counter-intuitive that IncludeFlags alone is not sufficient here. However, the current logic in ClangOptionDocEmitter.cpp will parse IncludeFlags and print all options that contains one of the included flags, as well as their aliases. So, for example, for -fopenmp (which is a supported Flang option), one would also get /fopenmp (i.e. CL mode equivalent for -fopenmp). By adding ExcludeFlags, we make sure that such aliases are excluded. I've also taken the liberty and moved FlangOptionsDocs.td. Originally it was located in Flang's "flang/include" directory, but there shouldn't be any implementation/documentation files there. Instead, I'm moving it to the "flang/docs" directory. Differential Revision: https://reviews.llvm.org/D130558
2022-07-26 09:49:29 +00:00
include "Options.td"
Reference in New Issue Copy Permalink