Lua Academy · Leçon

package.path et package.cpath

Configurez les chemins de recherche des modules Lua et C.

package.path et package.cpath est une leçon Lua Academy gratuite sur CoddyKit. Ceci est la leçon 3 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Lua Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Lua Academy comprend 4 leçons au total.

Contenu de package.path

package.path est une chaîne de modèles de recherche séparés par des points-virgules. Chaque modèle contient un emplacement ? qui est remplacé par le nom du module (les points étant convertis en séparateurs de répertoires). Lua essaie chaque modèle dans l'ordre jusqu'à trouver un fichier.

print(package.path)
-- ./?.lua;./?.luac;/usr/local/share/lua/5.4/?.lua;...

-- Dots in module names become directory separators
-- require("foo.bar") -> searches for foo/bar.lua
print(("foo.bar"):gsub("%.", "/"))  -- foo/bar

Ajouter des chemins de recherche

Ajoutez des chemins au début de package.path pour ajouter des répertoires de recherche. Les ajouter à la fin leur attribue une priorité moindre. Effectuez cette configuration avant tout appel à require qui doit utiliser ces nouveaux chemins.

-- Add multiple directories
package.path = table.concat({
  "./?.lua",
  "./lib/?.lua",
  "./lib/?/init.lua",
  package.path,  -- keep existing paths
}, ";")

-- Now require("json") searches:
-- ./json.lua -> ./lib/json.lua -> ./lib/json/init.lua -> ...

package.cpath pour les extensions C

package.cpath est le chemin de recherche des modules d'extension C (bibliothèques partagées : .so sous Linux, .dll sous Windows, .dylib sous macOS). La convention de nommage correspond à celle des bibliothèques partagées du système.

print(package.cpath)
-- ./?.so;/usr/local/lib/lua/5.4/?.so;...

-- Add a local C library directory
package.cpath = "./clib/?.so;" .. package.cpath

-- require("myextension") will now search:
-- ./clib/myextension.so

Variable d'environnement LUA_PATH

La variable d'environnement LUA_PATH définit la valeur initiale de package.path. Un ;; dans LUA_PATH est remplacé par le chemin par défaut. Utilisez cette variable pour configurer les chemins de recherche sans modifier les scripts — ce qui est utile pour le déploiement.

-- Set before launching Lua:
-- export LUA_PATH="./?.lua;./lib/?.lua;;"
-- The ";;" expands to the built-in default path

-- In Lua, check what was set:
print(package.path)

-- You can also use LUA_CPATH for C paths:
-- export LUA_CPATH="./clib/?.so;;"

package.searchpath

package.searchpath(name, path) recherche dans la chaîne de chemin un fichier correspondant au nom. Il renvoie la première correspondance trouvée, ou nil et un message d'erreur listant tous les emplacements essayés. Cela est utile pour trouver des fichiers sans réellement les charger.

local file, err = package.searchpath("json", package.path)
if file then
  print("Found:", file)
else
  print("Not found. Tried:\n" .. err)
end

-- Useful for checking if a module exists:
local function moduleExists(name)
  return package.searchpath(name, package.path) ~= nil
end
print(moduleExists("json"))

Algorithme de recherche de require

Lorsque vous appelez require("mod"), Lua suit cet ordre : (1) vérifier package.loaded, (2) vérifier package.preload, (3) rechercher un fichier .lua dans package.path, (4) rechercher une bibliothèque C dans package.cpath. La première correspondance est retenue.

-- Simulate what require does:
local function myRequire(name)
  -- 1. Check cache
  if package.loaded[name] ~= nil then
    return package.loaded[name]
  end
  -- 2. Check preload
  if package.preload[name] then
    return package.preload[name]()
  end
  -- 3. Search path
  local file = package.searchpath(name, package.path)
  if file then
    return dofile(file)  -- simplified
  end
  error("module not found: " .. name)
end

Fonctions de chargement

package.searchers (anciennement package.loaders) est un tableau de fonctions qui tentent de trouver et de charger un module. Vous pouvez ajouter des fonctions de recherche personnalisées à cette table. Chaque fonction reçoit un nom de module et renvoie une fonction de chargement ou nil.

-- Add a custom searcher that loads from a table
local builtins = {
  myconfig = function()
    return {host="localhost", port=8080}
  end
}

table.insert(package.searchers, 1, function(name)
  local loader = builtins[name]
  if loader then return loader end
end)

local cfg = require("myconfig")
print(cfg.host, cfg.port)   -- localhost  8080

Conventions de nommage des modules

Les noms de modules sont hiérarchiques et utilisent des points : "mylib.utils". Par convention, l'espace de noms de premier niveau est le nom de votre projet ou de votre organisation afin d'éviter les conflits. Les minuscules sont la norme. Évitez les tirets dans les noms de modules (utilisez plutôt des underscores), car ils entrent en conflit avec la syntaxe Lua.

-- Good: hierarchical, lowercase
-- require("myapp.db.connection")
-- require("myapp.utils.string")

-- Bad: dashes cause syntax issues in dot notation
-- local my-module = require("my-module")  -- SYNTAX ERROR
local mymodule = require("my_module")  -- ok

Débogage des chemins

Lorsque require ne parvient pas à trouver un module, le message d'erreur liste tous les chemins essayés. Affichez package.path pour voir l'ordre de recherche. Utilisez package.searchpath pour vérifier interactivement des chemins de modules précis.

-- Debug require failures:
local ok, err = pcall(require, "missing_module")
if not ok then
  -- The error message shows all tried paths
  print("require failed:")
  print(err)
  print("\nCurrent package.path:")
  for path in package.path:gmatch("[^;]+") do
    print("  " .. path)
  end
end

Rétablir le chemin par défaut

Si vous souhaitez disposer d'un chemin propre et minimal, sans les valeurs par défaut du système, vous pouvez réinitialiser entièrement package.path. Cela est utile dans les environnements Lua intégrés où le système de fichiers est limité ou isolé.

-- Minimal path for embedded environment
package.path  = "./?.lua;./lib/?.lua"
package.cpath = "./?.so"

-- Or get just the current directory patterns:
local function justLocal()
  return "./?.lua;./?/init.lua"
end

print("Minimal path:", justLocal())

Vérification rapide

Que représente le ? dans un modèle de package.path ?

Récapitulatif : package.path

Résumé :

package.path : modèles de recherche de fichiers Lua ; ? = nom du module
package.cpath : modèles de recherche de bibliothèques C
Ajoutez au début pour définir des répertoires prioritaires
Les variables d'environnement LUA_PATH/LUA_CPATH définissent les chemins initiaux
package.searchpath : vérifier si un module peut être trouvé
Ajoutez des fonctions de recherche personnalisées via package.searchers

Questions Fréquemment Posées

La leçon « package.path et package.cpath » est-elle gratuite ?

Oui — le texte complet de « package.path et package.cpath » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Lua Academy, passe à CoddyKit PRO. Le cours Lua Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « package.path et package.cpath » ?

Configurez les chemins de recherche des modules Lua et C. Tu pratiques Lua Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer Lua Academy ?

Aucune expérience préalable n'est requise. Lua Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 3 sur 4.

Combien de temps prend la leçon « package.path et package.cpath » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon Lua Academy ?

Oui. Chaque leçon Lua Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

← Retour à Lua Academy