نام (NAME)

cscope - بررسی تعاملی برنامه‌های C

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

cscope [-bCcdehkLlqRTUuVvX] [-Fsymfile] [-freffile] [-Iincdir] [-inamefile] [-0123456789pattern] [-pn] [-sdir] [files]

توضیحات (DESCRIPTION)

ابزار cscope یک ابزار تعاملی و مبتنی بر صفحه ترمینال است که به کاربر امکان می‌دهد کدهای منبع C را برای یافتن بخش‌ها و عناصر مشخص پیمایش کند.

به طور پیش‌فرض، cscope فایل‌های منبع C (.c و .h)، لکس (.l) و یاک (.y) را در دایرکتوری جاری بررسی می‌کند. همچنین می‌توان cscope را برای فایل‌های منبع مشخص‌شده در خط فرمان فراخوانی کرد. در هر دو حالت، cscope دایرکتوری‌های استاندارد را برای فایل‌های #include که در دایرکتوری جاری پیدا نمی‌شوند جستجو می‌کند. cscope از یک جدول ارجاع متقابل نمادها (symbol cross-reference) که به طور پیش‌فرض cscope.out نامیده می‌شود، برای مکان‌یابی توابع، فراخوانی‌های توابع، ماکروها، متغیرها و نمادهای پیش‌پردازنده در فایل‌ها استفاده می‌کند.

ابزار cscope پایگاه ارجاع متقابل نمادها را در اولین باری که روی فایل‌های منبع برنامه اجرا می‌شود می‌سازد. در فراخوانی‌های بعدی، cscope ارجاع متقابل را تنها زمانی بازسازی می‌کند که یک فایل منبع تغییر کرده باشد یا لیست فایل‌های منبع تفاوت کرده باشد. هنگامی که ارجاع متقابل بازسازی می‌شود، داده‌های فایل‌های تغییرنیافته از ارجاع متقابل قدیمی کپی می‌شوند که بازسازی را بسیار سریع‌تر از ساخت اولیه می‌کند.

گزینه‌ها (OPTIONS)

برخی از آرگومان‌های خط فرمان تنها می‌توانند به عنوان یگانه آرگومان در اجرای cscope ظاهر شوند. این گزینه‌ها باعث می‌شوند برنامه صرفاً خروجی خاصی را چاپ کرده و فوراً خارج شود:

-h: نمایش راهنمای کامل نحوه استفاده.
-V: چاپ شماره نسخه cscope در اولین سطر صفحه نمایش.
--help: مشابه -h
--version: مشابه -V

گزینه‌های زیر می‌توانند در هر ترکیبی ظاهر شوند:

-b: صرفاً ساخت جدول ارجاع متقابل (بدون ورود به رابط تعاملی).
-C: نادیده گرفتن بزرگی و کوچکی حروف در هنگام جستجو.
-c: استفاده تنها از کاراکترهای اسکی در فایل ارجاع متقابل، یعنی داده‌ها فشرده نشوند.
-d: عدم به‌روزرسانی جدول ارجاع متقابل.
-e: عدم نمایش اعلان کلید <Ctrl>-e بین فایل‌ها.
-Fsymfile: خواندن خطوط ارجاع نمادها از symfile. (فایل ارجاع نماد توسط < و >> ایجاد می‌شود و با استفاده از دستور < نیز قابل خواندن است).
-freffile: استفاده از reffile به عنوان نام فایل ارجاع متقابل به جای پیش‌فرض "cscope.out".
-Iincdir: جستجو در دایرکتوری incdir (پیش از جستجو در $INCDIR که محل استاندارد فایل‌های سرآیند و معمولاً /usr/include است) برای فایل‌های #include که نام آن‌ها با "/" شروع نمی‌شود و در خط فرمان یا در namefile تعیین نشده‌اند. دایرکتوری incdir علاوه بر پوشه جاری و لیست استاندارد جستجو می‌شود.
-inamefile: پیمایش تمام فایل‌های منبعی که نام آن‌ها در namefile فهرست شده است (نام‌های جداشده با فاصله، تب یا خط جدید) به جای فایل پیش‌فرض cscope.files. اگر نام فایل حاوی فاصله است باید درون دو گیومه قرار گیرد.
-k: حالت هسته ("Kernel Mode")؛ خاموش کردن استفاده از مسیر پیش‌فرض include (معمولاً /usr/include) در زمان ساخت پایگاه داده، زیرا درخت منبع هسته عموماً از آن استفاده نمی‌کند.
-L: انجام جستجوی تکی با خروجی خط‌محور زمانی که همراه با گزینه -num pattern استفاده شود.
-l: رابط خط‌محور (Line-oriented interface).
-[0-9]pattern: رفتن به فیلد ورودی num (شمارش از 0) و یافتن pattern.
-Ppath: افزودن پیشوند path به مسیرهای نسبی فایل‌ها در فایل ارجاع متقابل از پیش ساخته‌شده. این گزینه تنها همراه با گزینه -d معتبر است.
-pn: نمایش آخرین n بخش مسیر فایل به جای پیش‌فرض (1). استفاده از 0 باعث عدم نمایش نام فایل می‌شود.
-q: فعال‌سازی جستجوی سریع نمادها از طریق نمایه معکوس (inverted index). این گزینه موجب ایجاد دو فایل اضافی ("cscope.in.out" و "cscope.po.out") در کنار پایگاه‌داده اصلی می‌شود که سرعت جستجو را در پروژه‌های بزرگ به میزان چشمگیری افزایش می‌دهد.
-R: جستجوی بازگشتی زیرپوشه‌ها برای یافتن فایل‌های منبع.
-sdir: جستجو در dir برای فایل‌های منبع اضافی.
-T: استفاده تنها از هشت کاراکتر نخست برای تطبیق با نمادهای C.
-U: بررسی برچسب زمانی فایل‌ها. برچسب زمانی پایگاه داده را حتی اگر فایلی تغییر نکرده باشد به‌روز می‌کند.
-u: ساخت بدون قید و شرط فایل ارجاع متقابل (با فرض اینکه تمام فایل‌ها تغییر کرده‌اند).
-v: حالت پرگو در حالت خط‌محور؛ نمایش گزارش پیشرفت هنگام ساخت پایگاه داده و جستجوها.
-X: حذف فایل ارجاع cscope و نمایه‌های معکوس در زمان خروج.
files: لیستی از نام فایل‌ها برای پردازش.

گزینه‌های -I، -c، -k، -p، -q و -T می‌توانند درون فایل cscope.files نیز قرار گیرند.

درخواست جستجوی اولیه (Requesting the initial search)

پس از آماده شدن ارجاع متقابل، cscope این منو را نمایش می‌دهد:

Find this C symbol:

Find this function definition:
Find functions called by this function:
Find functions calling this function:
Find this text string:
Change this text string:
Find this egrep pattern:
Find this file:
Find files #including this file:
Find assignments to this symbol:

کلیدهای <Up> یا <Down> را برای حرکت به فیلد ورودی دلخواه فشار دهید، متن مورد نظر برای جستجو را تایپ کرده و سپس کلید <Return> را بفشارید.

ارسال درخواست‌های بعدی (Issuing subsequent requests)

در صورت موفقیت جستجو، هر یک از این دستورات تک‌کاراکتری می‌توانند استفاده شوند:

0-9a-zA-Z: ویرایش فایل ارجاع داده‌شده با شماره خط مشخص.
<Space>: نمایش مجموعه بعدی خطوط منطبق.
<Tab>: جابجایی بین منو و لیست خطوط منطبق.
<Up>: حرکت به گزینه قبلی منو یا حرکت به خط منطبق قبلی.
<Down>: حرکت به گزینه بعدی منو یا حرکت به خط منطبق بعدی.
+: نمایش مجموعه بعدی خطوط منطبق.
-: نمایش مجموعه قبلی خطوط منطبق.
^e: ویرایش فایل‌های نمایش‌داده‌شده به ترتیب.
>: نوشتن لیست خطوط نمایش‌داده‌شده در یک فایل.
>>: الحاق لیست خطوط نمایش‌داده‌شده به یک فایل.
<: خواندن خطوط از یک فایل با قالب ارجاع نماد (ایجادشده با > یا >>)، همانند گزینه -F.
^: فیلتر کردن تمام خطوط از طریق یک دستور پوسته و نمایش خطوط حاصل به جای خطوط قبلی.
|: هدایت (pipe) تمام خطوط به یک دستور پوسته و نمایش آن‌ها بدون تغییر.

در هر زمان این دستورات تک‌کاراکتری نیز قابل استفاده هستند:

<Return>: حرکت به فیلد ورودی بعدی.
^n: حرکت به فیلد ورودی بعدی.
^p: حرکت به فیلد ورودی قبلی.
^y: جستجو با آخرین متن تایپ‌شده.
^b: حرکت به فیلد ورودی و الگوی جستجوی قبلی.
^f: حرکت به فیلد ورودی و الگوی جستجوی بعدی.
^c: تغییر حالت نادیده‌گرفتن/حساسیت به بزرگی و کوچکی حروف در جستجو.
^r: بازسازی پایگاه ارجاع متقابل.
!: اجرای یک پوسته تعاملی (تایپ ^d برای بازگشت به cscope).
^l: بازتولید و رسم مجدد صفحه نمایش.
?: نمایش اطلاعات راهنما درباره دستورات cscope.
^d: خروج از cscope.

نکته: اگر کاراکتر اول متن مورد جستجو با یکی از دستورات بالا همخوانی دارد، ابتدا یک بک‌اسلش ( تایپ کنید تا اسکیپ شود.

جایگزینی متن جدید به جای متن قدیمی

پس از وارد کردن متنی که باید تغییر یابد، cscope متن جدید را درخواست می‌کند و سپس خطوط حاوی متن قدیمی را نمایش می‌دهد. خطوط مورد نظر برای تغییر را با این دستورات انتخاب کنید:

0-9a-zA-Z: علامت‌گذاری یا لغو علامت خط مورد تغییر.
*: علامت‌گذاری یا لغو علامت تمام خطوط نمایش‌داده‌شده.
<Space>: نمایش مجموعه بعدی خطوط.
+: نمایش مجموعه بعدی خطوط.
-: نمایش مجموعه قبلی خطوط.
a: علامت‌گذاری یا لغو علامت تمام خطوط مورد نظر برای تغییر.
^d: تغییر خطوط علامت‌گذاری‌شده و خروج.
<Esc>: خروج بدون تغییر خطوط علامت‌گذاری‌شده.
!: اجرای یک پوسته تعاملی (تایپ ^d برای بازگشت به cscope).
^l: بازتولید و رسم مجدد صفحه نمایش.
?: ارائه اطلاعات راهنما درباره دستورات cscope.
کلیدهای ویژه: اگر ترمینال شما کلیدهای جهتی دارد که در vi کار می‌کنند، می‌توانید از آن‌ها برای حرکت در فیلدهای ورودی استفاده کنید. کلیدهای <CLEAR>، <NEXT> یا <PREV> به ترتیب مانند دستورات ^l، + و - عمل می‌کنند.

رابط خط‌محور (Line-Oriented interface)

گزینه -l امکان استفاده از cscope را در جایی که رابط گرافیکی یا تمام‌صفحه مناسب نیست (مثلاً از داخل برنامه‌ای دیگر) فراهم می‌کند.

هنگامی که cscope آماده باشد با << اعلان می‌دهد که ورودی را با شماره فیلد (شروع از 0) به همراه الگوی جستجو دریافت کند؛ برای مثال "lmain" تعریف تابع main را می‌یابد.

اگر تنها یک جستجوی منفرد می‌خواهید، به جای گزینه -l از گزینه‌های -L و -num pattern استفاده کنید تا اعلان << ظاهر نشود.

برای گزینه -l، برنامه تعداد خطوط ارجاع را چاپ می‌کند: cscope: 2 lines

به ازای هر ارجاع یافت‌شده، cscope خطی متشکل از نام فایل، نام تابع، شماره خط و متن خط چاپ می‌کند که با فاصله از هم جدا شده‌اند، مانند: main.c main 161 main(argc, argv)

توجه داشته باشید که برخلاف رابط تمام‌صفحه، ویرایشگر متن برای نمایش ارجاع تکی فراخوانی نمی‌شود.

می‌توانید از دستور c برای تغییر حساسیت به بزرگی و کوچکی حروف استفاده کنید.

می‌توانید از دستور r برای بازسازی پایگاه‌داده استفاده کنید.

برنامه cscope در زمان تشخیص پایان فایل (EOF) یا با دریافت کاراکتر "^d" یا "q" در ابتدای خط ورودی خاتمه می‌یابد.

متغیرهای محیطی (ENVIRONMENT VARIABLES)

CSCOPE_EDITOR: جایگزین متغیرهای EDITOR و VIEWER می‌شود.
CSCOPE_LINEFLAG: قالب فلگ شماره سطر برای ویرایشگر شما. به طور پیش‌فرض cscope ویرایشگر را به صورت "editor +N file" فراخوانی می‌کند که N شماره سطر است. برای قالب متفاوت می‌توان از %s به عنوان جایگزین استفاده کرد، مثلاً "-#%s".
CSCOPE_LINEFLAG_AFTER_FILE: اگر ویرایشگر شما نیاز دارد گزینه شماره خط پس از نام فایل بیاید، این متغیر را برابر "yes" قرار دهید.
EDITOR: ویرایشگر متن ترجیحی که پیش‌فرض آن vi است.
HOME: دایرکتوری خانگی کاربر.
INCLUDEDIRS: لیست دایرکتوری‌های جداشده با دو نقطه برای جستجوی فایل‌های #include.
SHELL: پوسته ترجیحی که پیش‌فرض آن sh است.
SOURCEDIRS: لیست دایرکتوری‌های جداشده با دو نقطه برای جستجوی فایل‌های منبع اضافی.
TERM: نوع ترمینال.
TERMINFO: مسیر کامل دایرکتوری اطلاعات ترمینال terminfo.
TMPDIR: دایرکتوری فایل‌های موقت که پیش‌فرض آن /var/tmp است.
VIEWER: برنامه ترجیحی نمایش فایل (مانند less) که اولویت بالاتری از EDITOR دارد.
VPATH: لیست دایرکتوری‌های جداشده با دونقطه برای مسیر جستجوی فایل‌های منبع.

فایل‌ها (FILES)

cscope.files: فایل پیش‌فرض شامل گزینه‌های -I، -p، -q، -T و فهرست فایل‌های منبع.
cscope.out: فایل ارجاع متقابل نمادها که در صورت عدم امکان ایجاد در پوشه جاری، در دایرکتوری خانگی ذخیره می‌شود.
cscope.in.out
cscope.po.out: فایل‌های پیش‌فرض حاوی نمایه معکوس برای جستجوی سریع نمادها (گزینه -q).
INCDIR: دایرکتوری استاندارد برای فایل‌های #include (معمولاً /usr/include).

نکات و تذکرات (Notices)

ابزار cscope تعاریف توابع را با الگوی زیر شناسایی می‌کند:

fname blank ( args ) white arg_decs white {
که در آن:: fname نام تابع است
blank: صفر یا چند فاصله، تب، فرم‌فید بدون خط جدید است
args: هر رشته‌ای که شامل گیومه یا خط جدید نباشد
white: صفر یا چند فاصله، تب، فرم‌فید یا خط جدید است
arg_decs: صفر یا چند اعلان آرگومان است

ضرورتی ندارد اعلان تابع از ابتدای خط شروع شود. نوع برگشتی می‌تواند قبل از نام تابع باشد. تعاریف تابعی که از این الگو پیروی نکنند توسط cscope شناسایی نمی‌شوند.

ستون "Function" در خروجی جستجو برای گزینه Find functions called by this function تنها اولین تابع فراخوانی‌شده در خط را نمایش می‌دهد.

گاهی ممکن است تعریف یا فراخوانی یک تابع به دلیل وجود آکولادها درون دستورات #if شناسایی نشود. مشابهاً استفاده از یک متغیر ممکن است به اشتباه به عنوان تعریف آن شناخته شود.

یک نام typedef پیش از یک عبارت پیش‌پردازنده ممکن است به اشتباه به عنوان یک تعریف سراسری شناخته شود. عبارات پیش‌پردازنده همچنین می‌توانند مانع از تشخیص یک تعریف سراسری شوند.

اعلان یک تابع درون یک تابع دیگر به اشتباه به عنوان فراخوانی تابع شناسایی می‌شود.

ابزار cscope کلاس‌های C++ را با جستجوی کلمه کلیدی class شناسایی می‌کند، اما ساختار struct را به عنوان کلاس تشخیص نمی‌دهد و تعاریف توابع عضو درون ساختار را نمی‌شناسد. همچنین تعاریف توابع عملگر (operator) و توابع دارای آرگومان اشاره‌گر به تابع را شناسایی نمی‌کند.