diff --git a/flang/docs/DesignGuideline.md b/flang/docs/DesignGuideline.md new file mode 100644 --- /dev/null +++ b/flang/docs/DesignGuideline.md @@ -0,0 +1,115 @@ + +# Design Guideline + +```eval_rst +.. contents:: + :local: +``` +## Documenting the design + +### Designing support for a new feature + +When working on a new feature in flang, some design document should +be produced before submitting patches to the code. Note that new features +that need support in flang are listed in llvm github project +[Flang features to be implemented](https://github.com/orgs/llvm/projects/12). + +The preferred organization of such documents is: +1) Problem description +2) Proposed solution +3) Implementation details overview +4) Testing plan + +If several solutions can be considered, it is best to briefly describe the +alternate solutions in 2) and why they were not retained. + +The design document should be added to the `docs` folder as a markdown document, +ideally using the name of the feature as the document name. Its approval on +Phabricator is the pre-requisite to submitting patches implementing new +features. + +An RFC on flang https://discourse.llvm.org can first be made as one sees fit, +but this document should still be produced to summarize, organize, and formalize +the discussions. If a related discourse RFC was made it is a good idea to give a +link to it in the document for future reference. If no RFC was made before +sending the design document for review, it is highly encouraged to make a small +announcement on https://discourse.llvm.org with a link to the Phabricator +design document review. + +The Testing Plan should briefly describe what aspects will be tested with LLVM +unit test tools (see +[LLVM Testing Guide](https://llvm.org/docs/TestingGuide.html)), and if some +existing end-to-end test suite or application can be used to validate the +feature implementation. + +Features impacting projects outside of flang (like work OpenMP or OpenACC that +may require touching parts outside of flang tree) should follow [the general +LLVM process](https://llvm.org/docs/DeveloperPolicy.html#making-a-major-change), +or the related subproject process. There should still be a related flang design +document if part of the solution impacts flang in significant ways (e.g. if the +changes in the code that lowers the parse-tree to OpenMP and FIR dialects are +not straightforwardly mapping parse-tree nodes to dialect operations). + +### Updating the implementation solution of a feature + +When doing a significant change to the implementation solution for a feature, +the related design document should be updated so that it will justify the new +solution. + +## Design tips + +### Design document style + +The document does not have to be long. It is highly encouraged to: +- Stick to well-defined Fortran terms when talking about Fortran + (definitions of these terms can be found in Section 3 of Fortran 2018 + standard). +- Be precise (e.g., pointing to the standard reference or constraint numbers). + References should currently be given against the Fortran 2018 standard + version. +- Illustrate with a few small Fortran code snippets if applicable +- When dealing with lowering, illustrate lowering output with a few FIR + and LLVM IR code snippets. +- Illustrations do not have to be fully functional programs, it is better to + keep them small and focused on the feature. More detailed expectations + can be added in a second time or in parallel as LIT tests for example. + +### Thinking through the design of a Fortran feature + +Below is a set of suggested steps that one can take to fully apprehend a +Fortran feature before writing a design for its implementation in flang. + +- Identify the relevant sections and constraints in the standard. +- Write Fortran programs using the feature and, if possible, + verify your expectations with existing compilers. +- Check if the related constraints (Cxxx numbers in the standard) are enforced + by semantic checks in the compiler. If not, it is a good idea to start by + adding the related checks (this does not require writing a design document). +- Identify if the feature affects compatibility with programs compiled by other + Fortran compilers, or if a given solution for flang could not be changed in + the future without breaking compatibility with programs previously compiled + with flang. It is not a goal to be 100% binary compatible with other + compilers outside of Fortran 77, but sources of incompatibility should be + known and justified. By binary compatibility, it is meant that F77 libraries + compiled with other Fortran compilers (at least gfortran) should link with + flang compiled code and vice-versa. +- Identify related features, or contexts that matter for the feature (e.g, + does being in an internal procedure, a module, a block… affect what should + happen?). +- Not everything has to be inlined code, delegating part of the work to the + Fortran runtime may be a solution. Identify the relevant Fortran runtime + API if any. +- For inlined code, consider what should happen when generating the FIR, + what should happen in the FIR transformation passes (FIR to FIR), + and what should happen when lowering the FIR to LLVM IR. +- For inlined ops, look at how the existing dialects can be reused. + If new FIR operations are required, justify their purpose. +- Look at the related representation in Semantics (e.g., is some information + from the parse tree, the Symbol or evaluate::Expr required? Are there tools + to query this information easily?).