Lua Academy · Aula

package.path e package.cpath

Configure caminhos de pesquisa para módulos Lua e C.

package.path e package.cpath é uma aula grátis de Lua Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Lua Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Lua Academy inclui 4 aulas no total.

Conteúdo de package.path

package.path é uma cadeia de padrões de pesquisa separados por ponto e vírgula. Cada padrão tem um marcador ?, que é substituído pelo nome do módulo (com os pontos convertidos em separadores de diretório). Lua tenta cada padrão na ordem até encontrar um arquivo.

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

Adicionando caminhos de pesquisa

Preponha caminhos a package.path para adicionar diretórios de pesquisa. Acrescentá-los adiciona locais de prioridade mais baixa. Defina isso antes de qualquer chamada a require que precise dos novos caminhos.

-- 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 extensões C

package.cpath é o caminho de pesquisa para módulos de extensão C (bibliotecas compartilhadas: .so no Linux, .dll no Windows, .dylib no macOS). A convenção de nomenclatura corresponde às convenções do sistema para bibliotecas compartilhadas.

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

Variável de ambiente LUA_PATH

A variável de ambiente LUA_PATH define o valor inicial de package.path. Uma sequência ;; em LUA_PATH é substituída pelo caminho padrão. Use isso para configurar caminhos de pesquisa sem modificar os scripts — útil na implantação.

-- 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) pesquisa um arquivo correspondente ao nome na cadeia de caminhos. Retorna a primeira correspondência encontrada ou nil e uma mensagem de erro listando todos os locais testados. É útil para encontrar arquivos sem realmente carregá-los.

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 pesquisa de require

Quando o senhor chama require("mod"), Lua segue esta ordem: (1) verifica package.loaded, (2) verifica package.preload, (3) pesquisa em package.path um arquivo .lua, (4) pesquisa em package.cpath uma biblioteca C. A primeira correspondência vence.

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

Funções de carregamento

package.searchers (anteriormente package.loaders) é uma matriz de funções que tentam localizar e carregar um módulo. O senhor pode adicionar localizadores personalizados a essa tabela. Cada localizador recebe um nome de módulo e retorna uma função de carregamento 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

Convenções para nomes de módulos

Os nomes de módulos são hierárquicos e usam pontos: "mylib.utils". O espaço de nomes convencional de nível superior é o nome do seu projeto ou organização, para evitar conflitos. Letras minúsculas são o padrão. Evite hífens nos nomes de módulos (use sublinhados), pois eles entram em conflito com a sintaxe 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

Depuração de caminhos

Quando require não consegue encontrar um módulo, a mensagem de erro lista todos os caminhos testados. Imprima package.path para ver a ordem de pesquisa. Use package.searchpath para verificar interativamente caminhos específicos de módulos.

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

Redefinindo para o caminho padrão

Se quiser um caminho limpo e mínimo, sem os padrões do sistema, o senhor pode redefinir completamente package.path. Isso é útil em ambientes Lua incorporados nos quais o sistema de arquivos é limitado ou isolado.

-- 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ção rápida

O que o ? em um padrão de package.path representa?

Recapitulação: package.path

Resumo:

package.path: padrões de pesquisa de arquivos Lua; ? = nome do módulo
package.cpath: padrões de pesquisa de bibliotecas C
Preponha caminhos para adicionar diretórios de alta prioridade
As variáveis de ambiente LUA_PATH/LUA_CPATH definem os caminhos iniciais
package.searchpath: verifica se um módulo pode ser encontrado
Adicione localizadores personalizados por meio de package.searchers

Perguntas Frequentes

A aula “package.path e package.cpath” é grátis?

Sim — o texto completo de “package.path e package.cpath” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Lua Academy, atualize para CoddyKit PRO. O curso de Lua Academy inclui 4 aulas no total.

O que vou aprender em “package.path e package.cpath”?

Configure caminhos de pesquisa para módulos Lua e C. Você pratica Lua Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Lua Academy?

Nenhuma experiência prévia é necessária. Lua Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “package.path e package.cpath”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Lua Academy?

Sim. Cada aula de Lua Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Lua Academy