'\" t
.\"     Title: crystal
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-07-23
.\"    Manual: Crystal Compiler Command Line Reference Guide
.\"    Source: crystal 1.21.0
.\"  Language: English
.\"
.TH "CRYSTAL" "1" "2026-07-23" "crystal 1.21.0" "Crystal Compiler Command Line Reference Guide"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "نام (NAME)"
crystal \- کامپایلر زبان کریستال (Crystal)
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBcrystal\fP \fIدستور\fP [\fIسوییچ‌ها\fR] \fIفایل_برنامه\fP \(em [\fIآرگومان‌ها\fR]
.SH "توضیحات (DESCRIPTION)"
.sp
کریستال (Crystal) یک زبان برنامه‌نویسی با بررسی نوع ایستا (Statically type-checked) است. این زبان با در نظر گرفتن زیبایی زبان روبی (Ruby) و کارایی زبان C طراحی و ساخته شده است.
.SH "نحوه استفاده (USAGE)"
.sp
می‌توانید با فراخوانی کامپایلر به همراه نام یک فایل، برنامه را کامپایل کرده و اجرا کنید:
.sp
.if n .RS 4
.nf
.fam C
crystal some_program.cr
.fam
.fi
.if n .RE
.sp
فایل‌های کریستال معمولاً با پسوند .cr خاتمه می‌یابند، هرچند این موضوع اجباری نیست.
.sp
همچنین می‌توانید از دستور run استفاده کنید:
.sp
.if n .RS 4
.nf
.fam C
crystal run some_program.cr
.fam
.fi
.if n .RE
.sp
برای ساخت یک فایل اجرایی از دستور build استفاده کنید:
.sp
.if n .RS 4
.nf
.fam C
crystal build some_program.cr
.fam
.fi
.if n .RE
.sp
این کار یک فایل اجرایی به نام "some_program" ایجاد می‌کند.
.sp
توجه داشته باشید که فایل‌های اجرایی تولیدشده به صورت پیش‌فرض کاملاً بهینه‌سازی نشده‌اند. برای فعال کردن بهینه‌سازی‌ها، از پرچم \fB\-\-release\fP استفاده کنید:
.sp
.if n .RS 4
.nf
.fam C
crystal build \-\-release some_program.cr
.fam
.fi
.if n .RE
.sp
حتماً همیشه برای فایل‌های اجرایی آماده محیط عملیاتی و هنگام اجرای بنچمارک‌ها از \fB\-\-release\fP استفاده کنید.
.sp
بهینه‌سازی‌ها به صورت پیش‌فرض فعال نیستند زیرا زمان کامپایل بدون آن‌ها بسیار سریع‌تر است و کارایی برنامه بدون آن‌ها نیز همچنان بسیار خوب است؛ بنابراین این امکان را می‌دهد که از دستور \fBcrystal\fP تقریباً به گونه‌ای استفاده شود که گویی یک مفسر است.
.SH "دستورات کریستال (CRYSTAL COMMANDS)"
.SS "دستورات اصلی (Main commands)"
.sp
\fBcrystal\-init(1)\fP
.RS 4
ایجاد یک پروژه جدید کریستال
.RE
.sp
\fBcrystal\-build(1)\fP
.RS 4
کامپایل یک برنامه کریستال
.RE
.sp
\fBcrystal\-docs(1)\fP
.RS 4
تولید مستندات API برای کدهای کریستال
.RE
.sp
\fBcrystal\-env(1)\fP
.RS 4
چاپ متغیرهای محیطی برای کامپایلر کریستال
.RE
.sp
\fBcrystal\-eval(1)\fP
.RS 4
ارزیابی و اجرای سریع یک برنامه کریستال
.RE
.sp
\fBcrystal\-play(1)\fP
.RS 4
اجرای محیط تعاملی و زمین بازی (Playground) کریستال
.RE
.sp
\fBcrystal\-run(1)\fP
.RS 4
کامپایل و اجرای یک برنامه کریستال
.RE
.sp
\fBcrystal\-spec(1)\fP
.RS 4
کامپایل و اجرای فایل‌های آزمون (Spec) کریستال
.RE
.sp
\fBcrystal\-clear_cache\fP
.RS 4
پاک‌سازی حافظه پنهان کامپایلر (واقع در \*(AqCRYSTAL_CACHE_DIR\*(Aq).
.RE
.sp
\fBcrystal\-help\fP
.RS 4
نمایش راهنما. برای دریافت راهنمای اختصاصی هر دستور نیز می‌توان گزینه \fB\-\-help\fP یا \fB\-h\fP را به هر دستور اضافه کرد.
.RE
.sp
\fBcrystal\-version\fP
.RS 4
نمایش نسخه.
.RE
.SS "ابزارها (Tools)"
.sp
\fBcrystal\-tool\-context\fP
.RS 4
نمایش بافتار و موقعیت (Context) برای یک مکان مشخص در کد
.RE
.sp
\fBcrystal\-tool\-dependencies(1)\fP
.RS 4
نمایش درخت فایل‌های سورس مورد نیاز
.RE
.sp
\fBcrystal\-tool\-expand\fP
.RS 4
نمایش بسط ماکرو برای یک مکان مشخص در کد
.RE
.sp
\fBcrystal\-tool\-flags\fP
.RS 4
چاپ تمام مقادیر ماکروی \*(Aqflag?\*(Aq
.RE
.sp
\fBcrystal\-tool\-format(1)\fP
.RS 4
قالب‌بندی و فرمت فایل‌های سورس کریستال
.RE
.sp
\fBcrystal\-tool\-hierarchy\fP
.RS 4
نمایش سلسله‌مراتب نوع‌ها (Types) از فایل. همچنین نمایش اعضای کلاس‌ها و ساختارها (Struct) به همراه نوع و اندازه. نوع‌ها را می‌توان با استفاده از گزینه \fB\-e\fP با عبارت باقاعده (Regex) فیلتر کرد.
.RE
.sp
\fBcrystal\-tool\-implementations\fP
.RS 4
نمایش پیاده‌سازی‌ها برای یک فراخوانی مشخص. برای مشخص کردن موقعیت مکان‌نما از \fB\-\-cursor\fP استفاده کنید. قالب موقعیت مکان‌نما به صورت file:line:column است.
.RE
.sp
\fBcrystal\-tool\-macro_code_coverage\fP
.RS 4
تولید گزارش پوشش کد ماکرو.
.RE
.sp
\fBcrystal\-tool\-types\fP
.RS 4
نمایش نوع متغیرهای اصلی فایل.
.RE
.sp
\fBcrystal\-tool\-unreachable(1)\fP
.RS 4
شناسایی متدهایی که هرگز فراخوانی نمی‌شوند
.RE
.SH "بهینه‌سازی‌ها (OPTIMIZATIONS)"
.sp
سطح بهینه‌سازی، میزان تلاش تولید کد (Codegen) برای تولید کد بهینه را مشخص می‌کند. این یک تعادل میان کارایی کامپایل (که با هر سطح بهینه‌سازی کاهش می‌یابد) و کارایی زمان اجرا (که با هر سطح بهینه‌سازی افزایش می‌یابد) است.
.sp
نسخه‌های بیلد نهایی و عملیاتی معمولاً باید بالاترین سطح بهینه‌سازی را داشته باشند. بهترین نتایج با \fB\-\-release\fP حاصل می‌شود که به طور خودکار \fB\-\-single\-module\fP را نیز در بر دارد.
.sp
\fB\-O0\fP
.RS 4
بدون بهینه‌سازی (پیش‌فرض)
.RE
.sp
\fB\-O1\fP
.RS 4
بهینه‌سازی کم
.RE
.sp
\fB\-O2\fP
.RS 4
بهینه‌سازی متوسط
.RE
.sp
\fB\-O3\fP
.RS 4
بهینه‌سازی بالا
.RE
.sp
\fB\-Os\fP
.RS 4
بهینه‌سازی متوسط با تمرکز بر حجم فایل
.RE
.sp
\fB\-Oz\fP
.RS 4
بهینه‌سازی متوسط با تمرکز تهاجمی بر حجم فایل
.RE
.SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)"
.SS "CRYSTAL_CACHE_DIR"
.sp
مسیری را مشخص می‌کند که کریستال نتایج کامپایل جزئی را برای سرعت بخشیدن به ساخت‌های بعدی در آن ذخیره می‌کند. این مسیر همچنین برای ذخیره موقت فایل‌های اجرایی زمانی که برنامه‌های کریستال به جای \*(Aq\fBcrystal\fP build\*(Aq با \*(Aq\fBcrystal\fP run\*(Aq اجرا می‌شوند، استفاده می‌شود.
.SS "CRYSTAL_EXEC_PATH"
.sp
مسیری را تعیین می‌کند که \fBcrystal\fP در آن به دنبال زیردستورات خارجی می‌گردد.
.SS "CRYSTAL_LIBRARY_PATH"
.sp
مسیرهایی را مشخص می‌کند که کریستال در آن‌ها به دنبال کتابخانه‌ها (باینری) جستجو می‌کند. مسیرهای چندگانه را می‌توان با ":" از هم جدا کرد. این مسیرها به عنوان پرچم‌های \f(CR\-L\fP به لینکر ارسال می‌شوند.
.sp
الگوی \*(Aq$ORIGIN\*(Aq در ابتدای مسیر به دایرکتوری محل قرارگیری باینری کامپایلر بسط می‌یابد. به عنوان مثال، \*(Aq$ORIGIN/../lib/crystal\*(Aq مسیر کتابخانه استاندارد را به صورت عمومی و مستقل از مسیرهای مطلق (با فرض صحیح بودن مکان نسبی) نسبت به مکان کامپایلر حل می‌کند.
.SS "CRYSTAL_PATH"
.sp
مسیرهایی را مشخص می‌کند که کریستال در آن‌ها به دنبال فایل‌های سورس مورد نیاز جستجو می‌کند. مسیرهای چندگانه را می‌توان با ":" از هم جدا کرد.
.sp
الگوی \*(Aq$ORIGIN\*(Aq در ابتدای مسیر به دایرکتوری محل قرارگیری باینری کامپایلر بسط می‌یابد. به عنوان مثال، \*(Aq$ORIGIN/../share/crystal/src\*(Aq مسیر کتابخانه استاندارد را به صورت عمومی و مستقل از مسیرهای مطلق (با فرض صحیح بودن مکان نسبی) نسبت به مکان کامپایلر حل می‌کند.
.SS "CRYSTAL_OPTS"
.sp
گزینه‌هایی را برای کامپایلر کریستال تعریف می‌کند تا علاوه بر آرگومان‌های خط فرمان استفاده شوند. ساختار نحوی آن دقیقاً مشابه آرگومان‌های خط فرمان است. این قابلیت هنگام استفاده از کریستال در پیکربندی‌های ساخت مفید است، برای مثال \*(AqCRYSTAL_OPTS=\-\-debug make build\*(Aq.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBshards\fP(1)
.sp
.URL "https://crystal\-lang.org" "" ""
وب‌سایت رسمی.
.sp
.URL "https://github.com/crystal\-lang/crystal" "" ""
مخزن رسمی.