JEP 293: Guidelines for JDK Command-Line Tool Options

Аннотация

Этот информационный JEP излагает рекомендации по обработке опций в инструментах командной строки JDK, включая Java launcher (программу запуска Java).

Мотивация

Со временем в инструментах командной строки JDK сложились самые разные соглашения для их опций. Например:

• различные инструменты: -classpath (краткая форма -cp)
• javac: -verbose, -version, -XprintRounds, -Xlint:unchecked
• jar в JDK 8: -c, -t, -x и т. д.
• pack200: -g, --no-gzip, --gzip, --version

Даже опции для вывода справки по командной строке различаются у разных инструментов JDK: среди вариантов встречаются -help, -?, --help.

Когда в существующие инструменты добавляются новые опции, а в платформу добавляются новые инструменты, желательно, чтобы опции использовались единообразно.

Кроме того, среди инструментов командной строки, которыми пользуются разработчики, всё чаще встречается синтаксис в стиле GNU, также описанный в getopt(3): имя опции задаётся короткой последовательностью слов, разделённых дефисами, или эквивалентной краткой формой из одного символа.

Пора инструментам JDK стать более согласованными как между собой, так и с общепринятой практикой отрасли. Это не значит, что нужно в одночасье изменить все опции всех наших инструментов, но нам следует установить рекомендации по использованию новых опций в новых и существующих инструментах.

Синтаксис в стиле GNU даёт путь вперёд: он достаточно хорошо уживается с существующими опциями существующих инструментов JDK, он знаком многим, и для него есть библиотечная поддержка, которую можно использовать в новых инструментах.

Существующие инструменты продолжат поддерживать существующие опции, но могут также поддерживать для них псевдонимы в новом стиле. И по практическим соображениям, и ради совместимости новый стиль может так никогда и не быть принят для некоторых существующих опций существующих инструментов.

Синтаксис опций

Правила для имён опций следующие:

• У опций есть длинное имя — короткая последовательность слов, которая начинается с '--', а слова разделяются '-'. Например: --example-option

• У опций может быть краткая форма из одного символа. Например, -e

• Опции могут требовать аргумент. Для опций в длинной форме аргумент может отделяться от имени опции пробельным символом или '='. Для односимвольных опций аргумент может следовать сразу за символом или отделяться пробельным символом. Например:

  • --example-option value
  • --example-option=value
  • -e value
  • -evalue

• Опции могут допускать аргумент. Если такой аргумент указан, синтаксис опции такой же, как если бы опция требовала аргумент. Например:

  • --example-option
  • --example-option value
  • --example-option=value

• Регистр всегда имеет значение — как в длинном имени, так и в односимвольной форме. Например, --Example-Option — не то же самое, что --example-option.

• Длинные имена нельзя сокращать в командной строке. Например, --example-o — не то же самое, что --example-option.

• Использование опций для подкоманд в эти правила не входит.

• Односимвольные опции можно объединять в один токен. Например, если -a и -b — односимвольные опции, в командной строке их можно указать вместе как -ab.

• Хотя некоторые библиотеки разбора опций могут поддерживать объединение односимвольных форм нескольких опций в одно слово, не требуется поддерживать это для опций, которым нужны аргументы. Например, односимвольная опция, принимающая аргумент, может конфликтовать с использованием существующего аргумента в стиле JDK.

• Для некоторых опций аргументом может быть последовательность значений. Если значения — это расположения в файловой системе, например каталоги или файлы, их следует разделять платформенно-зависимым символом-разделителем путей (; в системах Windows, : на других платформах). В остальных случаях рекомендуемый разделитель — запятая.

• Для новых опций префикс -X, обозначающий «нестандартные» опции, больше использоваться не будет, хотя справка по командной строке может и дальше разделять более часто используемые опции и опции для продвинутого использования.

• Некоторые формы в командной строке могут быть неоднозначными; инструменты могут пытаться хитро разрешать такие случаи. В целом инструментам рекомендуется не поддерживать сочетания, которые могут быть неоднозначными, а пользователям рекомендуется не использовать формы, которые могут быть неоднозначными. Например, инструменты, поддерживающие старую краткую форму опции -cp для classpath, могут решить не поддерживать одновременно -c и -p как односимвольные формы новых опций.

• Существующие опции, определённые в существующих инструментах, будут поддерживаться, пока их не выведут из употребления или не заменят; решение принимается в каждом случае отдельно. В некоторых случаях этого может не произойти никогда.

HotSpot VM будет принимать через JNI Invocation API подмножество этих правил, в котором новые опции задаются длинным именем, а в качестве разделителя для значения аргумента используется =. HotSpot VM не будет менять форму ни одной из текущего набора опций -XX.

Форма с '=' также упростит передачу опций из инструмента, отличного от программы запуска, в нижележащую VM с помощью -J. Например, можно использовать одну опцию J, как в -J--<name>=<value>, вместо двух опций -J, как раньше: -J-<name> -J<value>. Форма = также позволяет использовать общую форму для набора опций, которые могут передаваться программе запуска Java, HotSpot VM (через интерфейс JNI) и таким инструментам, как javac.

Модуль jdk.internal.opt содержит копию библиотеки JOptSimple для модулей JDK, предоставляющих инструменты командной строки.

Общие опции

Реализация в JDK системы Java Platform Module System (модульная система платформы Java) вводит ряд новых опций для настройки модульной системы.

Любой инструмент, который позволяет настраивать какой-либо аспект модульной системы, должен по возможности предоставлять опцию, согласованную с другими инструментами с эквивалентной функциональностью. Как базовый минимум, все инструменты и API должны поддерживать опцию в длинной форме с '=' для отделения аргумента.

Набор общих опций приведён ниже. Примечание: список лишь указывает имена опций и общий вид аргументов, которые они могут принимать. Точные подробности этих опций описаны в других местах, например в JEP 261 или в документации конкретного инструмента, предоставляющего опцию.

Не все инструменты могут поддерживать все эти опции. Некоторые инструменты могут не поддерживать односимвольную форму, если она конфликтует с ранее определённой опцией.

• --module-path <path>,   -p <path>

  Задаёт путь к модулям приложения.

• --upgrade-module-path <path>

  Задаёт путь к обновляемым модулям.

• --add-modules <module>(,<module>)*

Задаёт корневые модули, которые нужно разрешить в дополнение к начальному модулю.

• --limit-modules <module>(,<module>)*

  Ограничивает множество наблюдаемых модулей.

• --add-reads <module>=<target-module>(,<target-module>)*

  Добавить ребро чтения от <module> к каждому <target-module>.

• --add-exports <module>/<package>=<target-module>(,<target-module>)*

  Добавить квалифицированный экспорт <package> из <module> в <target-module>.

• --patch-module <module>=<file>(:<file>)*

  Переопределить или дополнить модуль классами и ресурсами из JAR-файлов или каталогов.

Кроме того, инструменты, которые сейчас поддерживают опцию -classpath, должны поддерживать эквивалентную ей опцию в длинной форме нового стиля:

• --class-path <path>

Поскольку -cp уже поддерживается как краткая форма -classpath, односимвольная форма введена не будет.

Все инструменты должны предоставлять хотя бы какую-то справку по командной строке. Как минимум должно поддерживаться следующее.

• --help

Со временем в этот список могут быть добавлены и другие опции, общие для разных инструментов.

@-файлы

Пользователи иногда упираются в системные ограничения на длину командной строки, когда составляют командную строку с большим количеством опций или с длинными аргументами опций для конкретного инструмента.

Инструменты, для которых это частая проблема, могут поддерживать «файлы аргументов», или «@-файлы», содержащие строки, которые подставляются вместо аргумента @file. Инструментам рекомендуется поддерживать единый синтаксис токенов внутри таких файлов аргументов.

Справка по командной строке

Инструменты должны поддерживать справку по командной строке с опцией --help. Некоторые опции принимают сложные структурированные значения. Для отображения таких структурированных значений справка по командной строке должна использовать следующие правила:

• Показывать имена заполнителей в виде <name>.

• Использовать круглые скобки для группировки: (...)

• Использовать * для повторения ноль или более раз.

Инструменты должны следить, чтобы вывод справки по командной строке умещался по ширине терминала с настройками по умолчанию: обычно это 80 символов.

Инструменты, показывающие справку по командной строке для опции в длинной форме, принимающей аргумент, обычно должны показывать опцию с пробелом в качестве разделителя аргумента и в конце давать примечание, что разделителем также может быть =.

Инструменты, предоставляющие эквивалентные опции, должны выводить одинаковый текст справки по командной строке.