Lua Academy · Lezione

Distribuire un plugin

Lo strutturi e lo condivida.

Distribuire un plugin è una lezione Lua Academy gratuita su CoddyKit. Questa è la lezione 4 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.

Struttura delle directory del plugin

Un plugin Neovim è semplicemente una directory presente nel runtimepath. La struttura convenzionale prevede cartelle di primo livello che Neovim tratta in modo speciale.

Directory principali: lua/ per i moduli, plugin/ per la configurazione caricata automaticamente, ftplugin/ per gli script dei filetype, doc/ per la documentazione della guida e after/ per le sostituzioni tardive.

-- myplugin/
--   lua/myplugin/init.lua
--   plugin/myplugin.lua
--   doc/myplugin.txt

La directory lua/

I file all'interno di lua/ sono accessibili con require. Un modulo in lua/myplugin/init.lua viene caricato con require('myplugin').

La nidificazione corrisponde ai percorsi puntati: lua/myplugin/config.lua diventa require('myplugin.config'). È così che i plugin espongono un namespace pubblico ordinato.

-- in lua/myplugin/init.lua
local M = {}
function M.hello() print('hi') end
return M

Restituire una tabella di modulo

Il pattern idiomatico per un modulo dichiara una tabella locale M, vi associa delle funzioni e la restituisce. Chi effettua la chiamata può quindi accedere a require('myplugin').hello().

Mantenga gli helper interni come semplici variabili locali, in modo che sia pubblica solo l'interfaccia prevista. Questo rispecchia l'incapsulamento dei moduli presente in altri ecosistemi.

local M = {}
local function private() end
function M.run() private() end
return M

La convenzione setup()

La maggior parte dei plugin espone una funzione setup(opts). Questa unisce le opzioni dell'utente a quelle predefinite e svolge operazioni di inizializzazione, come la creazione di comandi e autocomandi.

Usi vim.tbl_deep_extend('force', defaults, opts or {}) così una configurazione utente parziale conserva comunque tutte le impostazioni predefinite.

local M = {}
local defaults = { width = 40 }
function M.setup(opts)
  M.config = vim.tbl_deep_extend('force', defaults, opts or {})
end
return M

La directory plugin/

Gli script in plugin/ vengono eseguiti automaticamente all'avvio di Neovim, dopo la creazione del runtimepath. Li mantenga molto brevi.

Un'operazione comune consiste nel registrare comandi o una protezione, così i moduli pesanti vengono caricati pigramente. Eviti di svolgere qui operazioni costose: le rimandi a setup o agli autocomandi per mantenere rapido l'avvio.

-- in plugin/myplugin.lua
if vim.g.loaded_myplugin then return end
vim.g.loaded_myplugin = true

Protezioni di caricamento

Una protezione di caricamento impedisce una doppia inizializzazione se il file viene eseguito due volte. Imposti un flag vim.g.loaded_* e termini subito in caso di nuovo ingresso.

È essenziale perché i gestori di plugin e :runtime possono eseguire nuovamente i file; comandi o autocomandi duplicati causano bug difficili da individuare.

if vim.g.loaded_myplugin == 1 then return end
vim.g.loaded_myplugin = 1

Caricamento lazy

Un avvio rapido significa caricare il codice solo quando serve. Registri un comando leggero in plugin/ che richieda il modulo pesante al primo utilizzo.

I gestori di plugin come lazy.nvim formalizzano questo approccio con gli attivatori cmd, ft e keys, così il modulo non viene toccato finché non viene richiamato.

vim.api.nvim_create_user_command('MyStart', function()
  require('myplugin').run()
end, {})

runtimepath e packpath

Neovim individua i plugin analizzando runtimepath. Il sistema nativo dei pacchetti carica automaticamente le directory sotto pack/*/start/ e, su richiesta, quelle sotto pack/*/opt/ tramite :packadd.

La maggior parte degli utenti si affida a un gestore, ma comprendere runtimepath spiega come vengono trovate le cartelle.

print(vim.o.runtimepath:sub(1, 60))
-- :packadd loads an opt plugin manually

Controlli di stato

Fornisca un file lua/myplugin/health.lua con una funzione check, così gli utenti possono eseguire :checkhealth myplugin. Comunichi lo stato tramite l'API vim.health.

Usi vim.health.start, vim.health.ok, vim.health.warn e vim.health.error per segnalare chiaramente le dipendenze mancanti.

local M = {}
function M.check()
  vim.health.start('myplugin')
  vim.health.ok('all good')
end
return M

Documentazione e tag

Includa un file della guida doc/myplugin.txt. Esegua :helptags doc/ (oppure lasci che lo faccia il gestore) per generare l'indice dei tag, così :help myplugin funzionerà.

Una buona documentazione elenca i comandi, le opzioni di setup e le mappature dei tasti predefinite, rendendo il plugin facile da trovare direttamente da Neovim.

-- generate tags from the doc directory
vim.cmd('helptags ' .. vim.fn.expand('%:p:h'))

Versionamento e pubblicazione

Ospiti il plugin in un repository git; gli utenti lo installano tramite il percorso owner/repo. Contrassegni le release con versioni semantiche, così i gestori possono fissare le versioni.

Includa un README con esempi di installazione per i gestori più diffusi, una licenza e un esempio di configurazione minimo per ridurre la soglia di adozione.

-- lazy.nvim spec
-- { 'owner/myplugin', config = function()
--     require('myplugin').setup({})
--   end }

Verifica rapida

Verifichi la Sua comprensione del pacchettizzamento dei plugin.

Riepilogo: pacchettizzare un plugin

Un plugin è una directory del runtimepath con moduli lua/, uno script plugin/ eseguito automaticamente e, facoltativamente, file doc/, ftplugin/ e per i controlli di stato.

Restituisca tabelle di modulo, esponga un setup che unisca le impostazioni predefinite, impedisca i caricamenti duplicati, carichi pigramente il codice pesante, documenti il plugin con helptags e lo pubblichi tramite git con tag di versione semantica.

Domande Frequenti

La lezione «Distribuire un plugin» è gratuita?

Sì — il testo completo di «Distribuire un plugin» è 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 «Distribuire un plugin»?

Lo strutturi e lo condivida. 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 4 di 4.

Quanto tempo richiede la lezione «Distribuire un plugin»?

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