# التجميع

جمّع مشاريع LaTeX وTypst وMarkdown، واختر خيارات التجميع لكل محرك، واقرأ السجلات، وتحكم في جلب الحزم دون اتصال.

يبدأ مشروع LaTeX جديد على محرك التجميع الافتراضي المحدد في **Settings → Engines → LaTeX**. وهذا المحرك افتراضيًا هو **Tectonic**، محرك يعتمد على XeTeX ويأتي مع Oleafly. ويمكنك أيضًا استخدام `latexmk` عندما يحتاج مشروع إلى سلسلة أدوات TeX تقليدية، لمشروع واحد أو كخيار افتراضي. أما مشاريع Typst فتُجمَّع بنسخة Typst المدمجة أو بنسخة أخرى يحددها المشروع، وتمر مشاريع Markdown عبر Pandoc وTectonic. ومجمّع LaTeX ونسخة Typst يخصان المشروع، فتغيير مشروع واحد لا يؤثر في المشاريع الأخرى.

## بدء عملية تجميع

![استخدم Recompile في شريط أدوات المشروع؛ السهم المجاور له يفتح خيارات التجميع.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1265,0,330,48)

- ⌘↵ (Ctrl+Enter)، من أي مكان.
- زر **Compile** في أعلى يمين شريط الأدوات. ويصبح اسمه **Recompile** متى صار للمشروع نتيجة.
- **Recompile** في لوحة الأوامر ⌘K.
- فتح مشروع في طريقة عرض تُظهر لوحة PDF يجمعه مرة واحدة تلقائيًا، فتصل مباشرة إلى معاينة حديثة.
- `oleafly build` في طرفية أو في نص برمجي. انظر [أداة سطر الأوامر](/docs/cli/).

يحفظ التجميع دائمًا الملف النشط أولًا، فيطابق ملف PDF ما تراه. وإذا كنت في طريقة عرض المحرر فقط، فسيكشف التجميع العرض المقسوم لتتابع النتيجة.

## خيارات التجميع

يفتح السهم المجاور لـ**Recompile** خيارات التجميع. ولا تعرض القائمة إلا الخيارات التي تفعل شيئًا لمحرك المشروع.

| المجموعة | LaTeX مع Tectonic | LaTeX مع `latexmk` | Typst | Markdown |
|---|---|---|---|---|
| **Auto compile** | نعم | نعم | نعم | نعم |
| **Compile mode** (Normal أو Fast) | نعم | لا | لا | لا |
| **Syntax checks** | نعم | نعم | لا | لا |
| **Compiler (this project)** | نعم | نعم | لا | لا |
| **Typst version**، **Fonts**، **Build**، **Variant** | لا | لا | نعم | لا |
| **Compile error handling** | نعم | نعم | لا | لا |

يقع الخياران **Stop compilation** و**Recompile from scratch** أسفل القائمة لكل محرك. وتظهر مجموعة **Variant** متى صار لمشروع Typst متغيرات بناء.

ضمن **Compiler (this project)**، يكون **Tectonic** مدمجًا. ويشغّل **Auto** نسخة TeX الموجودة على نظامك عبر `latexmk` ويختار المجمّع من المصدر. أما **pdfLaTeX** و**XeLaTeX** و**LuaLaTeX** فتُثبّت ذلك المجمّع وتعمل أيضًا عبر `latexmk`، ويجمّع **upLaTeX** و**pLaTeX** المستندات اليابانية. وكل خيار عدا Tectonic يحتاج إلى توزيعة TeX. وإذا لم يكن لدى هذا الحاسوب أي منها، يعرض Oleafly تثبيت TinyTeX عندما تختار واحدًا. انظر [عندما لا يكون TeX مثبّتًا](/docs/latex-engines/#when-no-tex-is-installed). وتُغطى مجموعات Typst في [مشاريع Typst](/docs/typst/).

## التجميع التلقائي

اضبط **Auto compile** على **On** في خيارات التجميع، أو شغّل **Enable auto-compile** من لوحة ⌘K. وهو متوقف افتراضيًا، وينطبق على كل مشروع، وتعيد التحكمات نفسها إيقافه.

في مشروع LaTeX أو Markdown، يعيد Oleafly التجميع بعد نحو 2.5 ثانية من توقفك عن الكتابة. التعديلات الحقيقية وحدها تطلبه، أما تبديل علامات التبويب أو فتح الملفات فلا.

في مشروع Typst، التجميع التلقائي هو المعاينة الحية. يبقي Oleafly عملية Typst واحدة تعمل، ويحفظ الملف المفتوح نفسه بعد لحظة من توقفك عن الكتابة، ويتحدّث ملف PDF عند موضع التمرير نفسه. انظر [المعاينة الحية مع التجميع التلقائي](/docs/typst/#live-preview-with-auto-compile).

لا تتراكم عمليات التجميع أبدًا. إذا عدّلت أثناء تشغيل تجميع تلقائي، أوقفه Oleafly وبدأ من جديد بآخر نص لديك، فيلحق ملف PDF أسرع. ويسمح لعملية تجميع بأن تكتمل عندما تكون أنت أو وكيل قد بدأها، أو عندما تكون تنزّل حزمًا، أو عندما تكون على وشك الانتهاء، أو عندما تكون هي نفسها إعادة تشغيل. وفي هذه الحالات يُصفّ تجميع تالٍ واحد بالضبط، فيظل ملف PDF النهائي يعكس آخر تعديلاتك.

## متابعة التقدم

يمتد شريط تقدم رفيع أعلى المعاينة أثناء البناء، وقبل وجود أول ملف PDF تعرض اللوحة تقديرًا بالنسبة المئوية. وعندما ينتهي البناء، يعرض شريط الأدوات **رقاقة حالة** تحمل زمن التجميع وأيقونة شدة:

- علامة تحقق خضراء: تم التجميع بنجاح.
- مثلث كهرماني: تم التجميع مع تحذيرات. وتحصل على ملف PDF رغم ذلك.
- علامة X حمراء: تم التجميع مع أخطاء.

تتحول المعاينة إلى ملف PDF تلقائيًا عند النجاح. ولا ينقلك إلى عرض Logs إلا فشل حقيقي (لم يُنتَج ملف PDF).

![تعثّر التجميع وعُلِّم في المحرر والسجل، ثم أُصلح وجُمِّع مرة أخرى.](https://cdn.oleafly.com/images/gifs/desktop/compile-errors.gif?v=2)

## قراءة السجلات

![تقع Logs ومدة آخر بناء يسار شريط أدوات المعاينة.](https://cdn.oleafly.com/images/screenshots/desktop/docs/llama-writing-dark-window-v2.png#view=1146,44,239,42)

يبدّل زر **Logs** في يسار شريط أدوات المعاينة بين ملف PDF وسجل التجميع، مع شارة تعدّ الأخطاء (حمراء) أو التحذيرات (كهرمانية):

- **قائمة تشخيصات** محلَّلة في الأعلى: كل خطأ أو تحذير مع نوعه، ومرجع السطر `l.42` عندما يكون معروفًا. والأحرف التي لم تستطع الخطوط عرضها تُجمع تحت **Missing characters**.
- سجل المجمّع الخام الكامل في الأسفل، ملوّن: الأخطاء بأحمر عريض، ومراجع الأسطر مميزة، وتداخل الملفات بمسافة بادئة.
- زر **Copy log** يأخذ السجل كله لتقرير خطأ أو منشور في منتدى. كما تنسخ ⌘A متبوعة بـ⌘C في السجل كلَه.
- يخفي **Clear**، بجانب **Copy log**، السجل وأخطاءه حتى التجميع التالي. وتبقى ملفات البناء لديك، ويكتب التجميع التالي سجلًا جديدًا.

تفتح السجلات الطويلة فورًا، حتى التي تحوي 100,000 سطر، وتُمرَّر دون مناطق فارغة.

وتتحول أخطاء التجميع أيضًا إلى خطوط متعرجة في المحرر عبر [مسار المدقق](/docs/editor/#the-built-in-latex-linter)، ويمكن لـ[المساعد الذكي](/docs/ai-chat/) قراءة هذا السجل نفسه بأداته `get_log` عندما تطلب منه إصلاح الأخطاء.

تُعلَّم أخطاء Typst في المحرر عند الموضع الدقيق الذي يبلغ عنه Typst، مع السطر في المصدر وتلميحات Typst نفسها. وتأتي الأخطاء الشائعة أيضًا مع شرح بسيط لما حدث.

## الحزم والتجميع دون اتصال

ينزّل Tectonic حزمة LaTeX في المرة الأولى التي يحتاجها فيها مستند، ثم يخزّنها محليًا. ويجلب أول تجميع على الحاسوب أيضًا دفعة من الحزم الشائعة الاستخدام دفعة واحدة. قد يكون ذلك التجميع الأول أبطأ ويحتاج إلى اتصال بالشبكة. وتستخدم عمليات التجميع اللاحقة ذاكرة التخزين المؤقت. وإذا فشلت مرآة الحزم الخاصة بـOleafly، يعود التجميع إلى المصدر الأصلي ويقول السجل ذلك.

يجعل **Offline mode**، في Settings أو General أو لوحة الأوامر، هذا مضمونًا لـTectonic. يعمل المجمّع بـ`--only-cached` ولا يجلب حزمة أبدًا. ويفشل المستند الذي يحتاج إلى حزمة ليست في ذاكرة التخزين المؤقت برسالة تسمّي الملف متى أمكن، ويوقف **Turn off and compile** وضع عدم الاتصال ويجمّع مرة أخرى.

يغطي وضع عدم الاتصال Typst أيضًا. لا يستطيع Typst تنزيل حزمة أثناء تفعيله، لذا يجب أن تكون كل حزمة `@preview` موجودة سلفًا في ذاكرة التخزين المؤقت أو منسوخة داخل مجلد المشروع `typst-packages`. انظر [حزم من Typst Universe](/docs/typst/#packages-from-typst-universe). وتتجاهل مشاريع Markdown وضع عدم الاتصال، ويذكر السجل ذلك.

يستخدم `latexmk` توزيعة TeX المثبتة سلفًا على جهازك. يتحقق Oleafly من توزيعات النظام أولًا، بما فيها MacTeX وTeX Live وMiKTeX وTinyTeX، ويعلّم **Settings → Engines → LaTeX** التوزيعة التي يجمّع بها بالعلامة **In use**. وإذا لم تتوفر أي منها، استطاع التطبيق تثبيت نسخة TinyTeX خاصة به وإدارتها. ويحتاج MiKTeX أيضًا إلى Perl لتشغيل `latexmk`؛ انظر [MiKTeX وPerl](/docs/latex-engines/#miktex-and-perl). ولأن عملية TeX النظامية تستطيع قراءة الملفات المتاحة لحساب مستخدمك، استخدم `latexmk` مع المشاريع التي تثق بها فقط.

عندما لا يجد بناء `latexmk` ملف `.sty` أو `.cls` أو نمط مراجع أو ملف خط أو ملف لغة babel أو مكتبة TikZ أو ملف TeX آخر، يمكن لـOleafly أن يعرض **Find and install** في رسالة الخطأ. وغالبًا ما يختلف اسم الملف عن اسم الحزمة: فملف `tikz.sty` مثلًا ينتمي إلى حزمة TeX Live المسماة `pgf`. يحدد Oleafly ذلك المالك، ويثبّت الحزمة بـ`tlmgr`، ويحدّث قائمة الحزم، ويعيد التجميع. وعلى Debian وUbuntu وFedora، تتبع TeX Live مدير حزم النظام، لذا يعطيك Oleafly أمر `apt` أو `dnf` بدلًا من ذلك. استخدم قائمة **Packages** في **Settings → Engines → LaTeX** عندما تفضل البحث أولًا أو إدارة الحزم يدويًا.

## الحدود وصمامات الأمان

- تعمل عملية تجميع واحدة فقط في كل مرة لكل مشروع، في طابور يخدم الأحدث فقط: تحل الطلبات الأحدث محل القديمة، فلا يرسم تبديل المشاريع أثناء البناء ملف PDF خاطئًا أبدًا، ولا تتشكل عاصفة تجميع أثناء كتابتك.
- البناء المستبدَل أو المنتهي المهلة يُلغى فعلًا: ينهي Oleafly شجرة عمليات المجمّع بأكملها، على كل منصة، بدل تركها تعمل في الخلفية.
- التجميع الذي يستمر أكثر من 5 دقائق يُوقف بدل تركه يدور إلى الأبد. وما دام Tectonic ينزّل حزمًا، يدفع كل تنزيل الحد إلى الأمام، حتى 30 دقيقة في المجموع. ويحصل Markdown إلى PDF على 15 دقيقة، ويحصل Quarto وCalepin على ساعة.
- تحمل النتائج هوية مرتبطة بالطلب، فيُرفض ملف PDF قديم ناتج عن اكتمال خارج الترتيب بدل عرضه.

## أعطال شائعة وإصلاحات سريعة

- **"Missing package" في وضع عدم الاتصال**: اختر **Turn off and compile** في الرسالة، أو أوقف وضع عدم الاتصال لتجميع واحد حتى تُجلب الحزمة وتُخزَّن، ثم أعد تفعيله.
- **"This compiler needs a working TeX distribution"**: يحتاج pdfLaTeX وبقية مجمّعات `latexmk` إلى TeX على هذا الحاسوب، لذا يفتح اختيار أحدها دون ذلك مربع الحوار هذا. اختر **Download and use TinyTeX**، أو **Switch back to Tectonic** للعودة إلى المحرك المدمج. وإذا فشل تجميع بهذا السبب فعلًا، تعرض المعاينة **Download and use TinyTeX** و**Use Tectonic**. انظر [عندما لا يكون TeX مثبّتًا](/docs/latex-engines/#when-no-tex-is-installed).
- **"latexmk needs Perl"** على MiKTeX: ثبّت Strawberry Perl، أو ثبّت TinyTeX الذي يأتي بـPerl خاص به. انظر [MiKTeX وPerl](/docs/latex-engines/#miktex-and-perl).
- **ملف مفقود في بناء `latexmk`**: استخدم **Find and install**. وإذا فشل البحث، فابحث عن اسم الملف أو الحزمة في قائمة **Packages** ضمن **Settings → Engines → LaTeX**. وعلى Debian أو Ubuntu أو Fedora، ثبّته بـ`apt` أو `dnf`. تُدار حزم MiKTeX في MiKTeX Console.
- **upLaTeX أو pLaTeX غير مثبّت**: اختر **Install Japanese support (about 450 MB)** عندما يُعرض، أو شغّل الأمر الذي تسمّيه الرسالة. انظر [المستندات اليابانية](/docs/latex-engines/#japanese-documents-uplatex-and-platex).
- **نص مفقود من ملف PDF**، وغالبًا كوري أو صيني أو ياباني: ليس في الخط رموز لتلك الأحرف، ويتركها TeX دون أن يفشل. ينبّهك Oleafly ويعطيك السجل إعدادًا تلصقه. انظر [أحرف مفقودة من ملف PDF](/docs/latex-engines/#characters-missing-from-the-pdf)، أو [أحرف تظهر مربعات](/docs/typst/#characters-that-show-as-boxes) في Typst.
- **فهرس أو مسرد أو قائمة رموز مفقودة من ملف PDF**: لا يستطيع Tectonic تشغيل `makeindex`. حوّل المشروع إلى `latexmk`، أو ابنِ المسارد بـ`\makenoidxglossaries` الذي لا يحتاج إلى أداة خارجية. وعلى `latexmk`، لا تُبنى القوائم المصنوعة بـ`xindy` أو `\newglossary`.
- **انتهى وقت التجميع**: جمّع مرة أخرى. وإذا كانت الحزم لا تزال تُنزَّل، يتابع التنزيل من حيث توقف. وللمسودات الطويلة على Tectonic، اضبط **Compile mode** على **Fast**.
- **شكل EPS، أو محرك `pdftex` مفروض، أو ملف حزمة مفقود في Tectonic**: يفتح مربع حوار المحرك. وإن لم يفتح، أو أغلقته، فاختر **Choose engine**. ويذكر [عندما لا يكفي Tectonic](/docs/latex-engines/#when-tectonic-isnt-enough) مكانه في كل عرض. اختر الخيار الموسوم **Recommended**: LaTeX النظامي لديك عندما يجد Oleafly توزيعة TeX تعمل، أو **Download and use TinyTeX** عندما لا يجد. وللحزمة المفقودة، يمكن لـOleafly المتابعة إلى مثبّتها بعد التحويل.
- **عندما يُحجب `minted` أو PythonTeX أو `\write18`**: إذا كنت تثق بكل ملف في المشروع، فاختر **Allow external commands** في الشريط أعلى المحرر. انظر [السماح بالأوامر الخارجية](/docs/latex-engines/#allow-external-commands).
- **فشل تنزيل حزمة في Tectonic**: تحقق من الاتصال واختر **Compile again** في الرسالة. جرّب Oleafly المصدر الأصلي بعد مرآته، ويتابع التنزيل من حيث توقف، وإذا كان الحاسوب غير متصل، يعيد التجميع نفسه تلقائيًا متى عاد الاتصال.
- **"Typst 0.13.1 is not installed"**: يحدد المشروع نسخة Typst لا يمتلكها هذا الحاسوب. اختر **Download Typst 0.13.1** في المعاينة، أو اختر **Use Typst** متبوعة بنسختك الافتراضية لإسقاط التحديد. انظر [عندما تكون النسخة المحددة مفقودة](/docs/typst/#when-a-pinned-version-is-missing).
- **تحذيرات استشهاد أو مرجع غير معرف**: يحدد [Preflight](/docs/preflight/#six-independent-checks) كل واحد منها بدقة، مع الملف والسطر.
- **خطأ لا تستطيع تفسيره**: اسأل الذكاء الاصطناعي. جملة "Fix the LaTeX errors" تطلق حلقة تجميع وقراءة سجل وتعديل موجه وإعادة تجميع، باستخدام [سياسة الاعتماد](/docs/ai-chat/) التي اخترتها.

## محركات مستندات أخرى

اختيار مجمّع LaTeX منفصل عن محرك مستند المشروع:

- **مشاريع Typst** تُجمَّع بنسخة Typst 0.15.1 المدمجة أو بالنسخة التي يحددها المشروع. انظر [مشاريع Typst](/docs/typst/).
- **مشاريع Markdown** تُبنى إلى PDF عبر نسخة Pandoc مُدارة مع Tectonic كمحرك PDF.
- **مشاريع Quarto** تحوّل ملفات `.qmd` و`.Rmd` عبر Quarto إلى PDF أو صفحة ويب. انظر [Quarto](/docs/engines/#quarto).
- **مشاريع Calepin** تشغّل الشيفرة في مستند Typst عبر Calepin، ثم تبني ملف PDF بنسخة Typst المدمجة. انظر [Calepin](/docs/engines/#calepin). ولا يشغّل أي من المحركين شيفرة المشروع حتى [تسمح بذلك](/docs/engines/#allow-code-in-a-project).
- **ملفات PDF الموسومة والميسّرة** تستخدم LuaLaTeX عبر تثبيت TeX نظامي أو TinyTeX المُدار من Oleafly. انظر [محركات وحزم LaTeX](/docs/latex-engines/). وTypst 0.14 وما بعده يوسم كل ملف PDF دون خطوات إضافية.

المحرك اختيار لكل مشروع يُتخذ عند إنشائه، وتتكيف الواجهة معه: الإجراءات التي لا يستطيع المحرك دعمها تُخفى بدل تركها تفشل. لنقل مشروع LaTeX إلى Typst، [حوّله إلى مشروع Typst جديد](/docs/typst/#convert-a-latex-project-to-typst).

## احتفظ بالمصدر خلف بناء ناجح

فعّل [نقاط الحفظ](/docs/checkpoints/) لحفظ المصدر الذي استخدمته عمليات التجميع الناجحة. يمكنك مقارنة بناء سابق واستعادته دون تغيير سير عملك اليدوي في Git.

ولإبقاء ملف PDF المجمَّع نفسه في مجلد المشروع، شغّل [Sync PDF on compiles](/docs/pdf-preview/#sync-pdf-on-compiles) من قائمة الحفظ في المعاينة.
