flang/docs/DesignGuideline.md

   1 <!--===- docs/DesignGuideline.md
   2
   3    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4    See https://llvm.org/LICENSE.txt for license information.
   5    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6
   7 -->
   8 # Design Guideline
   9
  10 ```{contents}
  11 ---
  12 local:
  13 ---
  14 ```
  15 ## Documenting the design
  16
  17 ### Designing support for a new feature
  18
  19 When working on a new feature in flang, some design document should
  20 be produced before submitting patches to the code. Note that new features
  21 that need support in flang are listed in llvm github project
  22 [Flang features to be implemented](https://github.com/orgs/llvm/projects/12).
  23
  24 The preferred organization of such documents is:
  25 1) Problem description
  26 2) Proposed solution
  27 3) Implementation details overview
  28 4) Testing plan
  29
  30 If several solutions can be considered, it is best to briefly describe the
  31 alternate solutions in 2) and why they were not retained.
  32
  33 The design document should be added to the `docs` folder as a markdown document,
  34 ideally using the name of the feature as the document name. Its approval on
  35 Phabricator is the pre-requisite to submitting patches implementing new
  36 features.
  37
  38 An RFC on flang https://discourse.llvm.org can first be made as one sees fit,
  39 but this document should still be produced to summarize, organize, and formalize
  40 the discussions. If a related discourse RFC was made it is a good idea to give a
  41 link to it in the document for future reference. If no RFC was made before
  42 sending the design document for review, it is highly encouraged to make a small
  43 announcement on https://discourse.llvm.org with a link to the Phabricator
  44 design document review.
  45
  46 The Testing Plan should briefly describe what aspects will be tested with LLVM
  47 unit test tools (see
  48 [LLVM Testing Guide](https://llvm.org/docs/TestingGuide.html)), and if some
  49 existing end-to-end test suite or application can be used to validate the
  50 feature implementation.
  51
  52 Features impacting projects outside of flang (like work OpenMP or OpenACC that
  53 may require touching parts outside of flang tree) should follow [the general
  54 LLVM process](https://llvm.org/docs/DeveloperPolicy.html#making-a-major-change),
  55 or the related subproject process. There should still be a related flang design
  56 document if part of the solution impacts flang in significant ways (e.g. if the
  57 changes in the code that lowers the parse-tree to OpenMP and FIR dialects are
  58 not straightforwardly mapping parse-tree nodes to dialect operations).
  59
  60 ### Updating the implementation solution of a feature
  61
  62 When doing a significant change to the implementation solution for a feature,
  63 the related design document should be updated so that it will justify the new
  64 solution.
  65
  66 ## Design tips
  67
  68 ### Design document style
  69
  70 The document does not have to be long. It is highly encouraged to:
  71 - Stick to well-defined Fortran terms when talking about Fortran
  72   (definitions of these terms can be found in Section 3 of Fortran 2018
  73   standard).
  74 - Be precise (e.g., pointing to the standard reference or constraint numbers).
  75   References should currently be given against the Fortran 2018 standard
  76   version.
  77 - Illustrate with a few small Fortran code snippets if applicable
  78 - When dealing with lowering, illustrate lowering output with a few FIR
  79   and LLVM IR code snippets.
  80 - Illustrations do not have to be fully functional programs, it is better to
  81   keep them small and focused on the feature. More detailed expectations
  82   can be added in a second time or in parallel as LIT tests for example.
  83
  84 ### Thinking through the design of a Fortran feature
  85
  86 Below is a set of suggested steps that one can take to fully apprehend a
  87 Fortran feature before writing a design for its implementation in flang.
  88
  89 - Identify the relevant sections and constraints in the standard.
  90 - Write Fortran programs using the feature and, if possible,
  91   verify your expectations with existing compilers.
  92 - Check if the related constraints (Cxxx numbers in the standard) are enforced
  93   by semantic checks in the compiler. If not, it is a good idea to start by
  94   adding the related checks (this does not require writing a design document).
  95 - Identify if the feature affects compatibility with programs compiled by other
  96   Fortran compilers, or if a given solution for flang could not be changed in
  97   the future without breaking compatibility with programs previously compiled
  98   with flang. It is not a goal to be 100% binary compatible with other
  99   compilers outside of Fortran 77, but sources of incompatibility should be
 100   known and justified. By binary compatibility, it is meant that F77 libraries
 101   compiled with other Fortran compilers (at least gfortran) should link with
 102   flang compiled code and vice-versa.
 103 - Identify related features, or contexts that matter for the feature (e.g,
 104   does being in an internal procedure, a module, a block… affect what should
 105   happen?).
 106 - Not everything has to be inlined code, delegating part of the work to the
 107   Fortran runtime may be a solution. Identify the relevant Fortran runtime
 108   API if any.
 109 - For inlined code, consider what should happen when generating the FIR,
 110   what should happen in the FIR transformation passes (FIR to FIR),
 111   and what should happen when lowering the FIR to LLVM IR.
 112 - For inlined ops, look at how the existing dialects can be reused.
 113   If new FIR operations are required, justify their purpose.
 114 - Look at the related representation in Semantics (e.g., is some information
 115   from the parse tree, the Symbol or evaluate::Expr required? Are there tools
 116   to query this information easily?).