TeX 디렉터리 구조와 경로

이 페이지를 쓴 TeX Live 2024 환경에서 kpsewhich -expand-path='$TEXINPUTS'를 실행하면 8,798개의 디렉터리, 약 50만 자에 이르는 경로가 출력됩니다. 그런데도 \usepackage{amsmath}는 순식간에 해결됩니다. 이유는 간단합니다. LaTeX은 평소에 그 디렉터리들을 거의 들여다보지 않기 때문입니다. 이 페이지는 그 비결의 두 축을 실제 명령 출력으로 해부합니다. 모든 texmf 파일의 위치를 정한 지도인 TDS(TeX Directory Structure), 그리고 그 위를 달리는 탐색 엔진 kpathsea입니다. 어느 트리가 업그레이드에서 통째로 갈리고 어느 트리가 살아남는가. 그리고 왜 TEXMFHOME에 넣은 파일만은 mktexlsr 없이도 찾아지는가.

TDS: 왜 패키지 하나가 아홉 군데에 흩어지는가

TDS는 파일을 패키지 단위가 아니라 종류 단위로 정리합니다. 그래서 한 패키지의 파일이 한곳에 모이는 일은 없습니다. amssymb를 제공하는 amsfonts를 이 TeX Live 2024에서 세어 보면 texmf-dist 아래 아홉 개 디렉터리에 흩어져 있습니다. 매크로는 tex/latex/amsfonts/, 주석이 달린 원본 .dtx는 source/latex/amsfonts/, 설명서 PDF는 doc/fonts/amsfonts/에 있고, 글꼴 자체는 형식별로 fonts/tfm/, fonts/type1/, fonts/afm/, fonts/map/, fonts/source/로 다시 갈립니다. plain TeX용만 tex/plain/amsfonts/로 따로 놓입니다.

$ find /usr/local/texlive/2024/texmf-dist -maxdepth 4 -type d -path '*amsfonts*' | sort
/usr/local/texlive/2024/texmf-dist/doc/fonts/amsfonts
/usr/local/texlive/2024/texmf-dist/fonts/afm/public/amsfonts
/usr/local/texlive/2024/texmf-dist/fonts/map/dvips/amsfonts
/usr/local/texlive/2024/texmf-dist/fonts/source/public/amsfonts
/usr/local/texlive/2024/texmf-dist/fonts/tfm/public/amsfonts
/usr/local/texlive/2024/texmf-dist/fonts/type1/public/amsfonts
/usr/local/texlive/2024/texmf-dist/source/latex/amsfonts
/usr/local/texlive/2024/texmf-dist/tex/latex/amsfonts
/usr/local/texlive/2024/texmf-dist/tex/plain/amsfonts

왜 이렇게 나눌까요. 답은 이식성입니다. TeX은 macOS, 유닉스, 윈도우에서 돌아가고 CTAN(Comprehensive TeX Archive Network)에는 수천 개의 패키지가 모여 있습니다. 배포처마다 파일 위치가 다르면 패키지를 내놓는 쪽도 찾는 쪽도 매번 걸려 넘어집니다. TeX 사용자 모임(TUG)이 1990년대에 정리한 TDS는 “매크로는 tex/ 아래, 글꼴은 fonts/<형식>/<공급처>/<서체>/ 아래”라는 규칙을 전 세계가 공유하게 했습니다. 덕분에 어떤 OS, 어떤 배포판에서도 파일의 위치를 규칙만으로 짐작할 수 있습니다. tex/ 아래에는 한 단계가 더 있어 tex/<포맷>/<패키지>/ 형태가 되며, <포맷>은 latex, plain, generic 등입니다.

표에서 뜻밖인 대목이 있다면 이것입니다. 설명서가 소프트웨어 본체보다 무겁습니다. texmf-dist 전체 7.9 GB 중 doc/가 3.7 GB이고, 매크로 본체인 tex/는 594 MB에 지나지 않습니다. TeX Live 설치 프로그램에 “문서를 넣지 않음” 선택지가 있는 이유가 여기에 있고, Docker 이미지가 -doc 유무로 갈리는 이유도 같습니다. 이 배치를 알아 두면 쓸모도 있습니다. 패키지의 동작이 납득되지 않을 때 source/latex/<패키지>/*.dtx를 바로 읽으러 갈 수 있고, texdoc가 여는 설명서가 doc/에 있는 실제 파일임을 알게 됩니다.

어느 트리가 업그레이드에서 살아남는가

통째로 갈리는 것은 texmf-dist뿐입니다. TeX Live는 해마다 디렉터리를 만들고(/usr/local/texlive/2024), 배포본 본체인 texmf-dist를 그 안에 넣습니다. 이듬해가 되면 옆에 2025가 생기고 texmf-dist는 새것으로 교체됩니다. 그러므로 배포본 안에 자기 파일을 넣는 것은 자살 행위이고, 뒤집어 말하면 연도 디렉터리 바깥에 있는 것은 무사합니다. TEXMFLOCAL이 /usr/local/texlive/texmf-local, 곧 2024의 바깥에 놓인 것은 우연이 아니라 바로 이 설계입니다. TEXMFHOME은 그보다 더 바깥, 홈 디렉터리 안에 있습니다.

# Never guess these paths - ask. Values below: TeX Live 2024 on macOS.
$ kpsewhich -var-value=TEXMFROOT
/usr/local/texlive/2024
$ kpsewhich -var-value=TEXMFLOCAL      # note: OUTSIDE the year directory
/usr/local/texlive/texmf-local
$ kpsewhich -var-value=TEXMFHOME      # ~/texmf on Linux, ~/Library/texmf on macOS
/Users/you/Library/texmf
$ kpsewhich -var-value=TEXMFVAR
/Users/you/Library/texlive/2024/texmf-var

같은 이름의 파일이 여러 트리에 있으면 어느 쪽이 이길까요. 그것을 정하는 것이 TEXMF라는 변수 하나이고, 그 값은 탐색 우선순위를 차례대로 늘어놓은 목록에 지나지 않습니다. 이 TeX Live 2024에서는 아래와 같습니다. 왼쪽이 강해서 자기 설정과 캐시가 먼저, 다음이 개인 트리 TEXMFHOME, 그다음이 컴퓨터 전체의 TEXMFLOCAL, 마지막이 배포본 TEXMFDIST입니다. 즉 TEXMFHOME에 mystyle.sty를 두면 배포본의 같은 이름 파일을 가릴 수 있습니다. 덮어쓰는 것이 아니라 개인 → 사이트 → 배포본이라는 자연스러운 서열입니다. 일부 항목 앞의 !! 표시는 다음 절에서 설명합니다.

$ kpsewhich -var-value=TEXMF
{{}/Users/you/Library/texlive/2024/texmf-config,
 /Users/you/Library/texlive/2024/texmf-var,
 /Users/you/Library/texmf,
 !!/usr/local/texlive/texmf-local,
 !!/usr/local/texlive/2024/texmf-config,
 !!/usr/local/texlive/2024/texmf-var,
 !!/usr/local/texlive/2024/texmf-dist}

# Note which entries carry "!!" - and which do not.

texmf-var는 지워도 되는가

안에 든 것은 모두 생성물이므로 원리적으로는 지워도 잃을 것이 없습니다. 다만 “지우면 낫는다”를 외우기 전에 무엇이 들어 있는지 한번 보아 둘 값어치는 있습니다. 이 TeX Live 2024에서 시스템 쪽 texmf-var는 259 MB이고, 그중 233 MB가 web2c/로 .fmt 파일 53개가 들어 있습니다. pdflatex.fmt 하나만 7.8 MB입니다. 포맷 파일은 매번 latex.ltx와 클래스 파일을 다시 읽지 않아도 되게 해 주는 “통조림 메모리 이미지”입니다. 사용자 쪽 texmf-var는 더 커서 293 MB이고, 그중 257 MB가 luatex-cache/, 곧 LuaTeX이 글꼴을 해석한 결과입니다. updmap이 써 내는 psfonts.map도 여기 있습니다.

$ du -sh /usr/local/texlive/2024/texmf-var/*
4.0K    ls-R
 36K    tex
 26M    fonts
233M    web2c          # 53 .fmt files; pdflatex.fmt alone is 7.8 MB

$ du -sh "$(kpsewhich -var-value=TEXMFVAR)"/*
 32K    fonts
2.1M    texdoc
 12M    web2c
 22M    luatexja
257M    luatex-cache   # LuaTeX font analysis, rebuilt on demand

여기서 실무 판단이 나옵니다. 포맷 파일이 낡아 동작이 이상할 때는 디렉터리를 지우는 대신 fmtutil-sys --all로 다시 만드는 것이 정석입니다. 트리를 통째로 지우는 것은 LuaTeX 폰트 캐시가 깨져 luaotfload가 이상한 오류를 뱉는 경우처럼 범위를 좁힐 수 있을 때로 한정합니다. 다 지워도 다음 컴파일이 수십 초 느려질 뿐이지만, texmf-var와 texmf-config를 혼동하지 마세요. 후자까지 함께 날리면 updmap 설정도 사라집니다. 재생성 명령의 자세한 내용은 패키지·글꼴 관리 페이지가 다룹니다.

kpathsea는 파일을 어떻게 찾는가

탐색을 맡는 것은 kpathsea(kpath search)라는 공유 라이브러리입니다. pdftex, xetex, luatex, dvipdfmx, bibtex 중 어느 것도 스스로 찾지 않고, 모두 kpathsea에게 “amsmath.sty는 어디 있나”라고 묻습니다. kpathsea가 받는 것은 규칙이 담긴 문자열 하나입니다. 기억할 기호는 셋입니다. $VAR는 변수 전개, 끝의 //는 “이 아래를 재귀적으로 전부”, 앞의 !!는 “디스크를 훑지 말고 다음 절에서 설명할 파일 이름 데이터베이스만 보라”입니다. LaTeX 원본을 찾는 TEXINPUTS를 출력해 보면 셋이 한꺼번에 나옵니다.

$ kpsewhich -progname=pdflatex -var-value=TEXINPUTS
.:{...the TEXMF list...}/tex/{latex,generic,}//

# The same query, run as a different program:
$ kpsewhich -progname=pdflatex-dev -var-value=TEXINPUTS
.:{...the TEXMF list...}/tex/{latex-dev,latex,generic,}//

# How many real directories does that string stand for?
$ kpsewhich -progname=pdflatex -expand-path='$TEXINPUTS' | tr : '\n' | wc -l
    8798

읽는 법은 이렇습니다. 먼저 .(원고가 있는 디렉터리), 없으면 각 texmf 트리의 tex/ 아래를 latex → generic → 나머지 순으로 재귀 탐색합니다. 원고 옆의 파일이 최우선이라는 것은 직관 그대로이고, 이 절의 함정도 바로 거기에 있습니다. 또 하나 눈여겨볼 것은 {latex,generic,}의 첫 항목이 실행 중인 프로그램 이름에 따라 바뀐다는 점입니다. pdflatex-dev로 부르면 {latex-dev,latex,generic,}이 되어 개발판 트리를 먼저 봅니다. kpathsea는 “누가 물었는가”에 따라 답을 바꿉니다. 덧붙여 -expand-path가 돌려준 8,798이라는 숫자는 경고이기도 합니다. ls-R라는 색인이 없다면 조회할 때마다 그만큼의 디렉터리를 열어야 한다는 뜻이니까요.

ls-R와 TEXMFDBS: TEXMFHOME만 mktexlsr가 필요 없는 이유

답은 한 줄로 씁니다. 색인을 가진 트리의 목록인 TEXMFDBS에 TEXMFHOME이 들어 있지 않기 때문입니다. 앞 절의 8,798개 디렉터리를 매번 여는 것은 말이 안 되므로, kpathsea는 각 트리의 뿌리에 ls-R라는 파일 이름 데이터베이스를 두고 그쪽을 봅니다. 어느 트리가 색인을 갖는지는 TEXMFDBS가 밝히는데, 이 TeX Live 2024에서는 정확히 넷——TEXMF에서 !!가 붙어 있던 바로 그 트리들——만 나옵니다. TEXMFHOME은 없습니다. 그래서 TEXMFHOME은 매번 디스크를 훑고, 파일을 두는 순간부터 찾아집니다.

$ kpsewhich -var-value=TEXMFDBS
{!!/usr/local/texlive/texmf-local,
 !!/usr/local/texlive/2024/texmf-config,
 !!/usr/local/texlive/2024/texmf-var,
 !!/usr/local/texlive/2024/texmf-dist}
# TEXMFHOME is absent from this list.

# The experiment: the SAME file, the SAME TDS layout, two different trees.
$ mkdir -p /tmp/t/tex/latex/demo && touch /tmp/t/tex/latex/demo/demo.sty

$ TEXMFHOME=/tmp/t  kpsewhich -progname=pdflatex demo.sty
/tmp/t/tex/latex/demo/demo.sty          # found - no ls-R, no mktexlsr

$ TEXMFLOCAL=/tmp/t kpsewhich -progname=pdflatex demo.sty
$ echo $?
1                                       # NOT found: "!!" means index-only

ls-R 파일 자체는 수수한 텍스트입니다. 첫 줄은 언제나 % ls-R -- filename database for kpathsea; do not change this line.이고, 그 뒤로 디렉터리별 파일 목록이 이어집니다. 이 기계의 texmf-dist/ls-R는 5.2 MB, 276,953행이며 16,063개 디렉터리에 있는 228,764개 파일을 색인합니다. 색인을 다시 만드는 명령은 mktexlsr이고, texhash는 그것을 가리키는 심볼릭 링크——같은 프로그램의 다른 이름——입니다. 실무 규칙은 깔끔합니다. TEXMFLOCAL이나 시스템 트리에 손으로 파일을 두면 mktexlsr가 필요하고, TEXMFHOME이면 필요 없습니다. 위의 실험이 그 이유의 전부입니다. 명령의 자세한 쓰임은 패키지·글꼴 관리 페이지에서 다룹니다.

kpsewhich --all: 오래된 사본에 가려진 파일 찾아내기

kpsewhich --all NAME은 일치하는 파일을 탐색 순서대로 전부 출력합니다. 옵션 없는 kpsewhich는 첫 번째, 곧 실제로 읽히는 파일만 돌려주므로 두 번째 이후를 보려면 --all이 필요합니다. “같은 이름의 파일이 둘 있고 오래된 쪽이 이기고 있다”는 전형적인 사고가 명령 하나로 드러납니다. 깨끗한 TeX Live 2024에서도 amsmath.sty는 실제로 두 개 존재합니다. 안정판인 tex/latex/amsmath/와 개발판인 tex/latex-dev/amsmath/입니다.

$ kpsewhich --all amsmath.sty
/usr/local/texlive/2024/texmf-dist/tex/latex/amsmath/amsmath.sty
/usr/local/texlive/2024/texmf-dist/tex/latex-dev/amsmath/amsmath.sty

# Same two files, opposite order - because the program name changed the path.
$ kpsewhich --all -progname=pdflatex-dev amsmath.sty
/usr/local/texlive/2024/texmf-dist/tex/latex-dev/amsmath/amsmath.sty
/usr/local/texlive/2024/texmf-dist/tex/latex/amsmath/amsmath.sty

이 두 번의 실행은 환경을 건드리지 않고도 반복할 수 있는 실험이며, “첫 번째가 이긴다”는 규칙을 확인해 줍니다. 그런데 실무에서 이 규칙이 이빨을 드러내는 곳은 대개 원고 바로 옆입니다. TEXINPUTS가 .으로 시작하므로, 몇 해 전에 어디선가 받아 프로젝트 폴더에 섞여 든 낡은 amsmath.sty나 article.cls가 배포본의 최신 사본보다 먼저 읽힙니다. 게다가 가장 고약한 형태로 나타납니다. 내 기계에서는 되는데 공저자 환경에서는 안 되는 것입니다. 짚이는 데 없는 오류——! LaTeX Error: Command \... already defined. 같은——나 두 기계 사이의 불일치를 만나면 먼저 kpsewhich --all을 치십시오. 그것이 가장 짧은 길입니다.

kpsewhich 사용법: -var-value와 -expand-path의 차이

-var-value는 설정이 말하는 것을, -expand-path는 실제로 디스크에 있는 것을 보여 줍니다. 이 틈이 진단에서 힘을 발휘합니다. 이 TeX Live 2024에서 TEXMF를 두 방식으로 출력하면, -var-value는 !! 표시까지 붙은 트리 일곱 개를 늘어놓는데 -expand-path는 다섯 개만 돌려줍니다. 빠진 둘——~/Library/texlive/2024/texmf-config와 ~/Library/texmf——은 아직 만들어지지 않았을 뿐입니다. 즉 설정에는 있는데 전개 결과에 없다면 그 디렉터리는 존재하지 않습니다. TEXMFHOME에 분명히 넣었는데 파일이 안 찾아진다면 가장 먼저 의심할 곳이 여기입니다.

texmf.cnf: 변수 값은 어디에서 오는가

지금까지 나온 TEXMF, TEXINPUTS, 각 트리의 위치는 모두 texmf.cnf라는 설정 파일에 적혀 있습니다. kpathsea는 무엇보다 먼저 이 파일을 읽어 탐색 경로, 트리의 위치, 메모리 상한 같은 동작 매개변수를 받아 옵니다. 재미있는 것은 texmf.cnf가 하나뿐이 아닐 수 있다는 점입니다. kpathsea는 TEXMFCNF라는 전용 탐색 경로를 따라 여러 texmf.cnf를 차례로 읽고, 어떤 변수든 가장 먼저 찾은 정의를 채택합니다(나중에 읽는 파일이 앞의 정의를 덮어쓰지 않습니다). 이 기계에서는 두 개가 쌓여 있습니다.

$ kpsewhich -all texmf.cnf
/usr/local/texlive/2024/texmf.cnf                     # TeX Live's thin override, read first
/usr/local/texlive/2024/texmf-dist/web2c/texmf.cnf    # hundreds of lines of defaults

위쪽의 얇은 texmf.cnf(TeX Live가 써 내는 차이분만 담긴 파일)가 먼저 읽히고, 아래쪽의 두툼한 기본값 파일이 나중입니다. 그러므로 값을 영구히 바꾸고 싶을 때의 정석은 배포본 파일을 고치는 것이 아니라, 우선순위가 높은 자리에 필요한 줄만 적는 것입니다. TEXMFLOCAL/web2c/texmf.cnf가 그 자리입니다. 이렇게 하면 설정이 배포판 업그레이드를 살아남고, 무엇을 바꿨는지도 몇 줄만 보면 알 수 있습니다. 정리하면, texmf.cnf가 트리의 위치와 탐색 경로의 모양을 정하고, kpathsea가 그 순서대로(대개 ls-R를 거쳐) 목적 파일을 찾습니다. \usepackage{...} 한 줄이 조용히 해결되는 구조는 이 두 층으로 되어 있습니다.

PATH가 찾는 것은 프로그램, kpathsea가 찾는 것은 파일

이 둘은 전혀 다른 구조여서, 혼동하면 진단이 어긋납니다. kpathsea가 찾는 것은 TeX이 읽는 파일(.sty, .cls, 글꼴)이지만, 그보다 먼저 셸이 실행 파일 자체, 곧 pdflatex를 찾아야 합니다. 그것은 운영체제의 몫이고, 환경 변수 PATH에 나열된 디렉터리를 차례로 훑는 일에 지나지 않습니다. TeX Live는 실행 파일을 OS·아키텍처별 bin 디렉터리 하나에 모아 두고, macOS의 MacTeX은 연도에 의존하지 않는 안정 링크 /Library/TeX/texbin을 마련합니다. 그러므로 pdflatex: command not found는 kpathsea 문제가 아니라 거의 확실히 PATH 문제입니다. 반대로 ! LaTeX Error: File 'foo.sty' not found.는 PATH와 무관합니다. 설정 절차 자체는 데스크톱 설치 페이지가 다룹니다.

$ which pdflatex
/Library/TeX/texbin/pdflatex
$ readlink /Library/TeX/texbin
Distributions/Programs/texbin

직접 만든 .sty는 어디에 두는가

개인용은 TEXMFHOME, 연구실 공용은 TEXMFLOCAL, 그리고 어느 쪽이든 TDS 배치를 지킬 것. 규칙은 이게 전부입니다. 다만 위치를 넘겨짚지 마십시오. TEXMFHOME의 기본값은 OS마다 달라서 리눅스는 ~/texmf지만 macOS의 MacTeX은 ~/Library/texmf입니다. 그래서 절차는 반드시 kpsewhich -var-value=TEXMFHOME에서 시작합니다. 반대로 학회의 myconf.cls나 학술지의 journal.sty처럼 그 원고 한 벌에만 속하는 파일은 원고 옆에 두어도 됩니다. TEXINPUTS가 .을 먼저 보기 때문입니다. 다만 article.cls 같은 흔한 이름을 원고 옆에 두는 것은 앞 절의 가림 사고를 손수 만드는 일입니다.

# Ask for the tree, never hard-code it: this is ~/texmf on Linux,
# ~/Library/texmf on macOS, %USERPROFILE%\texmf on Windows.
HOME_TREE="$(kpsewhich -var-value=TEXMFHOME)"

mkdir -p "$HOME_TREE/tex/latex/thesisstyle"
cp thesisstyle.sty "$HOME_TREE/tex/latex/thesisstyle/"

# Confirm which copy TeX will pick up. No mktexlsr needed for TEXMFHOME.
kpsewhich thesisstyle.sty
kpsewhich --all thesisstyle.sty    # and check nothing else shadows it

kpsewhich가 기대한 경로를 돌려주면 원고에는 \usepackage{thesisstyle}라고 쓰기만 하면 됩니다. 아무것도 돌려주지 않는다면 순서대로 셋을 의심하십시오. (1) 파일이 tex/latex/<패키지명>/ 아래에 있는가(TEXINPUTS는 tex/ 아래만 봅니다). (2) 파일 이름의 대소문자가 맞는가. (3) 시스템 트리에 두었다면 mktexlsr를 돌렸는가. 이 순서로 확인하면 증상이 “TeX이 망가졌다”에서 “탐색 지도의 어디에 두었나”라는, 답이 나오는 질문으로 바뀝니다.