Публичный API V8

Этот документ обсуждает стабильность публичного API V8 и как разработчики могут вносить изменения в него.

Стабильность API

Если V8 в версии Chromium canary оказывается нестабильным, он откатывается к версии V8 предыдущего canary. Поэтому важно поддерживать совместимость API V8 от одной версии canary к другой.

Мы постоянно запускаем бота, который сигнализирует о нарушениях стабильности API. Он компилирует Chromium HEAD с текущей canary версией V8.

Сбои этого бота на данный момент только для информации (FYI), и никакие действия не требуются. Список виновных может быть использован для легкой идентификации зависимых CL в случае отката.

Если вы нарушите работу этого бота, помните, что необходимо увеличить окно между изменением в V8 и соответствующим изменением в Chromium в следующий раз.

Как изменить публичный API V8

V8 используется многими различными интеграторами: Chrome, Node.js, gjstest и др. При изменении публичного API V8 (в основном, файлы в каталоге include/) необходимо гарантировать, что интеграторы смогут плавно обновиться до новой версии V8. В частности, нельзя предполагать, что интегратор обновится до новой версии V8 и одновременно адаптирует свой код к новому API в одной атомарной операции.

Интегратор должен иметь возможность адаптировать свой код к новому API и при этом использовать предыдущую версию V8. Все следующие инструкции основаны на этом правиле.

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

• Добавление нового параметра в функцию безопасно, если параметр имеет стандартное значение.

• Удаление или переименование типов, констант, функций небезопасно. Используйте макросы V8_DEPRECATED и V8_DEPRECATE_SOON, которые вызывают предупреждения на этапе компиляции, когда интегратор вызывает устаревшие методы. Например, предположим, мы хотим переименовать функцию foo в bar. Тогда необходимо выполнить следующие шаги:

  • Добавьте новую функцию bar рядом с существующей функцией foo.
  • Дождитесь, пока CL попадет в Chrome. Адаптируйте Chrome для использования bar.
  • Аннотируйте foo с помощью V8_DEPRECATED("Используйте bar вместо этого") void foo();
  • В том же CL измените тесты, использующие foo, для работы с bar.
  • Напишите в CL мотивацию изменения и инструкции для обновления на высоком уровне.
  • Дождитесь следующей ветки V8.
  • Удалите функцию foo.

  V8_DEPRECATE_SOON является более мягкой версией V8_DEPRECATED. Chrome не сломается с ним, поэтому шаг b не нужен. V8_DEPRECATE_SOON недостаточен для удаления функции.

  Вам все равно нужно аннотировать с помощью V8_DEPRECATED и дождаться следующей ветки перед удалением функции.

  V8_DEPRECATED можно протестировать с использованием флага GN v8_deprecation_warnings. V8_DEPRECATE_SOON можно протестировать с использованием v8_imminent_deprecation_warnings.

• Изменение сигнатур функций небезопасно. Используйте макросы V8_DEPRECATED и V8_DEPRECATE_SOON, как описано выше.

Мы ведем документ, упоминающий важные изменения API для каждой версии V8.

Также существует регулярно обновляемая документация doxygen API.