TOML Fortran verwenden#

Dieses Tutorial zeigt, wie sich die TOML Fortran-Bibliothek mit Deinem Build-System integrieren kannst und sie einfach in Dein Projekt verwendest.

Mit dem Fortran-Paket-Manager verwenden#

Der Fortran-Paket-Manager (fpm) ist ein Werkzeug zum Erstellen von Fortran-Projekten und Verwaltung von Abhängigkeiten von Fortran-Bibliotheken. Um TOML Fortran in Deinem fpm-Projekt zu aktivieren, füge folgenden Eintrag in Deinen Paket-Manifest ein:

fpm.toml#

[dependencies]
toml-f.git = "https://github.com/toml-f/toml-f"

Wenn Du Dein Projekt baust, wird fpm automatisch TOML Fortran für Dich herunterladen und als Teil Deines Projekts kompilieren. Die TOML Fortran-Module werden in Deinem Projekt dann verfügbar gemacht.

Mit meson integrieren#

Um TOML Fortran in meson zu verwenden, ist es am einfachsten, wenn Du es als Unterprojekt mit einer git-Wrap-Datei im subprojects-Verzeichnis einbindest.

subprojects/toml-f.wrap#

[wrap-git]
directory = toml-f
url = https://github.com/toml-f/toml-f
revision = head

Die Revision kann angepasst werden, um eine bestimmte Release-Tag von TOML Fortran festzulegen und die Stabilität zu erhöhen. In den Meson Build-Dateien kannst Du dann TOML Fortran als Abhängigkeit verwenden, dank der Wrap-Datei, wird eine Fallback-Version definiert und TOML Fortran kann bei Bedarf mitzukompiliert werden.

meson.build#

# Create TOML Fortran as subproject
tomlf_dep = dependency(
  'toml-f',
  version: '>=0.2.0',
  fallback: ['toml-f', 'tomlf_dep'],
  default_options: ['default_library=static'],
)

Damit kannst Du tomlf_dep als Abhängigkeit zu einem beliebigen Ziel hinzufügen und bist fertig.

Mit CMake integrieren#

Um TOML Fortran in CMake-basierten Projekten zu verwenden, ist es nützlich, ein eigenes find-Modul zu definieren, um TOML Fortran entweder bei Bedarf mitzukompiliert oder auch die Installation von installierten Paketen von sowohl meson als auch CMake-basierten Builds zu ermöglichen.

.
├── CMakeLists.txt
├── cmake
│   └── Findtoml-f.cmake
:

In Deiner primären CMake-Build Datei musst Du das eigene find-Modul in Deinem CMAKE_MODULE_PATH einbinden, danach kannst Du find_package verwenden, um das toml-f::toml-f-Ziel zu erhalten und dagegen zu verlinken.

CMakeLists.txt#

# ...

# Make custom find modules available for project
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
set(CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH}" PARENT_SCOPE)

# Find TOML Fortran, check whether target is already available,
# e.g. when build as subproject of another project also using TOML Fortran
if(NOT TARGET "toml-f::toml-f")
  find_package(toml-f REQUIRED)
endif()

# ...

# Add library target
library(
  "${PROJECT_NAME}"
)

# Link against TOML Fortran library
target_link_libraries(
  "${PROJECT_NAME}"
  PUBLIC
  "toml-f::toml-f"
)

# ...

# Follow GNU conventions for installation destinations
include(GNUInstallDirs)

# Make custom find-modules available when installing project
install(
  DIRECTORY
  "${CMAKE_CURRENT_SOURCE_DIR}/cmake/"
  DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}"
)

Beachte, dass wir auch die find-Module installieren, das ist wichtig, wenn Du Deine CMake-Projekte in der gleichen Weise wie TOML Fortran in anderen Projekt verwenden kannst. Zuletzt brauchst Du ein paar Zeilen Code, um das eigene find-Modul zu definieren, siehe unten.

Importierte Ziele#

Dieses Modul stellt folgende importierte Ziele bereit, falls es gefunden wurde:

toml-f::toml-f: Die toml-f Bibliothek

Ergebnisvariablen#

Dieses Modul definiert folgende Variablen:

TOML_FORTRAN_FOUND: Wahr wenn die toml-f Bibliothek verfügbar ist
TOML_FORTRAN_SOURCE_DIR: Pfad zum Quellverzeichnis des toml-f Projekts, nur gesetzt, wenn das Projekt als Quellcode eingebunden wird.
TOML_FORTRAN_BINARY_DIR: Pfad zum Buildverzeichnis des toml-f Projekts, nur gesetzt, wenn das Projekt als Quellcode eingebunden wird.

Cachevariablen#

Die folgenden Cachevariablen können gesetzt werden um die Einbindung der Bibliothek zu beeinflussen:

TOML_FORTRAN_FIND_METHOD

Möglichkeiten zum Finden oder zum Erstellen des Projekts. Verfügbar sind

cmake: Versuche via CMake Konfigurationsdatei zu finden
pkgconf: Versuche via pkg-config Datei zu finden
subproject: Verwende Quellcode in Unterprojektverzeichnis
fetch: Hole den Quellcode vom Upstream Repository

TOML_FORTRAN_DIR

Wird für die Suche der CMake Konfigurationsdatei verwendet

TOML_FORTRAN_SUBPROJECT

Verzeichnis zum Finden des toml-f Unterprojekts, relativ zum Projekt Wurzelverzeichnis

cmake/Findtoml-f.cmake#

set(_lib "toml-f")
set(_pkg "TOML_FORTRAN")
set(_url "https://github.com/toml-f/toml-f")
set(_rev "HEAD")

if(NOT DEFINED "${_pkg}_FIND_METHOD")
  if(DEFINED "${PROJECT_NAME}-dependency-method")
    set("${_pkg}_FIND_METHOD" "${${PROJECT_NAME}-dependency-method}")
  else()
    set("${_pkg}_FIND_METHOD" "cmake" "pkgconf" "subproject" "fetch")
  endif()
  set("_${_pkg}_FIND_METHOD")
endif()

foreach(method ${${_pkg}_FIND_METHOD})
  if(TARGET "${_lib}::${_lib}")
    break()
  endif()

  if("${method}" STREQUAL "cmake")
    message(STATUS "${_lib}: Find installed package")
    if(DEFINED "${_pkg}_DIR")
      set("_${_pkg}_DIR")
      set("${_lib}_DIR" "${_pkg}_DIR")
    endif()
    find_package("${_lib}" CONFIG QUIET)
    if("${_lib}_FOUND")
      message(STATUS "${_lib}: Found installed package")
      break()
    endif()
  endif()

  if("${method}" STREQUAL "pkgconf")
    find_package(PkgConfig QUIET)
    pkg_check_modules("${_pkg}" QUIET "${_lib}")
    if("${_pkg}_FOUND")
      message(STATUS "Found ${_lib} via pkg-config")

      add_library("${_lib}::${_lib}" INTERFACE IMPORTED)
      target_link_libraries(
        "${_lib}::${_lib}"
        INTERFACE
        "${${_pkg}_LINK_LIBRARIES}"
        )
      target_include_directories(
        "${_lib}::${_lib}"
        INTERFACE
        "${${_pkg}_INCLUDE_DIRS}"
        )

      break()
    endif()
  endif()

  if("${method}" STREQUAL "subproject")
    if(NOT DEFINED "${_pkg}_SUBPROJECT")
      set("_${_pkg}_SUBPROJECT")
      set("${_pkg}_SUBPROJECT" "subprojects/${_lib}")
    endif()
    set("${_pkg}_SOURCE_DIR" "${PROJECT_SOURCE_DIR}/${${_pkg}_SUBPROJECT}")
    set("${_pkg}_BINARY_DIR" "${PROJECT_BINARY_DIR}/${${_pkg}_SUBPROJECT}")
    if(EXISTS "${${_pkg}_SOURCE_DIR}/CMakeLists.txt")
      message(STATUS "Include ${_lib} from ${${_pkg}_SUBPROJECT}")
      add_subdirectory(
        "${${_pkg}_SOURCE_DIR}"
        "${${_pkg}_BINARY_DIR}"
      )

      add_library("${_lib}::${_lib}" INTERFACE IMPORTED)
      target_link_libraries("${_lib}::${_lib}" INTERFACE "${_lib}")
      break()
    endif()
  endif()

  if("${method}" STREQUAL "fetch")
    message(STATUS "Retrieving ${_lib} from ${_url}")
    include(FetchContent)
    FetchContent_Declare(
      "${_lib}"
      GIT_REPOSITORY "${_url}"
      GIT_TAG "${_rev}"
      )
    FetchContent_MakeAvailable("${_lib}")

    add_library("${_lib}::${_lib}" INTERFACE IMPORTED)
    target_link_libraries("${_lib}::${_lib}" INTERFACE "${_lib}")

    FetchContent_GetProperties("${_lib}" SOURCE_DIR "${_pkg}_SOURCE_DIR")
    FetchContent_GetProperties("${_lib}" BINARY_DIR "${_pkg}_BINARY_DIR")
    break()
  endif()

endforeach()

if(TARGET "${_lib}::${_lib}")
  set("${_pkg}_FOUND" TRUE)
else()
  set("${_pkg}_FOUND" FALSE)
endif()

if(DEFINED "_${_pkg}_SUBPROJECT")
  unset("${_pkg}_SUBPROJECT")
  unset("_${_pkg}_SUBPROJECT")
endif()
if(DEFINED "_${_pkg}_DIR")
  unset("${_lib}_DIR")
  unset("_${_pkg}_DIR")
endif()
if(DEFINED "_${_pkg}_FIND_METHOD")
  unset("${_pkg}_FIND_METHOD")
  unset("_${_pkg}_FIND_METHOD")
endif()
unset(_lib)
unset(_pkg)
unset(_url)
unset(_rev)

Andere Buildsysteme#

Andere Buildsysteme müssen eine vorkompilierte TOML Fortran Bibliothek auf dem System finden und nutzen. Dazu wird das pkg-config Tool verwendet. Nach der Installation von TOML Fortran mit Meson oder CMake wird eine pc-Datei erzeugt, die von pkg-config gefunden werden kann und beschreibt, wie gegen die installierten Moduldateien kompiliert werden kann und wie sich die TOML Fortran Bibliothek verlinken lässt.Zunächst prüfe, ob das pkg-config Tool verfügbar ist und TOML Fortran gefunden werden kann.

pkg-config --modversion toml-f

Stelle sicher, dass die Umgebungsvariable PKG_CONFIG_PATH auf das richtige Installationsverzeichnis zeigt. Mit den --libs und --cflags Optionen können die Bibliotheken, die verlinkt werden sollen, und die Include-Verzeichnisse erhalten werden:

pkg-config --cflags toml-f
pkg-config --libs toml-f

In einem handgeschriebenen Makefile können diese wie folgt genutzt werden

TOML_FORTRAN_INCLUDE_FLAGS := $(shell pkg-config --cflags toml-f)
TOML_FORTRAN_LIBRARY_FLAGS := $(shell pkg-config --libs toml-f)

TOML Fortran

TOML Fortran verwenden

Contents