https://github.com/matthalex/fortran-project-template
An opinionated one-stop shop for new and old Fortran projects, offering seamless compiling, building, packaging, linting, formatting, and more, with modern tools like FPM, pre-commit, fprettify, and ford.
https://github.com/matthalex/fortran-project-template
fortran fortran-package-manager python template
Last synced: 5 months ago
JSON representation
An opinionated one-stop shop for new and old Fortran projects, offering seamless compiling, building, packaging, linting, formatting, and more, with modern tools like FPM, pre-commit, fprettify, and ford.
- Host: GitHub
- URL: https://github.com/matthalex/fortran-project-template
- Owner: MatthAlex
- License: mit
- Created: 2024-06-12T15:10:35.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2024-11-09T11:57:20.000Z (6 months ago)
- Last Synced: 2024-11-09T12:20:53.562Z (6 months ago)
- Topics: fortran, fortran-package-manager, python, template
- Language: Fortran
- Homepage: https://github.com/MatthAlex/fortran-project-template
- Size: 20.5 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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?](#why-this-template)
- [Getting Started](#getting-started)
- [Code Quality](#code-quality)
- [Documentation](#documentation)
- [Development Tools](#development-tools)
- [Contributing](#contributing)
- [Contact](#contact)
- [License](#license)
- [Appendix](#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):
```sh
module load gcc
# or
module load intel
```
1. Create and activate a Python environment:
```sh
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:
```sh
pip3 install . # Install runtime dependencies from pyproject.toml
pip3 install .[dev] # Install development dependencies
```
3. Run the tests and main program:
```sh
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](./docs/MIGRATION.md).
## Code Quality
This template integrates several tools to maintain high code quality:
### IDE Integration
- Real-time error detection and linting via the Modern Fortran extension and `fortls` language server
- Intelligent code completion and navigation
- Code formatting with `fprettify` for consistent style
### Automated Checks
- Pre-commit hooks run tests and quality checks before git commit and push
- Automated testing with `fpm test`
- Compile-time checks with `fpm build` (debug/release modes)
For detailed configuration and usage instructions, see [TOOLING.md](./docs/TOOLING.md).
## Documentation
Automated documentation is generated by using the [ford](https://github.com/Fortran-FOSS-Programmers/ford) package. For example config files and usage, see [here](https://forddocs.readthedocs.io/en/latest/index.html).
To generate dcoumentation for this sample project, and then view it on the browser, run:
```sh
ford ford.md
firefox docs/ford/index.html # Alternatively, use your preferred browser
```
## Development Tools
The template includes preconfigured development tools and settings for Modern Fortran development, with optimized configurations for:
- VS Code integration
- Language server features
- Code formatting
- Automated testing
- Package management
For detailed setup instructions and tool configurations, see [TOOLING.md](./docs/TOOLING.md).
## Contributing
Contributions from the community are welcome. To contribute, consider opening an issue or pull request with changes and suggestions.
## Contact
For questions or suggestions, please contact us at [email]([email protected]) or open an issue.
## License
The project is operating under an [MIT](./LICENSE) 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
```sh
$ tree -Ia '__pycache__|.git|.pytest_cache|.venv|build|.gen*|ford'
.
├── app # The main program driver(s) resides here
│ └── main.f90
├── docs
│ ├── MIGRATION.md
│ └── TOOLING.md
├── ford.md # FORD config file
├── .fortls # VSCode Modern Fortran config file
├── 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
├── 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](https://github.com/urbanjost/easy).
- [`fpm`](https://github.com/fortran-lang/fpm)
- [Modern Fortran extension](https://github.com/fortran-lang/vscode-fortran-support)
- [`fortls`](https://github.com/fortran-lang/fortls)
- [`fprettify`](https://github.com/pseewald/fprettify)
- [`pre-commit`](https://pre-commit.com/)
- [`ford`](https://github.com/Fortran-FOSS-Programmers/ford)
- [`uv`](https://github.com/astral-sh/uv)