GTAGS(1) General Commands Manual GTAGS(1)

gtags - ایجاد فایل‌های برچسب برای global

gtags [-ciIOqvw][-C dir][-d tag-file][-f file][dbpath]

دستور gtags برای ایجاد فایل‌های برچسب (tag) برای global(1) به کار می‌رود.

Gtags به‌طور بازگشتی فایل‌های منبع موجود در دایرکتوری جاری را جمع‌آوری کرده، نمادها را استخراج می‌کند و داده‌های ارجاع متقابل (cross-reference) را درون فایل‌های برچسب (´GTAGS´، ´GRTAGS´ و ´GPATH´) می‌نویسد.

به‌طور پیش‌فرض، gtags فایل‌های منبع 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 فایل‌های باینری را پردازش نمی‌کند.

اگر ´gtags.files´ در دایرکتوری جاری وجود داشته باشد یا فایلی با گزینهٔ -f مشخص شده باشد، فایل‌های هدف به آن محدود می‌شوند. خطوطی که با ´. ´ شروع می‌شوند، توضیح (کامنت) هستند.

گزینه‌های زیر در دسترس هستند:

پذیرش فایل‌ها و دایرکتوری‌هایی که نام آن‌ها با نقطه شروع می‌شود. به‌طور پیش‌فرض، gtags آن‌ها را نادیده می‌گیرد.
ایجاد ´GTAGS´ در قالب فشرده (compact). این گزینه بر ´GRTAGS´ تأثیری ندارد، زیرا آن فایل همیشه در قالب فشرده ایجاد می‌شود.
تغییر دایرکتوری پیش از انجام تمام کارها از جمله تحلیل پارامترها. این گزینه در GTAGS_OPTIONS نادیده گرفته می‌شود. لطفاً آن را مستقیماً در خط فرمان مشخص کنید.
چاپ مقدار متغیر پیکربندی name. اگر name مشخص نشده باشد، تمام نام‌ها و مقادیر چاپ می‌شوند. علاوه بر این، می‌توانید به نام دایرکتوری محل نصب سیستم به عنوان متغیرهای فقط‌خواندنی رجوع کنید: bindir، libdir، datadir، localstatedir و sysconfdir.
تخلیه (dump) محتوای یک فایل برچسب به صورت متنی در خروجی استاندارد. قالب خروجی به صورت 'key<tab>data' است. این گزینه برای اشکال‌زدایی کاربرد دارد.
توضیح دادن نحوهٔ پردازش فایل‌ها.
ارائهٔ فهرستی از کاندیداهای فایل‌های هدف. فایل‌هایی که در فهرست نباشند نادیده گرفته می‌شوند. آرگومان file می‌تواند ´-´ تعیین شود تا فهرستی از فایل‌ها را از ورودی استاندارد بپذیرد. نام فایل‌ها باید با خط جدید (newline) از یکدیگر جدا شوند. برای ساخت این فهرست می‌توانید از find(1) استفاده کنید که گزینه‌های غنی برای انتخاب فایل‌ها دارد.
تنظیم متغیر محیطی GTAGSCONF روی file.
تنظیم متغیر محیطی GTAGSLABEL روی label.
چاپ پیام راهنما.
علاوه بر فایل‌های برچسب، پایگاه داده شناسه (ID) برای idutils(1) نیز ساخته شود.
به‌روزرسانی افزایشی (incremental) فایل‌های برچسب. بهتر است از global(1) همراه با دستور -u استفاده کنید.
استفاده از دایرکتوری obj به سبک BSD به عنوان محل ذخیرهٔ فایل‌های برچسب. اگر GTAGSOBJDIRPREFIX تنظیم شده باشد و دایرکتوری ´$GTAGSOBJDIRPREFIX´ وجود داشته باشد، gtags دایرکتوری ´$GTAGSOBJDIRPREFIX/<current directory>´ را ایجاد کرده و فایل‌های برچسب را درون آن می‌سازد. اگرچه می‌توانید به جای GTAGSOBJDIRPREFIX از MAKEOBJDIRPREFIX استفاده کنید، اما منسوخ شده است. اگر dbpath مشخص شده باشد، این گزینه نادیده گرفته می‌شود.
به‌روزرسانی فایل‌های برچسب برای یک فایل مشخص. چنین در نظر گرفته می‌شود که file اضافه، به‌روزرسانی یا حذف شده است، و هیچ تغییری در فایل‌های دیگر رخ نداده است. این گزینه به طور ضمنی گزینهٔ -i را فعال می‌کند.
رد کردن فایل‌های غیرقابل‌خواندن.
رد کردن پیوندهای نمادین (symbolic links). اگر type برابر 'f' باشد، تنها پیوندهای نمادین به فایل‌ها رد می‌شوند، و اگر 'd' باشد تنها پیوندهای نمادین به دایرکتوری‌ها رد خواهند شد. مقدار پیش‌فرض type برابر با 'a' است (همهٔ پیوندهای نمادین).
استفاده از Sqlite 3 API برای ساخت فایل‌های برچسب. به‌طور پیش‌فرض، از BSD/DB 1.85 API استفاده می‌شود. برای استفاده از این گزینه، لازم است در مرحلهٔ ساخت، اسکریپت configure را با --with-sqlite3 فراخوانی کرده باشید.
چاپ اطلاعات آماری.
حالت بی‌صدا.
حالت پرگو.
نمایش شماره نسخه.
چاپ پیام‌های هشدار.
دایرکتوری‌ای که فایل‌های برچسب در آن تولید می‌شوند. پیش‌فرض، دایرکتوری جاری است.

$ ls -F
Makefile      src/    lib/
$ gtags -v
$ global -x main
main              10 src/main.c  main (argc, argv) {

´GTAGS´
فایل برچسب برای تعاریف (definitions).
´GRTAGS´
فایل برچسب برای ارجاعات (references).
´GPATH´
فایل برچسب برای فایل‌های منبع.
´gtags.conf´, ´$HOME/.globalrc´
داده‌های پیکربندی GNU Global. به gtags.conf(5) مراجعه کنید.
´gtags.files´
فهرست کاندیداهای فایل‌های هدف.
´.notfunction´
فهرست نمادهایی که تعریف به شمار نمی‌آیند. اگر این فایل در دایرکتوری ریشهٔ پروژه وجود داشته باشد، gtags نمادهای فهرست‌شده در این فایل را به عنوان تعریف در نظر نمی‌گیرد. خطوطی که با ';' شروع می‌شوند، خطوط توضیح هستند.

متغیرهای محیطی زیر بر اجرای gtags تأثیر می‌گذارند:

اندازهٔ حافظهٔ نهان B-tree. مقدار پیش‌فرض 50000000 (بایت) است.
فایل پیکربندی.
اگر این متغیر تنظیم شود، هر فایلی که پسوند آن ´.h´ باشد، اجباراً توسط تجزیه‌کنندهٔ داخلی ++C پردازش می‌شود. اگر از افزونه‌های تجزیه‌کننده استفاده می‌کنید این متغیر را تنظیم نکنید. این متغیر و تجزیه‌کنندهٔ داخلی ++C منسوخ شده‌اند.
اگر این متغیر تنظیم شود، هر کاراکتر } در ستون نخست، نشان‌دهندهٔ پایان بلوک در سطح 0 تلقی می‌شود.
برچسب پیکربندی. مقدار پیش‌فرض ´default´ است.
اگر این متغیر تنظیم شود، ´$GTAGSLOGGING´ به عنوان مسیر فایل لاگ استفاده می‌شود. مقدار پیش‌فرضی وجود ندارد.
این متغیر تنها از طریق قلاب (hook) قابل ارجاع است (به gtags_hook مراجعه کنید). Gtags خط فرمان مؤثر خود را پیش از فراخوانی قلاب در این متغیر قرار می‌دهد. هر آرگومان با فاصله از یکدیگر جدا شده و فاصلهٔ واقعی با '%20' نمایش داده می‌شود. این متغیر فقط‌خواندنی است.
مقدار این متغیر به ابتدای آرگومان‌ها اضافه می‌شود.
اگر این متغیر تنظیم شود، به عنوان نام objdir به سبک BSD استفاده می‌شود. مقدار پیش‌فرض ´obj´ است. اگرچه می‌توانید به جای GTAGSOBJDIR از MAKEOBJDIR استفاده کنید، اما منسوخ شده است.
اگر این متغیر تنظیم شود، به عنوان پیشوند objdir به سبک BSD استفاده می‌شود. مقدار پیش‌فرض ´/usr/obj´ است. اگرچه می‌توانید به جای GTAGSOBJDIRPREFIX از MAKEOBJDIRPREFIX استفاده کنید، اما منسوخ شده است.
محل مورد استفاده برای ذخیرهٔ فایل‌های موقت. مقدار پیش‌فرض ´/tmp´ است.

متغیرهای پیکربندی زیر بر اجرای gtags تأثیر می‌گذارند. می‌توانید مقدار پیش‌فرض هر متغیر را با گزینهٔ --config مشاهده کنید.

نگاشت میان نام‌های زبان و افزونه‌های تجزیه‌کننده (plug-in parsers) را مشخص می‌کند. هر بخش جداشده با کاما شامل یک نام زبان، یک دونقطه، مسیر شیء اشتراکی (shared object)، و یک دونقطهٔ اختیاری همراه با نام تابع است. اگر نام تابع مشخص نشود، مقدار 'parser' فرض می‌شود. به عنوان یک استثنای ویژه، gtags مقادیر را از چندین متغیر gtags_parser جمع‌آوری می‌کند. برای این نگاشت‌ها، نخستین مورد منطبق انتخاب می‌شود.
خط فرمانی را مشخص می‌کند که باید در ابتدای اجرای gtags پس از بارگذاری فایل پیکربندی اجرا شود. می‌توانید از این قلاب برای به‌روزرسانی پویای ´gtags.files´ استفاده کنید. عبارت "./" در آن همیشه به معنای دایرکتوری ریشهٔ پروژه است، چرا که gtags همیشه در آنجا فراخوانی می‌شود.

این قلاب هنگام مشخص شدن گزینه‌های زیر نادیده گرفته می‌شود: --version، --help، --config، --dump.

نادیده گرفتن تمایز حروف کوچک و بزرگ در مسیر. بررسی پسوندها تحت تأثیر این قابلیت قرار می‌گیرد.
نگاشت زبان‌ها. هر نگاشت جداشده با کاما شامل یک نام زبان، یک دونقطه، و فهرستی از پسوندهای فایل است. می‌توانید برای فایل‌های بدون پسوند به جای پسوند، از یک الگوی glob داخل پرانتز استفاده کنید (مانند Make:([Mm]akefile).mak.mk). به عنوان یک استثنای ویژه، gtags مقادیر را از چندین متغیر langmap جمع‌آوری می‌کند. برای این نگاشت‌ها، نخستین مورد منطبق انتخاب می‌شود. نگاشت پیش‌فرض عبارت است از:
´c:.c.h,yacc:.y,asm:.s.S,java:.java,cpp:.c++.cc.hh.cpp.cxx.hxx.hpp.C.H,php:.php.php3.phtml´.
Gtags فایل‌ها و دایرکتوری‌هایی را که در این فهرست مشخص شده‌اند نادیده می‌گیرد. به عنوان یک استثنای ویژه، gtags مقادیر را از چندین متغیر skip جمع‌آوری می‌کند. اگر مقدار با ´/´ پایان یابد، به عنوان یک دایرکتوری در نظر گرفته شده و gtags تمام فایل‌های درون آن را رد می‌کند. این مقدار می‌تواند شامل الگوهای glob (*, ?, [...], [!...], [^...]) باشد.

اگر مقدار با ´/´ شروع شود، به عنوان یک مسیر نسبی از دایرکتوری ریشهٔ پروژه در نظر گرفته می‌شود. نمی‌توانید از الگوهای glob برای نام مسیر استفاده کنید. با این وجود، این شیوه قدیمی بوده و توصیه نمی‌شود. در عوض، می‌توانید از گزینهٔ -f که با find(1) ترکیب می‌شود استفاده کنید. از آنجا که find(1) گزینه‌های بسیار غنی برای انتخاب فایل‌ها دارد، می‌توانید هر فایلی را مشخص کنید. افزون بر این، این تکنیک می‌تواند برای سایر سیستم‌های برچسب‌گذاری مانند ctags(1)، cscope(1) و غیره نیز به کار رود.

فهرست نادیده‌گیری همچنین هنگامی که از -f یا ´gtags.files´ استفاده می‌کنید نیز مؤثر است.

#
# 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

در صورت بروز خطا، gtags با مقداری غیر از 0 خارج می‌شود، و در غیر این صورت مقدار خروجی 0 خواهد بود.

توجه داشته باشید فایل‌هایی که توسط gtags با کد خروج غیرصفر ایجاد شده‌اند باید فاسد و آسیب‌دیده تلقی شوند.

global(1), htags(1), gtags.conf(5).

سیستم برچسب‌گذاری کد منبع GNU Global
(http://www.gnu.org/software/global).

فایل‌های ´GTAGS´ و ´GRTAGS´ بسیار حجیم هستند. پیش از استفاده از این دستور، فضای دیسک خود را بررسی کنید.

پشتیبانی از زبان اسمبلی با کامل بودن فاصلهٔ زیادی دارد. این ابزار تنها ENTRY() و ALTENTRY() را از فایل منبع استخراج می‌کند. احتمالاً تنها برای کد منبع کرنل‌های FreeBSD و Linux معتبر است.

پشتیبانی از ++C منسوخ شده است.

هیچ کنترل همزمانی (concurrency control) روی فایل‌های برچسب وجود ندارد.

Shigio YAMAGUCHI، Hideki IWAMOTO و دیگران.

دستور gtags در FreeBSD 2.2.2 ظاهر شد.

February 2021 GNU Project