GTAGS(1)                    General Commands Manual                   GTAGS(1)

نام (NAME)
       gtags - ایجاد فایل‌های برچسب برای global

خلاصه دستور (SYNOPSIS)
       gtags [-ciIOqvw][-C dir][-d tag-file][-f file][dbpath]

توضیحات (DESCRIPTION)
       دستور 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 مشخص شده باشد، فایل‌های هدف به آن محدود می‌شوند. خطوطی که با ´. ´ شروع
       می‌شوند، توضیح (کامنت) هستند.

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

       --accept-dotfiles
              پذیرش فایل‌ها و دایرکتوری‌هایی که نام آن‌ها با نقطه شروع می‌شود.
              به‌طور پیش‌فرض، gtags آن‌ها را نادیده می‌گیرد.

       -c, --compact
              ایجاد ´GTAGS´ در قالب فشرده (compact).  این گزینه بر ´GRTAGS´
              تأثیری ندارد، زیرا آن فایل همیشه در قالب فشرده ایجاد می‌شود.

       -C, --directory dir
              تغییر دایرکتوری پیش از انجام تمام کارها از جمله تحلیل پارامترها.
              این گزینه در GTAGS_OPTIONS نادیده گرفته می‌شود.  لطفاً آن را
              مستقیماً در خط فرمان مشخص کنید.

       --config[=name]
              چاپ مقدار متغیر پیکربندی name.  اگر name مشخص نشده باشد، تمام
              نام‌ها و مقادیر چاپ می‌شوند.  علاوه بر این، می‌توانید به نام
              دایرکتوری محل نصب سیستم به عنوان متغیرهای فقط‌خواندنی رجوع کنید:
              bindir، libdir، datadir، localstatedir و sysconfdir.

       -d, --dump tag-file
              تخلیه (dump) محتوای یک فایل برچسب به صورت متنی در خروجی
              استاندارد.  قالب خروجی به صورت 'key<tab>data' است. این گزینه
              برای اشکال‌زدایی کاربرد دارد.

       --explain
              توضیح دادن نحوهٔ پردازش فایل‌ها.

       -f, --file file
              ارائهٔ فهرستی از کاندیداهای فایل‌های هدف.  فایل‌هایی که در فهرست
              نباشند نادیده گرفته می‌شوند.  آرگومان file می‌تواند ´-´ تعیین شود
              تا فهرستی از فایل‌ها را از ورودی استاندارد بپذیرد.  نام فایل‌ها
              باید با خط جدید (newline) از یکدیگر جدا شوند.  برای ساخت این
              فهرست می‌توانید از find(1) استفاده کنید که گزینه‌های غنی برای
              انتخاب فایل‌ها دارد.

       --gtagsconf file
              تنظیم متغیر محیطی GTAGSCONF روی file.

       --gtagslabel label
              تنظیم متغیر محیطی GTAGSLABEL روی label.

       --help چاپ پیام راهنما.

       -I, --idutils
              علاوه بر فایل‌های برچسب، پایگاه داده شناسه (ID) برای idutils(1)
              نیز ساخته شود.

       -i, --incremental
              به‌روزرسانی افزایشی (incremental) فایل‌های برچسب.  بهتر است از
              global(1) همراه با دستور -u استفاده کنید.

       -O, --objdir
              استفاده از دایرکتوری obj به سبک BSD به عنوان محل ذخیرهٔ فایل‌های
              برچسب.  اگر GTAGSOBJDIRPREFIX تنظیم شده باشد و دایرکتوری
              ´$GTAGSOBJDIRPREFIX´ وجود داشته باشد، gtags دایرکتوری
              ´$GTAGSOBJDIRPREFIX/<current directory>´ را ایجاد کرده و فایل‌های
              برچسب را درون آن می‌سازد.  اگرچه می‌توانید به جای
              GTAGSOBJDIRPREFIX از MAKEOBJDIRPREFIX استفاده کنید، اما منسوخ
              شده است.  اگر dbpath مشخص شده باشد، این گزینه نادیده گرفته
              می‌شود.

       --single-update file
              به‌روزرسانی فایل‌های برچسب برای یک فایل مشخص.  چنین در نظر گرفته
              می‌شود که file اضافه، به‌روزرسانی یا حذف شده است، و هیچ تغییری در
              فایل‌های دیگر رخ نداده است.  این گزینه به طور ضمنی گزینهٔ -i را
              فعال می‌کند.

       --skip-unreadable
              رد کردن فایل‌های غیرقابل‌خواندن.

       --skip-symlink [=type]
              رد کردن پیوندهای نمادین (symbolic links). اگر type برابر 'f'
              باشد، تنها پیوندهای نمادین به فایل‌ها رد می‌شوند، و اگر 'd' باشد
              تنها پیوندهای نمادین به دایرکتوری‌ها رد خواهند شد.  مقدار پیش‌فرض
              type برابر با 'a' است (همهٔ پیوندهای نمادین).

       --sqlite3
              استفاده از Sqlite 3 API برای ساخت فایل‌های برچسب. به‌طور پیش‌فرض،
              از BSD/DB 1.85 API استفاده می‌شود.  برای استفاده از این گزینه،
              لازم است در مرحلهٔ ساخت، اسکریپت configure را با --with-sqlite3
              فراخوانی کرده باشید.

       --statistics
              چاپ اطلاعات آماری.

       -q, --quiet
              حالت بی‌صدا.

       -v, --verbose
              حالت پرگو.

       --version
              نمایش شماره نسخه.

       -w, --warning
              چاپ پیام‌های هشدار.

       dbpath دایرکتوری‌ای که فایل‌های برچسب در آن تولید می‌شوند.  پیش‌فرض،
              دایرکتوری جاری است.

مثال‌ها (EXAMPLES)
       $ ls -F
       Makefile      src/    lib/
       $ gtags -v
       $ global -x main
       main              10 src/main.c  main (argc, argv) {

فایل‌ها (FILES)
       ´GTAGS´
              فایل برچسب برای تعاریف (definitions).

       ´GRTAGS´
              فایل برچسب برای ارجاعات (references).

       ´GPATH´
              فایل برچسب برای فایل‌های منبع.

       ´gtags.conf´, ´$HOME/.globalrc´
              داده‌های پیکربندی GNU Global.  به gtags.conf(5) مراجعه کنید.

       ´gtags.files´
              فهرست کاندیداهای فایل‌های هدف.

       ´.notfunction´
              فهرست نمادهایی که تعریف به شمار نمی‌آیند.  اگر این فایل در
              دایرکتوری ریشهٔ پروژه وجود داشته باشد، gtags نمادهای فهرست‌شده در
              این فایل را به عنوان تعریف در نظر نمی‌گیرد.  خطوطی که با ';' شروع
              می‌شوند، خطوط توضیح هستند.

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

       GTAGSCACHE
              اندازهٔ حافظهٔ نهان B-tree. مقدار پیش‌فرض 50000000 (بایت) است.

       GTAGSCONF
              فایل پیکربندی.

       GTAGSFORCECPP
              اگر این متغیر تنظیم شود، هر فایلی که پسوند آن ´.h´ باشد، اجباراً
              توسط تجزیه‌کنندهٔ داخلی ++C پردازش می‌شود. اگر از افزونه‌های
              تجزیه‌کننده استفاده می‌کنید این متغیر را تنظیم نکنید. این متغیر و
              تجزیه‌کنندهٔ داخلی ++C منسوخ شده‌اند.

       GTAGSFORCEENDBLOCK
              اگر این متغیر تنظیم شود، هر کاراکتر } در ستون نخست، نشان‌دهندهٔ
              پایان بلوک در سطح 0 تلقی می‌شود.

       GTAGSLABEL
              برچسب پیکربندی. مقدار پیش‌فرض ´default´ است.

       GTAGSLOGGING
              اگر این متغیر تنظیم شود، ´$GTAGSLOGGING´ به عنوان مسیر فایل لاگ
              استفاده می‌شود. مقدار پیش‌فرضی وجود ندارد.

       GTAGS_COMMANDLINE
              این متغیر تنها از طریق قلاب (hook) قابل ارجاع است (به gtags_hook
              مراجعه کنید).  Gtags خط فرمان مؤثر خود را پیش از فراخوانی قلاب
              در این متغیر قرار می‌دهد.  هر آرگومان با فاصله از یکدیگر جدا شده
              و فاصلهٔ واقعی با '%20' نمایش داده می‌شود. این متغیر فقط‌خواندنی
              است.

       GTAGS_OPTIONS
              مقدار این متغیر به ابتدای آرگومان‌ها اضافه می‌شود.

       GTAGSOBJDIR
              اگر این متغیر تنظیم شود، به عنوان نام objdir به سبک BSD استفاده
              می‌شود.  مقدار پیش‌فرض ´obj´ است.  اگرچه می‌توانید به جای
              GTAGSOBJDIR از MAKEOBJDIR استفاده کنید، اما منسوخ شده است.

       GTAGSOBJDIRPREFIX
              اگر این متغیر تنظیم شود، به عنوان پیشوند objdir به سبک BSD
              استفاده می‌شود.  مقدار پیش‌فرض ´/usr/obj´ است.  اگرچه می‌توانید به
              جای GTAGSOBJDIRPREFIX از MAKEOBJDIRPREFIX استفاده کنید، اما
              منسوخ شده است.

       TMPDIR محل مورد استفاده برای ذخیرهٔ فایل‌های موقت. مقدار پیش‌فرض ´/tmp´
              است.

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

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

       gtags_hook (command line)
              خط فرمانی را مشخص می‌کند که باید در ابتدای اجرای gtags پس از
              بارگذاری فایل پیکربندی اجرا شود. می‌توانید از این قلاب برای
              به‌روزرسانی پویای ´gtags.files´ استفاده کنید.  عبارت "./" در آن
              همیشه به معنای دایرکتوری ریشهٔ پروژه است، چرا که gtags همیشه در
              آنجا فراخوانی می‌شود.

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

       icase_path (boolean)
              نادیده گرفتن تمایز حروف کوچک و بزرگ در مسیر.  بررسی پسوندها تحت
              تأثیر این قابلیت قرار می‌گیرد.

       langmap (comma separated list)
              نگاشت زبان‌ها. هر نگاشت جداشده با کاما شامل یک نام زبان، یک
              دونقطه، و فهرستی از پسوندهای فایل است.  می‌توانید برای فایل‌های
              بدون پسوند به جای پسوند، از یک الگوی 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´.

       skip (comma separated list)
              Gtags فایل‌ها و دایرکتوری‌هایی را که در این فهرست مشخص شده‌اند
              نادیده می‌گیرد.  به عنوان یک استثنای ویژه، gtags مقادیر را از
              چندین متغیر skip جمع‌آوری می‌کند.  اگر مقدار با ´/´ پایان یابد، به
              عنوان یک دایرکتوری در نظر گرفته شده و gtags تمام فایل‌های درون آن
              را رد می‌کند.  این مقدار می‌تواند شامل الگوهای glob (*, ?, [...],
              [!...], [^...]) باشد.

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

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

مثال‌ها (EXAMPLES)
       #
       # 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

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

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

همچنین ببینید (SEE ALSO)
       global(1), htags(1), gtags.conf(5).

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

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

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

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

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

نویسندگان (AUTHORS)
       Shigio YAMAGUCHI، Hideki IWAMOTO و دیگران.

تاریخچه (HISTORY)
       دستور gtags در FreeBSD 2.2.2 ظاهر شد.

GNU Project                      February 2021                        GTAGS(1)