Fortran Project Template

Modern Fortran development made simple - an opinionated, batteries-included project template that brings contemporary development practices to Fortran projects.

• Why This Template?
• Getting Started
• Style Guide and Best Practices
• Development Tools
• Documentation
• Contributing
• License
• Appendix

Why This Template?

Fortran remains a crucial language in scientific computing, engineering, and high-performance computing. However, while the language has modernized significantly, the development workflow often lags behind contemporary software engineering practices. This template bridges that gap by providing:

• modern development features like code completion, automated testing, and documentation generation out of the box.
• seamless integration of Fortran codebases with modern DevOps practices, including continuous integration, code quality checks, and automated documentation.
• IDE-like tooling integration with VS Code and extensions.

Key Benefits

• 🚀 Instant Modern Setup: Get a fully configured development environment in minutes, not days
• 🔍 Code Intelligence: Real-time error detection, code completion, and refactoring support via VS Code integration
• 📊 Quality Assurance: Automated testing, formatting, and linting integrated with git workflow
• 📚 Automated Documentation: Generate professional documentation from your code comments
• 🛠️ Best Practices Built-in: Pre-configured tools enforce consistent code style and quality
• 🔄 Modern Workflow: Brings git-based workflow, dependency management, and automated builds to Fortran

Traditional vs Modern Fortran Development

Aspect	Traditional Approach	With This Template
Setup Time	Hours/days configuring tools	Minutes with pre-configured environment
Error Detection	At compile time	Real-time as you type
Code Style	Manual enforcement	Automated formatting and checks
Documentation	Manual maintenance	Generated from code comments
Testing	Often manual or ad-hoc	Automated with each commit
Dependencies	Manual management	Handled by package manager

Getting Started

Prerequisites

• Linux OS or WSL2 via Windows
• GFortran or oneAPI Fortran compiler

Optional

• VS Code installation
• Modern Fortran extension installation

Step-by-step instructions

0. Load compiler modules (if on a compute cluster):

   module load gcc
   # or
   module load intel
   

1. Create and activate a Python environment:

   python3 -m venv .venv
   source .venv/bin/activate
   

   Remember to activate your enviroment before runtime or development tasks.

2. Install the runtime and development packages:

   pip3 install .  # Install runtime dependencies from pyproject.toml
   pip3 install .[dev]  # Install development dependencies
   

3. Run the tests and main program:

   fpm test  # by default it uses gcc/gfortran to compile and run
   fpm run
   

4. Migrate your project:

   See a step-by-step guide on how to migrate your project.

Style Guide and Best Practices

The integrated tooling has been configured to automatically conform the code to a set of prescribed rules.

These rules are roughly outlined in the STYLE_GUIDE.md.

Development Tools

The template includes preconfigured development tools and settings for Modern Fortran development, with configurations for:

• VS Code integration with Modern Fortran extension
• Language server features with fortls
• Code formatting with fprettify
• Automated testing with fpm test
• Package management with fpm

For detailed setup instructions and tool configurations, see TOOLING.md.

Profiling

For information on profiling, see PROFILING.md.

Documentation

Automated documentation is generated by using the ford package. For example config files and usage, see here.

To generate dcoumentation for this sample project, and then view it on the browser, run:

ford ford.md
firefox docs/ford/index.html  # Alternatively, use your preferred browser

Contributing

Contributions from the community are welcome. To contribute, consider opening an issue or pull request with changes and suggestions.

License

The project is operating under an MIT license. You are free to use, modify, and distribute the code as needed for your project. Feel free to adapt and customize it to suit your requirements.

Appendix

Project Directory Structure

$ tree -Ia '__pycache__|.git|.pytest_cache|.venv|build|.gen*|ford'
.
├── app  # The main program driver(s) resides here
│   └── main.f90
├── docs
│   ├── MIGRATION.md
│   ├── PROFILING.md
│   ├── STYLE_GUIDE.md
│   └── TOOLING.md
├── .editorconfig
├── ford.md  # FORD config file
├── .fortls  # VSCode Modern Fortran config file
├── fpm.rsp
├── fpm.toml  # Fortran Package Manager config file
├── .fprettify.rc  # fprettify config file
├── .gitignore  # Git ignore list of files and directories
├── LICENSE
├── .pre-commit-config.yaml  # pre-commit config file
├── profiling
│   └── template_mpi.json
├── pyproject.toml  # config file
├── README.md  # you are here!
├── src  # All source code files are placed in here, except main driver
│   └── first_steps.f90
├── test  # All tests are placed in here
│   └── check.f90
└── .vscode  # Holds VSCode configs and runtime/debugging tasks
    ├── extensions.json  # simply populates the "Recommended" Extensions tab
    └── settings.json  # also referred to as "Workspace Settings (JSON)"

References and Links

This repository takes a lot of inspiration (and actual code) from easy.

• fpm
• Modern Fortran extension
• fortls
• fprettify
• pre-commit
• ford
• uv