نام (NAME)

regina-helper - ابزار کمکی برای کار با یک نسخهٔ نصب‌شده از Regina

خلاصه دستور (SYNOPSIS)

regina-helper action [ args ... ]

regina-helper action [ --help ]

توضیحات (DESCRIPTION)

این ابزار ساختار نسخهٔ نصب‌شدهٔ Regina را درک می‌کند و می‌تواند در کارهای گوناگونی که به این اطلاعات نیاز دارند، به شما کمک نماید. برای نمونه، می‌تواند برای شما Makefileها و/یا کدهای نمونهٔ C++ تولید کند، یا در اجرای مجموعه آزمون‌های Regina کمک نماید.

نخستین آرگومان برای regina-helper باید یک عملیات (action) باشد که مشخص می‌کند می‌خواهید این ابزار چه کاری انجام دهد. عملیات‌های موجود در ادامه با جزئیات شرح داده شده‌اند. برای آشنایی بیشتر با عملکرد یک عملیات، می‌توانید دستور regina-helper action --help را اجرا کنید.

این ابزار در بیشتر محیط‌ها در دسترس است، اما نه در تمام موارد:

•: اگر از GNU/Linux استفاده می‌کنید و Regina در مکانی سیستمی (مانند زیرمسیر /usr/ یا /usr/local/) نصب شده است، regina-helper باید در نسخهٔ نصب‌شدهٔ شما گنجانده شده باشد، و هر خروجی‌ای که تولید می‌کند مرتبط با این نصب سیستمی خواهد بود.
•: اگر از macOS استفاده می‌کنید و Regina را از یک بستهٔ برنامک (app bundle که ممکن است زیر /Applications/ یا هر مکان دیگری باشد) اجرا می‌کنید، می‌توانید regina-helper را از درون بستهٔ برنامک (.../Regina.app/Contents/MacOS/regina-helper) اجرا نمایید، و هر خروجی‌ای که تولید می‌کند متناسب با این بستهٔ برنامک خواهد بود.
•: اگر خودتان Regina را از درخت کد منبع (روی هر پلتفرمی) کامپایل و ایجاد می‌کنید، می‌توانید regina-helper را از همان درخت منبع اجرا کنید، و هر خروجی‌ای که تولید می‌کند وابسته به همین درخت منبع خواهد بود. به‌ویژه، فرض نخواهد کرد که شما حتماً Regina را نصب کرده‌اید.
•: اگر از بسته‌های ازپیش‌ساخته‌شدهٔ Regina روی Windows استفاده می‌کنید، regina-helper در نسخهٔ نصب‌شدهٔ شما گنجانده نخواهد شد.

عملیات‌ها (ACTIONS)

نخستین آرگومان به regina-helper باید یکی از عملیات‌های زیر باشد:

installtype

یک شناسهٔ تکی را در خروجی استاندارد می‌نویسد که نوع نصب Regina را مشخص می‌کند.

example$ regina-helper installtype
XDG
example$

خروجی یکی از موارد زیر خواهد بود:

XDG: نشان می‌دهد که Regina را از مکانی ثابت اجرا می‌کنید که از ساختار freedesktop.org پیروی می‌کند. این مورد در بسته‌های GNU/Linux نرم‌افزار Regina، و همچنین ساخت‌های محلی CMake بدون آرگومان‌های ویژه دیده می‌شود.
HPC: نشان می‌دهد که Regina را از یک نسخهٔ نصب‌شدهٔ محدودتر (برای نمونه، بدون رابط گرافیکی یا مستندات HTML) اجرا می‌کنید که در مکانی مشخص اما احتمالاً غیر استاندارد نصب شده و مناسب برای ساخت روی سیستم‌های محاسباتی با کارایی بالا است. این حالت معمولاً در ساخت‌های محلی CMake که در آن‌ها متغیر REGINA_INSTALL_TYPE به‌صراحت روی HPC تنظیم شده است دیده می‌شود.
Bundle: نشان می‌دهد که Regina را از درون یک بستهٔ برنامک (app bundle) در macOS اجرا می‌کنید.
Windows: نشان می‌دهد که Regina را از درون برنامهٔ Windows مربوط به Regina اجرا می‌کنید. البته بعید است که این مورد را مشاهده کنید، چرا که regina-helper همراه با بسته‌های نصبی Windows ارائه نمی‌شود.
Source: نشان می‌دهد که Regina را مستقیماً از درخت کد منبع اجرا می‌کنید (یعنی یک ساخت محلی که لزوماً نصب نشده است).

عملیات installtype هیچ آرگومان دیگری نمی‌پذیرد.

makefile

یک Makefile در دایرکتوری جاری ایجاد می‌کند که برای کامپایل برنامه‌های C++ همراه با Regina مناسب است. به‌ویژه، پس از ایجاد Makefile، می‌توانید (برای نمونه) یک برنامهٔ C++ به نام foo.cc را تنها با اجرای make foo کامپایل نمایید.

دلیل اصلی استفاده از این Makefile این است که شامل فلگ‌های کامپایلر و پیونددهنده برای دسترسی به موتور محاسباتی C++ در Regina است. (به‌ویژه، استفاده از این Makefile گزینه‌ای ساده‌تر نسبت به استخراج فلگ‌های کامپایلر و پیونددهنده از regina-engine-config است.)

عملیات makefile آرگومان‌های اختیاری --force و/یا --rpath را می‌پذیرد؛ این موارد در ادامه شرح داده شده‌اند.

cc, cpp

یک Makefile در دایرکتوری جاری ایجاد می‌کند که برای کامپایل برنامه‌های C++ با Regina مناسب است، و همچنین یک برنامهٔ نمونهٔ C++ می‌سازد که می‌تواند به عنوان نقطهٔ آغازی برای کد شما استفاده شود.

example$ regina-helper cc
Writing sample.cc...
Preparing Makefile...
example$ ls
Makefile  sample.cc
example$

برای توضیحات بیشتر دربارهٔ نحوهٔ استفاده از این Makefile، عملیات makefile را در بالا ببینید.

نام فایل منبع C++ بسته به این‌که cc یا cpp را به عنوان آرگومان عملیات به regina-helper داده باشید، sample.cc یا sample.cpp خواهد بود.

عملیات cc / cpp آرگومان‌های اختیاری --force و/یا --rpath را می‌پذیرد؛ این موارد در ادامه شرح داده شده‌اند.

test

مجموعه آزمون‌های دقیق و جامع موتور محاسباتی C++ در Regina را اجرا می‌کند.

نرم‌افزار Regina دارای یک مجموعه آزمون بزرگ و دقیق است که برای محافظت در برابر ناسازگاری‌های سیستمی و/یا باگ‌های پیش‌بینی‌نشده طراحی شده است. این مجموعه آزمون شامل چندین بخش است که موتور محاسباتی C++، اتصالات Python، و ابزارهای خط فرمان را هدف قرار می‌دهند. بخش عمدهٔ این آزمون‌ها برای موتور محاسباتی C++ است، و همان آزمون‌ها هستند که در اینجا اجرا خواهند شد.

example$ regina-helper test
Running C++ test suite from the installation beneath /usr/local/.
[==========] Running 522 tests from 53 test suites.
[----------] Global test environment set-up.
[----------] 2 tests from AbelianGroupTest
[ RUN      ] AbelianGroupTest.incrementalBuild
[       OK ] AbelianGroupTest.incrementalBuild (0 ms)
[ RUN      ] AbelianGroupTest.tightEncoding
[       OK ] AbelianGroupTest.tightEncoding (0 ms)
[----------] 2 tests from AbelianGroupTest (1 ms total)
[----------] 6 tests from CoversTest
[ RUN      ] CoversTest.trivial
[       OK ] CoversTest.trivial (2 ms)
...

مجموعه آزمون C++ از چارچوب Google Test استفاده می‌کند که از آرگومان‌های گوناگونی برای سفارشی‌سازی اجرای آزمون‌ها پشتیبانی می‌نماید. هر آرگومان اضافی که همراه با عملیات test مشخص کنید، مستقیماً به Google Test منتقل خواهد شد. می‌توانید دستور regina-helper test --help را اجرا کنید تا ببینید تمام این آرگومان‌های ممکن چه مواردی هستند.

help

اطلاعات نحوهٔ استفاده از ابزار regina-helper را در خروجی نمایش می‌دهد.

این عملیات آرگومان دیگری نمی‌پذیرد.

گزینه‌ها (OPTIONS)

--force

فایل‌های موجود قبلی (مانند Makefile یا sample.cc) را رونویسی می‌کند. به‌طور پیش‌فرض، regina-helper فایلی را که از قبل وجود داشته باشد رونویسی نخواهد کرد.

این گزینه با عملیات‌های makefile و cc / cpp استفاده می‌شود.

--rpath

همواره از گزینهٔ rpath در فلگ‌های پیونددهنده درون Makefile ساخته‌شده استفاده می‌کند. این گزینه برای زمانی که محل نصب Regina در مسیر استاندارد کتابخانه‌ها نباشد، سودمند است.

اگر برنامهٔ شما به‌درستی کامپایل و پیوند داده می‌شود اما هنگام اجرا متوقف می‌گردد زیرا نمی‌تواند کتابخانهٔ libregina-engine.so را پیدا کند، گزینهٔ --rpath ممکن است مشکل شما را حل کند. (البته پس از به‌روزرسانی Makefile باید برنامهٔ خود را دوباره بسازید.)

به‌طور پیش‌فرض، گزینهٔ rpath تنها در صورتی استفاده خواهد شد که Regina را مستقیماً از درخت منبع اجرا نمایید.

این گزینه با عملیات‌های makefile و cc / cpp استفاده می‌شود.

--help

اطلاعات دقیق نحوهٔ استفاده را برای یک عملیات خاص در regina-helper نمایش می‌دهد.

example$ regina-helper test --help
Usage: /usr/local/bin/regina-helper test [testsuite_args...]
Runs Regina's C++ test suite.
...

همچنین ببینید (SEE ALSO)

regina-engine-config.

نویسندگان (AUTHORS)

این ابزار توسط Benjamin Burton <bab@maths.uq.edu.au> نوشته شده است. افراد بسیاری در توسعهٔ Regina نقش داشته‌اند؛ برای مشاهدهٔ فهرست کامل دست‌اندرکاران به راهنمای کاربران مراجعه کنید.