빌드 도구

제대로 된 문서 하나를 완성하려면 보통 latex를 두 번 실행하고, 그 사이에 biber(참고문헌)나 makeindex(색인) 등을 끼워 넣어 여러 명령을 올바른 순서와 횟수로 돌려야 합니다. 이 과정을 손으로 반복하는 것은 번거롭고 실수하기 쉽습니다. 이를 자동화하는 것이 빌드 도구 입니다. 대표적으로 세 가지가 있습니다. 필요한 횟수를 자동으로 판단하는 latexmk, TOML로 설정을 쓰는 llmk, 절차를 소스에 명시하는 arara 입니다.

왜 빌드 도구가 필요한가

상호 참조와 목차를 확정하려면 최소 두 번 컴파일해야 합니다. 첫 번째 실행에서 번호를 .aux에 쓰고, 두 번째 실행에서 다시 본문으로 읽어 옵니다. 참고문헌이 있으면 중간에 biber나 bibtex, 색인이 있으면 makeindex, 용어집이면 또 다른 명령이 필요하며, 순서나 횟수가 틀리면 번호가 어긋납니다. 빌드 도구는 필요한 명령을 올바른 순서로, 필요한 만큼 자동 실행하고 결과가 안정될 때까지 반복합니다. 각 개별 명령의 역할은 “컴파일 명령”을 보세요.

latexmk — 자동으로 처리해 주는 표준 도구

latexmk(John Collins가 만든 Perl 스크립트)는 사실상의 표준이며, Overleaf도 기본적으로 이것을 사용합니다. .aux 같은 파일의 변화를 보고 다시 실행이 필요한지 스스로 판단 하고, 적절한 시점에 biber/bibtex와 makeindex도 호출합니다. 출력이 안정될 때까지 자동으로 반복하므로, 사용자는 사실상 “빌드해”라고 말하기만 하면 됩니다.

특히 편리한 것은 -pvc(preview continuously) 입니다. 소스를 저장할 때마다 필요한 만큼만 다시 빌드하고 뷰어를 갱신합니다.

latexmk -pdf -pvc document.tex   # 保存のたび自動ビルド / rebuild on every save
latexmk -c                       # 補助ファイルを掃除 / clean aux files

동작은 .latexmkrc 설정 파일(현재 디렉터리의 latexmkrc/.latexmkrc 또는 ~/.latexmkrc)에 쓸 수 있습니다. $pdf_mode로 출력 방식을 고르며, 현재 latexmk에서는 1이 pdfLaTeX, 2가 DVI → dvips → ps2pdf, 3이 DVI → dvipdf, 4가 LuaLaTeX, 5가 XeLaTeX입니다. 일본어 문서에서는 $latex를 uplatex로, $dvipdf를 dvipdfmx로 두고 $pdf_mode = 3으로 PDF 생성을 DVI 변환 경로에 맡기는 구성이 흔합니다.

# .latexmkrc
$pdf_mode = 1;   # 1 = pdflatex
$pdflatex = 'pdflatex -synctex=1 -interaction=nonstopmode %O %S';

llmk — 문서와 함께 이동하는 설정

llmk(Light LaTeX Make, Takuto Asakura 제작) 는 빌드 절차를 TOML로 선언적으로 쓰는 도구입니다. llmk.toml에 source(대상 파일)와 사용할 명령을 쓰거나, .tex 안의 매직 코멘트 로 같은 설정을 넣습니다. 목표는 “환경에 의존하지 않고 누가 어디서 실행해도 같은 결과가 나오는” 재현성입니다. 설정이 문서와 함께 이동하므로 공동 작업과 배포에 적합합니다.

# llmk.toml
latex  = "lualatex"
source = "main.tex"

매직 코멘트를 사용할 때는 세 개 이상의 + 문자로 된 줄 사이에 TOML을 씁니다. % !TEX 형식이나 YaTeX 형식도 읽을 수 있지만 TOML 블록이 우선합니다.

% +++
% latex = "uplatex"
% dvipdf = "dvipdfmx"
% +++
\documentclass{ujarticle}

arara — 절차를 소스에 명시하기

arara(Island of TeX, Paulo Cereda 등 제작) 는 로그를 분석해 횟수를 추측하는 대신, 할 일을 작성자가 명시하는 방식입니다. .tex 맨 앞에 디렉티브 를 주석으로 나열하고 arara document.tex를 실행하면 위에서 아래로 차례대로 실행됩니다. 각 단계가 성공해야 다음 단계로 넘어갑니다. 무엇이 실행되는지 소스만 보아도 분명합니다.

% arara: pdflatex
% arara: biber
% arara: pdflatex
% arara: pdflatex: { synctex: yes }
\documentclass{article}

각 디렉티브는 명령 호출 방식을 정의한 YAML 파일인 규칙 에 대응합니다. pdflatex 디렉티브는 pdflatex 규칙에 매핑되고, { synctex: yes } 같은 옵션도 전달할 수 있습니다. 절차를 완전히 제어하고 싶거나 특수한 공정을 엄밀히 재현해야 할 때 알맞습니다.

무엇을 선택할까

• latexmk — 필요한 실행 횟수를 자동 판단합니다. 가장 널리 쓰이고 -pvc 자동 미리보기가 쾌적합니다. 망설이면 이것입니다.
• llmk — TOML 설정을 문서와 함께 포함할 수 있어 환경에 덜 의존하고 재현성이 높습니다. 공동 작업과 배포에 적합합니다.
• arara — 절차를 소스에 명시합니다. 무엇이 실행되는지 한눈에 보이며, 공정을 엄밀하게 관리하고 싶을 때 좋습니다.

셋 모두 (u)platex → dvipdfmx를 손으로 순서대로 입력하는 것보다 안전하고 빠릅니다. 잘 모르겠다면 먼저 latexmk -pdf -pvc로 시작하고, 설정의 휴대성이나 명시성이 필요해지면 llmk와 arara를 검토하면 됩니다.

빌드 도구 장의 프로젝트 계약

빌드 도구는 단지 편리한 명령 이름이 아니라 공동 집필자와 CI 사이의 프로젝트 계약 입니다. .latexmkrc, llmk.toml, arara 디렉티브 중 무엇을 고르든 “이 원고는 어떤 엔진으로, 참고문헌은 어떤 도구로 처리하고, 색인을 만들며, PDF를 어디에 출력하는가”를 파일로 남깁니다. 빌드 도구 장의 프로젝트 계약을 먼저 작성해 두면 편집기를 바꾸어도 PDF 제출 전에 같은 절차를 재현할 수 있습니다.

운용할 때는 편집기 버튼도 CI도 같은 계약을 호출하게 합니다. 예를 들어 사람은 latexmk -pdf main.tex를 쓰고 CI는 별도의 원시 lualatex 호출을 쓰면, 글꼴이나 참고문헌 처리 실패가 제출 직전까지 드러나지 않을 수 있습니다. 먼저 명령줄에서 성공하는 한 가지 명령을 정하고, 그것을 편집기, 감시 빌드, CI에 배포하는 것이 안전합니다.