From 128306864b163557280b90aa620abb34563c38fb Mon Sep 17 00:00:00 2001 From: Paul Osmialowski Date: Thu, 19 Jun 2025 13:32:24 +0100 Subject: [PATCH] [flang] flang manpage overhaul Make the flang man page look more like the one clang is having. --- flang/docs/CMakeLists.txt | 36 ++++++++------- flang/docs/CommandGuide/index.rst | 77 +++++++++++++++++++++++-------- flang/docs/FlangOptionsDocs.td | 2 +- flang/docs/FlangOptionsMan.td | 23 +++++++++ flang/docs/conf.py | 2 +- 5 files changed, 103 insertions(+), 37 deletions(-) create mode 100644 flang/docs/FlangOptionsMan.td diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index a9f5811fcd064..568f942cb4aa6 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -82,20 +82,14 @@ if (LLVM_ENABLE_DOXYGEN) endif() endif() -function (gen_rst_file_from_td output_file td_option source) +function (gen_rst_file_from_td output_file td_option source target) if (NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${source}") message(FATAL_ERROR "Cannot find source file: ${source} in ${CMAKE_CURRENT_SOURCE_DIR}") endif() get_filename_component(TABLEGEN_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${source}" DIRECTORY) list(APPEND LLVM_TABLEGEN_FLAGS "-I${TABLEGEN_INCLUDE_DIR}") list(APPEND LLVM_TABLEGEN_FLAGS "-I${CMAKE_CURRENT_SOURCE_DIR}/../../clang/include/clang/Driver/") - clang_tablegen(Source/${output_file} ${td_option} SOURCE ${source} TARGET "gen-${output_file}") - # clang_tablegen() does not create the output directory automatically, - # so we have to create it explicitly. - add_custom_target(create-flang-rst-output-dir - COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/Source - ) - add_dependencies("gen-${output_file}" create-flang-rst-output-dir) + clang_tablegen(Source/${output_file} ${td_option} SOURCE ${source} TARGET ${target}) endfunction() if (LLVM_ENABLE_SPHINX) @@ -107,14 +101,22 @@ if (LLVM_ENABLE_SPHINX) # CLANG_TABLEGEN_EXE variable needs to be set for clang_tablegen to run without error find_program(CLANG_TABLEGEN_EXE "clang-tblgen" ${LLVM_TOOLS_BINARY_DIR} NO_DEFAULT_PATH) - # Generate the RST file from TableGen (shared by both HTML and MAN builds) - gen_rst_file_from_td(FlangCommandLineReference.rst -gen-opt-docs FlangOptionsDocs.td) + # Generate the RST file from TableGen (for both HTML and MAN builds) + gen_rst_file_from_td(FlangCommandLineReference.rst -gen-opt-docs FlangOptionsDocs.td "gen-FlangCommandLineReference.rst") + gen_rst_file_from_td(FlangCommandLineOptions.rst -gen-opt-docs FlangOptionsMan.td "gen-FlangCommandLineOptions.rst") + # clang_tablegen() (called from gen_rst_file_from_td()) does not create the + # output directory automatically, so we have to create it explicitly. + add_custom_target(create-flang-rst-output-dir + COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/Source + ) + add_dependencies("gen-FlangCommandLineReference.rst" create-flang-rst-output-dir) + add_dependencies("gen-FlangCommandLineOptions.rst" create-flang-rst-output-dir) if (${SPHINX_OUTPUT_HTML}) message(STATUS "Using index.md for html build") # Copy the entire flang/docs directory to the build Source dir, - # then remove the index.rst file, to avoid clash with index.md + # then remove the index.rst file, to avoid clash with index.md # which is used for the HTML build. add_custom_target(copy-flang-src-docs-html COMMAND "${CMAKE_COMMAND}" -E copy_directory @@ -141,12 +143,12 @@ if (LLVM_ENABLE_SPHINX) # MAN BUILD SETUP # ---------------------------- if (${SPHINX_OUTPUT_MAN}) - message(STATUS "NOTE: The Flang man page is currently a placeholder with a TODO. See docs/CommandGuide/index.rst for details") + message(STATUS "Using CommandGuide/index.rst for man build") # Create minimal Source dir with ONLY the files needed for man build: # - conf.py (Sphinx config) # - index.rst (top-level man page) - # - FlangCommandLineReference.rst (generated reference) + # - FlangCommandLineOptions.rst (generated reference) add_custom_target(copy-flang-src-docs-man COMMAND "${CMAKE_COMMAND}" -E make_directory "${FLANG_DOCS_MAN_DIR}" @@ -154,13 +156,13 @@ if (LLVM_ENABLE_SPHINX) "${CMAKE_CURRENT_SOURCE_DIR}/conf.py" "${FLANG_DOCS_MAN_DIR}/conf.py" COMMAND "${CMAKE_COMMAND}" -E copy - "${CMAKE_CURRENT_BINARY_DIR}/Source/FlangCommandLineReference.rst" - "${FLANG_DOCS_MAN_DIR}/FlangCommandLineReference.rst" + "${CMAKE_CURRENT_BINARY_DIR}/Source/FlangCommandLineOptions.rst" + "${FLANG_DOCS_MAN_DIR}/FlangCommandLineOptions.rst" COMMAND "${CMAKE_COMMAND}" -E copy "${CMAKE_CURRENT_SOURCE_DIR}/CommandGuide/index.rst" "${FLANG_DOCS_MAN_DIR}/index.rst" - DEPENDS flang-doc gen-FlangCommandLineReference.rst) - + DEPENDS flang-doc gen-FlangCommandLineOptions.rst) + add_sphinx_target(man flang SOURCE_DIR "${FLANG_DOCS_MAN_DIR}") add_dependencies(docs-flang-man copy-flang-src-docs-man) endif() diff --git a/flang/docs/CommandGuide/index.rst b/flang/docs/CommandGuide/index.rst index 093c79fa185be..1ba97464242e4 100644 --- a/flang/docs/CommandGuide/index.rst +++ b/flang/docs/CommandGuide/index.rst @@ -1,22 +1,63 @@ -Flang Manual Page (In Progress) -================================================== - -.. note:: - This man page is under development. - -For full documentation, please see the online HTML docs: - -https://flang.llvm.org/docs/ - -.. - The placeholder text "FlangCommandLineReference" below should eventually be replaced with the actual man page contents. - ----- - -Flang Command Line Reference ----------------------------- +flang - the Flang Fortran compiler +================================== + +SYNOPSIS +-------- + +:program:`flang` [*options*] *filename ...* + +DESCRIPTION +----------- + +:program:`flang` is a Fortran compiler which supports all of the Fortran 95 and +many newer language features. Flang supports OpenMP and has some support for +OpenACC and CUDA. It encompasses preprocessing, parsing, optimization, code +generation, assembly, and linking. Depending on the options passed in, Flang +will perform only some, or all, of these actions. While Flang is highly +integrated, it is important to understand the stages of compilation in order to +understand how to invoke it. These stages are: + +Driver + The flang executable is actually a small driver that orchestrates the + execution of other tools such as the compiler, assembler and linker. + Typically you do not need to interact with the driver, but you + transparently use it to run the other tools. + +Preprocessing + This stage performs tokenization of the input source file, macro expansion, + #include expansion and handles other preprocessor directives. + +Parsing and Semantic Analysis + This stage parses the input file, translating preprocessor tokens into a + parse tree. Once in the form of a parse tree, it applies semantic + analysis to compute types for expressions and determine whether + the code is well formed. Parse errors and most compiler warnings + are generated by this stage. + +Code Generation and Optimization + This stage translates the parse tree into intermediate code (known as + "LLVM IR") and, ultimately, machine code. It also optimizes this + intermediate code and handles target-specific code generation. The output + of this stage is typically a ".s" file, referred to as an "assembly" file. + + Flang also supports the use of an integrated assembler, in which the code + generator produces object files directly. This avoids the overhead of + generating the ".s" file and calling the target assembler explicitly. + +Assembler + This stage runs the target assembler to translate the output of the + compiler into a target object file. The output of this stage is typically + a ".o" file, referred to as an "object" file. + +Linker + This stage runs the target linker to merge multiple object files into an + executable or dynamic library. The output of this stage is typically + an "a.out", ".dylib" or ".so" file. + +OPTIONS +------- .. toctree:: :maxdepth: 1 - FlangCommandLineReference + FlangCommandLineOptions diff --git a/flang/docs/FlangOptionsDocs.td b/flang/docs/FlangOptionsDocs.td index 14d033f8587e3..f2847f07afdf3 100644 --- a/flang/docs/FlangOptionsDocs.td +++ b/flang/docs/FlangOptionsDocs.td @@ -1,4 +1,4 @@ -//==--- FlangOptionDocs.td - Option documentation -------------------------===// +//==--- FlangOptionsDocs.td - Options documentation -----------------------===// // // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. // See https://llvm.org/LICENSE.txt for license information. diff --git a/flang/docs/FlangOptionsMan.td b/flang/docs/FlangOptionsMan.td new file mode 100644 index 0000000000000..86cde115eb6f5 --- /dev/null +++ b/flang/docs/FlangOptionsMan.td @@ -0,0 +1,23 @@ +//==--- FlangOptionsMan.td - Options 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!! + ------------------------------------------------------------------- +}]; + + string Program = "Flang"; + list VisibilityMask = ["FlangOption"]; + list IgnoreFlags = ["HelpHidden", "Unsupported", "Ignored"]; +} + +#define GENERATING_DOCS +include "Options.td" diff --git a/flang/docs/conf.py b/flang/docs/conf.py index a470d8afd7186..0942dbf70ff16 100644 --- a/flang/docs/conf.py +++ b/flang/docs/conf.py @@ -233,7 +233,7 @@ ( "index", "flang", - "Flang Documentation (In Progress)", + "flang - the Flang Fortran compiler", ["Flang Contributors"], 1, )