Lua Academy · Lezione

package.path e package.cpath

Configuri i percorsi di ricerca per i moduli Lua e C.

package.path e package.cpath è una lezione Lua Academy gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Lua Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Lua Academy include 4 lezioni in totale.

Contenuto di package.path

package.path è una stringa di pattern di ricerca separati da punti e virgola. Ogni pattern contiene il segnaposto ?, che viene sostituito dal nome del modulo (con i punti convertiti nei separatori di directory). Lua prova ogni pattern nell'ordine indicato finché non trova un file.

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

Aggiunta di percorsi di ricerca

Anteponi i percorsi a package.path per aggiungere directory di ricerca. Aggiungerli in coda crea posizioni con priorità inferiore. Imposti il valore prima di qualsiasi chiamata a require che debba usare i nuovi percorsi.

-- 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 per le estensioni C

package.cpath è il percorso di ricerca dei moduli di estensione C (librerie condivise: .so su Linux, .dll su Windows, .dylib su macOS). La convenzione di denominazione corrisponde a quella delle librerie condivise del sistema.

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

Variabile d'ambiente LUA_PATH

La variabile d'ambiente LUA_PATH imposta il valore iniziale di package.path. Una sequenza ;; in LUA_PATH viene sostituita dal percorso predefinito. Usi questa variabile per configurare i percorsi di ricerca senza modificare gli script: è utile per la distribuzione.

-- 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) cerca nel percorso un file corrispondente al nome. Restituisce la prima corrispondenza trovata oppure nil e un messaggio di errore con tutte le posizioni provate. È utile per individuare i file senza caricarli effettivamente.

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"))

Algoritmo di ricerca di require

Quando si chiama require("mod"), Lua segue questo ordine: (1) controlla package.loaded, (2) controlla package.preload, (3) cerca un file .lua in package.path, (4) cerca una libreria C in package.cpath. Vince la prima corrispondenza.

-- 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

Funzioni di caricamento

package.searchers (in precedenza package.loaders) è un array di funzioni che cercano e caricano un modulo. È possibile aggiungere searcher personalizzati a questa tabella. Ogni searcher riceve il nome di un modulo e restituisce una funzione di caricamento oppure 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

Convenzioni per i nomi dei moduli

I nomi dei moduli sono gerarchici e usano i punti: "mylib.utils". Per convenzione, lo spazio dei nomi di primo livello è il nome del progetto o dell'organizzazione, così da evitare conflitti. Si usano normalmente le lettere minuscole. Eviti i trattini nei nomi dei moduli (usi invece i caratteri di sottolineatura), perché entrano in conflitto con la sintassi di 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

Debug dei percorsi

Quando require non riesce a trovare un modulo, il messaggio di errore elenca tutti i percorsi provati. Stampi package.path per visualizzare l'ordine di ricerca. Usi package.searchpath per controllare interattivamente percorsi specifici dei moduli.

-- 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

Ripristino del percorso predefinito

Se desidera un percorso pulito e minimale, senza le impostazioni predefinite del sistema, può reimpostare completamente package.path. È utile negli ambienti Lua incorporati in cui il file system è limitato o isolato in una sandbox.

-- 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())

Verifica rapida

Che cosa rappresenta ? in un pattern di package.path?

Riepilogo: package.path

Riepilogo:

package.path: pattern di ricerca dei file Lua; ? = nome del modulo
package.cpath: pattern di ricerca delle librerie C
Anteporre i percorsi aggiunge directory con priorità più alta
Le variabili d'ambiente LUA_PATH/LUA_CPATH impostano i percorsi iniziali
package.searchpath: verifica se è possibile trovare un modulo
Aggiunga searcher personalizzati tramite package.searchers

Domande Frequenti

La lezione «package.path e package.cpath» è gratuita?

Sì — il testo completo di «package.path e package.cpath» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Lua Academy, passa a CoddyKit PRO. Il corso Lua Academy include 4 lezioni in totale.

Cosa imparerò in «package.path e package.cpath»?

Configuri i percorsi di ricerca per i moduli Lua e C. Eserciti Lua Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Lua Academy?

Non è richiesta alcuna esperienza precedente. Lua Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «package.path e package.cpath»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Lua Academy?

Sì. Ogni lezione Lua Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a Lua Academy