نام (NAME)

jnativescan - ابزار تحلیل ایستا برای پویش یک یا چند فایل jar جهت یافتن موارد استفاده از قابلیت‌های محلی (native)، مانند فراخوانی متدهای محدودشده یا اعلان متدهای native.

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

jnativescan [گزینه‌ها]

گزینه‌ها: بخش گزینه‌های دستور jnativescan را مشاهده کنید.

توضیحات (DESCRIPTION)

ابزار jnativescan یک ابزار تحلیل ایستا ارائه‌شده توسط JDK است که یک فایل JAR را برای یافتن موارد استفاده از قابلیت‌های محلی (native)، از قبیل فراخوانی متدهای محدودشده یا اعلان‌های متد native پویش می‌کند.

ابزار jnativescan پیکربندی مسیر کلاس (class path) زمان اجرا و مسیر ماژول (module path)، مجموعه‌ای از ماژول‌های ریشه و یک نسخه انتشار هدف را دریافت می‌کند. این ابزار فایل‌های jar موجود در مسیرهای کلاس و ماژول را پویش کرده و استفاده از قابلیت‌های محلی را در ساختاری درختی (که کلاس‌ها و متدهای فراخواننده را نیز مشخص می‌کند) گزارش می‌دهد، یا در صورت تعیین سوییچ --print-native-access، آن‌ها را به‌صورت فهرستی از نام‌های ماژول‌ها نمایش می‌دهد.

گزینه‌ها (OPTIONS)

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

--class-path path: برای تعیین فهرستی از مسیرهای اشاره‌کننده به فایل‌های jar جهت پویش به کار می‌رود.

تمام فایل‌های jar مشخص‌شده از طریق این فهرست پویش خواهند شد. اگر یک فایل jar در مانیفست خود حاوی ویژگی Class-Path باشد، فایل‌های jar فهرست‌شده در آن نیز پویش خواهند شد. فایل‌های jar موجود در ویژگی مانیفست Class-Path که یافت نشوند، نادیده گرفته می‌شوند. تمام فایل‌های jar یافت‌شده طوری در نظر گرفته می‌شوند که گویی متعلق به ماژول بدون نام (unnamed module) هستند.

--module-path path: برای تعیین فهرستی از مسیرهای اشاره‌کننده به فایل‌های jar یا دایرکتوری‌های حاوی فایل‌های jar به کار می‌رود که ابزار می‌تواند از آن‌ها برای یافتن ماژول‌های نیازمند پویش استفاده کند. فهرست فایل‌های jar که پویش خواهند شد به گزینه --add-modules بستگی دارد.

برای هر دو گزینه --class-path و --module-path، مقدار path باید یک مسیر جستجو متشکل از یک یا چند فایل jar باشد که با جداکننده مسیر ویژه سیستم‌عامل از یکدیگر جدا شده‌اند. برای نمونه:

•: لینوکس و macOS:

--class-path /some/foo.jar:/another/different/bar.jar

نکته: در ویندوز، از نقطه ویرگول (;) به‌جای دو‌نقطه (:) به عنوان جداکننده استفاده کنید.

•: ویندوز:

--class-path C:\some\foo.jar;C:\another\different\bar.jar

--add-modules module[,module...]: برای تعیین فهرستی از نام‌های ماژول‌ها که با کاما از هم جدا شده‌اند به کار می‌رود تا ماژول‌های ریشه برای پویش را مشخص کند. تمام ماژول‌های ریشه و نیز هر ماژولی که به آن‌ها وابسته‌اند، پویش خواهند شد. این شامل وابستگی‌ها به پیاده‌سازی‌های سرویس است که از طریق دستور uses در فایل module-info ماژول مشخص شده‌اند. تمام ماژول‌های یافت‌شده در مسیر ماژول که پیاده‌سازی چنین سرویسی را ارائه می‌دهند نیز پویش خواهند شد.
--release version: برای مشخص کردن نگارش Java SE به کار می‌رود که مجموعه متدهای محدودشده برای پویش را تعیین می‌کند. برای فایل‌های jar چندنسخه‌ای (multi-release)، این گزینه همچنین نگارش فایل کلاسی را مشخص می‌کند که باید از فایل jar بارگذاری شود. این گزینه باید روی نگارشی از زمان اجرا تنظیم شود که برنامه در نهایت قرار است تحت آن اجرا گردد. اگر این سوییچ حذف شود، نگارش jnativescan به عنوان نگارش انتشار استفاده خواهد شد که همان نگارش JDK متعلق به ابزار است.
--print-native-access: چاپ فهرستی از نام‌های ماژول‌هایی که از قابلیت‌های محلی استفاده می‌کنند و با کاما جدا شده‌اند، به‌جای ساختار درختی پیش‌فرض.
--help یا -h: پیام راهنمای کامل را چاپ می‌کند.
--version: رشته نگارش مختصر ابزار را چاپ می‌کند.

مثال‌ها (EXAMPLES)

ابزار jnativescan یک پیکربندی زمان اجرا را در قالب مسیر کلاس، مسیر ماژول، مجموعه‌ای از ماژول‌های ریشه و یک نسخه انتشار هدف می‌پذیرد. برای مسیر کلاس، این ابزار تمام فایل‌های jar، از جمله مواردی را که به‌صورت بازگشتی از طریق ویژگی مانیفست Class-Path یافت می‌شوند، پویش می‌کند. برای مسیر ماژول، این ابزار تمام ماژول‌های ریشه مشخص‌شده از طریق --add-modules و هرگونه وابستگی (انتقالی) ماژول‌های ریشه، شامل هر ماژولی که حاوی پیاده‌سازی سرویس‌های استفاده‌شده توسط ماژول پویش‌شده باشد را پویش می‌کند.

به‌طور پیش‌فرض، این ابزار مشخص می‌کند که کدام فایل‌های jar، کلاس‌ها و متدها از قابلیت‌های محلی استفاده می‌کنند و این اطلاعات را در ساختاری درختی نمایش می‌دهد. در زیر یک خروجی نمونه آورده شده است:

$ jnativescan --class-path app.jar
app.jar (ALL-UNNAMED):
  foo.Main:
    foo.Main::main(String[])void references restricted methods:
      java.lang.foreign.MemorySegment::reinterpret(long)MemorySegment
    foo.Main::nativeMethod()void is a native method declaration

عبارت app.jar (ALL-UNNAMED) مسیر فایل jar است که نام ماژول در پرانتز پس از آن قرار دارد. از آنجا که در این حالت فایل jar در مسیر کلاس قرار دارد، عبارت ALL-UNNAMED برای نشان دادن ماژول بدون نام چاپ می‌شود. خط دوم خروجی، foo.Main، نشان می‌دهد که متدهای استفاده‌کننده از قابلیت‌های محلی در کلاس foo.Main یافت شده‌اند. خط بعدی:

foo.Main::main(String[])void references restricted methods:

نشان می‌دهد که متد main(String[]) در کلاس foo.Main به یک متد محدودشده ارجاع دارد که در خط بعد به‌صورت زیر فهرست شده است:

java.lang.foreign.MemorySegment::reinterpret(long)MemorySegment

در نهایت، متن:

foo.Main::nativeMethod()void is a native method declaration

نشان می‌دهد که کلاس foo.Main شامل اعلان یک متد native به نام nativeMethod است.

اگر گزینه --print-native-access را به خط فرمان نمونه اضافه کنیم، در عوض فهرستی از نام‌های ماژول‌هایی دریافت می‌کنیم که حاوی دسترسی به قابلیت‌های محلی هستند:

$ jnativescan --class-path app.jar --print-native-access
ALL-UNNAMED

در این حالت، خروجی فقط شامل ALL-UNNAMED است، که نشان می‌دهد یک فایل jar در مسیر کلاس، یعنی در ماژول بدون نام، حاوی دسترسی به قابلیت‌های محلی است.