[flang-commits] [flang] [flang] flang manpage overhaul (PR #144948)
Paul Osmialowski via flang-commits
flang-commits at lists.llvm.org
Fri Jun 20 09:01:12 PDT 2025
https://github.com/pawosm-arm updated https://github.com/llvm/llvm-project/pull/144948
>From e590330534d78c9a8060828920af25e5a94e1d65 Mon Sep 17 00:00:00 2001
From: Paul Osmialowski <pawel.osmialowski at arm.com>
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 | 75 +++++++++++++++++++++++--------
flang/docs/FlangOptionsDocs.td | 2 +-
flang/docs/FlangOptionsMan.td | 23 ++++++++++
flang/docs/conf.py | 2 +-
5 files changed, 101 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..0df53b45b6418 100644
--- a/flang/docs/CommandGuide/index.rst
+++ b/flang/docs/CommandGuide/index.rst
@@ -1,22 +1,61 @@
-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 Fortran compiler
+============================
+
+SYNOPSIS
+--------
+
+:program:`flang` [*options*] *filename ...*
+
+DESCRIPTION
+-----------
+
+:program:`flang` is a Fortran compiler which encompasses preprocessing, parsing,
+optimization, code generation, assembly, and linking. Depending on which
+high-level mode setting is passed, Flang will stop before doing a full link.
+While Flang is highly integrated, it is important to understand the stages of
+compilation, to understand how to invoke it. These stages are:
+
+Driver
+ The flang executable is actually a small driver which controls the overall
+ 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 handles tokenization of the input source file, macro expansion,
+ #include expansion and handling of 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 as well and determine whether
+ the code is well formed. This stage is responsible for generating most of
+ the compiler warnings as well as parse errors.
+
+Code Generation and Optimization
+ This stage creates the intermediate code (known as "LLVM IR") and ultimately
+ to machine code. This phase is responsible for optimizing the generated
+ code and handling target-specific code generation. The output of this stage
+ is typically called a ".s" file or "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 of calling the target assembler.
+
+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
+ called a ".o" file or "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 called
+ 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<string> VisibilityMask = ["FlangOption"];
+ list<string> IgnoreFlags = ["HelpHidden", "Unsupported", "Ignored"];
+}
+
+#define GENERATING_DOCS
+include "Options.td"
diff --git a/flang/docs/conf.py b/flang/docs/conf.py
index a470d8afd7186..d9c8ffb5430aa 100644
--- a/flang/docs/conf.py
+++ b/flang/docs/conf.py
@@ -233,7 +233,7 @@
(
"index",
"flang",
- "Flang Documentation (In Progress)",
+ "flang - the Fortran compiler",
["Flang Contributors"],
1,
)
More information about the flang-commits
mailing list