Contenu

Exigences relatives au nom du module

Exigences relatives au nom du module

Note

Les exigences en matière de dénomination des modules ne s’appliquent qu’aux paquets téléversés dans un registre fpm ; par défaut, aucune règle de dénomination n’est appliquée aux projets fpm locaux.

Note

TL;DR Préfixez toujours tous les noms de vos modules avec un préfixe de paquet standardisé.

  • Un préfixe par défaut (nom du paquet + double trait de soulignement : my_package__*) est toujours réservé par le registre.

  • Un préfixe personnalisé (pas de symboles + un seul trait de soulignement : mypkg_*) peut être spécifié, mais il est susceptible de ne pas être encore réservé dans le registre.

  • Définir le préfixe par défaut (module-naming=true) ou personnalisé (module-naming="mypfx") dans fpm.toml [build].

Le langage Fortran ne prend pas en charge les espaces de noms. Cela signifie que tous les noms publics (modules, mais aussi sous-routines et fonctions globales) doivent être uniques dans l’espace de construction. Toute construction contenant des noms dupliqués échouera car il est impossible de résoudre un nom en un objet unique. C’est pourquoi fpm exige par défaut que tous les paquets respectent des conventions de nommage simples qui s’appliquent à la fois au nom du paquet et à ses modules.

Noms Fortran : règles générales

Depuis Fortran 2003, les noms Fortran valides doivent respecter les règles suivantes :

  • Jusqu’à 63 caractères ;

  • Insensibles à la casse ;

  • Doit commencer par une lettre ;

  • Seuls les caractères alphanumériques (lettres, chiffres) et les traits de soulignement _ sont autorisés.

Exemples de noms Fortran non valides :

  1_package         ! Begins with #
  package$          ! Contains invalid symbol
  _package          ! Does not begin with letter
  my package        ! Contains space

Examples of valid Fortran names:

  my_module         ! Case insensitive: all versions valid,
  My_Module         ! but resolving to the same object
  MY_MODULE
  MyModule
  mypackage
  package_module    ! Underscores allowed
  my_package_123

Noms de registre fpm : règles pour les paquets et les modules

Pour réduire le risque de collisions de noms, tout nom de module Fortran dans un paquet doit commencer par un préfixe unique. Deux options sont proposées.

Noms de modules par défaut

L’option par défaut est toujours valable pour tous les paquets, car elle est liée de manière unique au nom du paquet. Elle comporte un nom de paquet fortranisé, suivi d’un double trait de soulignement, avec les règles suivantes :

  1. Doit commencer par le nom du paquet ;

  2. Le séparateur par défaut __ entre le bloc de nom de package et ce qui suit doit être utilisé ;

  3. Ni le module ni le nom du paquet ne doivent contenir ailleurs la séquence de séparateur par défaut.

Note

Le séparateur par défaut est un double trait de soulignement. Les traits de soulignement simples sont autorisés partout sauf à la fin d’un nom de paquet.

Noms de modules appliqués valides

Lorsque les conventions de nommage sont appliquées, voici des exemples de modules dans un paquet nommé my_pkg pour illustrer les règles :

   module my_pkg        ! Global API
   module my_pkg__1     ! We can now number them
   module my_pkg__123
   module my_pkg__core
   module my_pkg__utils
   module my_pkg__with_very_long_name

Noms de modules appliqués non valides

Considérant le même package my_pkg, les noms suivants seront invalides selon les règles de nommage :

   module my_pkg__      ! Nothing follows the separator
   module my_pkg__1__2  ! Separator must be unique
   module my_pkg__90123456789012345678901234567890123456789012345678901234 ! 64 chars: too long
   module my_pkg__util$ ! non-Fortran name

Noms de modules personnalisés

En option, il est possible de spécifier un préfixe personnalisé pour les modules du paquet. Le préfixe personnalisé doit être :

  1. Un nom Fortran valide ;

  2. Contenant uniquement des caractères alphanumériques (pas d’espaces, de symboles, de tirets, de traits de soulignement).

Contrairement à l’option par défaut, un préfixe personnalisé doit être validé par le registre, qui conserve une liste de préfixes personnalisés uniques afin d’éviter les collisions de noms.

Les noms de modules avec le préfixe personnalisé sont suivis d’un simple trait de soulignement _, ce qui rend cette option plus flexible et rétrocompatible avec les paquets existants. Lorsqu’un préfixe de module personnalisé est spécifié, le préfixe par défaut reste disponible. Si l’on considère par exemple un paquet nommé date-time, avec le préfixe choisi dt, les noms de modules suivants sont tous valides :

   module date_time        ! Same as package name
   module dt               ! Same as custom prefix
   module date_time__utils ! use standard naming -> double underscore
   module dt_utils         ! custom prefix -> single underscore
   module dt_123           ! custom prefix
   module dt_1
   module dt__1            ! also valid

Noms de paquets

Tous les paquets figurant dans les registres de FPM doivent avoir des noms uniques et doivent donc respecter les règles suivantes :

  1. Tous les noms de paquets doivent être des noms valides en Fortran ;

  2. Les tirets (-) sont également autorisés et sont traités par fpm comme des traits de soulignement (underscores) ;

  3. Les noms des paquets peuvent contenir des majuscules et des minuscules, mais leur identification unique ne tient pas compte de la casse ;

  4. Aucune duplication d’un nom de paquetage n’est autorisée à l’intérieur d’un même espace de noms.

Exemples de noms de paquets valides :

   my_package     ! 1 underscore allowed
   My_Package     ! same as the former
   mypackage123   ! Numbers OK
   my-package     ! Will be read by fpm as "my_package"

Exemples de noms de paquets non valides :

  my__package       ! Contains package__module separator
  package__         ! Contains separator
  package_          ! Ends with underscore
  my pac$age        ! Spaces and all symbols besides `_` not allowed
  _my_package       ! Does not begin with letter
  123package        ! Does not begin with letter

Paramètres du manifeste

Note

Faits saillants :

  • Par défaut, FPM n’applique pas de règles de dénomination. Si vous le souhaitez, activez-les dans fpm.toml

  • Les registres FPM les requièrent obligatoirement. Assurez-vous qu’ils sont activés dans fpm.toml.

  • Activez le préfixe standard avec module-naming=true, le préfixe personnalisé avec module-naming="prefixname".

Les exigences relatives à la dénomination des modules peuvent être activées dans fpm.toml dans la section build, à l’aide de l’indicateur booléen module-naming. Par défaut, module-naming = false, de sorte qu’aucune vérification des exigences de nommage du registre n’est effectuée pendant la construction.

Exemple:

[build]
auto-executables = true
auto-examples = false
auto-tests = false
module-naming = true          # Use default naming convention
external-modules = "netcdf"

[build]
auto-executables = true
auto-examples = false
auto-tests = false
module-naming = "tomlf"       # Use custom prefix, "tomlf"
external-modules = "netcdf"

Lignes directrices

Note

Il s’agit de suggestions de style non obligatoires visant à améliorer la lisibilité et l’uniformité du code.

Il est recommandé que l’API publique de chaque paquet soit contenue dans un module de premier niveau, dont le nom est identique à celui du paquet. Par exemple, en supposant qu’un paquet DateTime s’occupe de l’heure et de la date en Fortran, on pourrait avoir plusieurs modules en traitant certains aspects :

   module datetime__dates ; end module
   module datetime__time  ; end module
   module datetime__julian; end module

et une API publique unique contenue dans le module de premier niveau :

   module datetime
      use datetime__dates, only: [...]
      use datetime__time, only: [...]
      use datetime__julian, only: [...]
      implicit none(type,external)
      private

      ! Publish API
      public :: sub_1
      public :: fun_123

   end module datetime

Manuel de référence

[1] Metcalf, Reid, Cohen, « Modern Fortran Explained », Oxford University Press.

[2] Style Guide for Python Code (Guide stylistique pour les codes Python)

précédent

Téléversement d’un paquet

suivant

Actualités