# Biên dịch

Biên dịch các dự án LaTeX, Typst và Markdown, chọn tùy chọn biên dịch cho từng engine, đọc nhật ký và điều khiển việc tải gói khi ngoại tuyến.

Một dự án LaTeX mới bắt đầu với engine biên dịch mặc định từ **Settings → Engines → LaTeX**. Sẵn có ngay đó là **Tectonic**, một engine dựa trên XeTeX đi kèm với Oleafly. Bạn cũng có thể dùng `latexmk` khi một dự án cần chuỗi công cụ TeX truyền thống, cho riêng một dự án hoặc làm mặc định. Dự án Typst biên dịch bằng Typst tích hợp sẵn hoặc một phiên bản khác mà dự án ghim, và dự án Markdown đi qua Pandoc và Tectonic. Trình biên dịch LaTeX và phiên bản Typst thuộc về dự án, nên thay đổi một dự án không ảnh hưởng đến các dự án khác.

## Bắt đầu một lần biên dịch

![Dùng Recompile trên thanh công cụ dự án; mũi tên bên cạnh nó mở các tùy chọn biên dịch.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1265,0,330,48)

- ⌘↵ (Ctrl+Enter), ở bất kỳ đâu.
- Nút **Compile** ở góc trên bên phải của thanh công cụ. Nút hiển thị **Recompile** khi dự án đã có kết quả.
- **Recompile** trong bảng lệnh ⌘K.
- Mở một dự án vào chế độ xem có khung PDF sẽ tự động biên dịch một lần, để bạn có ngay một bản xem trước mới.
- `oleafly build` trong terminal hoặc trong một script. Xem [Công cụ dòng lệnh](/docs/cli/).

Việc biên dịch luôn lưu tệp đang hoạt động trước, nên PDF khớp với những gì bạn thấy. Nếu bạn đang ở chế độ chỉ trình soạn thảo, biên dịch sẽ chuyển sang chế độ chia đôi để bạn theo dõi kết quả.

## Tùy chọn biên dịch

Mũi tên bên cạnh **Recompile** mở các tùy chọn biên dịch. Menu chỉ hiển thị những tùy chọn có tác dụng với engine của dự án.

| Nhóm | LaTeX với Tectonic | LaTeX với `latexmk` | Typst | Markdown |
|---|---|---|---|---|
| **Auto compile** | Có | Có | Có | Có |
| **Compile mode** (Normal hoặc Fast) | Có | Không | Không | Không |
| **Syntax checks** | Có | Có | Không | Không |
| **Compiler (this project)** | Có | Có | Không | Không |
| **Typst version**, **Fonts**, **Build**, **Variant** | Không | Không | Có | Không |
| **Compile error handling** | Có | Có | Không | Không |

**Stop compilation** và **Recompile from scratch** nằm ở cuối menu cho mọi engine. Nhóm **Variant** xuất hiện khi một dự án Typst có các biến thể bản dựng.

Trong **Compiler (this project)**, **Tectonic** được tích hợp sẵn. **Auto** chạy TeX hệ thống của bạn qua `latexmk` và chọn trình biên dịch từ mã nguồn. **pdfLaTeX**, **XeLaTeX** và **LuaLaTeX** ghim trình biên dịch đó và cũng chạy qua `latexmk`, còn **upLaTeX** và **pLaTeX** biên dịch tài liệu tiếng Nhật. Mọi lựa chọn trừ Tectonic đều cần một bản phân phối TeX. Nếu máy tính này chưa có, Oleafly đề nghị cài TinyTeX khi bạn chọn một trong số đó. Xem [Khi chưa cài TeX](/docs/latex-engines/#when-no-tex-is-installed). Các nhóm Typst được trình bày trong [Dự án Typst](/docs/typst/).

## Auto compile

Đặt **Auto compile** thành **On** trong các tùy chọn biên dịch, hoặc chạy **Enable auto-compile** từ bảng lệnh ⌘K. Nó tắt theo mặc định, áp dụng cho mọi dự án, và bạn dùng chính các điều khiển đó để tắt nó trở lại.

Trong một dự án LaTeX hoặc Markdown, Oleafly biên dịch lại khoảng 2,5 giây sau khi bạn ngừng gõ. Chỉ những chỉnh sửa thực sự mới kích hoạt nó. Việc chuyển tab hay mở tệp thì không.

Trong một dự án Typst, Auto compile chính là bản xem trước trực tiếp. Oleafly giữ một tiến trình Typst chạy liên tục, tệp đang mở tự lưu một lúc sau khi bạn ngừng gõ, và PDF làm mới tại đúng vị trí cuộn. Xem [Bản xem trước trực tiếp với Auto compile](/docs/typst/#live-preview-with-auto-compile).

Các lần biên dịch không bao giờ chất đống. Nếu bạn chỉnh sửa trong khi một lần biên dịch tự động đang chạy, Oleafly dừng nó và bắt đầu lại với văn bản mới nhất của bạn, để PDF bắt kịp sớm hơn. Nó cho phép một lần biên dịch hoàn tất khi bạn hoặc một agent đã khởi động nó, khi nó đang tải gói, khi nó gần xong, hoặc khi chính nó là một lần chạy lại. Trong những trường hợp đó, đúng một lần biên dịch tiếp theo được xếp hàng, nên PDF cuối cùng vẫn phản ánh các chỉnh sửa mới nhất của bạn.

## Theo dõi tiến độ

Một thanh tiến độ mỏng chạy ngang đầu bản xem trước trong lúc bản dựng, và trước khi PDF đầu tiên tồn tại, khung hiển thị phần trăm ước tính. Khi một bản dựng hoàn tất, thanh công cụ hiển thị một **chip trạng thái** kèm thời gian biên dịch và biểu tượng mức độ:

- Dấu kiểm xanh: biên dịch thành công.
- Tam giác hổ phách: biên dịch có cảnh báo. Bạn vẫn nhận được PDF.
- Dấu X đỏ: biên dịch có lỗi.

Bản xem trước tự động chuyển sang PDF khi thành công. Chỉ một thất bại thực sự (không tạo được PDF) mới chuyển bạn sang chế độ xem Logs.

![Một lần biên dịch lỗi được đánh dấu trong trình soạn thảo và nhật ký, rồi được sửa và biên dịch lại.](https://cdn.oleafly.com/images/gifs/desktop/compile-errors.gif?v=2)

## Đọc nhật ký

![Logs và thời lượng bản dựng gần nhất nằm ở bên trái thanh công cụ bản xem trước.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1146,44,239,42)

Nút **Logs** ở bên trái thanh công cụ bản xem trước chuyển đổi giữa PDF và nhật ký biên dịch, với huy hiệu đếm lỗi (đỏ) hoặc cảnh báo (hổ phách):

- Một **danh sách chẩn đoán** đã phân tích ở phía trên: từng lỗi hoặc cảnh báo kèm loại của nó và, khi biết, tham chiếu dòng `l.42`. Những ký tự mà phông chữ không hiển thị được sẽ được gom dưới **Missing characters**.
- Toàn bộ nhật ký trình biên dịch thô ở phía dưới, có tô màu: lỗi đỏ in đậm, tham chiếu dòng được làm nổi, các tệp lồng nhau được thụt lề.
- Nút **Copy log** lấy toàn bộ nội dung cho một báo cáo lỗi hoặc một bài đăng diễn đàn. ⌘A rồi ⌘C trong nhật ký cũng sao chép được tất cả.
- **Clear**, bên cạnh **Copy log**, ẩn nhật ký và các lỗi của nó cho đến lần biên dịch tiếp theo. Các tệp bản dựng của bạn vẫn còn, và lần biên dịch tiếp theo ghi một nhật ký mới.

Nhật ký dài mở ngay lập tức, kể cả nhật ký có 100.000 dòng, và cuộn mà không có vùng trống.

Lỗi biên dịch cũng trở thành các đường gợn trong trình soạn thảo qua [chuỗi trình linter](/docs/editor/#the-built-in-latex-linter), và [trợ lý AI](/docs/ai-chat/) có thể đọc chính nhật ký này bằng công cụ `get_log` của nó khi bạn yêu cầu nó sửa các lỗi.

Lỗi Typst được đánh dấu trong trình soạn thảo tại đúng phạm vi Typst báo cáo, kèm dòng mã nguồn và chính các gợi ý của Typst. Các lỗi phổ biến còn kèm một giải thích đơn giản về điều gì đã sai.

## Gói và biên dịch ngoại tuyến

Tectonic tải xuống một gói LaTeX lần đầu tiên một tài liệu cần nó, rồi lưu vào bộ nhớ đệm cục bộ. Lần biên dịch đầu tiên trên một máy tính cũng tải về một loạt gói thường dùng trong một lượt. Lần biên dịch đầu tiên đó có thể chậm hơn và cần kết nối mạng. Các lần biên dịch sau dùng bộ nhớ đệm. Nếu mirror gói của Oleafly gặp sự cố, bản dựng chuyển sang nguồn thượng nguồn và nhật ký ghi rõ điều đó.

**Offline mode** trong Settings, General, hoặc bảng lệnh biến điều này thành một đảm bảo cho Tectonic. Trình biên dịch chạy với `--only-cached` và không bao giờ tải một gói. Một tài liệu cần gói chưa có trong bộ nhớ đệm sẽ thất bại với một thông báo nêu tên tệp khi có thể, và **Turn off and compile** tắt Offline mode rồi biên dịch lại.

Chế độ Offline cũng bao gồm Typst. Typst không thể tải một gói khi nó đang bật, nên mọi gói `@preview` phải đã có trong bộ nhớ đệm hoặc được vendored vào thư mục `typst-packages` của dự án. Xem [Gói từ Typst Universe](/docs/typst/#packages-from-typst-universe). Dự án Markdown bỏ qua Offline mode, và nhật ký nói rõ điều đó.

`latexmk` dùng bản phân phối TeX đã cài sẵn trên máy của bạn. Oleafly kiểm tra các bản phân phối hệ thống trước, bao gồm MacTeX, TeX Live, MiKTeX và TinyTeX, và **Settings → Engines → LaTeX** đánh dấu bản dùng để biên dịch là **In use**. Nếu không có bản nào khả dụng, ứng dụng có thể cài đặt và quản lý bản TinyTeX riêng của nó. MiKTeX cũng cần Perl để chạy `latexmk`; xem [MiKTeX và Perl](/docs/latex-engines/#miktex-and-perl). Vì một tiến trình TeX hệ thống có thể đọc các tệp mà tài khoản người dùng của bạn truy cập được, hãy chỉ dùng `latexmk` với những dự án bạn tin tưởng.

Khi một bản dựng `latexmk` không tìm thấy một tệp `.sty`, `.cls`, kiểu tài liệu tham khảo, tệp phông chữ, tệp ngôn ngữ babel, thư viện TikZ, hoặc tệp TeX khác, Oleafly có thể đề xuất **Find and install** trong thông báo lỗi. Tên tệp và tên gói thường khác nhau: `tikz.sty`, chẳng hạn, thuộc về gói `pgf` của TeX Live. Oleafly xác định chủ sở hữu đó, cài đặt nó bằng `tlmgr`, làm mới danh sách gói, rồi biên dịch lại. Trên Debian, Ubuntu và Fedora, TeX Live thuộc về trình quản lý gói của hệ thống, nên Oleafly đưa cho bạn lệnh `apt` hoặc `dnf` thay vì tự cài. Dùng danh sách **Packages** trong **Settings → Engines → LaTeX** khi bạn muốn tìm trước hoặc quản lý gói bằng tay.

## Giới hạn và van an toàn

- Mỗi lần chỉ một lần biên dịch chạy cho mỗi dự án, trong một hàng đợi chỉ giữ yêu cầu mới nhất: yêu cầu mới thay thế yêu cầu cũ, nên chuyển dự án giữa chừng bản dựng không bao giờ vẽ nhầm PDF, và một cơn bão biên dịch không bao giờ hình thành khi bạn đang gõ.
- Một bản dựng bị thay thế hoặc hết thời gian sẽ thực sự bị hủy: Oleafly chấm dứt toàn bộ cây tiến trình của trình biên dịch, trên mọi nền tảng, thay vì để nó chạy ngầm.
- Một lần biên dịch chạy quá 5 phút sẽ bị dừng thay vì để nó xoay mãi mãi. Khi Tectonic vẫn đang tải gói, mỗi lượt tải đẩy giới hạn lùi lại, tối đa 30 phút. Markdown sang PDF được 15 phút, còn Quarto và Calepin được một giờ.
- Kết quả mang một định danh gắn với yêu cầu, nên một PDF cũ từ một lần hoàn tất sai thứ tự sẽ bị từ chối thay vì được hiển thị.

## Lỗi thường gặp, cách sửa nhanh

- **“Missing package” trong Offline mode**: chọn **Turn off and compile** trong thông báo, hoặc tắt Offline mode cho một lần biên dịch để tải và lưu gói vào bộ nhớ đệm, rồi bật lại.
- **“This compiler needs a working TeX distribution”**: pdfLaTeX và các trình biên dịch `latexmk` khác cần TeX trên máy tính này, nên chọn một trong số đó khi chưa có TeX sẽ mở hộp thoại này. Chọn **Download and use TinyTeX**, hoặc **Switch back to Tectonic** để quay lại engine tích hợp sẵn. Nếu một lần biên dịch đã thất bại vì lý do này, bản xem trước đề xuất **Download and use TinyTeX** và **Use Tectonic**. Xem [Khi chưa cài TeX](/docs/latex-engines/#when-no-tex-is-installed).
- **“latexmk needs Perl”** trên MiKTeX: cài Strawberry Perl, hoặc cài TinyTeX, bản này tự mang theo Perl. Xem [MiKTeX và Perl](/docs/latex-engines/#miktex-and-perl).
- **Thiếu một tệp trong bản dựng `latexmk`**: dùng **Find and install**. Nếu việc tra cứu thất bại, hãy tìm tên tệp hoặc tên gói trong danh sách **Packages** ở **Settings → Engines → LaTeX**. Trên Debian, Ubuntu hoặc Fedora, cài nó bằng `apt` hoặc `dnf`. Gói MiKTeX được quản lý trong MiKTeX Console.
- **upLaTeX hoặc pLaTeX chưa được cài**: chọn **Install Japanese support (about 450 MB)** khi nó được đề xuất, hoặc chạy lệnh mà thông báo nêu. Xem [Tài liệu tiếng Nhật](/docs/latex-engines/#japanese-documents-uplatex-and-platex).
- **PDF thiếu chữ**, thường là tiếng Hàn, tiếng Trung hoặc tiếng Nhật: phông chữ không có glyph cho các ký tự đó, và TeX bỏ chúng đi mà không báo lỗi. Oleafly cảnh báo bạn và nhật ký đưa ra một đoạn thiết lập để dán vào. Xem [Ký tự bị thiếu trong PDF](/docs/latex-engines/#characters-missing-from-the-pdf), hoặc [Ký tự hiện thành ô vuông](/docs/typst/#characters-that-show-as-boxes) với Typst.
- **Mục lục tra cứu, bảng thuật ngữ hoặc bảng ký hiệu bị thiếu trong PDF**: Tectonic không chạy được `makeindex`. Chuyển dự án sang `latexmk`, hoặc tạo bảng thuật ngữ bằng `\makenoidxglossaries`, lệnh này không cần công cụ ngoài. Trên `latexmk`, các danh sách tạo bằng `xindy` hoặc `\newglossary` không được dựng.
- **Lần biên dịch hết thời gian**: biên dịch lại. Nếu các gói vẫn đang tải, lượt tải tiếp tục từ chỗ nó dừng. Với bản nháp dài trên Tectonic, đặt **Compile mode** thành **Fast**.
- **Một hình EPS, driver `pdftex` bị ép, hoặc tệp bundle bị thiếu trong Tectonic**: hộp thoại engine mở ra. Nếu nó không mở, hoặc bạn đã đóng nó, hãy chọn **Choose engine**. [Khi Tectonic chưa đủ](/docs/latex-engines/#when-tectonic-isnt-enough) cho biết nút này nằm ở đâu trong từng chế độ xem. Chọn tùy chọn được đánh dấu **Recommended**: LaTeX hệ thống của bạn khi Oleafly tìm thấy một bản TeX chạy được, hoặc **Download and use TinyTeX** khi không có. Với gói bị thiếu, Oleafly có thể tiếp tục đến trình cài đặt của nó sau khi chuyển.
- **`minted`, PythonTeX, hoặc `\write18` bị chặn**: nếu bạn tin tưởng mọi tệp trong dự án, chọn **Allow external commands** trong dải băng phía trên trình soạn thảo. Xem [Cho phép các lệnh ngoài](/docs/latex-engines/#allow-external-commands).
- **Một lượt tải gói trong Tectonic thất bại**: kiểm tra kết nối và chọn **Compile again** trong thông báo. Oleafly đã thử nguồn thượng nguồn sau mirror của nó, lượt tải tiếp tục từ chỗ nó dừng, và nếu máy tính đang ngoại tuyến, lần biên dịch tự chạy lại khi có mạng trở lại.
- **“Typst 0.13.1 is not installed”**: dự án ghim một phiên bản Typst mà máy tính này không có. Chọn **Download Typst 0.13.1** trong bản xem trước, hoặc **Use Typst** rồi chọn phiên bản mặc định của bạn để bỏ ghim. Xem [Khi thiếu một phiên bản đã ghim](/docs/typst/#when-a-pinned-version-is-missing).
- **Cảnh báo trích dẫn hoặc tham chiếu chưa định nghĩa**: [Preflight](/docs/preflight/#six-independent-checks) chỉ rõ từng cái, kèm tệp và dòng.
- **Một lỗi bạn không đọc hiểu được**: hãy hỏi AI. “Fix the LaTeX errors” kích hoạt một vòng lặp biên dịch, đọc nhật ký, chỉnh sửa có mục tiêu và biên dịch lại, dùng [chính sách phê duyệt](/docs/ai-chat/) bạn đã chọn.

## Các engine tài liệu khác

Việc chọn trình biên dịch LaTeX tách riêng khỏi engine tài liệu của dự án:

- **Dự án Typst** biên dịch bằng Typst 0.15.1 tích hợp sẵn hoặc phiên bản mà dự án ghim. Xem [Dự án Typst](/docs/typst/).
- **Dự án Markdown** dựng sang PDF qua một Pandoc được quản lý, với Tectonic làm engine PDF.
- **Dự án Quarto** render các tệp `.qmd` và `.Rmd` bằng Quarto, ra PDF hoặc trang web. Xem [Quarto](/docs/engines/#quarto).
- **Dự án Calepin** chạy mã trong một tài liệu Typst bằng Calepin, rồi dựng PDF bằng Typst tích hợp sẵn. Xem [Calepin](/docs/engines/#calepin). Cả hai engine đều không chạy mã của dự án cho đến khi bạn [cho phép](/docs/engines/#allow-code-in-a-project).
- **PDF có gắn thẻ, dễ tiếp cận** dùng LuaLaTeX qua một bản cài TeX hệ thống hoặc TinyTeX do Oleafly quản lý. Xem [Engine và gói LaTeX](/docs/latex-engines/). Typst 0.14 trở lên gắn thẻ mọi PDF mà không cần thêm bước nào.

Engine là một lựa chọn theo từng dự án, được quyết định khi dự án được tạo, và giao diện thích ứng theo nó: những hành động một engine không hỗ trợ sẽ bị ẩn thay vì để thất bại. Để chuyển một dự án LaTeX sang Typst, hãy [chuyển nó thành một dự án Typst mới](/docs/typst/#convert-a-latex-project-to-typst).

## Giữ mã nguồn phía sau một bản dựng thành công

Bật [các điểm khôi phục](/docs/checkpoints/) để lưu mã nguồn dùng cho các lần biên dịch thành công. Bạn có thể so sánh và khôi phục một bản dựng sớm hơn mà không thay đổi quy trình Git thủ công của mình.

Để giữ chính PDF đã biên dịch trong thư mục dự án, hãy bật [Đồng bộ PDF khi biên dịch](/docs/pdf-preview/#sync-pdf-on-compiles) trong menu lưu của bản xem trước.
