| JAR(1) | دستورات JDK | JAR(1) |
نام (NAME)
jar - ابزار ایجاد، مشاهده و مدیریت بسته‌های آرشیو JAR در OpenJDK 21
خلاصه دستور (SYNOPSIS)
jar [OPTION ...] [ [--release VERSION] [-C dir] files] ...
توضیحات (DESCRIPTION)
دستور jar یک ابزار چندمنظوره برای بایگانی و فشرده‌سازی بر پایه قالب‌های فشرده‌سازی ZIP و ZLIB است. در ابتدا، دستور jar برای بسته‌بندی اپلت‌های جاوا (که از JDK 11 به بعد پشتیبانی نمی‌شوند) یا برنامه‌های کاربردی طراحی شده بود؛ با این حال، از JDK 9 به بعد، کاربران می‌توانند از دستور jar برای ایجاد فایل‌های JAR ماژولار استفاده کنند. برای جابه‌جایی و استقرار، معمولاً بسته‌بندی ماژول‌ها به‌صورت JARهای ماژولار راحت‌تر است.
نحو دستور jar شبیه به نحو دستور tar است. این دستور دارای چندین حالت عملیاتی اصلی است که با یکی از آرگومان‌های اجباری عملیات مشخص می‌شوند. سایر آرگومان‌ها یا گزینه‌هایی هستند که رفتار عملیات را تغییر می‌دهند، یا برای انجام آن عملیات مورد نیازند.
هنگامی که ماژول‌ها یا اجزای یک برنامه (فایل‌ها، تصاویر و صداها) در یک آرشیو واحد ترکیب می‌شوند، یک عامل جاوا (مانند مرورگر) می‌تواند آن‌ها را در یک تراکنش HTTP واحد بارگیری کند، به‌جای اینکه برای هر قطعه به اتصال جدیدی نیاز باشد. این کار زمان بارگیری را به‌طور چشمگیری بهبود می‌بخشد. دستور jar همچنین فایل‌ها را فشرده می‌کند که زمان بارگیری را باز هم کاهش می‌دهد. دستور jar امکان امضای ورودی‌های منفرد در یک فایل را نیز فراهم می‌سازد تا اصالت منبع آن‌ها قابل تأیید باشد. یک فایل JAR می‌تواند چه فشرده باشد و چه نباشد، به‌عنوان یک ورودی در class path استفاده شود.
هنگامی که یک توصیف‌گر ماژول، یعنی module-info.class را در ریشه پوشه‌های داده‌شده یا در ریشه آرشیو .jar قرار دهید، آن آرشیو به یک JAR ماژولار تبدیل می‌شود. عملیات‌های زیر که در تغییردهنده‌های عملیات معتبر فقط در حالت‌های ایجاد و به‌روزرسانی شرح داده شده‌اند، فقط هنگام ایجاد یا به‌روزرسانی یک jar ماژولار یا به‌روزرسانی یک jar غیرماژولار موجود معتبر هستند:
- •
- --module-version
- •
- --hash-modules
- •
- --module-path
نکته:
تمام آرگومان‌های اجباری یا اختیاری برای گزینه‌های بلند، برای گزینه‌های کوتاه متناظر آن‌ها نیز اجباری یا اختیاری هستند.
حالت‌های اصلی عملیات (MAIN OPERATION MODES)
هنگام استفاده از دستور jar، باید عملیاتی را که می‌خواهید اجرا شود مشخص کنید. حالت عملیات دستور jar را با درج آرگومان‌های عملیاتی مناسب شرح‌داده‌شده در این بخش تعیین می‌کنید. می‌توانید یک آرگومان عملیاتی را با سایر گزینه‌های تک‌حرفی ترکیب کنید. معمولاً آرگومان عملیات اولین آرگومان مشخص‌شده در خط فرمان است.
- -c یا --create
- آرشیو را ایجاد می‌کند.
- -i FILE یا --generate-index=FILE
- اطلاعات ایندکس را برای فایل JAR مشخص‌شده تولید می‌کند. این گزینه منسوخ شده است و ممکن است در نسخه‌های آینده حذف شود.
- -t یا --list
- فهرست محتویات آرشیو را نمایش می‌دهد.
- -u یا --update
- یک فایل JAR موجود را به‌روزرسانی می‌کند.
- -x یا --extract
- فایل‌های نام‌برده‌شده (یا تمام فایل‌ها) را از آرشیو استخراج می‌کند.
- -d یا --describe-module
- توصیف‌گر ماژول یا نام ماژول خودکار را چاپ می‌کند.
تغییردهنده‌های عملیات معتبر در هر حالتی (OPERATION MODIFIERS VALID IN ANY MODE)
می‌توانید از گزینه‌های زیر برای سفارشی‌سازی رفتارهای هر یک از حالت‌های عملیاتی دستور jar استفاده کنید.
- -C DIR
- پوشه مشخص‌شده را تغییر می‌دهد و فایل‌های مشخص‌شده در انتهای خط فرمان را شامل می‌کند.
jar [OPTION ...] [ [--release VERSION] [-C dir] files]
- -f FILE یا --file=FILE
- نام فایل آرشیو را مشخص می‌کند.
- --release VERSION
- یک فایل JAR چندنسخه‌ای (multirelease) ایجاد می‌کند. تمام فایل‌های مشخص‌شده پس از این گزینه را در یک پوشه نسخه‌بندی‌شده از فایل JAR به نام META-INF/versions/VERSION/ قرار می‌دهد، که در آن VERSION باید یک عدد صحیح مثبت بزرگتر یا مساوی ۹ باشد.
در زمان اجرا، اگر بیش از یک نسخه از یک کلاس در JAR وجود داشته باشد، JDK اولین نسخه‌ای را که پیدا کند استفاده خواهد کرد؛ بدین صورت که ابتدا در ساختار پوشه‌ای که شماره VERSION آن با شماره نسخه اصلی JDK مطابقت دارد جستجو می‌کند. سپس پوشه‌های دارای شماره‌های VERSION پایین‌تر را بررسی می‌کند و در نهایت ریشه فایل JAR را می‌جوید.
- -v یا --verbose
- خروجی مشروح را به خروجی استاندارد ارسال کرده یا چاپ می‌کند.
تغییردهنده‌های عملیات معتبر فقط در حالت‌های ایجاد و به‌روزرسانی (OPERATION MODIFIERS VALID ONLY IN CREATE AND UPDATE MODES)
می‌توانید از گزینه‌های زیر برای سفارشی‌سازی رفتارهای حالت‌های اصلی ایجاد (create) و به‌روزرسانی (update) استفاده کنید:
- -e CLASSNAME یا --main-class=CLASSNAME
- نقطه ورود برنامه را برای برنامه‌های مستقلی که در یک فایل JAR ماژولار یا اجرایی بسته‌بندی شده‌اند مشخص می‌کند.
- -m FILE یا --manifest=FILE
- اطلاعات مانیفست را از فایل مانیفست داده‌شده در آرشیو می‌گنجاند.
- -M یا --no-manifest
- فایل مانیفست برای ورودی‌ها ایجاد نمی‌کند.
- --module-version=VERSION
- نسخه ماژول را هنگام ایجاد یا به‌روزرسانی فایل JAR ماژولار یا به‌روزرسانی فایل JAR غیرماژولار تعیین می‌کند.
- --hash-modules=PATTERN
- هش ماژول‌هایی را که با الگوی داده‌شده مطابقت دارند و به‌طور مستقیم یا غیرمستقیم به فایل JAR ماژولار در حال ایجاد یا فایل JAR غیرماژولار در حال به‌روزرسانی وابسته هستند، محاسبه و ثبت می‌کند.
- -p یا --module-path
- مسیر وابستگی‌های ماژول را برای تولید هش مشخص می‌کند.
- @file
- گزینه‌ها و نام فایل‌های jar را از یک فایل متنی می‌خواند، گویی که مستقیماً در خط فرمان وارد شده‌اند.
تغییردهنده‌های عملیات معتبر در حالت‌های ایجاد، به‌روزرسانی و تولید ایندکس (OPERATION MODIFIERS VALID ONLY IN CREATE, UPDATE, AND GENERATE-INDEX MODES)
می‌توانید از گزینه‌های زیر برای سفارشی‌سازی رفتارهای حالت‌های اصلی ایجاد (-c یا --create)، به‌روزرسانی (-u یا --update) و تولید ایندکس (-i یا --generate-index=FILE) استفاده کنید:
- -0 یا --no-compress
- فایل‌ها را بدون استفاده از فشرده‌سازی ZIP ذخیره می‌کند.
- --date=TIMESTAMP
- برچسب زمانی در قالب تاریخ-زمان گسترش‌یافته ISO-8601 همراه با منطقه زمانی اختیاری برای استفاده در تاریخ ورودی‌ها، مانند "2022-02-12T12:30:00-05:00".
سایر گزینه‌ها (OTHER OPTIONS)
گزینه‌های زیر توسط دستور jar شناخته می‌شوند و همراه با حالت‌های عملیاتی به کار نمی‌روند:
- -h یا --help[:compat]
- راهنمای خط فرمان برای دستور jar یا به‌صورت اختیاری راهنمای سازگاری را نمایش می‌دهد.
- --help-extra
- راهنما درباره گزینه‌های اضافی را نمایش می‌دهد.
- --version
- نسخه برنامه را چاپ می‌کند.
مثال‌هایی از نحو دستور JAR (EXAMPLES OF JAR COMMAND SYNTAX)
- •
- ایجاد یک آرشیو به نام classes.jar که شامل دو فایل کلاس Foo.class و Bar.class است:
jar --create --file classes.jar Foo.class Bar.class
- •
- ایجاد یک آرشیو به نام classes.jar که شامل دو فایل کلاس Foo.class و Bar.class بوده و تاریخ و زمان آخرین تغییر آن روی 2021 Jan 6 12:36:00 تنظیم شده است:
jar --create --date="2021-01-06T14:36:00+02:00" --file=classes.jar Foo.class Bar.class
- •
- ایجاد یک آرشیو به نام classes.jar با استفاده از یک مانیفست موجود به نام mymanifest که شامل تمامی فایل‌های درون پوشه foo/ است:
jar --create --file classes.jar --manifest mymanifest -C foo/
- •
- ایجاد یک آرشیو JAR ماژولار به نام foo.jar که در آن توصیف‌گر ماژول در مسیر classes/module-info.class قرار دارد:
jar --create --file foo.jar --main-class com.foo.Main --module-version 1.0 -C foo/classes resources
- •
- به‌روزرسانی یک JAR غیرماژولار موجود به نام foo.jar به یک فایل JAR ماژولار:
jar --update --file foo.jar --main-class com.foo.Main --module-version 1.0 -C foo/module-info.class
- •
- ایجاد یک JAR چندنسخه‌ای به نام foo.jar که فایل‌های موجود در پوشه classes را در ریشه JAR و فایل‌های موجود در پوشه classes-10 را در پوشه META-INF/versions/10 از JAR قرار می‌دهد:
در این مثال، پوشه classes/com/foo شامل دو کلاس com.foo.Hello (کلاس نقطه ورود) و com.foo.NameProvider است که هر دو برای JDK 8 کامپایل شده‌اند. پوشه classes-10/com/foo شامل نسخه متفاوتی از کلاس com.foo.NameProvider است که شامل کدهای مخصوص JDK 10 بوده و برای JDK 10 کامپایل شده است.
با این ساختار، فایل JAR چندنسخه‌ای foo.jar را با اجرای دستور زیر از داخل پوشه‌ای که حاوی پوشه‌های classes و classes-10 است ایجاد کنید:
jar --create --file foo.jar --main-class com.foo.Hello -C classes . --release 10 -C classes-10 .
اکنون فایل JAR به نام foo.jar شامل موارد زیر خواهد بود:
-
% jar -tf foo.jar META-INF/ META-INF/MANIFEST.MF com/ com/foo/ com/foo/Hello.class com/foo/NameProvider.class META-INF/versions/10/com/ META-INF/versions/10/com/foo/ META-INF/versions/10/com/foo/NameProvider.class
همراه با سایر اطلاعات، فایل META-INF/MANIFEST.MF شامل خطوط زیر خواهد بود تا نشان دهد این یک فایل JAR چندنسخه‌ای با نقطه ورود com.foo.Hello است:
-
... Main-Class: com.foo.Hello Multi-Release: true
با فرض اینکه کلاس com.foo.Hello متدی از کلاس com.foo.NameProvider را فراخوانی کند، اجرای برنامه با استفاده از JDK 10 تضمین می‌کند که کلاس com.foo.NameProvider همان نسخه موجود در META-INF/versions/10/com/foo/ باشد. اجرای برنامه با استفاده از JDK 8 نیز تضمین می‌کند که کلاس com.foo.NameProvider همان نسخه موجود در ریشه JAR در مسیر com/foo باشد.
- •
- ایجاد یک آرشیو به نام my.jar با خواندن گزینه‌ها و فهرست فایل‌های کلاس از فایل classes.list:
نکته:
برای کوتاه کردن یا ساده‌سازی دستور jar، می‌توانید یک فایل آرگومان (arg file) شامل فهرست فایل‌های مورد نظر برای گنجاندن در JAR ایجاد کرده و آن را با علامت اتساین (@) به‌عنوان پیشوند به دستور jar ارسال کنید.
jar --create --file my.jar @classes.list
اگر یک یا چند ورودی مشخص‌شده در فایل آرگومان پیدا نشود، دستور jar بدون ایجاد فایل JAR با خطا مواجه می‌شود.
| 2023 | JDK 21 |