.TH "META" "5" "The findlib package manager for OCaml" "User Manual"
.SH "نام (NAME)"
META \- فایل توصیف پکیج در کتابخانه OCaml findlib
.SH "گرامر (GRAMMAR)"
.ft R
.ft R
.ft B
.nf
\&\ \ \ \ \ \ \ \ \ metafile\ ::=\ entry*\c
\&
.br
\&\ \ \ \ \ \ \ \ \ \ \ \ entry\ ::=\ assignment\ |\ addition\ |\ subpackage\c
\&
.br
\&\ \ \ \ \ \ \ subpackage\ ::=\ "package"\ pkgname\ '('\ metafile\ ')'\c
\&
.br
\&\ \ \ \ \ \ \ assignment\ ::=\ variable_name\ [\ formal_predicates\ ]\ '='\ \ value\c
\&
.br
\&\ \ \ \ \ \ \ \ \ addition\ ::=\ variable_name\ [\ formal_predicates\ ]\ '+='\ value\c
\&
.br
formal_predicates\ ::=\ '('\ formal_predicate\ {\ ','\ formal_predicate\ }\ ')'\c
\&
.br
\&\ \ \ \ variable_name\ ::=\ name\c
\&
.br
\&\ formal_predicate\ ::=\ name\ |\ '-'\ name\c
\&
.br
\&\ \ \ \ \ \ \ \ \ \ \ \ \ name\ ::=\ [\ 'A'-'Z'\ 'a'-'z'\ '0'-'9'\ '_'\ '.'\ ]+\c
\&
.br
\&\ \ \ \ \ \ \ \ \ \ pkgname\ ::=\ '"'\ (character\ but\ not\ '.')*\ '"'\c
\&
.br
\&\ \ \ \ \ \ \ \ \ \ \ \ value\ ::=\ '"'\ character*\ '"'\c
.ft R
.fi
.SH "توضیحات (DESCRIPTION)"
.ft R
اگر دایرکتوری یک بسته حاوی فایلی با نام ثابت "META" باشد، مطابق آنچه در اینجا شرح داده شده تفسیر می‌شود. این فایل دنباله‌ای از ورودی‌هاست که از گرامر ارائه‌شده پیروی می‌کنند؛ هر ورودی یک متغیر را تحت شرایط خاصی که با فهرستی از گزاره‌های صوری مشخص می‌شود تعریف می‌کند، یا یک زیربسته (subpackage) را معرفی می‌نماید.
.PP
.ft R
فهرستی از متغیرهای از پیش تعریف‌شده و فهرستی از گزاره‌های استاندارد وجود دارد. این متغیرها مواردی همچون بسته‌های مورد نیاز، توضیحات، اطلاعات نسخه، دایرکتوری‌ها، فایل‌های آرشیو و گزینه‌های پیونددهنده را تعریف می‌کنند. گزاره‌ها شرایط به‌کارگیری متغیرها را مشخص می‌سازند: اینکه آیا از کامپایلر بایت‌کد یا کامپایلر محلی (native) استفاده می‌شود، آیا یک toploop در برنامه کامپایل شده است یا خیر، جزئیات اجرای چندنخی (multi-threading)، و جزئیات پروفایلینگ (profiling).
.SH "جزئیات قالب فایل (DETAILS OF THE FILE FORMAT)"
.ft R
این فایل از دنباله‌ای از ورودی‌ها تشکیل شده که باید به همان صورتی که در گرامر مشخص شده است شکل بگیرند. نشانه‌های واژگانی (lexical tokens) عبارتند از نام‌ها، مقادیر و علائم نگارشی مانند '(', ',' و غیره. توجه داشته باشید که شکستن خطوط (linefeeds) نقش خاصی ایفا نمی‌کنند، یعنی تعریف یک ورودی می‌تواند در بیش از یک خط آورده شود یا چندین تعریف ممکن است در یک خط قرار گیرند. همچنین ممکن است کامنت‌هایی وجود داشته باشند که با '#' آغاز شده و تا پایان خط ادامه پیدا می‌کنند.
.PP
.ft R
نام‌ها دنباله‌ای از نویسه‌های A-Z، a-z، 0-9 یا _ هستند. نام‌های حاوی حروف بزرگ و نام‌هایی که با ارقام شروع می‌شوند مجاز هستند اما توصیه نمی‌شوند.
.PP
.ft R
مقادیر درون نقل‌قول‌های دوتایی (double quotes) قرار می‌گیرند. مقادیر می‌توانند حاوی هر نویسه‌ای باشند. قبل از نویسه‌های " و \e باید از بک‌اسلش استفاده شود.
.PP
.ft R
نام‌های بسته‌ها نباید حاوی نویسه '.' باشند زیرا این نویسه به عنوان جداکننده نام‌های مرکب به کار می‌رود.
.SH "بسته‌های اصلی و زیربسته‌ها (MAIN PACKAGES AND SUBPACKAGES)"
.ft R
بیرونی‌ترین انتساب‌ها و الحاق‌های متغیر متعلق به بسته اصلی هستند. نام بسته اصلی درون META تعریف نمی‌شود؛ این نام یا نام دایرکتوری حاوی META است یا پسوند فایل META (در صورتی که نام فایل META به شکل META.name تشکیل شده باشد).
.PP
.ft R
کلیدواژه
.B package
تعریف یک زیربسته را آغاز می‌کند. نباید دو تعریف از این نوع با نام یکسان وجود داشته باشد. در داخل پرانتزها، انتساب‌ها و الحاق‌های متغیر به زیربسته ارجاع دارند. یک زیربسته مجاز است حاوی زیربسته‌های بیشتری نیز باشد.
.PP
.ft R
نام بسته‌ای که پس از
.B package
می‌آید نام محلی نسبت به بسته اصلی است؛ یعنی نام بسته اصلی ذکر نمی‌شود. با این حال، در تمام جاهای دیگر، نام زیربسته باید با نام بسته حاوی آن و با علامت '.' پیشوندگذاری شود.
.PP
.ft R
زیربسته‌ها از بسته حاوی خود مستقل هستند، به جز اینکه زیربسته به همان دایرکتوری نصبی اشاره می‌کند که بسته حاوی آن اشاره دارد (یعنی مکان دایرکتوری نصب از بسته حاوی آن به ارث برده می‌شود).
.SH "معناشناسی تعاریف متغیرها (SEMANTICS OF VARIABLE DEFINITIONS)"
.ft R
به منظور تعیین مقدار یک متغیر، ابتدا تمام انتساب‌ها بررسی می‌شوند و خاص‌ترین انتساب انتخاب می‌گردد (اگر هیچ انتسابی وجود نداشته باشد، رشته خالی به عنوان مقدار در نظر گرفته خواهد شد). در گام دوم، تمام الحاق‌ها یکی پس از دیگری به ترتیبی که در فایل آمده‌اند بررسی می‌شوند و مقادیر تمام الحاق‌های منطبق به مقدار فعلی اضافه می‌گردند. در ادامه توضیح داده می‌شود که کدام انتساب خاص‌ترین است، کدام الحاق‌ها واقعاً منطبق هستند، و جزئیات افزودن مقدار چگونه است.
.PP
.ft R
خاص‌ترین انتساب بر اساس مجموعه‌ای از گزاره‌های واقعی (actual predicates) انتخاب می‌شود؛ یعنی مجموعه‌ای از گزاره‌ها که فرض می‌شود درست هستند. گزاره‌هایی که در تعاریف انتساب‌ها و الحاق‌ها ظاهر می‌شوند «گزاره‌های صوری» (formal predicates) نامیده می‌شوند. این گزاره‌ها ممکن است مثبت یا منفی باشند؛ گزاره‌های منفی با یک علامت '-' پیشوندگذاری می‌شوند. برای تعیین مقدار پس از ارزیابی انتساب‌ها، قوانین زیر اعمال می‌شوند:
.PP
.ft R
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
یک انتساب تنها زمانی قابل استفاده است که تمام گزاره‌های صوری مثبت در مجموعه گزاره‌های واقعی گنجانده شده باشند، و تمام گزاره‌های صوری منفی در مجموعه گزاره‌های واقعی وجود نداشته باشند. به چنین انتسابی
.ft B
قابل اعمال (applicable)
.ft R
گفته می‌شود. اگر چنین انتسابی وجود نداشته باشد، متغیر هیچ مقداری نخواهد داشت.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
اگر بیش از یک انتساب قابل اعمال وجود داشته باشد، تعریفی که بیشترین تعداد گزاره‌های صوری را دارد انتخاب می‌شود.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
اگر همچنان بیش از یک انتساب قابل اعمال وجود داشته باشد که هم قابل اعمال باشند و هم بیشترین تعداد گزاره‌های صوری را داشته باشند، تعریفی که زودتر تعریف شده است انتخاب می‌شود.
.RE
.ft R
.PP
.ft R
یک الحاق زمانی منطبق است که تمام گزاره‌های صوری مثبت در مجموعه گزاره‌های واقعی گنجانده شده باشند، و تمام گزاره‌های صوری منفی گنجانده نشده باشند.
.PP
.ft R
مقدار یک الحاق به همراه یک فاصله خالی ضمنی به عنوان جداکننده، به مقدار فعلی افزوده می‌شود.
.SH "متغیرها (VARIABLES)"
.ft R
مجموعه‌ای از متغیرها با معانی از پیش تعریف‌شده وجود دارند:
.PP
.ft R
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "directory" مکان دایرکتوری بسته را مجدداً تعریف می‌کند. به طور معمول، فایل META نخستین فایلی است که در دایرکتوری بسته خوانده می‌شود و پیش از خوانده شدن هر فایل دیگری، متغیر "directory" ارزیابی می‌شود تا مشخص گردد آیا دایرکتوری بسته باید تغییر کند یا خیر. مقدار متغیر "directory" با یک مجموعه خالی از گزاره‌های واقعی تعیین می‌شود. این مقدار باید یکی از این موارد باشد: نام مسیر مطلق دایرکتوری جایگزین، نام مسیر نسبی نسبت به دایرکتوری stdlib در OCaml (نوشته‌شده به صورت "+path")، یا یک نام مسیر نسبی معمولی (بدون نحو ویژه). در حالت اخیر، تفسیر آن بستگی به این دارد که در یک بسته اصلی یا یک زیربسته قرار داشته باشد، و اینکه آیا ساختار مخزن استاندارد یا ساختار جایگزین فعال است (برای این اصطلاحات به
.B site-lib
مراجعه کنید). برای یک بسته اصلی در ساختار استاندارد، دایرکتوری پایه همان دایرکتوری است که فیزیکاً حاوی فایل META است و مسیر نسبی برای این دایرکتوری پایه تفسیر می‌شود. برای یک بسته اصلی در ساختار جایگزین، دایرکتوری پایه دایرکتوری است که فیزیکاً فایل‌های META.pkg را در بر دارد. دایرکتوری پایه برای زیربسته‌ها، دایرکتوری بسته حاوی آن‌ها است. (در حالتی که یک تعریف زیربسته فاقد تنظیمات "directory" باشد، زیربسته صرفاً دایرکتوری بسته حاوی خود را به ارث می‌برد. با نوشتن دستور "directory" می‌توان این مکان را دوباره تغییر داد.)
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "requires" فهرست بسته‌های مورد نیاز را مشخص می‌کند. نام بسته‌ها باید با فاصله خالی و/یا کاما از یکدیگر جدا شوند. نام‌ها باید کاملاً واجد شرایط (fully qualified) باشند (یعنی هنگامی که به یک زیربسته ارجاع می‌دهند، نام تمام بسته‌های در بر گیرنده آن باید با پیشوند و با علامت '.' از هم جدا شوند).
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "description" می‌تواند شامل توضیح کوتاهی درباره بسته باشد (که توسط
.B ocamlfind list
نمایش داده می‌شود).
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "version" رشته نسخه بسته را مشخص می‌کند.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "archive" فهرست فایل‌های آرشیو را مشخص می‌کند. این فایل‌ها باید به یکی از این اشکال ارائه شوند: (۱) نام‌های ساده بدون اطلاعات دایرکتوری؛ که فقط در دایرکتوری بسته جستجو می‌شوند. (۲) دارای قالب "+path" باشند که در این حالت فایل‌ها نسبت به کتابخانه استاندارد جستجو می‌شوند. (۳) به شکل "@name/file" باشند که در این حالت فایل‌ها در دایرکتوری بسته دیگری جستجو می‌شوند. (۴) یا به صورت مسیرهای مطلق ارائه شوند.
.PP
.ft R
نام فایل‌ها باید با فاصله خالی و/یا کاما از یکدیگر جدا شوند. در مرحله پیش‌پردازنده، فایل‌های آرشیو به عنوان افزونه به فراخوانی پیش‌پردازنده (camlp4) ارسال می‌شوند. در مرحله پیونددهنده (\-linkpkg)، فایل‌های آرشیو پیوند داده می‌شوند. در مرحله کامپایلر، فایل‌های آرشیو نادیده گرفته می‌شوند.
.PP
.ft R
توجه داشته باشید که "archive" فقط باید برای فایل‌های آرشیوی استفاده شود که قرار است در فایل‌های اجرایی گنجانده شوند یا در toploop بارگذاری گردند. برای ماژول‌هایی که در زمان اجرا بارگذاری می‌شوند، متغیر جداگانه "plugin" وجود دارد.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "plugin" آرشیوهای پلاگین بسته را مشخص می‌کند. این آرشیوها را می‌توان به طور پویا با ماژول
.B Fl_dynload
بارگذاری کرد. آرشیوهای پلاگین می‌توانند پسوند ".cmo"، ".cma" یا ".cmxs" داشته باشند.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "linkopts" گزینه‌های اضافی پیونددهنده را مشخص می‌کند.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "error" می‌تواند برای اعلام شرایط خطا استفاده شود. هنگامی که این متغیر قابل اعمال باشد، کامپایلرهای ocaml متوقف شده و یک پیام خطا چاپ می‌شود. این پیام همان مقدار متغیر است.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "warning" می‌تواند برای اعلام هشدارها استفاده شود. هنگامی که این متغیر قابل اعمال باشد، هشدار چاپ می‌شود، اما فرآیند کامپایل ادامه می‌یابد. پیام همان مقدار متغیر است.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "exists_if" می‌تواند برای غیرفعال کردن زیربسته‌ها به کار رود. مقدار "exists_if" یک فایل است؛ در صورتی که این فایل وجود نداشته باشد، زیربسته پنهان می‌شود. همچنین می‌توانید چندین فایل را ذکر کنید، که در این صورت اگر هیچ‌یک از فایل‌ها وجود نداشته باشند، زیربسته پنهان می‌گردد.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "ppx" دستوری است که از طریق گزینه
.B \-ppx
(در دسترس از OCaml-4.01) به فراخوانی کامپایلر اضافه می‌شود. اگر دستور نسبت به دایرکتوری جاری باشد (مانند ./cmd)، انتظار می‌رود که دستور در دایرکتوری بسته باشد. قالب‌های ویژه‌ای که برای "archive" تعریف شده‌اند نیز در دسترس هستند (مانند @otherpkg/cmd). آرگومان‌های اضافی را می‌توان در خط فرمان ocamlfind با گزینه
.B \-ppxopt
یا متغیر "ppxopt" مشخص کرد.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
متغیر "ppxopt" مجموعه‌ای از گزینه‌هاست که به فراخوانی بازنویس‌کننده ppx اضافه می‌شوند. محتوای این متغیر از یک یا چند بخش جداشده با فاصله خالی تشکیل شده است. هر بخش از چند زیربخش جداشده با کاما تشکیل می‌شود؛ نخستین زیربخش نشان‌دهنده بسته‌ای است که شامل فراخوانی بازنویس‌کننده ppx است، و باقی زیربخش‌ها شامل گزینه‌هایی هستند که باید اضافه شوند. اگر گزینه یک مسیر نسبت به دایرکتوری جاری باشد (مانند ./foo.cma)، مسیر نسبت به دایرکتوری بسته بسط داده می‌شود. قالب‌های ویژه تعریف‌شده برای "archive" نیز در دسترس هستند (مانند @otherpkg/foo.cma).
.RE
.ft R
.PP
.ft R
تعریف متغیرهای اضافی امکان‌پذیر است اما در حال حاضر هیچ نرم‌افزاری برای تفسیر آن‌ها وجود ندارد.
.SH "گزاره‌ها (PREDICATES)"
.ft R
فهرستی از گزاره‌های استاندارد وجود دارد:
.PP
.ft R
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "byte" به این معنی است که از کامپایلر بایت‌کد استفاده می‌شود.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "native" به این معنی است که از کامپایلر محلی (native) استفاده می‌شود.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "toploop" به این معنی است که toploop در برنامه پیوند داده شده در دسترس است. این گزینه فقط زمانی تنظیم می‌شود که toploop در حال اجرا باشد، نه زمانی که toploop تولید می‌شود.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "create_toploop" به این معنی است که یک toploop (با استفاده از
.BR ocamlmktop )
ایجاد می‌شود.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "mt" به این معنی است که برنامه چندنخی (multi-threaded) است.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "mt_posix" به این معنی است که در صورت تنظیم بودن "mt"، برای پیاده‌سازی نخ‌ها از کتابخانه‌های POSIX استفاده می‌شود.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "mt_vm" به این معنی است که در صورت تنظیم بودن "mt"، برای پیاده‌سازی نخ‌ها از کتابخانه‌های مبتنی بر ماشین مجازی (VM-based) استفاده می‌شود.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "gprof" به این معنی است که در صورت تنظیم بودن "native"، برنامه برای تحلیل کارایی (profiling) کامپایل می‌شود.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "autolink" به این معنی است که ocamlc می‌تواند/می‌خواهد پیوند خودکار را انجام دهد.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "preprocessor" به این معنی است که متغیرهای META برای گزینه‌های پیش‌پردازنده بررسی می‌شوند.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
گزاره "syntax" به این معنی است که گزینه
.B \-syntax
در خط فرمان وجود دارد.
.RE
.ft R
.sp
.RS "7m"
.ft R
\&\h'-3m'\z\(bu\h'3m'\c
.ft R
قدیمی (Legacy): گزاره "plugin" در برخی نسخه‌های findlib می‌توانست برای انتخاب آرشیوهای cmxs به جای آرشیوهای cmxa استفاده شود. این کاربرد همچنان امکان‌پذیر است اما توصیه نمی‌شود.
.RE
.ft R
.PP
.ft R
علاوه بر این گزاره‌ها، برای هر بسته‌ای که در نهایت انتخاب شود گزاره‌های بسته (package predicates) وجود دارند. البته این نوع از گزاره‌ها نباید برای انتخاب متغیرهای "directory" و "requires" استفاده شوند، اما برای سایر متغیرها کاملاً معتبر هستند. گزاره‌های بسته به شکل "pkg_" به همراه نام بسته (به صورت کامل و واجد شرایط) هستند.