GitHub copilot instructions examples

Readme.md

Locations of per-user instructions files

$HOME/.copilot/instructions/NAME.instructions.md

$HOME/.github/copilot-instructions.md

CMAKE.instructions.md

name	CMake Standards
description	Coding conventions for CMake files
applyTo	**/*.cmake,**/CMakeLists.txt

Editing rules

• Assume CMake 3.26 or newer is available cmake_minimum_required(VERSION 3.26)
• Use cmake_path() instead of get_filename_component()
• Always keep in mind the project might be consumed by FetchContent, therefore paths like CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR should only be used with caution

CMake and CTest binary exectuables

CMake and CTest executables are typically located in the following directories based on the operating system and installation method:

• macOS with Homebrew: /opt/homebrew/bin/
• Linux with apt: /usr/bin/
• Linux with snap: /snap/bin/
• Windows with CMake installer: $env:ProgramFiles/CMake/bin/

CMake environment variables

When available, we prefer to use Ninja generator, which is specified using the CMAKE_GENERATOR environment variable: CMAKE_GENERATOR=Ninja

copilot-instructions.md

Editing rules

• Except for trivial or auto-fix edits, make a regression test to ensure the change does not break existing functionality. When done, suggest test code to add to the test suite.

Compiler environment selection

On macOS and Linux, we typically have compiler environment setup scripts in our home directory. Some examples:

• GCC + Gfortran, source ~/gcc.sh
• GCC 15 (including Gfortran 15) source ~/gcc-15.sh
• Homebrew Clang + Flang source ~/clang-homebrew.sh
• oneAPI Linux: source ~/oneapi.sh

On Windows, compiler environments likewise are setup by PowerShell script we provide like:

• GCC + GFortran via MSYS2, . $HOME/gcc_ucrt.ps1
• LLVM Flang via MSYS2, . $HOME/clang_arm.ps1
• Intel oneAPI, . $HOME/oneapi.ps1

CMake

• we normally use the Ninja generator with CMake by environment variable CMAKE_GENERATOR=Ninja
• we run CTest in parallel with the --parallel option

CMake and CTest executables are typically located in the following directories based on the operating system and installation method:

• macOS with Homebrew: /opt/homebrew/bin/
• Linux with apt: /usr/bin/
• Linux with snap: /snap/bin/
• Windows with CMake installer: $env:ProgramFiles/CMake/bin/

Fortran compilers

While Fortran by design is platform independent, certain compilers are available only on certain OS.

macOS Fortran compilers

On macOS, GNU gfortran brew install gcc and LLVM Flang brew install flang are the usual compilers. Resolve them with command -v gfortran and command -v flang. With Homebrew, they're under "/opt/homebrew/bin/" by default.

Linux Fortran compilers

On Linux, in addition to gfortran and flang, the Intel oneAPI Fortran compiler ifx may be available. If oneAPI is not already enabled (indicated by environment variable FC=ifx or environment variable CMPLR_ROOT set to the oneapi compiler root dirctory) then the oneapi-vars.sh must be sourced. The default location is /opt/intel/oneapi/<oneapi_version>/oneapi-vars.sh.

NVIDIA HPC SDK with Fortran compiler nvfortran may be available. The default location is under /opt/nvidia/hpc_sdk. A source script to enable nvfortran is like:

NVCOMPILERS=/opt/nvidia/hpc_sdk

export MODULEPATH=$NVCOMPILERS/modulefiles:$MODULEPATH

# Debian-like distros e.g. Ubuntu may need "apt install environment-modules" and then reboot
module load nvhpc

Windows Fortran compilers

GCC and Flang are available via MSYS2. Intel oneAPI may be available under ${Env:ProgramFiles(x86)}/Intel/oneAPI. As on Linux, the oneAPI environment is set by running ${Env:ProgramFiles(x86)}/Intel/oneAPI/<oneapi_version>/oneapi-vars.bat

MATLAB program location

• macOS: $HOME/Applications/MATLAB_R20*.app/ or /Applications/MATLAB_R20*.app/
• Linux: $HOME/MATLAB/R20*/bin or /opt/MATLAB/R20*/bin or $HOME/.local/bin/ are among places to look for matlab executable
• Windows: $Env:ProgramFiles/MATLAB/R20*/bin/

FORTRAN-FIXED.instructions.md

name	Fixed-form Fortran
description	Fixed-form Fortran column rules and portability checks
applyTo	**/*.f,**/*.for,**/*.F,**/*.FOR

These rules apply only to fixed-form sources (.f, .for, .F, .FOR). Do not apply them to free-form .f90 / .F90 files.

Columns

• Columns 1–5: optional statement label, integer, typically right-justified. Not a line number. Leave these blank on a continuation line.
• Column 6: continuation. Any character except blank or 0. Use & for new continuations. Do not rewrite an existing non-blank continuation character just to make it &.
• Columns 7–72: statement text. Code here must not start before column 7.
• Columns 73 onward are outside the statement field. Text there is truncated by a standard fixed-form compiler. Treat that as a severe error, including comments that were meant to be significant.
• Comment lines: C, c, or * in column 1. A ! comment is also valid. Do not use tabs. A tab does not advance to a reliable column and will shift the statement field.

Checking truncation

Error on fixed-form truncation when the compiler can do it:

• gfortran: -Werror=line-truncation
• ifx: -warn truncated_source -diag-error:5194

Flang and nvfortran don't currently have a flag to error on truncation. Finish fixed-form edits by compiling the touched files with gfortran -Werror=line-truncation.

Edits

• When a line does not fit in columns 7–72, break it and put & in column 6 of the continuation line. Do not let code spill past column 72.

After a non-trivial edit, compile with a second compiler, and always include the gfortran -Werror=line-truncation check for fixed-form files.

FORTRAN.instructions.md

name	Fortran
description	Fortran portability checks
applyTo	**/*.f,**/*.for,**/*.F,**/*.FOR,**/*.f90,**/*.F90

These rules apply only to all Fortran source files (fixed- and free-form).

Edits

• We don't indent procedure bodies; start them at the first column.
• We indent if, select case, do, and other block constructs by two spaces.
• Replace tabs with spaces so that labels, the continuation column, and the statement field land on the real columns.
• Diagnostics should go to standard error, not standard output. In that scoping unit add use, intrinsic :: iso_fortran_env, only: error_unit and write with write(error_unit, FMT).
• If a termination is clearly an error, use error stop (Fortran 2008) instead of stop.

Prefer standard, portable Fortran when changing a file. Non-standard extensions that one compiler accepts may be a compile or run error on another. After a non-trivial edit, compile with a second compiler and run tests if possible to check for portability issues.

Fortran namelist is an elegant way to store and retrieve groups of variables in a structured manner. It allows for easy input and output of related data without having to write extensive parsing code. When old code is being modernized, consider converting ad-hoc input/output routines to use namelists for better readability and maintainability. However, namelists aren't appropriate for large data arrays, which may be better as "stream" I/O if not needed to use existing data files.

Fortran open(access='direct') and open(access='sequential') are common sources of portability issues, as different compilers may have varying support and behavior for these access modes. When there aren't existing data files to read, it's preferred to use open(access='stream') for better portability.

MATLAB.instructions.md

name	MATLAB Standards
description	Coding conventions for MATLAB files
applyTo	**/*.m

• We assume Matlab R2022b or newer is always available as a starting base level
• Where there is a benefit, suggest functions available within the last two releases of Matlab. For example, if R2026b is the current release and there's a new feature in R2026a that's useful, suggest it but have a fallback plan or warning for older releases.
• Where any kind of package setup is needed, use buildfile.m

Editing rules

• Except for trivial or auto-fix edits, make a regression test to ensure the change does not break existing functionality. When done, suggest test code to add to the test suite.
• Use name=value syntax for function arguments where applicable.
• Linting should be done with Matlab factory function codeIssues()

Indent style

• don't indent class definitions; start them at the first column.
• don't indent function body; start them at the first column.
• otherwise use 2 spaces for indentation (e.g. for for-loops, if statements, etc.)
• don't use semicolons where not needed to terminate, e.g. "disp()", "error()", "testCase.verifyEqual()" and similar

External language support

• We do NOT assume Matlab has Java available (as of MATLAB R2026b, Mathworks doesn't include Java from the factory anymore)
• We do not assume the user has Python configured with MATLAB. The Matlab to Python interface has stability issues that can crash Matlab if Python isn't strictly compatible - we use Python from Matlab in standalone scripts or when the user indicates they want to use Python in a function.
• We do not assume .NET is available, because on macOS and Linux .NET needs to be installed by the user for MATLAB.

Matlab Test principles

• Matlab tests are run for our Matlab projects generally like matlab -batch "buildtool test" from the top level of the project directory where buildfile.m is.
• "buildtool test" generally runs all project tests, but you can choose to run individual tests with runtests() intrinsic function as usual.
• Suggest features enabled by Matlab Test but with a fallback or at least still functioning without Matlab Test
• write class-based tests and assume Matlab R2024b or newer is available for the testing

MATLAB location

• macOS: under $HOME/Applications/MATLAB_R20*.app/ or /Applications/MATLAB_R20*.app/
• Windows: $Env:ProgramFiles/MATLAB/R20*.app/