.\" This file is generated automatically by convert.pl from gtags/manual.in.
.TH GTAGS 1 "February 2021" "GNU Project"
.SH "نام (NAME)"
gtags \- ایجاد فایل‌های برچسب برای global
.SH "خلاصه دستور (SYNOPSIS)"
\fBgtags\fP [-ciIOqvw][-C \fIdir\fP][-d \fItag-file\fP][-f \fIfile\fP][\fIdbpath\fP]
.br
.SH "توضیحات (DESCRIPTION)"
دستور \fBgtags\fP برای ایجاد فایل‌های برچسب (tag) برای \fBglobal\fP(1) به کار می‌رود.
.PP
\fBGtags\fP به‌طور بازگشتی فایل‌های منبع موجود در دایرکتوری جاری را جمع‌آوری کرده،
نمادها را استخراج می‌کند و داده‌های ارجاع متقابل (cross-reference) را درون فایل‌های برچسب
(\'GTAGS\'، \'GRTAGS\' و \'GPATH\') می‌نویسد.
.PP
به‌طور پیش‌فرض، \fBgtags\fP فایل‌های منبع
C،‏ Yacc، زبان اسمبلی، Java،‏ ++C و PHP را جمع‌آوری می‌کند.
فایل‌هایی که نام آن‌ها به \'.c\' و \'.h\' ختم می‌شود، فایل‌های منبع C در نظر گرفته می‌شوند.
فایل‌هایی که نام آن‌ها به \'.y\' ختم می‌شود، فایل‌های منبع Yacc در نظر گرفته می‌شوند.
فایل‌هایی که نام آن‌ها به \'.s\' و \'.S\' ختم می‌شود، فایل‌های منبع زبان اسمبلی در نظر گرفته می‌شوند.
فایل‌هایی که نام آن‌ها به \'.java\' ختم می‌شود، فایل‌های منبع Java در نظر گرفته می‌شوند.
فایل‌هایی که نام آن‌ها به \'.c++\'، \'.cc\'، \'.hh\'، \'.cpp\'، \'.cxx\'، \'.hxx\'، \'.hpp\'، \'.C\' و \'.H\' ختم می‌شود، فایل‌های منبع ++C در نظر گرفته می‌شوند.
فایل‌هایی که نام آن‌ها به \'.php\'، \'.php3\' و \'.phtml\' ختم می‌شود، فایل‌های منبع PHP در نظر گرفته می‌شوند.
سایر فایل‌ها به عنوان فایل متنی در نظر گرفته می‌شوند. Gtags فایل‌های باینری را پردازش نمی‌کند.
.PP
اگر \'gtags.files\' در دایرکتوری جاری وجود داشته باشد
یا فایلی با گزینهٔ \fB-f\fP مشخص شده باشد،
فایل‌های هدف به آن محدود می‌شوند. خطوطی که با \'. \' شروع می‌شوند، توضیح (کامنت) هستند.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های زیر در دسترس هستند:
.PP
.TP
\fB--accept-dotfiles\fP
پذیرش فایل‌ها و دایرکتوری‌هایی که نام آن‌ها با نقطه شروع می‌شود.
به‌طور پیش‌فرض، \fBgtags\fP آن‌ها را نادیده می‌گیرد.
.TP
\fB-c\fP, \fB--compact\fP
ایجاد \'GTAGS\' در قالب فشرده (compact).
این گزینه بر \'GRTAGS\' تأثیری ندارد،
زیرا آن فایل همیشه در قالب فشرده ایجاد می‌شود.
.TP
\fB-C\fP, \fB--directory\fP \fIdir\fP
تغییر دایرکتوری پیش از انجام تمام کارها از جمله تحلیل پارامترها.
این گزینه در \fBGTAGS_OPTIONS\fP نادیده گرفته می‌شود.
لطفاً آن را مستقیماً در خط فرمان مشخص کنید.
.TP
\fB--config\fP[=\fIname\fP]
چاپ مقدار متغیر پیکربندی \fIname\fP.
اگر \fIname\fP مشخص نشده باشد، تمام نام‌ها و مقادیر چاپ می‌شوند.
علاوه بر این، می‌توانید به نام دایرکتوری محل نصب سیستم به عنوان متغیرهای فقط‌خواندنی رجوع کنید:
\fBbindir\fP، \fBlibdir\fP، \fBdatadir\fP، \fBlocalstatedir\fP و \fBsysconfdir\fP.
.TP
\fB-d\fP, \fB--dump\fP \fItag-file\fP
تخلیه (dump) محتوای یک فایل برچسب به صورت متنی در خروجی استاندارد.
قالب خروجی به صورت 'key<tab>data' است. این گزینه برای اشکال‌زدایی کاربرد دارد.
.TP
\fB--explain\fP
توضیح دادن نحوهٔ پردازش فایل‌ها.
.TP
\fB-f\fP, \fB--file\fP \fIfile\fP
ارائهٔ فهرستی از کاندیداهای فایل‌های هدف.
فایل‌هایی که در فهرست نباشند نادیده گرفته می‌شوند.
آرگومان \fIfile\fP می‌تواند \'-\' تعیین شود تا فهرستی از
فایل‌ها را از ورودی استاندارد بپذیرد.
نام فایل‌ها باید با خط جدید (newline) از یکدیگر جدا شوند.
برای ساخت این فهرست می‌توانید از \fBfind\fP(1) استفاده کنید که گزینه‌های غنی برای انتخاب فایل‌ها دارد.
.TP
\fB--gtagsconf\fP \fIfile\fP
تنظیم متغیر محیطی \fBGTAGSCONF\fP روی \fIfile\fP.
.TP
\fB--gtagslabel\fP \fIlabel\fP
تنظیم متغیر محیطی \fBGTAGSLABEL\fP روی \fIlabel\fP.
.TP
\fB--help\fP
چاپ پیام راهنما.
.TP
\fB-I\fP, \fB--idutils\fP
علاوه بر فایل‌های برچسب، پایگاه داده شناسه (ID) برای \fBidutils\fP(1) نیز ساخته شود.
.TP
\fB-i\fP, \fB--incremental\fP
به‌روزرسانی افزایشی (incremental) فایل‌های برچسب.
بهتر است از \fBglobal\fP(1) همراه با دستور \fB-u\fP استفاده کنید.
.TP
\fB-O\fP, \fB--objdir\fP
استفاده از دایرکتوری obj به سبک BSD به عنوان محل ذخیرهٔ فایل‌های برچسب.
اگر \fBGTAGSOBJDIRPREFIX\fP تنظیم شده باشد و دایرکتوری \'$GTAGSOBJDIRPREFIX\' وجود داشته باشد،
\fBgtags\fP دایرکتوری \'$GTAGSOBJDIRPREFIX/<current directory>\' را ایجاد کرده
و فایل‌های برچسب را درون آن می‌سازد.
اگرچه می‌توانید به جای \fBGTAGSOBJDIRPREFIX\fP از \fBMAKEOBJDIRPREFIX\fP استفاده کنید،
اما منسوخ شده است.
اگر \fIdbpath\fP مشخص شده باشد، این گزینه نادیده گرفته می‌شود.
.TP
\fB--single-update\fP \fIfile\fP
به‌روزرسانی فایل‌های برچسب برای یک فایل مشخص.
چنین در نظر گرفته می‌شود که \fIfile\fP اضافه، به‌روزرسانی یا حذف شده است،
و هیچ تغییری در فایل‌های دیگر رخ نداده است.
این گزینه به طور ضمنی گزینهٔ \fB-i\fP را فعال می‌کند.
.TP
\fB--skip-unreadable\fP
رد کردن فایل‌های غیرقابل‌خواندن.
.TP
\fB--skip-symlink\fP [=\fItype\fP]
رد کردن پیوندهای نمادین (symbolic links). اگر \fItype\fP برابر 'f' باشد، تنها پیوندهای نمادین به
فایل‌ها رد می‌شوند، و اگر 'd' باشد تنها پیوندهای نمادین به دایرکتوری‌ها رد خواهند شد.
مقدار پیش‌فرض \fItype\fP برابر با 'a' است (همهٔ پیوندهای نمادین).
.TP
\fB--sqlite3\fP
استفاده از Sqlite 3 API برای ساخت فایل‌های برچسب. به‌طور پیش‌فرض، از BSD/DB 1.85 API استفاده می‌شود.
برای استفاده از این گزینه، لازم است در مرحلهٔ ساخت، اسکریپت configure را با
\fB--with-sqlite3\fP فراخوانی کرده باشید.
.TP
\fB--statistics\fP
چاپ اطلاعات آماری.
.TP
\fB-q\fP, \fB--quiet\fP
حالت بی‌صدا.
.TP
\fB-v\fP, \fB--verbose\fP
حالت پرگو.
.TP
\fB--version\fP
نمایش شماره نسخه.
.TP
\fB-w\fP, \fB--warning\fP
چاپ پیام‌های هشدار.
.TP
\fIdbpath\fP
دایرکتوری‌ای که فایل‌های برچسب در آن تولید می‌شوند.
پیش‌فرض، دایرکتوری جاری است.
.SH "مثال‌ها (EXAMPLES)"
.nf
$ ls -F
Makefile      src/    lib/
$ gtags -v
$ global -x main
main              10 src/main.c  main (argc, argv) {
.fi
.SH "فایل‌ها (FILES)"
.TP
\'GTAGS\'
فایل برچسب برای تعاریف (definitions).
.TP
\'GRTAGS\'
فایل برچسب برای ارجاعات (references).
.TP
\'GPATH\'
فایل برچسب برای فایل‌های منبع.
.TP
\'gtags.conf\', \'$HOME/.globalrc\'
داده‌های پیکربندی GNU Global.
به \fBgtags.conf\fP(5) مراجعه کنید.
.TP
\'gtags.files\'
فهرست کاندیداهای فایل‌های هدف.
.TP
\'.notfunction\'
فهرست نمادهایی که تعریف به شمار نمی‌آیند.
اگر این فایل در دایرکتوری ریشهٔ پروژه وجود داشته باشد، \fBgtags\fP نمادهای
فهرست‌شده در این فایل را به عنوان تعریف در نظر نمی‌گیرد.
خطوطی که با ';' شروع می‌شوند، خطوط توضیح هستند.
.PP
.SH "محیط (ENVIRONMENT)"
متغیرهای محیطی زیر بر اجرای \fBgtags\fP تأثیر می‌گذارند:
.PP
.TP
\fBGTAGSCACHE\fP
اندازهٔ حافظهٔ نهان B-tree. مقدار پیش‌فرض 50000000 (بایت) است.
.TP
\fBGTAGSCONF\fP
فایل پیکربندی.
.TP
\fBGTAGSFORCECPP\fP
اگر این متغیر تنظیم شود، هر فایلی که پسوند آن \'.h\' باشد، اجباراً
توسط تجزیه‌کنندهٔ داخلی ++C پردازش می‌شود. اگر از افزونه‌های تجزیه‌کننده استفاده می‌کنید
این متغیر را تنظیم نکنید. این متغیر و تجزیه‌کنندهٔ داخلی ++C منسوخ شده‌اند.
.TP
\fBGTAGSFORCEENDBLOCK\fP
اگر این متغیر تنظیم شود، هر کاراکتر } در ستون نخست، نشان‌دهندهٔ پایان بلوک
در سطح 0 تلقی می‌شود.
.TP
\fBGTAGSLABEL\fP
برچسب پیکربندی. مقدار پیش‌فرض \'default\' است.
.TP
\fBGTAGSLOGGING\fP
اگر این متغیر تنظیم شود، \'$GTAGSLOGGING\' به عنوان مسیر فایل لاگ استفاده می‌شود. مقدار پیش‌فرضی وجود ندارد.
.TP
\fBGTAGS_COMMANDLINE\fP
این متغیر تنها از طریق قلاب (hook) قابل ارجاع است (به gtags_hook مراجعه کنید).
\fBGtags\fP خط فرمان مؤثر خود را پیش از فراخوانی قلاب در این متغیر قرار می‌دهد.
هر آرگومان با فاصله از یکدیگر جدا شده و فاصلهٔ واقعی با '%20' نمایش داده می‌شود. این متغیر فقط‌خواندنی است.
.TP
\fBGTAGS_OPTIONS\fP
مقدار این متغیر به ابتدای آرگومان‌ها اضافه می‌شود.
.TP
\fBGTAGSOBJDIR\fP
اگر این متغیر تنظیم شود، به عنوان نام objdir به سبک BSD استفاده می‌شود.
مقدار پیش‌فرض \'obj\' است.
اگرچه می‌توانید به جای \fBGTAGSOBJDIR\fP از \fBMAKEOBJDIR\fP استفاده کنید،
اما منسوخ شده است.
.TP
\fBGTAGSOBJDIRPREFIX\fP
اگر این متغیر تنظیم شود، به عنوان پیشوند objdir به سبک BSD استفاده می‌شود.
مقدار پیش‌فرض \'/usr/obj\' است.
اگرچه می‌توانید به جای \fBGTAGSOBJDIRPREFIX\fP از \fBMAKEOBJDIRPREFIX\fP استفاده کنید،
اما منسوخ شده است.
.TP
\fBTMPDIR\fP
محل مورد استفاده برای ذخیرهٔ فایل‌های موقت. مقدار پیش‌فرض \'/tmp\' است.
.SH "پیکربندی (CONFIGURATION)"
متغیرهای پیکربندی زیر بر اجرای \fBgtags\fP تأثیر می‌گذارند.
می‌توانید مقدار پیش‌فرض هر متغیر را با گزینهٔ \fB--config\fP مشاهده کنید.
.PP
.TP
gtags_parser (comma separated list)
نگاشت میان نام‌های زبان و افزونه‌های تجزیه‌کننده (plug-in parsers) را مشخص می‌کند.
هر بخش جداشده با کاما شامل یک نام زبان، یک دونقطه،
مسیر شیء اشتراکی (shared object)، و یک دونقطهٔ اختیاری همراه با نام تابع است.
اگر نام تابع مشخص نشود، مقدار 'parser' فرض می‌شود.
به عنوان یک استثنای ویژه، \fBgtags\fP مقادیر را از
چندین متغیر gtags_parser جمع‌آوری می‌کند.
برای این نگاشت‌ها، نخستین مورد منطبق انتخاب می‌شود.
.TP
gtags_hook (command line)
خط فرمانی را مشخص می‌کند که باید در ابتدای اجرای \fBgtags\fP
پس از بارگذاری فایل پیکربندی اجرا شود. می‌توانید از این قلاب برای به‌روزرسانی پویای
\'gtags.files\' استفاده کنید.
عبارت "./" در آن همیشه به معنای دایرکتوری ریشهٔ پروژه است، چرا که \fBgtags\fP همیشه در آنجا فراخوانی می‌شود.

.br
این قلاب هنگام مشخص شدن گزینه‌های زیر نادیده گرفته می‌شود:
--version، --help، --config، --dump.
.TP
icase_path (boolean)
نادیده گرفتن تمایز حروف کوچک و بزرگ در مسیر.
بررسی پسوندها تحت تأثیر این قابلیت قرار می‌گیرد.
.TP
langmap (comma separated list)
نگاشت زبان‌ها. هر نگاشت جداشده با کاما شامل
یک نام زبان، یک دونقطه، و فهرستی از پسوندهای فایل است.
می‌توانید برای فایل‌های بدون پسوند به جای پسوند، از یک الگوی glob داخل پرانتز استفاده کنید
(مانند Make:([Mm]akefile).mak.mk).
به عنوان یک استثنای ویژه، \fBgtags\fP مقادیر را از
چندین متغیر langmap جمع‌آوری می‌کند.
برای این نگاشت‌ها، نخستین مورد منطبق انتخاب می‌شود.
نگاشت پیش‌فرض عبارت است از:
.br
\'c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml\'.
.TP
skip (comma separated list)
\fBGtags\fP فایل‌ها و دایرکتوری‌هایی را که در این فهرست مشخص شده‌اند نادیده می‌گیرد.
به عنوان یک استثنای ویژه، \fBgtags\fP مقادیر را از چندین متغیر skip جمع‌آوری می‌کند.
اگر مقدار با \'/\' پایان یابد، به عنوان یک دایرکتوری در نظر گرفته شده و
\fBgtags\fP تمام فایل‌های درون آن را رد می‌کند.
این مقدار می‌تواند شامل الگوهای glob (*, ?, [...], [!...], [^...]) باشد.

.br
اگر مقدار با \'/\' شروع شود، به عنوان یک مسیر نسبی از دایرکتوری ریشهٔ پروژه در نظر گرفته می‌شود.
نمی‌توانید از الگوهای glob برای نام مسیر استفاده کنید. با این وجود، این شیوه قدیمی بوده و
توصیه نمی‌شود. در عوض، می‌توانید از گزینهٔ \fB-f\fP که با
\fBfind\fP(1) ترکیب می‌شود استفاده کنید. از آنجا که \fBfind\fP(1) گزینه‌های بسیار غنی برای انتخاب فایل‌ها دارد،
می‌توانید هر فایلی را مشخص کنید. افزون بر این، این تکنیک می‌تواند برای سایر
سیستم‌های برچسب‌گذاری مانند \fBctags\fP(1)، \fBcscope\fP(1) و غیره نیز به کار رود.

.br
فهرست نادیده‌گیری همچنین هنگامی که از \fB-f\fP یا \'gtags.files\' استفاده می‌کنید نیز مؤثر است.
.SH "مثال‌ها (EXAMPLES)"
.nf
#
# There are several ways to use Universal Ctags plug-in parser.
#
$ gtags --gtagsconf=/usr/local/share/gtags/gtags.conf --gtagslabel=universal-ctags
$ gtags --explain
or
$ export GTAGSCONF=/usr/local/share/gtags/gtags.conf
$ export GTAGSLABEL=universal-ctags
$ gtags --explain
or
# In your project
$ cp /usr/local/share/gtags/gtags.conf .
$ vi gtags.conf		# default:tc=native => default:tc=universal-ctags
$ gtags --explain
.fi
.SH "خطاها (DIAGNOSTICS)"
در صورت بروز خطا، \fBgtags\fP با مقداری غیر از 0 خارج می‌شود، و در غیر این صورت مقدار خروجی 0 خواهد بود.
.PP
توجه داشته باشید فایل‌هایی که توسط \fBgtags\fP با کد خروج غیرصفر ایجاد شده‌اند باید
فاسد و آسیب‌دیده تلقی شوند.
.SH "همچنین ببینید (SEE ALSO)"
\fBglobal\fP(1),
\fBhtags\fP(1),
\fBgtags.conf\fP(5).
.PP
سیستم برچسب‌گذاری کد منبع GNU Global
.br
(http://www.gnu.org/software/global).
.SH "گزارش باگ‌ها (BUGS)"
فایل‌های \'GTAGS\' و \'GRTAGS\' بسیار حجیم هستند.
پیش از استفاده از این دستور، فضای دیسک خود را بررسی کنید.
.PP
پشتیبانی از زبان اسمبلی با کامل بودن فاصلهٔ زیادی دارد.
این ابزار تنها ENTRY() و ALTENTRY() را از فایل منبع استخراج می‌کند.
احتمالاً تنها برای کد منبع کرنل‌های FreeBSD و Linux معتبر است.
.PP
پشتیبانی از ++C منسوخ شده است.
.PP
هیچ کنترل همزمانی (concurrency control) روی فایل‌های برچسب وجود ندارد.
.SH "نویسندگان (AUTHORS)"
Shigio YAMAGUCHI، Hideki IWAMOTO و دیگران.
.SH "تاریخچه (HISTORY)"
دستور \fBgtags\fP در FreeBSD 2.2.2 ظاهر شد.