빌드 도구

“LaTeX을 설치했다”고 말할 때 실제로 디스크에 놓이는 것은 프로그램 한 개가 아니라 명령줄 도구로 가득 찬 디렉터리입니다. 지금 쓰고 있는 TeX Live 2024 기기에서는 그 디렉터리에 490개에 가까운 명령이 늘어서 있고, 원고를 쓰는 동안 실제로 입력하는 것은 그중 한둘뿐입니다. 나머지 사백여든 몇 개는 문서가 말을 듣지 않는 날을 위해 배포판이 챙겨 둔 예비입니다. 패키지가 실제로 어디에 있는지 묻는 kpsewhich, 그 설명서를 여는 texdoc, 빠진 것을 설치하는 tlmgr, 그림의 여백을 잘라 내는 pdfcrop 같은 것들입니다. 이 페이지는 그 예비를 “어떤 물음에 답해 주는가”로 다시 늘어놓은 지도입니다. 그 위에 올라앉는 빌드 드라이버(latexmk, llmk, arara)는 별도의 페이지가 있으니, 여기서는 그보다 한 단계 아래를 다룹니다.

“제 컴퓨터에서는 되는데요” — 이때 가장 먼저 치는 명령이 kpsewhich

같은 .tex 파일이 내 컴퓨터에서는 컴파일되고 공저자의 컴퓨터에서는 멈춥니다. 이런 증상은 거의 전부 “파일이 어디에 있는가”의 문제이고, kpsewhich 한 줄이면 판가름이 납니다. 이 명령이 믿을 만한 이유는 스스로 뒤지지 않기 때문입니다. TeX Live 2024의 모든 엔진은 파일 검색 라이브러리인 kpathsea(이 판에서는 6.4.0)에 링크되어 있고, kpsewhich는 바로 그 라이브러리를 단독 명령으로 감싼 것입니다. 따라서 출력되는 경로는 엔진이 실제로 열게 될 파일이며 추측이 아닙니다. kpsewhich amsmath.sty가 아무것도 출력하지 않는다면 그 패키지는 이 환경에 없는 것이고, 컴파일하면 ! LaTeX Error: File amsmath.sty not found.가 나옵니다. 반대로 무언가를 출력했다면 문제는 “없음”이 아니라 “다른 것이 보이고 있음”입니다.

kpsewhich amsmath.sty
# /usr/local/texlive/2024/texmf-dist/tex/latex/amsmath/amsmath.sty

kpsewhich article.cls          # classes are found the same way
kpsewhich --all texmf.cnf      # every match, in search order
kpsewhich --progname=xelatex --format=tfm cmr10.tfm

--all을 붙이면 첫 번째 일치만이 아니라 찾은 전부가 탐색 순서대로 나열됩니다. “없음”보다 고약한 사고가 숨는 곳이 바로 여기입니다. TeX은 처음 찾은 것을 쓰므로, 몇 년 전 원고 폴더에 복사해 둔 낡은 .sty가 배포판의 최신판을 조용히 가려 버립니다. 로그에는 아무 이상도 나타나지 않고 동작만 기기마다 달라집니다. kpsewhich --all을 한 번 실행하면 같은 이름이 두 번 나오는 형태로 눈에 보입니다. kpsewhich는 .sty 전용도 아닙니다. 클래스(article.cls), 폰트 메트릭, 설정 파일까지 같은 방식으로 찾습니다. 엔진마다 탐색 경로가 다르면 --progname=xelatex처럼 이름을 바꿔 물어볼 수 있고, --format=tfm으로 파일 종류를 지정하면 범위를 좁힐 수 있습니다(종류 목록은 kpsewhich --help-formats).

--var-value와 --show-path — 엔진이 믿고 있는 설정을 읽어 내기

kpsewhich --var-value=TEXMFHOME은 설정 변수 하나만, kpsewhich --show-path=tex는 .tex를 찾는 디렉터리 목록 전체를 순서대로 출력합니다. 앞의 것은 “어디에”, 뒤의 것은 “어떤 순서로”에 답합니다. 이 둘을 익히면 문서에 적힌 일반론이 아니라 지금 눈앞의 환경이 실제로 쓰는 값을 확인할 수 있습니다. 특히 중요한 것이 아래 네 가지인데, TeX의 탐색 트리는 개인용・사이트용・배포판・생성물이라는 역할로 나뉘어 있습니다. 순서에도 의미가 있어서, 개인 트리가 배포판보다 앞에 오기 때문에 직접 만든 .sty로 표준 파일을 덮어쓸 수 있습니다.

kpsewhich --var-value=TEXMFHOME
# /Users/you/Library/texmf

kpsewhich --show-path=tex      # the whole ordered search list
kpsewhich --expand-var='$TEXMFDIST/tex/latex'

직접 만든 .sty는 어디에 두는가 — 개인용 texmf 트리

직접 쓴 .sty나 .cls, CTAN에서 손수 내려받은 패키지는 TEXMFHOME에 둡니다. 위치를 짐작하지 말고 kpsewhich --var-value=TEXMFHOME에게 물어보십시오. macOS의 MacTeX에서는 ~/Library/texmf가, 리눅스의 TeX Live에서는 대개 ~/texmf가 돌아오며 환경마다 다릅니다. 여기에 함정이 하나 있습니다. 이 디렉터리는 대개 처음에는 존재하지 않습니다. kpsewhich는 “설정된 위치”를 답할 뿐 “실재하는 위치”를 답하는 것이 아니기 때문입니다. 그래서 출력된 경로를 직접 만드는 데서 시작합니다. 내부 구조는 TDS(TeX Directory Structure)를 따라, LaTeX 패키지라면 TEXMFHOME/tex/latex/<이름>/<이름>.sty에 둡니다.

mkdir -p "$(kpsewhich --var-value=TEXMFHOME)/tex/latex/mystyle"
cp mystyle.sty "$(kpsewhich --var-value=TEXMFHOME)/tex/latex/mystyle/"
kpsewhich mystyle.sty          # found immediately, no texhash needed

texhash와 mktexlsr — 이름이 둘인 같은 프로그램

texhash와 mktexlsr는 같은 일을 합니다. 더 정확히는 같은 파일입니다. TeX Live 2024의 bin 디렉터리를 들여다보면 texhash는 mktexlsr을 가리키는 심볼릭 링크입니다. 둘 다 파일 이름 데이터베이스인 ls-R을 다시 만드는 명령입니다. 배포판 트리는 거대해서, 이 환경에서는 texmf-dist/ls-R 하나만으로도 5 MB가 넘습니다. 매번 디스크를 훑기에는 너무 느리므로 시스템 쪽 트리는 ls-R만 조회하도록 하고, 대신 파일을 추가하면 데이터베이스를 다시 만든다는 약속을 둡니다. 그래서 “TEXMFLOCAL에 넣었는데도 찾지 못한다”의 답은 sudo mktexlsr입니다. 반대로 앞 절의 TEXMFHOME은 매번 디스크를 보러 가므로 거기에 둔 .sty는 그 자리에서 바로 찾힙니다. 실제로 하나 만들어 kpsewhich에 물으면 texhash를 한 번도 실행하지 않고 답이 돌아옵니다. 개인용 트리를 권하는 이유 가운데 하나가 이것입니다.

texdoc — 패키지 설명서는 이미 내 컴퓨터에 있습니다

texdoc geometry라고 치면 geometry 패키지의 PDF 설명서가 뷰어에서 열립니다. 네트워크는 필요 없습니다. CTAN에서 패키지가 올 때 설명서도 함께 들어왔기 때문입니다. 이 명령의 값어치가 바로 여기에 있습니다. 검색으로 찾아낸 오래된 해설보다, 지금 설치되어 있는 그 판의 설명서가 정확합니다. 같은 이름의 문서가 여럿일 수 있으니 헷갈리면 texdoc -l geometry로 후보를 나열합니다. 이 환경에서는 영어판 geometry.pdf 외에 독일어판 geometry-de.pdf도 함께 나옵니다. -s(showall)를 붙이면 관련이 옅은 것까지 건지고, -M을 붙이면 기계가 읽을 수 있는 목록이 됩니다. TeX Live 2024에 들어 있는 것은 Texdoc 4.1(2024-03-10)이며, 저작권 표시에는 Manuel Pégourié-Gonnard, Takuto Asakura, TeX Live Team의 이름이 적혀 있습니다.

texdoc geometry            # open the manual
texdoc -l geometry         # list every candidate first
texdoc texdoc              # the manual for texdoc itself

tlmgr install / update / info, 그리고 “TeX Live 2024 is frozen”의 뜻

tlmgr는 TeX Live의 패키지 관리자이고, 일상적으로 쓰는 것은 셋입니다. tlmgr info NAME으로 그 패키지에 대해 묻고, tlmgr install NAME으로 설치하며, tlmgr update --self --all로 전체를 최신으로 만듭니다. 그중 info의 출력이 가장 실용적입니다. installed: Yes로 설치 여부를, revision:으로 어느 판인지를, collection:으로 어느 묶음에 속하는지를 한눈에 볼 수 있습니다. 여기서 모르면 반나절을 날리는 사실이 하나 있습니다. 명령 이름과 TeX Live의 패키지 이름은 일치하지 않을 수 있습니다. 예컨대 tlmgr info llmk는 tlmgr: cannot find package llmk로 시작하지만, 이어서 스스로 설명과 파일 이름을 다시 검색해 light-latex-make를 제시합니다. llmk라는 명령은 같은 이름의 패키지에 들어 있지 않은 것입니다.

tlmgr info amsmath             # installed? which revision? which collection?
sudo tlmgr install siunitx     # a system-wide tree needs root
sudo tlmgr update --self --all
tlmgr --version                # also prints which installation is in use

처음 보면 또 하나 놀라게 되는 것이 동결 안내입니다. TeX Live 2024에서 tlmgr을 실행하면 대부분의 하위 명령이 먼저 TeX Live 2024 is frozen과 and will no longer be routinely updated.를 출력합니다. 이것은 오류가 아니라 안내입니다. 새 연도판이 나오면 이전 연도의 저장소는 정기 갱신을 멈춘다는 TeX Live의 운영 방식을 알릴 뿐이고, 명령 자체는 그 아래에서 평소대로 동작합니다. tlmgr info amsmath도 배너 뒤에 패키지 정보를 온전히 돌려줍니다. 따라서 대처는 “다시 실행하기”가 아니라 “새 연도판을 설치하기”입니다. 게다가 MacTeX 같은 표준 설치에서는 /usr/local/texlive/2024/texmf-dist의 소유자가 root이므로 tlmgr install과 tlmgr update에는 sudo가 필요합니다. 관리자 권한이 없는 기기에서는 여기서 씨름하기보다 앞 절처럼 TEXMFHOME에 손으로 넣는 편이 빠를 때가 많습니다.

pdfcrop — 그림 PDF의 흰 여백 잘라 내기

pdfcrop figure.pdf를 실행하면 쪽마다 여백을 계산해 잘라 낸 figure-crop.pdf가 만들어집니다. 쓸모가 있는 자리는 TikZ 그림을 별도 파일로 만들었을 때, 또는 다른 소프트웨어가 “A4 한가운데 작은 그림” 형태로 PDF를 내보냈을 때입니다. 그대로 \includegraphics로 넣으면 그림이 아니라 종이를 붙이는 셈이 됩니다. 여백을 일부러 조금 남기고 싶다면 --margins "5 5 5 5"처럼 네 변을 지정할 수 있고, 단위는 bp(big point)입니다. 함정은 의존성입니다. pdfcrop은 스스로 자르지 않고, 기본적으로 Ghostscript(gs, --gscmd로 변경 가능)와 TeX 엔진을 불러옵니다. “pdfcrop은 설치했는데 동작하지 않는다”는 보고는 대부분 Ghostscript가 없는 것이 원인입니다. TeX Live 2024에 들어 있는 것은 pdfcrop 1.42(2023/04/15, Heiko Oberdiek 작)입니다.

pdfcrop figure.pdf                       # -> figure-crop.pdf
pdfcrop --margins "5 5 5 5" figure.pdf   # keep 5bp on every side
pdfcrop --luatex figure.pdf              # drive lualatex instead of pdftex

완성된 PDF의 속을 들여다보기 — pdftotext는 TeX의 명령이 아닙니다

완성된 PDF에서 텍스트를 뽑아내고 싶을 때 많은 해설이 pdftotext를 듭니다. 다만 pdftotext는 TeX Live의 일부가 아닙니다. TeX Live 2024의 bin 디렉터리를 끝까지 훑어도 들어 있지 않으며, 이 맥에 있는 것은 Homebrew의 poppler가 설치한 것입니다. pdfinfo도 마찬가지입니다. 써도 상관없지만, TeX이 멀쩡히 설치된 기기에서 pdftotext: command not found가 나는 것은 고장이 아니라 애초에 다른 소프트웨어이기 때문입니다. TeX Live 쪽에 있는 것은 pdftosrc이며, 사용법 줄이 pdftosrc <PDF-file> [<stream-object-number>]인 그대로 PDF 안의 스트림 객체를 꺼내는 도구입니다. 일상적인 점검에서는 PDF를 들여다보기보다 .log를 읽는 편이 대개 빠르고, 로그를 간추리는 texfot, PDF를 다루는 Ghostscript, 벡터 출력을 만드는 dvisvgm 같은 이웃 도구들은 별도의 페이지에 정리되어 있습니다.

증상으로 명령을 찾기

몸에 익혀 둘 만한 것은 묻는 순서입니다. 무언가 이상하다 싶으면 남에게 묻기 전에 kpsewhich로 위치를, texdoc로 사양을 확인하십시오. 둘 다 네트워크도 관리자 권한도 필요 없고 몇 초 만에 답합니다. 그렇게 해서 정말로 없다는 것이 드러났을 때 비로소 tlmgr에 손을 뻗고, 둘 자리가 헷갈리면 TEXMFHOME을 고릅니다. 엔진을 몇 번 어떤 순서로 돌릴지 자동화하는 층(latexmk 등)과 이 “찾고・읽고・설치하는” 층은 서로 다릅니다. 뒤쪽이 단단해지지 않는 한, 앞쪽을 아무리 다듬어도 기기마다 생기는 어긋남은 사라지지 않습니다.