Skip to content

Add a migration guide for the ROCm-packaged Fortran bindings - #548

Draft
amontoison wants to merge 1 commit into
developfrom
docs/migration-guide
Draft

amontoison wants to merge 1 commit into
developfrom
docs/migration-guide

Conversation

@amontoison

@amontoison amontoison commented Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Adds docs/how-to/migration-guide.rst, a how-to for users moving from hipFORT to the Fortran bindings that ship inside ROCm (rocm-systems and rocm-libraries), in the spirit of the layout previewed in #540: one self-contained module per library, ROCm only.

What the page covers

  • The two edits. Rename the use statements (use hipfort_rocblas becomes use rocblas, helper modules folded in), and link the per-library Fortran archive (find_package(rocblas) gives roc::rocblas_fortran). Both as tables, plus a sed recipe for the rename and an explicit list of the cases it deliberately leaves to review (two use hip lines, files that used only hipfort_check, roctx and cuda_errors, fixed form, preprocessor guards).
  • Build options. BUILD_FORTRAN_BINDINGS, BUILD_FORTRAN_TESTS, and the tri-state FORTRAN_ARRAY_INTERFACES that replaces HIPFORT_USE_FPOINTER_INTERFACES plus HIPFORT_ASSUMED_RANK, with a table mapping every HIPFORT_* option to its successor.
  • Compiler support. Why a .mod is compiler- and version-specific, the per-compiler install layout, raw link lines for amdflang and gfortran, and how to rebuild one library's binding from source without rebuilding the C library.
  • What does not change, the special cases (in-tree vendor modules, CUDA), and an FAQ including the old/new coexistence matrix and the fixed-form question.

Also wires the page into docs/index.rst and docs/sphinx/_toc.yml.in under How to.

Status

Draft. The page states a ROCm 10.2 / 11.0 timeline and several conventions that are settled in the design document but not yet implemented in rocm-systems / rocm-libraries, so the content should be reviewed against whatever actually lands there.

--> Preview <--

Document the move from hipFORT to the bindings that ship inside ROCm
(rocm-systems and rocm-libraries), in the spirit of the layout previewed
in #540: one self-contained module per library, ROCm only.

The guide covers the two edits a consumer has to make (the `use`
statement rename, with a sed recipe and the cases it deliberately leaves
to review; and the per-library Fortran archive and CMake target), the
build options, the per-compiler install layout and how to rebuild a
binding for a non-amdflang compiler, what does not change, and an FAQ
covering the old/new coexistence.

Wire the page into the docs index and the Sphinx TOC.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant