نام (NAME)

jar-openjdk25 - ابزار ایجاد، مشاهده و مدیریت بسته‌های آرشیو JAR در OpenJDK 25

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

jar [گزینه ...] [ [--release نسخه] [-C پوشه] فایل‌ها] ...

توضیحات (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: فایل‌های نام‌برده‌شده (یا تمام فایل‌ها) را از آرشیو استخراج می‌کند. اگر فایلی با نام یکسان بیش از یک بار در آرشیو وجود داشته باشد، هر نسخه استخراج خواهد شد و نسخه‌های بعدی جایگزین نسخه‌های قبلی می‌شوند مگر اینکه گزینه -k مشخص شده باشد.
-d یا --describe-module: توصیف‌گر ماژول یا نام ماژول خودکار را چاپ می‌کند.
--validate: محتویات فایل JAR را اعتبارسنجی می‌کند. برای جزئیات بیشتر به بخش یکپارچگی و سلامت فایل JAR در ادامه مراجعه کنید.

تغییردهنده‌های عملیات معتبر در تمام حالت‌ها (OPERATION MODIFIERS VALID IN ANY MODE)

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

-C DIR: هنگامی که همراه با حالت عملیاتی ایجاد (create) استفاده شود، پوشه کاری را به پوشه مشخص‌شده تغییر می‌دهد و فایل‌های مشخص‌شده در انتهای خط فرمان را شامل می‌کند.

jar [گزینه ...] [ [--release نسخه] [-C پوشه] فایل‌ها] هنگامی که همراه با حالت عملیاتی استخراج (extract) استفاده شود، پوشه مقصدی را که فایل JAR در آن استخراج می‌شود مشخص می‌کند. برخلاف حالت ایجاد، این گزینه در حالت استخراج فقط یک بار می‌تواند مشخص شود.

-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".

تغییردهنده‌های عملیات معتبر فقط در حالت استخراج (OPERATION MODIFIERS VALID ONLY IN EXTRACT MODE)

--dir DIR: پوشه‌ای که فایل JAR در آن استخراج خواهد شد.
-k یا --keep-old-files: فایل‌های موجود را رونویسی نمی‌کند. اگر ورودی فایلی از JAR با همان نام در پوشه مقصد وجود داشته باشد، فایل موجود رونویسی نخواهد شد. در نتیجه، اگر یک فایل بیش از یک بار در آرشیو وجود داشته باشد، نسخه‌های بعدی نسخه‌های قبلی را بازنویسی نمی‌کنند. همچنین توجه داشته باشید که برخی از فایل‌سیستم‌ها به حروف بزرگ و کوچک حساس نیستند.

سایر گزینه‌ها (OTHER OPTIONS)

گزینه‌های زیر توسط دستور jar شناخته می‌شوند و همراه با حالت‌های عملیاتی به کار نمی‌روند:

-h یا --help[:compat]: راهنمای خط فرمان برای دستور jar یا به‌صورت اختیاری راهنمای سازگاری را نمایش می‌دهد.
--help-extra: راهنما درباره گزینه‌های اضافی را نمایش می‌دهد.
--version: نسخه برنامه را چاپ می‌کند.

یکپارچگی و سلامت فایل JAR (INTEGRITY OF A JAR FILE)

از آنجا که یک فایل JAR مبتنی بر قالب ZIP است، امکان ایجاد فایل JAR با استفاده از ابزارهایی غیر از دستور jar نیز وجود دارد. گزینه --validate می‌تواند برای انجام بررسی‌های یکپارچگی زیر روی فایل JAR استفاده شود:

عدم وجود نام‌های تکراری برای ورودی‌های Zip
تأیید اینکه نام ورودی Zip:

یک مسیر مطلق نباشد
نام فایل '.' یا '..' نباشد
شامل کاراکتر بک‌اسلش، '\' نباشد
شامل حرف درایو نباشد
اجزای مسیر شامل '.' یا '..' نباشد

•: تطابق و سازگاری API صادرشده توسط آرشیو jar چندنسخه‌ای در تمام نسخه‌های مختلف.

ابزار jar در صورتی که هیچ مشکلی در یکپارچگی مشاهده نشود با وضعیت 0 و در صورت بروز خطا یا هشدار با مقداری بزرگتر از صفر (>0) خارج می‌شود.

هنگامی که یک مشکل یکپارچگی گزارش می‌شود، اغلب نیاز است که فایل JAR توسط منبع اصلی تولیدکننده آن مجدداً ایجاد شود.

مثال‌ها (EXAMPLES)

•: ایجاد یک آرشیو به نام 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 با خطا مواجه می‌شود.

•: استخراج فایل JAR به نام foo.jar در پوشه /tmp/bar/:

jar -xf foo.jar -C /tmp/bar/

همچنین می‌توانید به‌صورت زیر عمل کنید:

jar --extract --file foo.jar --dir /tmp/bar/