# CMakeAddFortranSubdirectory

This module provides a command to add a Fortran project located in a subdirectory.

Load this module in a CMake project with:

    include(CMakeAddFortranSubdirectory)

## Commands

This module provides the following command:

cmake_add_fortran_subdirectory

  Adds a Fortran-only subproject from subdirectory to the current project:

      cmake_add_fortran_subdirectory(
        <subdir>
        PROJECT <project-name>
        ARCHIVE_DIR <dir>
        RUNTIME_DIR <dir>
        LIBRARIES <libs>...
        LINK_LIBRARIES
          [LINK_LIBS <lib> <deps>...]...
        [CMAKE_COMMAND_LINE <flags>...]
        NO_EXTERNAL_INSTALL
      )

  This command checks whether the current compiler supports Fortran or attempts to locate a Fortran compiler. If a compatible Fortran compiler is found, the Fortran project located in `<subdir>` is added as a subdirectory to the current project.

  If no Fortran compiler is found and the compiler is `MSVC`, it searches for the MinGW `gfortran` compiler. In this case, the Fortran project is built as an external project using MinGW tools, and Fortran-related imported targets are created. This setup works only if the Fortran code is built as a shared DLL library, so the `BUILD_SHARED_LIBS` variable is enabled in the external project. Additionally, the `CMAKE_GNUtoMS` variable is set to `ON` to ensure that Microsoft-compatible `.lib` files are created.

  The options are:

  `PROJECT`

    The name of the Fortran project as defined in the top-level `CMakeLists.txt` located in `<subdir>`.

  `ARCHIVE_DIR`

    Directory where the project places `.lib` archive files. A relative path is interpreted as relative to `CMAKE_CURRENT_BINARY_DIR`.

  `RUNTIME_DIR`

    Directory where the project places `.dll` runtime files. A relative path is interpreted as relative to `CMAKE_CURRENT_BINARY_DIR`.

  `LIBRARIES`

    Names of library targets to create or import into the current project.

  `LINK_LIBRARIES`

    Specifies link interface libraries for `LIBRARIES`. This option expects a list of `LINK_LIBS <lib> <deps>...` items, where:

    - `LINK_LIBS` marks the start of a new pair

    - `<lib>` is a library target.

    - `<deps>...` represents one or more dependencies required by `<lib>`.

  `CMAKE_COMMAND_LINE`

    Additional command-line flags passed to `cmake(1)` command when configuring the Fortran subproject.

  `NO_EXTERNAL_INSTALL`

    Prevents installation of the external project.

    Note

    The `NO_EXTERNAL_INSTALL` option is required for forward compatibility with a future version that supports installation of the external project binaries during `make install`.

## Examples

Adding a Fortran subdirectory to a project can be done by including this module and calling the `cmake_add_fortran_subdirectory()` command. In the following example, a Fortran project provides the `hello` library and its dependent `world` library:

    include(CMakeAddFortranSubdirectory)

    cmake_add_fortran_subdirectory(
      fortran-subdir
      PROJECT FortranHelloWorld
      ARCHIVE_DIR lib
      RUNTIME_DIR bin
      LIBRARIES hello world
      LINK_LIBRARIES
        LINK_LIBS hello world # hello library depends on the world library
      NO_EXTERNAL_INSTALL
    )

    # The Fortran target can be then linked to the main project target.
    add_executable(main main.c)
    target_link_libraries(main PRIVATE hello)

## See Also

There are multiple ways to integrate Fortran libraries. Alternative approaches include:

- The `add_subdirectory()` command to add the subdirectory directly to the build.

- The `export()` command can be used in the subproject to provide Imported Targets or similar for integration with other projects.

- The `FetchContent` or `ExternalProject` modules when working with external dependencies.