.\" Copyright (c) 2017, 2020, 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.3.1
.\"
.TH "JMOD" "1" "2021" "JDK 17" "JDK Commands"
.hy
.SH "نام (NAME)"
.PP
jmod \- ایجاد و دستکاری فایل‌های ماژول JMOD در جاوا (نسخه ۱۷)
.SH "خلاصه دستور (SYNOPSIS)"
.PP
\f[CB]jmod\f[R]
(\f[CB]create\f[R]|\f[CB]extract\f[R]|\f[CB]list\f[R]|\f[CB]describe\f[R]|\f[CB]hash\f[R])
[\f[I]options\f[R]] \f[I]jmod\-file\f[R]
.PP
شامل موارد زیر است:
.PP
\f[B]حالت‌های اصلی عملیات\f[R]
.TP
.B \f[CB]create\f[R]
یک فایل آرشیو JMOD جدید ایجاد می‌کند.
.RS
.RE
.TP
.B \f[CB]extract\f[R]
تمام فایل‌ها را از فایل آرشیو JMOD استخراج می‌کند.
.RS
.RE
.TP
.B \f[CB]list\f[R]
نام تمام مدخل‌ها را چاپ می‌کند.
.RS
.RE
.TP
.B \f[CB]describe\f[R]
جزئیات ماژول را چاپ می‌کند.
.RS
.RE
.TP
.B \f[CB]hash\f[R]
ماژول‌های برگ (leaf) را تعیین کرده و هش وابستگی‌هایی را که به‌طور مستقیم یا غیرمستقیم به آن‌ها نیاز دارند ثبت می‌کند.
.RS
.RE
.PP
\f[B]گزینه‌ها\f[R]
.TP
.B \f[I]options\f[R]
بخش \f[B]گزینه‌های jmod\f[R] را ببینید.
.RS
.RE
.PP
\f[B]الزامی\f[R]
.TP
.B \f[I]jmod\-file\f[R]
نام فایل JMOD را برای ایجاد یا بازیابی اطلاعات مشخص می‌کند.
.RS
.RE
.SH "توضیحات (DESCRIPTION)"
.PP
\f[B]نکته:\f[R] برای بیشتر کارهای توسعه، از جمله استقرار ماژول‌ها در مسیر ماژول (module path) یا انتشار آن‌ها در یک مخزن Maven، به بسته‌بندی ماژول‌ها در فایل‌های JAR ماژولار ادامه دهید.
ابزار \f[CB]jmod\f[R] برای ماژول‌هایی در نظر گرفته شده است که دارای کتابخانه‌های محلی (native) یا سایر فایل‌های پیکربندی هستند، یا برای ماژول‌هایی که قصد دارید با ابزار \f[B]jlink\f[R] به یک ایمیج زمان اجرا پیوند دهید.
.PP
قالب فایل JMOD به شما امکان می‌دهد فایل‌هایی غیر از فایل‌های \f[CB]\&.class\f[R]، متادیتا و منابع را تجمیع کنید.
این قالب قابل جابه‌جایی است اما قابل اجرا نیست، به این معنی که می‌توانید از آن در زمان کامپایل یا زمان پیوند استفاده کنید اما در زمان اجرا قابل استفاده نیست.
.PP
بسیاری از گزینه‌های \f[CB]jmod\f[R] شامل مشخص کردن مسیری هستند که محتویات آن در فایل‌های JMOD حاصل کپی می‌شود.
این گزینه‌ها تمام محتویات مسیر مشخص‌شده را کپی می‌کنند، از جمله زیرپوشه‌ها و محتویات آن‌ها، اما فایل‌هایی را که نام آن‌ها با الگوی مشخص‌شده توسط گزینه \f[CB]\-\-exclude\f[R] مطابقت دارد، مستثنی می‌کنند.
.PP
با گزینه \f[CB]\-\-hash\-modules\f[R] یا دستور \f[CB]jmod\ hash\f[R]، می‌توانید در توصیف‌گر هر ماژول، هش محتوای ماژول‌هایی را که مجاز به وابستگی به آن هستند ثبت کنید و بدین ترتیب این ماژول‌ها را به یکدیگر «متصل» کنید.
این کار امکان می‌دهد یک بسته از طریق برون‌سپاری‌های مقید (qualified exports) به یک یا چند ماژول با نام مشخص برون‌سپاری شود و به هیچ ماژول دیگری منتقل نشود.
محیط زمان اجرا بررسی می‌کند که آیا هش ثبت‌شده یک ماژول با هش حل‌شده در زمان اجرا مطابقت دارد یا خیر؛ در غیر این صورت، خطایی برمی‌گرداند.
.SH "گزینه‌ها (OPTIONS)"
.TP
.B \f[CB]\-\-class\-path\f[R] \f[I]path\f[R]
مکان فایل‌های JAR برنامه یا پوشه‌ای شامل کلاس‌ها را برای کپی در فایل JMOD حاصل مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-cmds\f[R] \f[I]path\f[R]
مکان دستورات محلی (native commands) را برای کپی در فایل JMOD حاصل مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-config\f[R] \f[I]path\f[R]
مکان فایل‌های پیکربندی قابل ویرایش توسط کاربر را برای کپی در فایل JMOD حاصل مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-dir\f[R] \f[I]path\f[R]
مکانی را مشخص می‌کند که \f[CB]jmod\f[R] فایل‌های استخراج‌شده از آرشیو JMOD مشخص‌شده را در آن قرار می‌دهد.
.RS
.RE
.TP
.B \f[CB]\-\-dry\-run\f[R]
یک اجرای آزمایشی از حالت hash انجام می‌دهد.
ماژول‌های برگ و ماژول‌های مورد نیاز آن‌ها را بدون ثبت هیچ مقدار هشی شناسایی می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-exclude\f[R] \f[I]pattern\-list\f[R]
فایل‌های مطابق با فهرست الگوهای ارائه‌شده با کاما را مستثنی می‌کند؛ هر عنصر از یکی از قالب‌های زیر استفاده می‌کند:
.RS
.IP \[bu] 2
\f[I]glob\-pattern\f[R]
.IP \[bu] 2
\f[CB]glob:\f[R]\f[I]glob\-pattern\f[R]
.IP \[bu] 2
\f[CB]regex:\f[R]\f[I]regex\-pattern\f[R]
.PP
برای ساختار نحوی \f[I]glob\-pattern\f[R] متد \f[B]\f[BC]FileSystem.getPathMatcher\f[B]\f[R] را ببینید.
برای ساختار نحوی \f[I]regex\-pattern\f[R]، که یک عبارت باقاعده (regular expression) را نشان می‌دهد، کلاس \f[B]\f[BC]Pattern\f[B]\f[R] را ببینید.
.RE
.TP
.B \f[CB]\-\-hash\-modules\f[R] \f[I]regex\-pattern\f[R]
بر اساس گراف ماژول ماژول‌های منطبق بر \f[I]regex\-pattern\f[R] داده‌شده، ماژول‌های برگ را تعیین کرده و هش وابستگی‌هایی را که به‌طور مستقیم و غیرمستقیم به آن‌ها نیاز دارند ثبت می‌کند.
هش‌ها در فایل آرشیو JMOD در حال ایجاد، یا یک آرشیو JMOD یا JAR ماژولار در مسیر ماژول مشخص‌شده توسط دستور \f[CB]jmod\ hash\f[R] ثبت می‌شوند.
.RS
.RE
.TP
.B \f[CB]\-\-header\-files\f[R] \f[I]path\f[R]
مکان فایل‌های هدر (header files) را برای کپی در فایل JMOD حاصل مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-help\f[R] یا \f[CB]\-h\f[R]
پیام راهنمای نحوه استفاده را چاپ می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-help\-extra\f[R]
راهنمای گزینه‌های اضافی را چاپ می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-legal\-notices\f[R] \f[I]path\f[R]
مکان اطلاعیه‌های حقوقی (legal notices) را برای کپی در فایل JMOD حاصل مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-libs\f[R] \f[I]path\f[R]
مکان کتابخانه‌های محلی (native libraries) را برای کپی در فایل JMOD حاصل مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-main\-class\f[R] \f[I]class\-name\f[R]
کلاس اصلی را برای ثبت در فایل module\-info.class مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-man\-pages\f[R] \f[I]path\f[R]
مکان صفحات راهنما (man pages) را برای کپی در فایل JMOD حاصل مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-module\-version\f[R] \f[I]module\-version\f[R]
نسخه ماژول را برای ثبت در فایل module\-info.class مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-module\-path\f[R] \f[I]path\f[R] یا \f[CB]\-p\f[R] \f[I]path\f[R]
مسیر ماژول (module path) را مشخص می‌کند.
اگر گزینه \f[CB]\-\-hash\-modules\f[R] را مشخص کنید، این گزینه الزامی است.
.RS
.RE
.TP
.B \f[CB]\-\-target\-platform\f[R] \f[I]platform\f[R]
پلتفرم مقصد را مشخص می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-version\f[R]
اطلاعات نسخه ابزار \f[CB]jmod\f[R] را چاپ می‌کند.
.RS
.RE
.TP
.B \f[CB]\@\f[R]\f[I]filename\f[R]
گزینه‌ها را از فایل مشخص‌شده می‌خواند.
.RS
.PP
فایل گزینه‌ها یک فایل متنی است که شامل گزینه‌ها و مقادیری است که معمولاً در خط فرمان وارد می‌کنید.
گزینه‌ها می‌توانند در یک خط یا در چندین خط قرار گیرند.
نمی‌توانید متغیرهای محیطی را برای نام مسیرها مشخص کنید.
می‌توانید با قرار دادن یک نماد هش (\f[CB]#\f[R]) در ابتدای خط، خطوط را کامنت کنید.
.PP
در ادامه نمونه‌ای از یک فایل گزینه‌ها برای دستور \f[CB]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\ "x86_x64"\ \-\-os\-name\ "Mac\ OS\ X"
\ \ \-\-os\-version\ "10.10.5"\ greetingsmod
\f[R]
.fi
.RE
.SH "گزینه‌های اضافی (EXTRA OPTIONS)"
.PP
علاوه بر گزینه‌های شرح داده‌شده در \f[B]گزینه‌ها\f[R]، موارد زیر گزینه‌های اضافی هستند که می‌توان با این دستور استفاده کرد.
.TP
.B \f[CB]\-\-do\-not\-resolve\-by\-default\f[R]
از مجموعه ماژول‌های ریشه پیش‌فرض مستثنی می‌کند.
.RS
.RE
.TP
.B \f[CB]\-\-warn\-if\-resolved\f[R]
راهنمایی برای ابزار جهت صدور هشدار در صورت حل شدن ماژول.
یکی از مقادیر deprecated، deprecated\-for\-removal، یا incubating.
.RS
.RE
.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\ "x86_x64"\ \-\-os\-name\ "Mac\ OS\ X"
\ \ \-\-os\-version\ "10.10.5"\ greetingsmod
\f[R]
.fi
.SH "مثال محاسبه هش JMOD (JMOD HASH EXAMPLE)"
.PP
مثال زیر نشان می‌دهد چه اتفاقی می‌افتد هنگامی که تلاش می‌کنید یک ماژول برگ (در این مثال، \f[CB]ma\f[R]) را با یک ماژول مورد نیاز (\f[CB]mb\f[R]) پیوند دهید، و مقدار هش ثبت‌شده در ماژول مورد نیاز با ماژول برگ مطابقت نداشته باشد.
.IP "1." 3
فایل‌های \f[CB]\&.java\f[R] زیر را ایجاد و کامپایل کنید:
.RS 4
.IP \[bu] 2
\f[CB]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[CB]jmodhashex/src/mb/module\-info.java\f[R]
.RS 2
.IP
.nf
\f[CB]
module\ mb\ {
}
\f[R]
.fi
.RE
.IP \[bu] 2
\f[CB]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[CB]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[CB]jmodhashex/jmods\f[R] و \f[CB]jmodhashex2/jmods\f[R] را ایجاد کنید، سپس دستورات زیر را ابتدا از پوشه \f[CB]jmodhashex\f[R] و سپس از پوشه \f[CB]jmodhashex2\f[R] اجرا کنید:
.RS 4
.IP \[bu] 2
\f[CB]jmod\ create\ \-\-class\-path\ mods/ma\ jmods/ma.jmod\f[R]
.IP \[bu] 2
\f[CB]jmod\ create\ \-\-class\-path\ mods/mb\ jmods/mb.jmod\f[R]
.RE
.IP "3." 3
در صورت تمایل پیش‌نمایش دستور \f[CB]jmod\ hash\f[R] را مشاهده کنید.
دستور زیر را از پوشه \f[CB]jmodhashex\f[R] اجرا کنید:
.RS 4
.PP
\f[CB]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[CB]jmod\ hash\f[R] (بدون گزینه \f[CB]\-\-dry\-run\f[R]) مقدار هش ماژول برگ \f[CB]ma\f[R] را در ماژول \f[CB]mb\f[R] ثبت خواهد کرد.
.RE
.IP "4." 3
مقادیر هش را در فایل‌های آرشیو JMOD موجود در پوشه \f[CB]jmodhashex\f[R] ثبت کنید.
دستور زیر را از پوشه \f[CB]jmodhashex\f[R] اجرا کنید:
.RS 4
.RS
.PP
\f[CB]jmod\ hash\ \-\-module\-path\ jmods\ \-\-hash\-modules\ .*\f[R]
.RE
.PP
این دستور خروجی زیر را چاپ می‌کند:
.RS
.PP
\f[CB]Hashes\ are\ recorded\ in\ module\ mb\f[R]
.RE
.RE
.IP "5." 3
اطلاعات مربوط به هر آرشیو JMOD موجود در پوشه \f[CB]jmodhashex\f[R] را چاپ کنید.
دستورات مشخص‌شده را از پوشه \f[CB]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
تلاش کنید یک ایمیج زمان اجرا ایجاد کنید که شامل ماژول \f[CB]ma\f[R] از پوشه \f[CB]jmodhashex2\f[R] باشد اما ماژول \f[CB]mb\f[R] از پوشه \f[CB]jmodhashex\f[R] گرفته شود.
دستور زیر را از پوشه \f[CB]jmodhashex2\f[R] اجرا کنید:
.RS 4
.IP \[bu] 2
\f[B]لینوکس و OS X:\f[R]
.RS 2
.RS
.PP
\f[CB]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[CB]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