Lua Academy · 강의

플러그인 패키징하기

구조화하고 공유해 보세요.

플러그인 패키징하기은(는) CoddyKit의 무료 Lua Academy 강의입니다. 이것은 4개 중 4번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Lua Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Lua Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

플러그인 디렉터리 구조

Neovim 플러그인은 runtimepath에 있는 하나의 디렉터리일 뿐입니다. 일반적인 구조에서는 Neovim이 특별하게 처리하는 최상위 폴더를 사용합니다.

주요 디렉터리는 모듈을 위한 lua/, 자동으로 로드되는 초기화를 위한 plugin/, 파일 형식 스크립트를 위한 ftplugin/, 도움말을 위한 doc/, 나중에 적용할 재정의를 위한 after/입니다.

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

루아 디렉터리

lua/ 아래의 파일은 require로 불러올 수 있습니다. lua/myplugin/init.lua의 모듈은 require('myplugin')으로 불러옵니다.

중첩된 구조는 점으로 구분된 경로에 대응합니다. lua/myplugin/config.lua는 require('myplugin.config')이 됩니다. 이렇게 하면 플러그인이 깔끔한 공개 네임스페이스를 제공할 수 있습니다.

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

모듈 테이블 반환하기

관용적인 모듈 패턴은 로컬 테이블 M을 선언하고, 여기에 함수를 연결한 다음 반환하는 방식입니다. 그러면 호출하는 쪽에서 require('myplugin').hello()에 접근할 수 있습니다.

내부 도우미는 일반 로컬로 유지하여 의도한 표면만 공개되도록 하세요. 이는 다른 생태계의 모듈 캡슐화 방식과 비슷합니다.

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

setup() 관례

대부분의 플러그인은 setup(opts) 함수를 제공합니다. 이 함수는 기본값에 사용자 옵션을 병합하고, 명령과 자동 명령을 만드는 등의 초기화를 수행합니다.

vim.tbl_deep_extend('force', defaults, opts or {})를 사용하면 사용자가 설정의 일부만 지정해도 모든 기본값을 적용할 수 있습니다.

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

플러그인 디렉터리

plugin/의 스크립트는 Neovim이 시작되고 runtimepath가 구성된 뒤 자동으로 실행됩니다. 이 스크립트는 작게 유지하세요.

일반적인 역할은 명령을 등록하거나 무거운 모듈을 지연 로드하기 위한 방어 코드를 등록하는 것입니다. 여기서 비용이 큰 작업은 피하고, 시작 속도를 유지할 수 있도록 setup이나 자동 명령으로 미루세요.

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

중복 로드 방지

로드 방지 코드는 파일이 두 번 소싱될 때 중복 초기화를 막습니다. vim.g.loaded_* 플래그를 설정하고 다시 진입하면 즉시 빠져나오세요.

플러그인 관리자와 :runtime이 파일을 다시 소싱할 수 있기 때문에 이는 필수입니다. 명령이나 자동 명령이 중복되면 원인을 찾기 어려운 문제가 발생합니다.

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

지연 로딩

빠른 시작을 위해서는 코드가 필요할 때만 로드되어야 합니다. plugin/에 가벼운 명령을 등록하고, 처음 사용할 때 무거운 모듈을 require하도록 하세요.

lazy.nvim과 같은 플러그인 관리자는 cmd, ft, keys 트리거로 이 방식을 체계화합니다. 따라서 모듈은 호출될 때까지 로드되지 않습니다.

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

런타임 경로와 패키지 경로

Neovim은 runtimepath를 검색하여 플러그인을 찾습니다. 내장 패키지 시스템은 pack/*/start/ 아래의 디렉터리를 자동으로 로드하고, :packadd를 통해 필요할 때 pack/*/opt/를 로드합니다.

대부분의 사용자는 관리자를 사용하지만, runtimepath를 이해하면 플러그인의 폴더를 어떻게 찾는지 알 수 있습니다.

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

상태 확인

lua/myplugin/health.lua 파일에 check 함수를 제공하면 사용자가 :checkhealth myplugin을 실행할 수 있습니다. vim.health API로 상태를 보고하세요.

vim.health.start, vim.health.ok, vim.health.warn, vim.health.error를 사용하면 누락된 의존성을 명확하게 표시할 수 있습니다.

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

문서와 태그

doc/myplugin.txt 도움말 파일을 함께 제공하세요. :helptags doc/를 실행하거나 관리자가 실행하도록 하면 태그 색인이 생성되어 :help myplugin이 작동합니다.

좋은 문서에는 명령, setup 옵션, 기본 키 매핑이 정리되어 있어야 합니다. 그러면 Neovim 안에서 플러그인을 쉽게 찾을 수 있습니다.

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

버전 관리와 게시

플러그인을 Git 저장소에 호스팅하면 사용자는 owner/repo 경로로 설치할 수 있습니다. 관리자가 버전을 고정할 수 있도록 의미 기반으로 릴리스에 태그를 지정하세요.

널리 사용되는 관리자용 설치 예시가 담긴 README, 라이선스, 최소한의 설정 예시를 포함하여 도입 장벽을 낮추세요.

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

간단한 확인

플러그인 패키징에 대해 이해한 내용을 확인해 보세요.

복습: 플러그인 패키징

플러그인은 lua/ 모듈과 자동 실행되는 plugin/ 스크립트를 포함하고, 선택적으로 doc/, ftplugin/, 상태 확인 파일을 포함하는 runtimepath 디렉터리입니다.

모듈 테이블을 반환하고, 기본값을 병합하는 setup을 제공하며, 중복 로드를 방지하세요. 무거운 코드는 지연 로드하고, 도움말 태그로 문서화한 뒤, 의미 기반 버전 태그를 사용해 Git으로 게시하세요.

자주 묻는 질문

“플러그인 패키징하기” 강의는 무료인가요?

네 — “플러그인 패키징하기” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Lua Academy 강의 전체를 잠금 해제할 수 있습니다. Lua Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“플러그인 패키징하기”에서 뭘 배우나요?

구조화하고 공유해 보세요. 브라우저에서 직접 실행하는 실습 코드로 Lua Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

Lua Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 Lua Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 4번째 강의입니다.

“플러그인 패키징하기” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 Lua Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 Lua Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← Lua Academy(으)로 돌아가기