Lua Academy · Lección

package.path y package.cpath

Configure las rutas de búsqueda para módulos de Lua y C.

package.path y package.cpath es una lección gratuita de Lua Academy en CoddyKit. Esta es la lección 3 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Lua Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Lua Academy incluye 4 lecciones en total.

Contenido de package.path

package.path es una cadena de patrones de búsqueda separados por punto y coma. Cada patrón contiene un marcador ? que se sustituye por el nombre del módulo (con los puntos convertidos en separadores de directorios). Lua prueba cada patrón en orden hasta encontrar un archivo.

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

Añadir rutas de búsqueda

package.path para añadir directorios de búsqueda. Añadirlas al final incorpora ubicaciones de menor prioridad. Establezca esto antes de cualquier llamada a require que necesite las nuevas rutas.

-- 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 para extensiones de C

package.cpath es la ruta de búsqueda de módulos de extensión de C (bibliotecas compartidas: .so en Linux, .dll en Windows y .dylib en macOS). La convención de nombres coincide con las convenciones del sistema para bibliotecas compartidas.

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 de entorno LUA_PATH

La variable de entorno LUA_PATH establece el valor inicial de package.path. Una secuencia ;; en LUA_PATH se sustituye por la ruta predeterminada. Use esto para configurar las rutas de búsqueda sin modificar los scripts, algo útil para la implementación.

-- 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) busca un archivo cuyo nombre coincida en la cadena de rutas. Devuelve la primera coincidencia encontrada, o nil y un mensaje de error que enumera todas las ubicaciones probadas. Resulta útil para encontrar archivos sin cargarlos realmente.

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 de búsqueda de require

Cuando llama a require("mod"), Lua sigue este orden: (1) comprueba package.loaded, (2) comprueba package.preload, (3) busca un archivo .lua en package.path, (4) busca una biblioteca de C en package.cpath. Gana la primera coincidencia.

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

Funciones de carga

package.searchers (antes package.loaders) es una matriz de funciones que intentan encontrar y cargar un módulo. Puede añadir buscadores personalizados a esta tabla. Cada buscador recibe un nombre de módulo y devuelve una función de carga o 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

Convenciones para nombres de módulos

Los nombres de los módulos son jerárquicos y utilizan puntos: "mylib.utils". El espacio de nombres de nivel superior convencional es el nombre de su proyecto u organización, para evitar conflictos. Las minúsculas son lo habitual. Evite los guiones en los nombres de módulos (use guiones bajos en su lugar), ya que entran en conflicto con la sintaxis de 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

Depuración de rutas

Cuando require no encuentra un módulo, el mensaje de error enumera todas las rutas probadas. Imprima package.path para ver el orden de búsqueda. Use package.searchpath para comprobar interactivamente rutas de módulos específicas.

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

Restablecer la ruta predeterminada

Si desea una ruta limpia y mínima, sin los valores predeterminados del sistema, puede restablecer completamente package.path. Esto resulta útil en entornos de Lua embebido donde el sistema de archivos es limitado o está aislado.

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

Comprobación rápida

¿Qué representa el ? en un patrón de package.path?

Resumen: package.path

Resumen:

package.path: patrones de búsqueda de archivos Lua; ? = nombre del módulo
package.cpath: patrones de búsqueda de bibliotecas de C
Anteponer rutas añade directorios de alta prioridad
Las variables de entorno LUA_PATH/LUA_CPATH establecen las rutas iniciales
package.searchpath: comprueba si se puede encontrar un módulo
Añada buscadores personalizados mediante package.searchers

Preguntas frecuentes

¿La lección «package.path y package.cpath» es gratis?

Sí — el texto completo de «package.path y package.cpath» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Lua Academy, actualiza a CoddyKit PRO. El curso de Lua Academy incluye 4 lecciones en total.

¿Qué aprenderé en «package.path y package.cpath»?

Configure las rutas de búsqueda para módulos de Lua y C. Practicas Lua Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Lua Academy?

No se requiere experiencia previa. Lua Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 3 de 4.

¿Cuánto tiempo toma la lección «package.path y package.cpath»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Lua Academy?

Sí. Cada lección de Lua Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

← Volver a Lua Academy