نام (NAME)

jmod - ایجاد و دستکاری فایل‌های ماژول JMOD در جاوا (نسخه ۱۷)

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

jmod (create|extract|list|describe|hash) [options] jmod-file

شامل موارد زیر است:

حالت‌های اصلی عملیات

create: یک فایل آرشیو JMOD جدید ایجاد می‌کند.

extract: تمام فایل‌ها را از فایل آرشیو JMOD استخراج می‌کند.

list: نام تمام مدخل‌ها را چاپ می‌کند.

describe: جزئیات ماژول را چاپ می‌کند.

hash: ماژول‌های برگ (leaf) را تعیین کرده و هش وابستگی‌هایی را که به‌طور مستقیم یا غیرمستقیم به آن‌ها نیاز دارند ثبت می‌کند.

گزینه‌ها

options: بخش گزینه‌های jmod را ببینید.

الزامی

jmod-file: نام فایل JMOD را برای ایجاد یا بازیابی اطلاعات مشخص می‌کند.

توضیحات (DESCRIPTION)

نکته: برای بیشتر کارهای توسعه، از جمله استقرار ماژول‌ها در مسیر ماژول (module path) یا انتشار آن‌ها در یک مخزن Maven، به بسته‌بندی ماژول‌ها در فایل‌های JAR ماژولار ادامه دهید. ابزار jmod برای ماژول‌هایی در نظر گرفته شده است که دارای کتابخانه‌های محلی (native) یا سایر فایل‌های پیکربندی هستند، یا برای ماژول‌هایی که قصد دارید با ابزار jlink به یک ایمیج زمان اجرا پیوند دهید.

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

بسیاری از گزینه‌های jmod شامل مشخص کردن مسیری هستند که محتویات آن در فایل‌های JMOD حاصل کپی می‌شود. این گزینه‌ها تمام محتویات مسیر مشخص‌شده را کپی می‌کنند، از جمله زیرپوشه‌ها و محتویات آن‌ها، اما فایل‌هایی را که نام آن‌ها با الگوی مشخص‌شده توسط گزینه --exclude مطابقت دارد، مستثنی می‌کنند.

با گزینه --hash-modules یا دستور jmod hash، می‌توانید در توصیف‌گر هر ماژول، هش محتوای ماژول‌هایی را که مجاز به وابستگی به آن هستند ثبت کنید و بدین ترتیب این ماژول‌ها را به یکدیگر «متصل» کنید. این کار امکان می‌دهد یک بسته از طریق برون‌سپاری‌های مقید (qualified exports) به یک یا چند ماژول با نام مشخص برون‌سپاری شود و به هیچ ماژول دیگری منتقل نشود. محیط زمان اجرا بررسی می‌کند که آیا هش ثبت‌شده یک ماژول با هش حل‌شده در زمان اجرا مطابقت دارد یا خیر؛ در غیر این صورت، خطایی برمی‌گرداند.

گزینه‌ها (OPTIONS)

--class-path path: مکان فایل‌های JAR برنامه یا پوشه‌ای شامل کلاس‌ها را برای کپی در فایل JMOD حاصل مشخص می‌کند.

--cmds path: مکان دستورات محلی (native commands) را برای کپی در فایل JMOD حاصل مشخص می‌کند.

--config path: مکان فایل‌های پیکربندی قابل ویرایش توسط کاربر را برای کپی در فایل JMOD حاصل مشخص می‌کند.

--dir path: مکانی را مشخص می‌کند که jmod فایل‌های استخراج‌شده از آرشیو JMOD مشخص‌شده را در آن قرار می‌دهد.

--dry-run: یک اجرای آزمایشی از حالت hash انجام می‌دهد. ماژول‌های برگ و ماژول‌های مورد نیاز آن‌ها را بدون ثبت هیچ مقدار هشی شناسایی می‌کند.

--exclude pattern-list: فایل‌های مطابق با فهرست الگوهای ارائه‌شده با کاما را مستثنی می‌کند؛ هر عنصر از یکی از قالب‌های زیر استفاده می‌کند:

•: glob-pattern
•: glob:glob-pattern
•: regex:regex-pattern

برای ساختار نحوی glob-pattern متد FileSystem.getPathMatcher را ببینید. برای ساختار نحوی regex-pattern، که یک عبارت باقاعده (regular expression) را نشان می‌دهد، کلاس Pattern را ببینید.

--hash-modules regex-pattern: بر اساس گراف ماژول ماژول‌های منطبق بر regex-pattern داده‌شده، ماژول‌های برگ را تعیین کرده و هش وابستگی‌هایی را که به‌طور مستقیم و غیرمستقیم به آن‌ها نیاز دارند ثبت می‌کند. هش‌ها در فایل آرشیو JMOD در حال ایجاد، یا یک آرشیو JMOD یا JAR ماژولار در مسیر ماژول مشخص‌شده توسط دستور jmod hash ثبت می‌شوند.

--header-files path: مکان فایل‌های هدر (header files) را برای کپی در فایل JMOD حاصل مشخص می‌کند.

--help یا -h: پیام راهنمای نحوه استفاده را چاپ می‌کند.

--help-extra: راهنمای گزینه‌های اضافی را چاپ می‌کند.

--legal-notices path: مکان اطلاعیه‌های حقوقی (legal notices) را برای کپی در فایل JMOD حاصل مشخص می‌کند.

--libs path: مکان کتابخانه‌های محلی (native libraries) را برای کپی در فایل JMOD حاصل مشخص می‌کند.

--main-class class-name: کلاس اصلی را برای ثبت در فایل module-info.class مشخص می‌کند.

--man-pages path: مکان صفحات راهنما (man pages) را برای کپی در فایل JMOD حاصل مشخص می‌کند.

--module-version module-version: نسخه ماژول را برای ثبت در فایل module-info.class مشخص می‌کند.

--module-path path یا -p path: مسیر ماژول (module path) را مشخص می‌کند. اگر گزینه --hash-modules را مشخص کنید، این گزینه الزامی است.

--target-platform platform: پلتفرم مقصد را مشخص می‌کند.

--version: اطلاعات نسخه ابزار jmod را چاپ می‌کند.

@filename: گزینه‌ها را از فایل مشخص‌شده می‌خواند.

فایل گزینه‌ها یک فایل متنی است که شامل گزینه‌ها و مقادیری است که معمولاً در خط فرمان وارد می‌کنید. گزینه‌ها می‌توانند در یک خط یا در چندین خط قرار گیرند. نمی‌توانید متغیرهای محیطی را برای نام مسیرها مشخص کنید. می‌توانید با قرار دادن یک نماد هش (#) در ابتدای خط، خطوط را کامنت کنید.

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


#Wed Dec 07 00:40:19 EST 2016
create --class-path mods/com.greetings --module-path mlib
  --cmds commands --config configfiles --header-files src/h
  --libs lib --main-class com.greetings.Main
  --man-pages man --module-version 1.0
  --os-arch "x86_x64" --os-name "Mac OS X"
  --os-version "10.10.5" greetingsmod

گزینه‌های اضافی (EXTRA OPTIONS)

علاوه بر گزینه‌های شرح داده‌شده در گزینه‌ها، موارد زیر گزینه‌های اضافی هستند که می‌توان با این دستور استفاده کرد.

--do-not-resolve-by-default: از مجموعه ماژول‌های ریشه پیش‌فرض مستثنی می‌کند.

--warn-if-resolved: راهنمایی برای ابزار جهت صدور هشدار در صورت حل شدن ماژول. یکی از مقادیر deprecated، deprecated-for-removal، یا incubating.

مثال ایجاد JMOD (JMOD CREATE EXAMPLE)

در ادامه نمونه‌ای از ایجاد یک فایل JMOD آمده است:


jmod create --class-path mods/com.greetings --cmds commands
  --config configfiles --header-files src/h --libs lib
  --main-class com.greetings.Main --man-pages man --module-version 1.0
  --os-arch "x86_x64" --os-name "Mac OS X"
  --os-version "10.10.5" greetingsmod

مثال محاسبه هش JMOD (JMOD HASH EXAMPLE)

مثال زیر نشان می‌دهد چه اتفاقی می‌افتد هنگامی که تلاش می‌کنید یک ماژول برگ (در این مثال، ma) را با یک ماژول مورد نیاز (mb) پیوند دهید، و مقدار هش ثبت‌شده در ماژول مورد نیاز با ماژول برگ مطابقت نداشته باشد.

1.: فایل‌های .java زیر را ایجاد و کامپایل کنید:

•: jmodhashex/src/ma/module-info.java


module ma {
  requires mb;
}

•: jmodhashex/src/mb/module-info.java


module mb {
}

•: jmodhashex2/src/ma/module-info.java


module ma {
  requires mb;
}

•: jmodhashex2/src/mb/module-info.java


module mb {
}

2.: برای هر ماژول یک آرشیو JMOD ایجاد کنید. پوشه‌های jmodhashex/jmods و jmodhashex2/jmods را ایجاد کنید، سپس دستورات زیر را ابتدا از پوشه jmodhashex و سپس از پوشه jmodhashex2 اجرا کنید:

•: jmod create --class-path mods/ma jmods/ma.jmod
•: jmod create --class-path mods/mb jmods/mb.jmod

3.: در صورت تمایل پیش‌نمایش دستور jmod hash را مشاهده کنید. دستور زیر را از پوشه jmodhashex اجرا کنید:

jmod hash --dry-run -module-path jmods --hash-modules .*

این دستور خروجی زیر را چاپ می‌کند:


Dry run:
mb
  hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a

این نشان می‌دهد که دستور jmod hash (بدون گزینه --dry-run) مقدار هش ماژول برگ ma را در ماژول mb ثبت خواهد کرد.

4.: مقادیر هش را در فایل‌های آرشیو JMOD موجود در پوشه jmodhashex ثبت کنید. دستور زیر را از پوشه jmodhashex اجرا کنید:

jmod hash --module-path jmods --hash-modules .*

این دستور خروجی زیر را چاپ می‌کند:

Hashes are recorded in module mb

5.: اطلاعات مربوط به هر آرشیو JMOD موجود در پوشه jmodhashex را چاپ کنید. دستورات مشخص‌شده را از پوشه jmodhashex اجرا کنید:


jmod describe jmods/ma.jmod
ma
  requires mandated java.base
  requires mb
jmod describe jmods/mb.jmod
mb
  requires mandated java.base
  hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a

6.: تلاش کنید یک ایمیج زمان اجرا ایجاد کنید که شامل ماژول ma از پوشه jmodhashex2 باشد اما ماژول mb از پوشه jmodhashex گرفته شود. دستور زیر را از پوشه jmodhashex2 اجرا کنید:

•: لینوکس و OS X:

jlink --module-path $JAVA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod --add-modules ma --output ma-app

•: ویندوز:

jlink --module-path %JAVA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod --add-modules ma --output ma-app

این دستور پیامی مشابه خطای زیر را چاپ می‌کند:


Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb