빌드와 컴파일

빌드 시스템 개요

TeX64는 latexmk 엔진을 사용해 LaTeX 문서를 컴파일합니다. latexmk는 참고문헌, 색인, 상호 참조가 포함된 복잡한 문서를 빌드하는 데 필요한 중간 단계를 자동으로 관리합니다.

모든 빌드는 사용자의 컴퓨터에서 로컬로 실행되어 인터넷 연결이 필요하지 않습니다. TeX64는 완전히 오프라인으로 동작하며 보안과 개인정보를 보호합니다. 컴파일 과정은 빠르고 투명합니다.

빌드 방법

빌드를 시작하는 방법은 간단합니다. 다음 중 하나를 사용할 수 있습니다:

• 툴바 버튼 — 툴바의 빌드 버튼(재생 아이콘)을 클릭합니다. Cmd+B는 편집기에서 \textbf{}를 입력하는 용도로 예약되어 있습니다.
• 클린 빌드 — Settings > Build Profile을 열고 Clean을 클릭합니다. 생성된 출력 파일까지 삭제하려면 Clean -C를 사용하세요.

빌드가 성공적으로 완료되면 PDF 미리보기가 자동으로 업데이트됩니다.

빌드 과정

빌드 중에 latexmk가 자동으로 관리하는 항목:

• 다중 컴파일 패스 — LaTeX는 일반적으로 상호 참조를 해결하기 위해 2~3회 실행됩니다
• BibTeX/Biber — 참고문헌 항목을 자동으로 처리합니다
• 색인 생성 — makeindex 또는 xindy를 실행하여 색인 항목을 생성합니다
• 상호 참조 — \ref, \cite, \pageref 등의 명령이 올바르게 해결되도록 합니다
• 변경 감지 — 파일이 변경되지 않은 경우 빌드를 건너뛰어 시간을 절약합니다

빌드 출력은 컴파일 중 로그 패널에 실시간으로 표시됩니다. 진행 상황을 실시간으로 확인하고 latexmk가 무엇을 하고 있는지 정확히 볼 수 있습니다.

루트 파일 선택

여러 .tex 파일이 있는 프로젝트에서 TeX64는 어떤 파일이 루트(메인) 문서인지 식별합니다. 루트 파일에만 존재하는 \documentclass 명령을 스캔하여 이를 수행합니다.

대부분의 경우 자동 감지가 완벽하게 작동합니다. 그러나 여러 \documentclass 선언이 있는 복잡한 프로젝트 구조라면 프로젝트 설정에서 루트 파일을 수동으로 지정할 수 있습니다.

TeX64는 항상 루트 파일에서 컴파일을 시작합니다. 다른 모든 파일은 루트 파일의 \input 또는 \include 명령으로 포함되어야 합니다.

빌드 프로필

TeX64에서는 여러 빌드 프로필을 구성할 수 있으며, 각 프로필마다 별도의 LaTeX 엔진과 사용자 지정 설정을 갖습니다. 다양한 엔진으로 문서를 테스트할 때 유용합니다.

프로필은 프로젝트 설정에서 생성하고 관리할 수 있습니다. 각 프로필에는 이름, 엔진 선택, 선택적 사용자 지정 플래그가 있습니다.

프로필은 다음과 같은 상황에 유용합니다:

• 서로 다른 엔진으로 문서를 테스트(예: pdflatex vs xelatex)
• 프로덕션과 초안 모드에 대해 별도의 빌드 구성을 유지
• 발표 자료나 특수 형식을 위한 사용자 지정 엔진 옵션 사용

지원 엔진

TeX64는 다음 주요 LaTeX 엔진을 지원합니다:

pdflatex

pdflatex는 가장 확립되고 널리 사용되는 엔진입니다. 거의 모든 LaTeX 패키지와 템플릿과 호환되어 표준 문서에 이상적입니다. PDF 출력을 직접 생성하며 속도도 빠릅니다.

권장 용도: 학술 논문, 기술 보고서, 책 및 대부분의 표준 문서. 어떤 엔진을 사용해야 할지 확신이 없다면 pdflatex가 안전한 선택입니다.

xelatex

xelatex는 유니코드와 시스템 글꼴을 기본 지원하므로 한국어, 중국어, 일본어, 아랍어 등 비라틴 문자에 이상적입니다. 컴퓨터에 설치된 모든 시스템 글꼴을 사용할 수 있습니다.

권장 용도: 다국어 문서, 비라틴 문자, 시스템 글꼴이 필요한 모든 프로젝트. 한국어, 일본어, 중국어 또는 기타 복잡한 문자 체계를 다룬다면 xelatex가 적합합니다.

lualatex

lualatex는 Lua 스크립팅 기능과 고급 글꼴 처리를 통합한 현대적 엔진입니다. OpenType 글꼴을 기본 지원하며 정교한 타이포그래피 제어가 가능합니다.

권장 용도: 고급 스크립팅, 복잡한 타이포그래피, 현대적 글꼴 기술이 필요한 프로젝트. xelatex의 장점과 Lua의 확장성을 결합합니다.

사용자 지정 latexmk 플래그

고급 사용자는 빌드 동작을 세밀하게 조정하기 위해 사용자 지정 latexmk 플래그를 추가할 수 있습니다. 이러한 플래그는 프로젝트 설정에서 구성합니다.

일반적인 플래그:

• -shell-escape — \write18을 활성화하여 LaTeX 내부에서 외부 프로그램을 실행합니다(Minted 같은 패키지에 필요)
• -interaction=nonstopmode — 오류가 발생해도 컴파일을 계속합니다(여러 문제를 한 번에 확인하는 데 유용)
• -output-directory= — PDF와 중간 파일을 위한 사용자 지정 출력 디렉터리를 지정합니다
• -pdf — PDF 출력 모드를 강제합니다

컴파일 로그

컴파일 로그는 LaTeX 컴파일러와 latexmk의 전체 출력을 표시합니다. TeX64는 이 출력을 분석하여 오류와 경고를 색상으로 강조합니다.

• 오류 — 빨간색으로 강조됩니다. 성공적인 컴파일을 방해합니다.
• 경고 — 노란색 또는 주황색으로 강조됩니다. 컴파일을 방해하지는 않지만 출력 품질에 영향을 줄 수 있습니다.
• 메시지 — 회색으로 표시됩니다. 빌드 과정에 대한 정보성 메시지입니다.

로그의 오류나 경고를 클릭하면 소스 코드의 문제 라인으로 바로 이동합니다. 파일과 줄 번호가 강조되어 빠르게 디버깅할 수 있습니다.

오류 파싱

TeX64는 LaTeX 오류를 자동으로 파싱하여 올바른 파일과 줄 번호를 식별합니다.

일반적인 오류 패턴:

• Undefined control sequence — 명령이 정의되지 않았거나 오타가 있습니다
• Missing \endcsname inserted — 대개 중괄호나 괄호가 일치하지 않아 발생합니다
• File not found — \input 또는 \include로 참조된 파일이 존재하지 않습니다
• Package not found — \usepackage로 지정된 패키지가 설치되어 있지 않습니다
• Runaway argument — 대개 명령 인수의 중괄호가 닫히지 않아 발생합니다

LaTeX는 종종 연쇄적인 오류를 발생시키므로 첫 번째 오류를 찾는 것이 매우 중요합니다. 로그의 첫 번째 오류를 수정하면 이후의 많은 오류가 함께 해결되는 경우가 많습니다.

AI 보조 디버깅

TeX64의 AI 도우미는 컴파일 로그를 분석하여 오류에 대한 수정 방안을 제안할 수 있습니다. 이해하기 어려운 LaTeX 오류 메시지에 특히 유용합니다.

빌드 실패 후 AI 디버깅을 사용하려면:

1. 컴파일 로그 패널의 「Ask AI」 버튼을 클릭합니다
2. TeX64가 전체 오류 컨텍스트를 AI에 전송합니다
3. AI가 가능한 원인과 해결 방법을 제안합니다

AI의 제안은 항상 정확한 것은 아니지만 유용한 시작점이 됩니다. 깊은 TeX 지식이 없을 때 특히 유용합니다.

환경 진단

TeX64는 시작 시 빌드에 필요한 모든 도구가 시스템에 설치되어 있는지 확인합니다. 다음 항목을 검증합니다:

• latexmk — LaTeX 빌드 자동화 엔진(필수)
• TeX distribution — TeX Live, MacTeX, MiKTeX 또는 기타 TeX 배포판(필수)
• latexindent — 코드 포맷팅 도구(선택 사항이지만 권장)
• synctex — 소스와 PDF 동기화(선택 사항이지만 권장)

필수 도구가 누락된 경우, TeX64가 경고를 표시하고 설치 방법을 안내합니다.

클린 빌드

클린 빌드는 모든 중간 파일을 제거한 다음 전체 문서를 처음부터 다시 빌드합니다.

클린 빌드는 다음을 제거합니다:

• .aux — 보조 파일(상호 참조 등)
• .log — 빌드 로그
• .toc — 목차 파일
• .lof, .lot — 그림/표 목록
• .bbl, .blg — 참고문헌 파일
• .fdb_latexmk — latexmk 파일 의존성 데이터베이스

다음과 같은 경우 클린 빌드를 사용하세요:

• 빌드가 이상한 상태에 멈춰 있고 일반 빌드로 해결되지 않을 때
• 주요 구조 변경 후(예: 챕터를 추가하거나 제거한 경우)
• 상호 참조나 번호 매김에 캐싱 문제가 의심될 때
• 프로젝트 설정이나 엔진 옵션을 변경한 후

증분 컴파일

기본적으로 TeX64는 증분 컴파일을 사용합니다. latexmk는 어떤 파일이 변경되었는지 추적하고 필요한 컴파일 단계만 다시 실행합니다.

이를 통해 작은 변경 후 빌드 속도가 크게 향상됩니다. latexmk는 내부적으로 의존성을 추적하며, 정말 필요한 경우에만 전체 재빌드를 수행합니다.

증분 컴파일이 일부 변경 사항을 놓치는 것 같다면 클린 빌드로 전체 재빌드를 강제하세요.

빌드 문제 해결

빌드가 실패하면 다음의 일반적인 문제를 확인하세요:

성능 팁

빌드 시간을 줄이기 위한 전략:

• 드래프트 모드 — \documentclass에 draft 옵션을 추가하여 이미지 처리를 건너뛰고 레이아웃만 컴파일합니다
• 선택적 컴파일 — \includeonly를 사용하여 특정 챕터만 컴파일합니다
• 이미지 최적화 — 큰 비트맵 이미지를 PDF로 변환하거나 크기를 줄입니다
• 글꼴 선택 — Computer Modern 글꼴(기본값)은 복잡한 시스템 글꼴보다 빠르게 컴파일됩니다
• TikZ/PGFPlots 최적화 — 복잡한 다이어그램을 사전에 PDF로 컴파일하고 이미지로 포함합니다

이러한 기법을 결합하면 대규모 프로젝트의 빌드 시간을 크게 줄일 수 있습니다.