.\" Copyright (c) 2017, 2023, Oracle and/or its affiliates. All rights reserved.
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
.\"
.\" This code is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License version 2 only, as
.\" published by the Free Software Foundation.
.\"
.\" This code is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" version 2 for more details (a copy is included in the LICENSE file that
.\" accompanied this code).
.\"
.\" You should have received a copy of the GNU General Public License version
.\" 2 along with this work; if not, write to the Free Software Foundation,
.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
.\" or visit www.oracle.com if you need additional information or have any
.\" questions.
.\"
.\" Automatically generated by Pandoc 2.19.2
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[R]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "JMOD" "1" "2023" "JDK 21" "JDK Commands"
.hy
.SH "نام (NAME)"
.PP
jmod \- ایجاد و مدیریت فایل‌های ماژول JMOD جاوا در OpenJDK 21
.SH "خلاصه دستور (SYNOPSIS)"
.PP
\f[V]jmod\f[R]
(\f[V]create\f[R]|\f[V]extract\f[R]|\f[V]list\f[R]|\f[V]describe\f[R]|\f[V]hash\f[R])
[\f[I]options\f[R]] \f[I]jmod-file\f[R]
.PP
شامل موارد زیر است:
.PP
\f[B]حالت‌های اصلی عملیات\f[R]
.TP
\f[V]create\f[R]
یک فایل آرشیو JMOD جدید ایجاد می‌کند.
.TP
\f[V]extract\f[R]
تمام فایل‌ها را از فایل آرشیو JMOD استخراج می‌کند.
.TP
\f[V]list\f[R]
نام تمام ورودی‌ها و محتویات را چاپ می‌کند.
.TP
\f[V]describe\f[R]
جزئیات و مشخصات ماژول را چاپ می‌کند.
.TP
\f[V]hash\f[R]
ماژول‌های برگ (leaf) را تعیین کرده و هش وابستگی‌هایی را که به‌طور مستقیم و غیرمستقیم به آن‌ها نیاز دارند ثبت می‌کند.
.PP
\f[B]گزینه‌ها\f[R]
.TP
\f[I]options\f[R]
بخش \f[B]گزینه‌های jmod\f[R] را ببینید.
.PP
\f[B]الزامی\f[R]
.TP
\f[I]jmod-file\f[R]
نام فایل JMOD را برای ایجاد یا برای بازیابی اطلاعات از آن مشخص می‌کند.
.SH "توضیحات (DESCRIPTION)"
.PP
\f[B]نکته:\f[R] برای بیشتر وظایف توسعه، از جمله استقرار ماژول‌ها در مسیر ماژول (module path) یا انتشار آن‌ها در یک مخزن Maven، همچنان ماژول‌ها را در قالب فایل‌های مدولار JAR بسته‌بندی کنید.
ابزار \f[V]jmod\f[R] برای ماژول‌هایی در نظر گرفته شده است که دارای کتابخانه‌های بومی (native libraries) یا فایل‌های پیکربندی دیگر هستند، یا برای ماژول‌هایی که قصد دارید با ابزار \f[B]jlink\f[R] به یک ایمیج زمان اجرا (runtime image) پیوند دهید.
.PP
قالب فایل JMOD به شما امکان می‌دهد فایل‌هایی غیر از فایل‌های \f[V].class\f[R]، متادیتا و منابع را تجمیع کنید.
این قالب قابل حمل و انتقال است اما قابل اجرا نیست، به این معنی که می‌توانید در زمان کامپایل یا زمان پیوند (link time) از آن استفاده کنید، اما در زمان اجرا (run time) قابل استفاده نیست.
.PP
بسیاری از گزینه‌های \f[V]jmod\f[R] شامل مشخص کردن مسیری است که محتویات آن در فایل‌های JMOD حاصل کپی می‌شود.
این گزینه‌ها تمام محتویات مسیر مشخص‌شده، از جمله زیرشاخه‌ها و محتویات آن‌ها را کپی می‌کنند، اما فایل‌هایی را که نام آن‌ها با الگوی مشخص‌شده توسط گزینه \f[V]--exclude\f[R] مطابقت دارد مستثنی می‌کنند.
.PP
با گزینه \f[V]--hash-modules\f[R] یا دستور \f[V]jmod hash\f[R]، می‌توانید در توصیف‌کننده (descriptor) هر ماژول، هش محتوای ماژول‌هایی را که مجاز به وابستگی به آن هستند ثبت کنید و بدین ترتیب این ماژول‌ها را به یکدیگر متصل نمایید.
این کار امکان می‌دهد یک بسته از طریق برون‌سپاری اختصاصی (qualified exports) به یک یا چند ماژول با نام مشخص برون‌سپاری شود و به هیچ ماژول دیگری ارسال نگردد.
زمان اجرا بررسی می‌کند که آیا هش ثبت‌شده یک ماژول با هش حل‌شده در زمان اجرا مطابقت دارد یا خیر؛ در غیر این صورت، زمان اجرا خطایی برمی‌گرداند.
.SH "گزینه‌های JMOD (OPTIONS FOR JMOD)"
.TP
\f[V]--class-path\f[R] \f[I]path\f[R]
محل فایل‌های JAR برنامه یا یک دایرکتوری حاوی کلاس‌ها را برای کپی شدن در فایل JMOD حاصل مشخص می‌کند.
.TP
\f[V]--cmds\f[R] \f[I]path\f[R]
محل دستورات اجرایی بومی (native commands) را برای کپی شدن در فایل JMOD حاصل مشخص می‌کند.
.TP
\f[V]--compress\f[R] \f[I]compress\f[R]
میزان فشرده‌سازی مورد استفاده در ایجاد فایل JMOD را مشخص می‌کند.
مقادیر پذیرفته‌شده \f[V]zip-[0-9]\f[R] هستند که در آن \f[V]zip-0\f[R] فشرده‌سازی انجام نمی‌دهد و \f[V]zip-9\f[R] بالاترین میزان فشرده‌سازی را فراهم می‌کند.
مقدار پیش‌فرض \f[V]zip-6\f[R] است.
.TP
\f[V]--config\f[R] \f[I]path\f[R]
محل فایل‌های پیکربندی قابل ویرایش توسط کاربر را برای کپی شدن در فایل JMOD حاصل مشخص می‌کند.
.TP
\f[V]--date\f[R] \f[I]TIMESTAMP\f[R]
برچسب زمانی با قالب تاریخ-زمان گسترش‌یافته ISO-8601 به همراه منطقه زمانی اختیاری، برای استفاده به عنوان برچسب زمانی ورودی‌ها؛ برای مثال
\[dq]2022-02-12T12:30:00-05:00\[dq].
.TP
\f[V]--dir\f[R] \f[I]path\f[R]
مسیری را مشخص می‌کند که \f[V]jmod\f[R] فایل‌های استخراج‌شده از آرشیو JMOD مشخص‌شده را در آن قرار می‌دهد.
.TP
\f[V]--dry-run\f[R]
یک اجرای آزمایشی از حالت هش را انجام می‌دهد.
این گزینه ماژول‌های برگ و ماژول‌های مورد نیاز آن‌ها را بدون ثبت هیچ‌گونه مقدار هش شناسایی می‌کند.
.TP
\f[V]--exclude\f[R] \f[I]pattern-list\f[R]
فایل‌های منطبق با لیست الگوهای ارائه‌شده که با کاما جدا شده‌اند را مستثنی می‌کند؛ هر عنصر از یکی از قالب‌های زیر استفاده می‌کند:
.RS
.IP \[bu] 2
\f[I]glob-pattern\f[R]
.IP \[bu] 2
\f[V]glob:\f[R]\f[I]glob-pattern\f[R]
.IP \[bu] 2
\f[V]regex:\f[R]\f[I]regex-pattern\f[R]
.PP
برای ساختار نحوی \f[I]glob-pattern\f[R] به متد \f[B]\f[VB]FileSystem.getPathMatcher\f[B]\f[R] مراجعه کنید.
برای ساختار نحوی \f[I]regex-pattern\f[R] که نشان‌دهنده یک عبارت منظم است به کلاس \f[B]\f[VB]Pattern\f[B]\f[R] مراجعه کنید.
.RE
.TP
\f[V]--hash-modules\f[R] \f[I]regex-pattern\f[R]
بر اساس گراف ماژول ماژول‌های منطبق با \f[I]regex-pattern\f[R] داده‌شده، ماژول‌های برگ را تعیین کرده و هش وابستگی‌هایی را که به‌طور مستقیم و غیرمستقیم به آن‌ها نیاز دارند ثبت می‌کند.
هش‌ها در فایل آرشیو JMOD در حال ایجاد، یا یک آرشیو JMOD یا JAR مدولار در مسیر ماژول مشخص‌شده توسط دستور \f[V]jmod hash\f[R] ثبت می‌شوند.
.TP
\f[V]--header-files\f[R] \f[I]path\f[R]
محل فایل‌های هدر (header files) را برای کپی شدن در فایل JMOD حاصل مشخص می‌کند.
.TP
\f[V]--help\f[R] یا \f[V]-h\f[R]
پیام راهنمای نحوه استفاده را چاپ می‌کند.
.TP
\f[V]--help-extra\f[R]
راهنمای گزینه‌های اضافی را چاپ می‌کند.
.TP
\f[V]--legal-notices\f[R] \f[I]path\f[R]
محل اعلانات حقوقی و مجوزها را برای کپی شدن در فایل JMOD حاصل مشخص می‌کند.
.TP
\f[V]--libs\f[R] \f[I]path\f[R]
محل کتابخانه‌های بومی (native libraries) را برای کپی شدن در فایل JMOD حاصل مشخص می‌کند.
.TP
\f[V]--main-class\f[R] \f[I]class-name\f[R]
کلاس اصلی را برای ثبت در فایل module-info.class مشخص می‌کند.
.TP
\f[V]--man-pages\f[R] \f[I]path\f[R]
محل صفحات راهنما (man pages) را برای کپی شدن در فایل JMOD حاصل مشخص می‌کند.
.TP
\f[V]--module-version\f[R] \f[I]module-version\f[R]
نسخه ماژول را برای ثبت در فایل module-info.class مشخص می‌کند.
.TP
\f[V]--module-path\f[R] \f[I]path\f[R] یا \f[V]-p\f[R] \f[I]path\f[R]
مسیر ماژول (module path) را مشخص می‌کند.
در صورت استفاده از گزینه \f[V]--hash-modules\f[R]، این گزینه الزامی است.
.TP
\f[V]--target-platform\f[R] \f[I]platform\f[R]
پلتفرم هدف را مشخص می‌کند.
.TP
\f[V]--version\f[R]
اطلاعات نسخه ابزار \f[V]jmod\f[R] را چاپ می‌کند.
.TP
\f[V]\[at]\f[R]\f[I]filename\f[R]
گزینه‌ها را از فایل مشخص‌شده می‌خواند.
.RS
.PP
یک فایل گزینه‌ها، فایلی متنی است که شامل گزینه‌ها و مقادیری است که معمولاً در اعلان خط فرمان وارد می‌کنید.
گزینه‌ها می‌توانند در یک خط یا در چندین خط قرار گیرند.
نمی‌توانید متغیرهای محیطی را برای نام مسیرها مشخص کنید.
می‌توانید با قرار دادن یک نماد هش (\f[V]#\f[R]) در ابتدای خط، آن خط را به عنوان یادداشت (کامنت) مشخص کنید.
.PP
در ادامه نمونه‌ای از یک فایل گزینه‌ها برای دستور \f[V]jmod\f[R] آمده است:
.IP
.nf
\f[CB]
#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 \[dq]x86_x64\[dq] --os-name \[dq]macOS\[dq]
  --os-version \[dq]10.10.5\[dq] greetingsmod
\f[R]
.fi
.RE
.SH "گزینه‌های اضافی JMOD (EXTRA OPTIONS FOR JMOD)"
.PP
علاوه بر گزینه‌های شرح‌داده‌شده در بخش \f[B]گزینه‌های jmod\f[R]، موارد زیر گزینه‌های اضافی هستند که می‌توان با این دستور استفاده کرد:
.TP
\f[V]--do-not-resolve-by-default\f[R]
استثنا کردن از مجموعه ریشه پیش‌فرض ماژول‌ها.
.TP
\f[V]--warn-if-resolved\f[R]
راهنمایی برای یک ابزار جهت صدور هشدار در صورت حل شدن ماژول.
یکی از مقادیر deprecated، deprecated-for-removal یا incubating.
.SH "مثال ایجاد JMOD (JMOD CREATE EXAMPLE)"
.PP
در ادامه نمونه‌ای از ایجاد یک فایل JMOD آمده است:
.IP
.nf
\f[CB]
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 \[dq]x86_x64\[dq] --os-name \[dq]macOS\[dq]
  --os-version \[dq]10.10.5\[dq] greetingsmod
\f[R]
.fi
.PP
ایجاد یک فایل JMOD با تعیین تاریخ برای ورودی‌ها به صورت \f[V]2022 March 15 00:00:00\f[R]:
.IP
.nf
\f[CB]
jmod create --class-path build/foo/classes --date 2022-03-15T00:00:00Z
   jmods/foo1.jmod
\f[R]
.fi
.SH "مثال هش JMOD (JMOD HASH EXAMPLE)"
.PP
مثال زیر نشان می‌دهد چه اتفاقی می‌افتد هنگامی که تلاش می‌کنید یک ماژول برگ (در این مثال \f[V]ma\f[R]) را با یک ماژول مورد نیاز (\f[V]mb\f[R]) پیوند دهید، در حالی که مقدار هش ثبت‌شده در ماژول مورد نیاز با مقدار هش ماژول برگ مطابقت ندارد.
.IP "1." 3
فایل‌های \f[V].java\f[R] زیر را ایجاد و کامپایل کنید:
.RS 4
.IP \[bu] 2
\f[V]jmodhashex/src/ma/module-info.java\f[R]
.RS 2
.IP
.nf
\f[CB]
module ma {
  requires mb;
}
\f[R]
.fi
.RE
.IP \[bu] 2
\f[V]jmodhashex/src/mb/module-info.java\f[R]
.RS 2
.IP
.nf
\f[CB]
module mb {
}
\f[R]
.fi
.RE
.IP \[bu] 2
\f[V]jmodhashex2/src/ma/module-info.java\f[R]
.RS 2
.IP
.nf
\f[CB]
module ma {
  requires mb;
}
\f[R]
.fi
.RE
.IP \[bu] 2
\f[V]jmodhashex2/src/mb/module-info.java\f[R]
.RS 2
.IP
.nf
\f[CB]
module mb {
}
\f[R]
.fi
.RE
.RE
.IP "2." 3
برای هر ماژول یک آرشیو JMOD ایجاد کنید.
دایرکتوری‌های \f[V]jmodhashex/jmods\f[R] و \f[V]jmodhashex2/jmods\f[R] را ایجاد کرده و سپس دستورات زیر را ابتدا از دایرکتوری \f[V]jmodhashex\f[R] و سپس از دایرکتوری \f[V]jmodhashex2\f[R] اجرا کنید:
.RS 4
.IP \[bu] 2
\f[V]jmod create --class-path mods/ma jmods/ma.jmod\f[R]
.IP \[bu] 2
\f[V]jmod create --class-path mods/mb jmods/mb.jmod\f[R]
.RE
.IP "3." 3
به‌صورت اختیاری پیش‌نمایش دستور \f[V]jmod hash\f[R] را مشاهده کنید.
دستور زیر را از دایرکتوری \f[V]jmodhashex\f[R] اجرا کنید:
.RS 4
.PP
\f[V]jmod hash --dry-run -module-path jmods --hash-modules .*\f[R]
.PP
دستور خروجی زیر را چاپ می‌کند:
.IP
.nf
\f[CB]
Dry run:
mb
  hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
\f[R]
.fi
.PP
این خروجی نشان می‌دهد که دستور \f[V]jmod hash\f[R] (بدون گزینه \f[V]--dry-run\f[R]) مقدار هش ماژول برگ \f[V]ma\f[R] را در ماژول \f[V]mb\f[R] ثبت خواهد کرد.
.RE
.IP "4." 3
مقادیر هش را در فایل‌های آرشیو JMOD موجود در دایرکتوری \f[V]jmodhashex\f[R] ثبت کنید.
دستور زیر را از دایرکتوری \f[V]jmodhashex\f[R] اجرا کنید:
.RS 4
.RS
.PP
\f[V]jmod hash --module-path jmods --hash-modules .*\f[R]
.RE
.PP
دستور خروجی زیر را چاپ می‌کند:
.RS
.PP
\f[V]Hashes are recorded in module mb\f[R]
.RE
.RE
.IP "5." 3
اطلاعات مربوط به هر آرشیو JMOD موجود در دایرکتوری \f[V]jmodhashex\f[R] را چاپ کنید.
دستورات برجسته‌شده را از دایرکتوری \f[V]jmodhashex\f[R] اجرا کنید:
.RS 4
.IP
.nf
\f[CB]
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
\f[R]
.fi
.RE
.IP "6." 3
تلاش کنید یک ایمیج زمان اجرا (runtime image) ایجاد کنید که شامل ماژول \f[V]ma\f[R] از دایرکتوری \f[V]jmodhashex2\f[R] و ماژول \f[V]mb\f[R] از دایرکتوری \f[V]jmodhashex\f[R] باشد.
دستور زیر را از دایرکتوری \f[V]jmodhashex2\f[R] اجرا کنید:
.RS 4
.IP \[bu] 2
\f[B]لینوکس و macOS:\f[R]
.RS 2
.RS
.PP
\f[V]jlink --module-path $JAVA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod --add-modules ma --output ma-app\f[R]
.RE
.RE
.IP \[bu] 2
\f[B]ویندوز:\f[R]
.RS 2
.RS
.PP
\f[V]jlink --module-path %JAVA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod --add-modules ma --output ma-app\f[R]
.RE
.RE
.PP
دستور پیامی مشابه خطای زیر را چاپ می‌کند:
.IP
.nf
\f[CB]
Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb
\f[R]
.fi
.RE