\engine{latexmk}

latexmk دليل

يؤتمت latexmk خط معالجة (pipeline) تجميع LaTeX متعدد التمريرات. يحدد بدقة عدد التمريرات المطلوبة، ويشغّل bibtex أو biber عند الحاجة، ويراقب ملفات المصدر بحثًا عن التغييرات. كفّ عن عدّ مرات تشغيل pdflatex يدويًا.

latexmk— أتمتة ذكية متعددة التمريرات

\section{ما هو latexmk}

ما هو latexmk؟

latexmk سكربت Perl كتبه John Collins ويعمل كنظام بناء ذكي لمستندات LaTeX. عند تشغيل latexmk -pdf، يفحص ملفات .aux و.toc و.bbl وغيرها من الملفات المساعدة بعد كل تمريرة ليحدد ما إذا كانت هناك حاجة إلى تمريرة أخرى. ويستمر في التشغيل حتى يستقر الناتج، وعادةً من تمريرتين إلى أربع تمريرات لمستند فيه قائمة مراجع وإحالات مرجعية.

تمريرات متعددة تلقائية

يكتشف الحاجة إلى تمريرة pdflatex أخرى بمقارنة المجاميع الاختبارية للملفات المساعدة.

تتبّع التبعيات

يراقب ملفات .tex و.bib والصور والملفات المضمّنة. ولا يعيد التجميع إلا عند حدوث تغيير فعلي.

قابل للضبط عبر .latexmkrc

تتحكم ملفات الإعدادات الخاصة بالمشروع والعامة في اختيار المحرك ومجلدات المخرجات والقواعد المخصصة.

\subsection{الاستخدام الأساسي}

أوامر latexmk الأساسية

يأتي latexmk مع كل تثبيت لـ TeX Live. هذه هي الأوامر التي ستستخدمها أكثر من غيرها، من التجميع البسيط إلى PDF حتى مراقبة الملفات.

أوامر latexmk

# Compile with pdfLaTeX (default) — runs as many passes as needed
latexmk -pdf document.tex

# Compile with XeLaTeX
latexmk -xelatex document.tex

# Compile with LuaLaTeX
latexmk -lualatex document.tex

# Compile and open the resulting PDF
latexmk -pdf -pv document.tex

# Watch for file changes and recompile automatically
latexmk -pdf -pvc document.tex

# Clean up auxiliary files (.aux, .log, .toc, .out …)
latexmk -c document.tex

# Clean up ALL generated files including the PDF
latexmk -C document.tex

-pdfالتجميع إلى PDF باستخدام pdfLaTeX (المحرك الافتراضي)

-xelatexالتجميع إلى PDF باستخدام XeLaTeX

-lualatexالتجميع إلى PDF باستخدام LuaLaTeX

-pvcمعاينة مستمرة: يراقب الملفات ويعيد التجميع عند التغيير

-cنظّف الملفات المساعدة مع الإبقاء على ملف PDF

-Cنظّف جميع الملفات المولّدة بما فيها ملف PDF

\subsection{.latexmkrc}

ضبط latexmk باستخدام .latexmkrc

يحدد ملف .latexmkrc في جذر مشروعك لـ latexmk المحرك الذي يستخدمه، ومكان كتابة ملفات المخرجات، وكيفية التعامل مع قائمة المراجع. وهذا يغنيك عن خيارات سطر الأوامر الطويلة.

.latexmkrc

# .latexmkrc — project-level configuration
# Place this file in the same directory as your .tex file

# Use pdfLaTeX by default
$pdf_mode = 1;

# Or use XeLaTeX
# $pdf_mode = 5;

# Or use LuaLaTeX
# $pdf_mode = 4;

# Custom PDF viewer (optional)
$pdf_previewer = 'evince %S';

# Run biber instead of bibtex for bibliography
$biber = 'biber %O %S';

# Write output files to ./build directory
$out_dir = 'build';

# Extra extensions to clean with latexmk -c
@generated_exts = (@generated_exts, 'synctex.gz', 'run.xml', 'bcf');

# Extra dependencies to watch (e.g. bibliography files)
@default_files = ('document.tex');

قيم $pdf_mode

$pdf_mode = 1 — pdfLaTeX $pdf_mode = 4 — LuaLaTeX $pdf_mode = 5 — XeLaTeX

\section{التكامل مع CI/CD}

latexmk في GitHub Actions

النمط الأكثر شيوعًا لـ CI/CD مع LaTeX هو التجميع عند الدفع إلى main ورفع ملف PDF كمُخرَج (artifact). يستخدم سير العمل أدناه الإجراء teatimeguest/setup-texlive-action لتثبيت TeX Live، الذي يتضمن latexmk، على المشغّل (runner).

.github/workflows/latex.yml

دليل CI/CD الكامل

# .github/workflows/latex.yml
name: Compile LaTeX

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install TeX Live
        uses: teatimeguest/setup-texlive-action@v3
        with:
          packages: scheme-small latexmk

      - name: Compile with latexmk
        run: |
          latexmk -pdf -interaction=nonstopmode -halt-on-error document.tex

      - name: Upload PDF artifact
        uses: actions/upload-artifact@v4
        with:
          name: document-pdf
          path: document.pdf

يشغّل latexmk ما يلزم من تمريرات pdflatex، فلا حاجة إلى عدّ التمريرات في سير عملك

استخدم -halt-on-error مع -interaction=nonstopmode لإفشال مهمة CI عند أي خطأ في LaTeX

ارفع ملف PDF كمُخرَج (artifact) ليكون قابلًا للتنزيل من ملخص تشغيل Actions

لتسريع تشغيلات CI، استبدل تثبيت TeX Live المحلي بـ FormaTeX API: طلب HTTP واحد دون إعداد TeX Live

\section{Comparison}

latexmk مقابل pdflatex اليدوي

بالنسبة لمستند بسيط من صفحة واحدة، فإن pdflatex اليدوي مكافئ. أما لأي مستند فيه إحالات مرجعية أو قائمة مراجع أو فهرس محتويات، فـ latexmk أفضل بوضوح.

المهمة

pdflatex اليدوي

latexmk

تجميع بتمريرة واحدةpdflatex document.texlatexmk -pdf document.tex

حل الإحالات المرجعيةشغّل pdflatex مرتين يدويًاتلقائي، إذ يكتشف latexmk تغيّرات .aux

قائمة المراجع (bibtex/biber)pdflatex → bibtex → pdflatex → pdflatexتلقائي، إذ يشغّل latexmk كلًا من bibtex/biber عند الحاجة

فهرس المحتوياتشغّل pdflatex مرتين (أو أكثر)تلقائي، إذ يعيد latexmk التشغيل حتى يستقر الناتج

تغيير المحركاستبدل الملف التنفيذي pdflatex في الأمرالخيار -xelatex أو -lualatex في latexmk

وضع المراقبة (إعادة التجميع التلقائية)غير مدمج؛ يتطلب مراقبًا خارجيًاlatexmk -pvc (يراقب جميع التبعيات)

تنظيف الملفات المساعدةrm *.aux *.log *.toc … (قائمة يدوية)latexmk -c (يعرف ما أنشأه)

مجلد المخرجاتpdflatex -output-directory=./build$out_dir = 'build' في .latexmkrc

\subsection{البديل في FormaTeX}

تجاوز تثبيت TeX المحلي بالكامل

يحل latexmk مشكلة التمريرات المتعددة على جهازك المحلي. ويحل FormaTeX مشكلة البنية التحتية: لا TeX Live ولا latexmk ولا صور Docker، بل مجرد طلب HTTP يعيد ملف PDF.

مع latexmk المحلي

ثبّت TeX Live (حوالي 5 غيغابايت)
اضبط .latexmkrc لكل مشروع
أدِر تحديثات TeX Live
أعدّ مشغّل CI باستخدام إجراء TeX Live
تتبّع الإخفاقات الخاصة بكل محرك محليًا

مع FormaTeX API

دون تثبيت، واستدعاء API يعيد ملف PDF
اختر المحرك عبر الحقل engine
إصدار TeX Live محدّث دائمًا على الخادم
يندمج CI بأمر curl واحد
المحرك نفسه والمخرجات نفسها في كل مرة

latexmk مدعوم عبر API

أتمتة تجميع LaTeX على نطاق واسع

يتولى FormaTeX التجميع متعدد التمريرات على الخادم. مرّر "engine": "latexmk" لتشغيل خط معالجة latexmk كاملًا، فتُحل قائمة المراجع والإحالات المرجعية وكل شيء في استدعاء API واحد.

افتح الـ playground احصل على مفتاح API