TeX 설치는 매크로, 클래스, 글꼴, 구성 등 수만 개의 파일 더미입니다. \usepackage{amsmath} 한 줄을 쓰면 왜 디스크 어딘가에서 amsmath.sty를 안정적으로 찾을 수 있나요? 그 뒤에는 파일이 있는 위치에 대한 표준(TDS)과 파일을 찾는 메커니즘(kpathsea)이라는 두 가지 규칙이 있습니다. 이 페이지는 그 지도를 그립니다.
TDS: 모든 것을 위한 표준 장소
모든 것은 texmf 트리라는 디렉토리 트리에서 시작됩니다. "texmf"는 *TeX 및 Metafont*의 약어입니다. 그 아래에는 종류별로 파일 분기가 있습니다. 매크로와 클래스는 tex/ 아래에, 글꼴과 관련된 모든 것은 fonts/ 아래에, 참고문헌 데이터는 bibtex/ 아래에, 문서(설명서)는 doc/ 아래에, 스크립트는 scripts/ 아래에 있습니다. 모든 시스템에서 이 레이아웃을 표준화하는 것은 1990년대 TeX Users Group(TUG)가 정의한 TDS(TeX Directory Structure)의 작업입니다.
왜 표준이 있습니까? TeX는 macOS, Unix, Windows 등에서 실행되며 CTAN(Comprehensive TeX Archive Network)는 엄청난 양의 패키지 더미를 수집합니다. 모든 사이트에서 파일을 다르게 정렬하면 패키지를 배송하는 사람과 패키지를 찾는 도구가 매번 비틀거리게 됩니다. "tex/ 아래에 존재하는 매크로"가 수정되면 OS 및 배포에서 규칙만으로 모든 파일의 위치를 추론할 수 있습니다. 이식성은 TDS가 해결하는 문제입니다.
지점에는 자체 규칙이 있습니다. tex/는 형식별로, 그 다음 패키지별로 분할되어 tex/<format>/<package>/를 제공합니다(여기서 <format>는 latex, plain, generic, …). 예를 들어 표준 article.cls는 아래 경로에 있으며 나중에 소개되는 kpsewhich 도구는 사용자 컴퓨터에서 매우 동일한 위치를 보고합니다.
$ kpsewhich article.cls
/usr/local/texlive/2026/texmf-dist/tex/latex/base/article.cls글꼴이 한 단계 더 정교해졌습니다: fonts/<type>/<supplier>/<typeface>/. <type>는 일종의 파일입니다. TeX 글꼴 메트릭의 경우 tfm, 가상 글꼴의 경우 vf, type1, opentype, truetype 등이 있습니다. <supplier>는 이를 제공한 사람(public, adobe, ams, …)이고 <typeface>는 글꼴 이름(cm = Computer Modern)입니다. 아래 표에는 가장 자주 만나는 지점과 각 지점의 내용이 나열되어 있습니다.
| 디렉토리 | 그것이 담고 있는 것 |
|---|---|
tex/ | 매크로, 클래스, 스타일(.tex .sty .cls); 예를 들어 tex/latex/... |
fonts/ | 유형별 모든 글꼴 파일: tfm, vf, type1, opentype, enc, map, … |
bibtex/ | 참고문헌 데이터베이스 bib/ 및 스타일 bst/ |
doc/ | 패키지 매뉴얼 및 문서(texdoc가 열리는 내용) |
scripts/ | OS-독립 실행 가능 스크립트(mktexlsr의 본문 등) |
web2c/ | 엔진 구성; texmf.cnf 및 형식 정의의 홈 |
여러 개의 트리, 어느 쪽이 이기나요?
texmf 트리는 한 가지가 아닙니다. TeX Live는 각각 TEXMF… 변수로 명명된 고유한 역할을 가진 여러 트리를 묶습니다. 왜 그들을 분리합니까? 세 가지를 구분하려면 배포판(읽기 전용, 업데이트할 때마다 대체됨), 추가한 항목(사라지지 않아야 함) 및 자동 생성된 작업 데이터입니다. 이를 혼합하고 배포판을 업데이트하면 자신의 스타일이 즉시 사라질 수 있습니다.
| 변수 | 역할 및 기본 위치(예: TeX Live 2026) |
|---|---|
TEXMFDIST | 배포 자체; 패키지의 대부분. 만지지 마세요. .../texlive/2026/texmf-dist |
TEXMFLOCAL | 모든 사용자가 공유하는 사이트 전체 추가 사항입니다. .../texlive/texmf-local |
TEXMFHOME | 개인 트리; 자신만의 스타일과 수업이 여기에 있습니다. 기본값: Linux의 ~/texmf, macOS의 ~/Library/texmf, Windows의 %USERPROFILE%\texmf |
TEXMFVAR | 자동 생성된 캐시(형식, 글꼴 등) 절대 직접 편집하지 마세요 |
TEXMFCONFIG | 사용자별 구성 저장소(updmap 등으로 작성) |
TEXMFSYSVAR / SYSCONFIG | 위의 VAR / CONFIG에 대응하는 시스템 전체 |
TEXMFROOT | 전체 설치의 루트입니다. .../texlive/2026 |
같은 이름의 파일이 여러 트리에 존재한다면 어느 것이 승리할까요? 이는 단순히 검색 우선순위를 순서대로 나열하는 TEXMF 변수에 의해 결정됩니다. 쿼리하면 대략 다음 시퀀스가 반환됩니다(가장 왼쪽이 우선).
$ kpsewhich -var-value=TEXMF
{$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST}다음과 같이 읽어보세요: 먼저 자신의 구성(TEXMFCONFIG) 및 작업 데이터(TEXMFVAR), 개인 트리 TEXMFHOME, 사이트 전체 TEXMFLOCAL, 마지막으로 시스템 구성, 작업 데이터 및 배포 TEXMFDIST입니다. 이 순서로 인해 자신의 mystyle.sty를 TEXMFHOME에 놓으면 배포본의 복사본이 숨겨집니다 — 흠집이 나지 않고 개인 → 사이트 → 배포의 자연스러운 순위가 됩니다. (선행 !!는 다음 섹션에서 설명됩니다.)
kpathsea: 파일을 찾는 방법
레이아웃이 고정되어 있어도 실제로 파일을 찾는 사람은 누구입니까? 그것은 kpathsea (kpse, *kpath search*) — TeX 및 그 동반 도구가 공유하는 경로 검색 라이브러리입니다. tex, pdflatex, dvipdfmx 및 나머지는 자체적으로 검색하지 않습니다. 그들은 모두 kpathsea에게 “amsmath.sty는 어디에 있나요?”라고 묻습니다.
kpathsea는 검색 경로를 규칙이 있는 문자열로 표현합니다. 세 가지 기호는 알아 둘 가치가 있습니다. $VAR는 변수를 확장합니다. 후행 //는 "이 아래의 모든 항목을 재귀적으로 검색"을 의미합니다. 선행 !!는 "디스크를 직접 스캔하지 마십시오. 아래 설명된 파일 이름 데이터베이스만 참조하십시오."를 의미합니다. LaTeX 소스를 찾는 경로인 TEXINPUTS는 실제로 다음과 같습니다.
$ kpsewhich -var-value=TEXINPUTS
.:$TEXMF/tex/{latex,generic,}//다음과 같이 읽으십시오: 먼저 .(현재 디렉토리)를 살펴보십시오. 실패하면 각 texmf 트리의 tex/ 분기를 latex → generic → 다른 모든 순서로 반복합니다. 이는 여러분이 기대하는 직관적인 동작을 제공합니다. 원고 옆에 있는 파일이 우선하고, 그렇지 않으면 배포판으로 돌아갑니다.
그러나 매번 수만 개의 디렉터리를 실제로 검색하는 것은 너무 느릴 것입니다. 따라서 kpathsea는 각 트리의 루트에 있는 ls-R라는 파일 이름 데이터베이스를 사용합니다. 즉, 어떤 파일이 어떤 디렉터리에 있는지 텍스트 목록으로 보여줍니다. 디스크를 탐색하는 대신 해당 인덱스를 참조하면 조회가 즉시 이루어집니다. 앞서 본 !!는 "인덱스만 신뢰(실제 디스크는 건드리지 않음)"라는 뜻으로, 거의 변하지 않는 분포와 같은 트리에 붙어있습니다.
반대 측면: 트리에 파일을 추가한 후 TeX는 ls-R가 다시 빌드될 때까지 파일을 찾지 못할 수 있습니다 — 특히 !! 시스템 트리에서. 인덱스를 재생성하는 명령은 mktexlsr(texhash라고도 함)입니다. TEXMFHOME와 같은 개인 트리는 더 관대하게 처리되며 종종 다시 빌드할 필요가 없지만 TEXMFLOCAL에 무언가를 넣은 후 안전한 조치는 아래 한 줄을 실행하는 것입니다.
# Rebuild the ls-R filename databases after adding files to a tree
$ mktexlsr # texhash is an exact alias문제가 발생하면 첫 번째 조치는 kpsewhich를 사용하여 파일과 변수를 직접 쿼리하는 것입니다. "실제로 읽고 있는 파일은 무엇입니까?" 그리고 "이 변수는 무엇으로 확장되나요?" 즉시 답변을 제공하므로 잘못된 구성을 찾아낼 수 있습니다. kpsewhich 옵션의 전체 세트와 tlmgr와 같은 관리 명령은 별도의 페이지에서 자세히 다룹니다.
PATH: 명령으로 가는 길
kpathsea는 TeX가 읽는 파일을 찾지만, 그 전에 쉘은 실행 파일 자체, pdflatex를 찾아야 합니다. 이것이 OS의 작업입니다. PATH 환경 변수에 나열된 디렉토리를 순서대로 검색합니다. TeX Live는 단일 OS별, 아키텍처별 bin 디렉토리에 실행 파일을 보관하며 이를 PATH에 넣는 것이 설치의 마무리 작업입니다.
디렉토리 이름에는 연도와 플랫폼이 포함되어 있습니다. Linux /usr/local/texlive/2026/bin/x86_64-linux, macOS /usr/local/texlive/2026/bin/universal-darwin, Windows ...\bin\windows. macOS에서 MacTeX는 /Library/TeX/texbin에서 연도 독립적이고 안정적인 심볼릭 링크를 제공하므로 연간 업그레이드 시 PATH를 편집할 필요가 없습니다. 현재 다음과 같이 무엇을 가리키는지 확인할 수 있습니다.
$ which pdflatex
/Library/TeX/texbin/pdflatex
$ readlink /Library/TeX/texbin
Distributions/Programs/texbin"pdflatex: command not found"가 표시되면 10번 중 9번은 bin 디렉토리가 PATH에서 누락된 것입니다. 설정을 위한 OS-by-OS 절차와 설치 후 확인은 설치 페이지에 남아 있습니다.
texmf.cnf: 설정의 출처
지금까지의 모든 변수(TEXMF, TEXINPUTS, 각 트리의 위치)는 실제로 어디에서 왔습니까? 대답은 texmf.cnf라는 구성 파일입니다. 어떤 작업을 수행하기 전에 kpathsea는 이를 읽어 작동 매개변수: 검색 경로, 각 트리가 있는 위치, 메모리 제한 등을 선택합니다. 마스터 복사본은 배포판의 web2c/ 아래에 있습니다.
$ kpsewhich texmf.cnf
/usr/local/texlive/2026/texmf.cnf흥미로운 부분은 하나 이상 texmf.cnf가 있을 수 있다는 것입니다. kpathsea는 전용 검색 경로(TEXMFCNF 변수)를 따라 여러 위치에서 texmf.cnf를 순서대로 읽고 주어진 변수에 대해 찾은 첫 번째 정의를 취합니다(이후 파일은 이전 파일을 재정의하지 않습니다). 따라서 배포의 큰 기본 파일은 그대로 두고 우선 순위가 더 높은 위치에 작은 재정의 파일을 삭제합니다. 이는 변경 사항만 안전하게 추가하는 계층화 구성표입니다. -all를 추가하면 실제로 쌓인 파일이 표시됩니다.
$ kpsewhich -all texmf.cnf
/usr/local/texlive/2026/texmf.cnf
/usr/local/texlive/2026/texmf-dist/web2c/texmf.cnf여기서 위쪽 texmf.cnf(TeX Live의 씬 재정의)는 아래쪽 texmf-dist/web2c/texmf.cnf(기본값 수백 줄) 이전에 읽혀집니다. 값을 영구적으로 변경하려는 경우 배포 파일을 편집하는 것이 아니라 TEXMFLOCAL/web2c/texmf.cnf와 같은 우선 순위가 높은 위치에 필요한 줄만 쓰는 것이 관례입니다. 그렇게 하면 배포 업그레이드 후에도 설정이 유지됩니다.
요약하자면, TeX가 파일을 찾는 방법은 다음과 같습니다. texmf.cnf는 먼저 트리의 위치와 검색 경로의 모양을 수정합니다. 해당 순서에 따라 kpathsea는 (보통 ls-R 인덱스를 통해) 대상을 찾습니다. PATH는 실행 파일 자체에 대한 진입점을 제공합니다. 이 세 개의 레이어는 함께 결합되어 \usepackage{...}의 단일 라인이 조용히 해결됩니다.
자신의 파일을 넣을 위치
가장 중요한 실제 규칙은 배포 트리를 편집하지 마십시오입니다. /usr/local/texlive/2026/texmf-dist 안에 논문 전용 thesisstyle.sty 또는 연구실 전체 labreport.cls를 배치하면 업데이트나 재설치로 지워질 수 있습니다. 개인 파일은 TEXMFHOME에, 연구실 전체 파일은 TEXMFLOCAL에 넣고 TDS 레이아웃을 유지합니다.
대조적으로 하나의 제출 번들에만 속하는 파일(컨퍼런스 myconf.cls 또는 저널 journal.sty)은 원고 옆에 있을 수 있습니다. TEXINPUTS는 현재 디렉토리를 먼저 확인하므로 TeX는 해당 복사본을 선호합니다. 이것이 원고 옆에 article.cls 또는 오래된 amsmath.sty와 같은 일반 이름을 배치하는 것이 위험한 이유이기도 합니다. 이는 배포를 가리고 다른 시스템에만 나타나는 오류를 생성합니다.
# 個人用スタイルを TEXMFHOME に置く例
mkdir -p ~/texmf/tex/latex/thesisstyle
cp thesisstyle.sty ~/texmf/tex/latex/thesisstyle/
# TeX がどれを拾うか確認する
kpsewhich thesisstyle.stykpsewhich가 예상한 경로를 보고하면 원고에서는 간단히 \usepackage{thesisstyle}라고 말할 수 있습니다. 아무것도 보고하지 않으면 파일이 tex/latex/<package>/ 아래에 있는지, 파일 이름 대소문자가 일치하는지, 시스템 트리에 대해 mktexlsr가 실행되었는지 순서대로 확인하세요. 이는 실패를 "검색 맵의 어디에 넣었습니까?"로 구성합니다. "TeX가 깨졌습니다."가 아니라.