Include

Definition

Include file handling and resolution for the fpx Fortran preprocessor.

This module implements robust and standard-compliant processing of #include directives with full support for:

• Both forms: #include "file.h" (local/user) and #include <file.h> (system)
• Proper search order: quotes search source dir first, angle brackets skip source dir
• Relative paths resolved against the directory of the parent source file
• Search in user-defined include directories (globalincludedir)
• Search in system PATH environment variable directories
• Fallback to current working directory
• Proper error reporting with file name and line number context
• Recursion safety through integration with the main preprocessor loop
• Seamless integration via the abstract preprocess procedure pointer

The routine correctly strips quotes or angle brackets, performs path resolution, checks file existence, opens the file, and recursively invokes the main preprocessing engine on the included content using the same macro environment.

Search Order

For #include "file":

1. Directory of the parent source file
2. Directories specified by -I or -Y options (globalincludedir)
3. Directories in INCLUDE environment variable
4. Current working directory

For #include <file>:

1. Directories specified by -I or -Y options (globalincludedir)
2. Directories in INCLUDE environment variable
3. Current working directory

Examples

1. Include a local header from the same directory using quotes:

   #include 
   !> fpx will look for ./config.h relative to the current source file first

2. Include a system header using angle brackets:

   #include <stdlib.h>
   !> fpx will skip the source directory and search -I paths, then PATH

3. Using from the driver program (adding include paths):

   global%includedir = ['/usr/include', './include', './headers']
   call preprocess('main.F90', 'main.f90')
   !> All #include <...> will search these directories in order

4. Verbose error reporting when a file is not found:

   $ fpx -v src/utils.F90
   Error: Cannot find include file 'missing.h' at src/utils.F90:27

Data Types
interface	read_unit
	Abstract interface for the main preprocessing routine (used for recursion) Allows handle_include to recursively call the top-level preprocess_unit routine without creating circular module dependencies. More...

Methods

get_system_paths()

character(:) function, dimension(:), allocatable get_system_paths

private

Get system include paths from PATH environment variable Returns an array of directory paths found in PATH.

Returns

Array of path strings, empty if PATH not set

Remarks

Definition at line 251 of file include.f90.

handle_include()

recursive subroutine, public handle_include	(	type(context), intent(in)	ctx,
		integer, intent(in)	ounit,
		procedure(read_unit)	preprocess,
		type(macro), dimension(:), intent(inout), allocatable	macros,
		character(*), intent(in)	token )

Process a include directive encountered during preprocessing Resolves the include file name (quoted or angle-bracketed), searches for the file using standard C preprocessor rules:

• Quoted includes search: parent directory, -I paths, PATH, cwd
• Angle bracket includes search: -I paths, PATH, cwd (skips parent directory) Opens the file and recursively preprocesses its contents into the output unit.

Parameters

[in]	ctx	Context line containing the include directive
[in]	ounit	Output unit where preprocessed content is written
[in]	preprocess	Procedure pointer to the main line-by-line preprocessor
[in,out]	macros	Current macro table (shared across recursion levels)
[in]	token	Usually 'INCLUDE' – the directive keyword

Remarks

Definition at line 116 of file include.f90.