JMOD(1)                          JDK Commands                          JMOD(1)

نام (NAME)
       jmod - ایجاد و مدیریت فایل‌های ماژول JMOD جاوا در OpenJDK 21

خلاصه دستور (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 libraries) یا
       فایل‌های پیکربندی دیگر هستند، یا برای ماژول‌هایی که قصد دارید با ابزار
       jlink به یک ایمیج زمان اجرا (runtime image) پیوند دهید.

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

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

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

گزینه‌های JMOD (OPTIONS FOR JMOD)
       --class-path path
              محل فایل‌های JAR برنامه یا یک دایرکتوری حاوی کلاس‌ها را برای کپی
              شدن در فایل JMOD حاصل مشخص می‌کند.

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

       --compress compress
              میزان فشرده‌سازی مورد استفاده در ایجاد فایل JMOD را مشخص می‌کند.
              مقادیر پذیرفته‌شده zip-[0-9] هستند که در آن zip-0 فشرده‌سازی انجام
              نمی‌دهد و zip-9 بالاترین میزان فشرده‌سازی را فراهم می‌کند.  مقدار
              پیش‌فرض zip-6 است.

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

       --date TIMESTAMP
              برچسب زمانی با قالب تاریخ-زمان گسترش‌یافته ISO-8601 به همراه
              منطقه زمانی اختیاری، برای استفاده به عنوان برچسب زمانی ورودی‌ها؛
              برای مثال "2022-02-12T12:30:00-05:00".

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

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

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

              • glob-pattern

              • glob:glob-pattern

              • regex:regex-pattern

              برای ساختار نحوی glob-pattern به متد FileSystem.getPathMatcher
              مراجعه کنید.  برای ساختار نحوی regex-pattern که نشان‌دهنده یک
              عبارت منظم است به کلاس 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
              محل اعلانات حقوقی و مجوزها را برای کپی شدن در فایل 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 "macOS"
                       --os-version "10.10.5" greetingsmod


گزینه‌های اضافی JMOD (EXTRA OPTIONS FOR JMOD)
       علاوه بر گزینه‌های شرح‌داده‌شده در بخش گزینه‌های jmod، موارد زیر گزینه‌های
       اضافی هستند که می‌توان با این دستور استفاده کرد:

       --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 "macOS"
                --os-version "10.10.5" greetingsmod


       ایجاد یک فایل JMOD با تعیین تاریخ برای ورودی‌ها به صورت 2022 March 15
       00:00:00:


              jmod create --class-path build/foo/classes --date 2022-03-15T00:00:00Z
                 jmods/foo1.jmod


مثال هش 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. تلاش کنید یک ایمیج زمان اجرا (runtime image) ایجاد کنید که شامل
          ماژول ma از دایرکتوری jmodhashex2 و ماژول mb از دایرکتوری jmodhashex
          باشد.  دستور زیر را از دایرکتوری jmodhashex2 اجرا کنید:

           • لینوکس و macOS:

                    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


JDK 21                               2023                              JMOD(1)