Lua Academy · Leçon

Empaqueter une extension

Structurez-la et partagez-la.

Empaqueter une extension est une leçon Lua Academy gratuite sur CoddyKit. Ceci est la leçon 4 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.

Organisation des répertoires d’un module complémentaire

Un module complémentaire Neovim est simplement un répertoire du runtimepath. L’organisation conventionnelle comprend des dossiers de premier niveau que Neovim traite de manière particulière.

Répertoires principaux : lua/ pour les modules, plugin/ pour la configuration chargée automatiquement, ftplugin/ pour les scripts associés aux types de fichiers, doc/ pour l’aide et after/ pour les surcharges tardives.

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

Le répertoire lua/

Les fichiers du répertoire lua/ sont accessibles avec require. Un module situé dans lua/myplugin/init.lua se charge avec require('myplugin').

Les sous-répertoires correspondent aux chemins séparés par des points : lua/myplugin/config.lua devient require('myplugin.config'). C’est ainsi que les modules complémentaires exposent un espace de noms public clair.

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

Retourner une table de module

Le modèle de module courant déclare une table locale M, lui ajoute des fonctions, puis la retourne. Les appelants peuvent alors accéder à require('myplugin').hello().

Gardez les fonctions auxiliaires internes sous forme de simples variables locales afin que seule l’interface prévue soit publique. Cela reprend le principe d’encapsulation des modules utilisé dans d’autres écosystèmes.

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

La convention setup()

La plupart des modules complémentaires exposent une fonction setup(opts). Elle fusionne les options de l’utilisateur avec les valeurs par défaut et effectue l’initialisation, comme la création de commandes et de commandes automatiques.

Utilisez vim.tbl_deep_extend('force', defaults, opts or {}) afin qu’une configuration utilisateur partielle bénéficie tout de même de toutes les valeurs par défaut.

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

Le répertoire plugin/

Les scripts du répertoire plugin/ s’exécutent automatiquement au démarrage de Neovim, une fois le chemin d’exécution construit. Gardez-les très courts.

Ils servent souvent à enregistrer des commandes ou un garde-fou afin que les modules volumineux soient chargés de manière différée. Évitez les opérations coûteuses ici ; reportez-les à setup ou aux commandes automatiques pour conserver un démarrage rapide.

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

Garde-fous de chargement

Un garde-fou de chargement empêche une double initialisation si le fichier est chargé deux fois. Définissez un indicateur vim.g.loaded_*, puis quittez immédiatement en cas de nouvelle tentative.

C’est essentiel, car les gestionnaires de modules complémentaires et :runtime peuvent charger à nouveau les fichiers, et les commandes ou commandes automatiques en double provoquent des bogues difficiles à détecter.

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

Chargement différé

Un démarrage rapide consiste à ne charger le code qu’au moment où vous en avez besoin. Enregistrez une commande légère dans plugin/ qui demande le module volumineux lors de sa première utilisation.

Les gestionnaires de modules complémentaires comme lazy.nvim formalisent cette approche avec les déclencheurs cmd, ft et keys, afin que votre module ne soit pas chargé avant son invocation.

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

Chemins d’exécution et de paquets

Neovim découvre les modules complémentaires en parcourant runtimepath. Le système natif de paquets charge automatiquement les répertoires sous pack/*/start/ et, à la demande, ceux sous pack/*/opt/ via :packadd.

La plupart des utilisateurs s’appuient sur un gestionnaire, mais comprendre runtimepath explique comment vos dossiers sont trouvés.

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

Vérifications de santé

Fournissez un fichier lua/myplugin/health.lua contenant une fonction check afin que les utilisateurs puissent exécuter :checkhealth myplugin. Signalez l’état du module avec l’API vim.health.

Utilisez vim.health.start, vim.health.ok, vim.health.warn et vim.health.error pour signaler clairement les dépendances manquantes.

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

Documentation et balises

Fournissez un fichier d’aide doc/myplugin.txt. Exécutez :helptags doc/ — ou laissez le gestionnaire s’en charger — afin de générer l’index des balises et de permettre l’utilisation de :help myplugin.

Une bonne documentation répertorie les commandes, les options de setup et les mappages de touches par défaut, afin que votre module complémentaire soit facile à découvrir depuis Neovim.

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

Gestion des versions et publication

Hébergez le module complémentaire dans un dépôt Git ; les utilisateurs l’installent avec le chemin owner/repo. Créez des balises de version selon le versionnage sémantique afin que les gestionnaires puissent verrouiller les versions.

Incluez un README avec des extraits d’installation pour les gestionnaires populaires, une licence et un exemple minimal de configuration afin de faciliter l’adoption.

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

Vérification rapide

Vérifiez votre compréhension de la mise en paquet d’un module complémentaire.

Récapitulatif : mettre un module complémentaire en paquet

Un module complémentaire est un répertoire du chemin d’exécution contenant des modules lua/, un script plugin/ exécuté automatiquement et, éventuellement, des répertoires doc/, ftplugin/ ainsi que des fichiers de diagnostic.

Retournez des tables de module, exposez une fonction setup qui fusionne les valeurs par défaut, protégez-vous contre les chargements multiples, chargez le code volumineux de manière différée, documentez votre module avec des balises d’aide et publiez-le via Git avec des balises de version sémantique.

Questions Fréquemment Posées

La leçon « Empaqueter une extension » est-elle gratuite ?

Oui — le texte complet de « Empaqueter une extension » 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 « Empaqueter une extension » ?

Structurez-la et partagez-la. 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 4 sur 4.

Combien de temps prend la leçon « Empaqueter une extension » ?

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