Начало разработки плагинов с SketchUp Ruby API: пошаговое руководство

Чему вы научитесь в этом руководстве?

SketchUp Ruby API — это интерфейс для взаимодействия с моделями и приложением SketchUp. Согласно официальной документации SketchUp, API можно использовать внутри приложения; это не самостоятельный инструмент. Поэтому первый шаг в разработке — определить, как превратить задачу, которую нужно автоматизировать, в плагин для SketchUp.

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

Требования и подготовка

• SketchUp: Ruby API работает внутри SketchUp и не может использоваться самостоятельно. Поэтому для разработки и тестирования понадобится приложение SketchUp.

• Знание Ruby: В источниках API описывается как интерфейс для Ruby. Требование к углублённому знанию Ruby не указано, однако код плагина пишется на Ruby.

• Ресурсы для разработчиков: Среди материалов, с которых можно начать, — официальная документация SketchUp Ruby API, Ruby API Overview и SketchUp Developer Center.

• IDE и отладка: SketchUp предоставляет интерфейс отладки, который можно использовать с IDE и редакторами, поддерживающими протокол Ruby Debug. Для RubyMine есть пример настройки, а для VSCode — пример проекта.

• Тестирование: Код, работающий внутри SketchUp, может быть сложно проверять стандартными сценариями тестирования, рассчитанными на Ruby-консоль вне SketchUp. Для такого случая TestUp предлагает обёртку на базе Minitest и графический интерфейс для управления тестами.

В источниках не указаны стоимость, требования к учётной записи или таблица совместимости со всеми версиями SketchUp. Поэтому перед началом проекта стоит отдельно изучить официальную документацию API и примеры для целевой версии SketchUp.

Этапы разработки с SketchUp Ruby API

1. Определите задачу для автоматизации

Сначала уточните, какую повторяющуюся задачу должен упростить плагин. SketchUp Developer Center отмечает, что плагины могут автоматизировать рабочие процессы и интегрироваться с внешними данными. Это полезная отправная точка для определения объёма проекта, однако способы реализации конкретной задачи с помощью API необходимо проверять в соответствующей документации.

На первом этапе небольшой объём работ поможет понять, какие данные будет получать плагин и какой результат он должен предоставлять пользователю. Это рекомендация по планированию проекта, а не описание конкретной возможности API или пункта меню SketchUp.

2. Начните с официального обзора и примеров

Ruby API Overview в документации SketchUp Ruby API — основная отправная точка. Официальная документация также содержит ссылки на примеры и обучающие материалы, описывающие распространённые сценарии и концепции. При создании первой реализации изучите примеры и выберите те, что относятся к цели плагина. Не полагайтесь на неподтверждённые предположения о классах, методах или поведении, которые не описаны в документации, — сначала проверьте их.

В SketchUp Developer Center собраны вводные материалы, примеры расширений и ресурсы по API. Они помогут разобраться в том, как расширения добавляют в SketchUp новые инструменты и функции. Если вы планируете делиться расширением с другими пользователями, Developer Center также предлагает вариант публикации через Extension Warehouse.

3. Подготовьте IDE для работы с API

Ruby stubs API предназначены для того, чтобы среда разработки распознавала SketchUp API. В официальных материалах есть инструкция по настройке проекта в RubyMine и пример проекта для VSCode. Выберите пример для используемой IDE и следуйте описанным шагам настройки.

Для отладки можно использовать интерфейс SketchUp Ruby Debugger. Он предназначен для работы с функциями отладки редакторов и IDE, поддерживающих протокол Ruby Debug. Источники не указывают, что обязательно нужно использовать какую-либо конкретную IDE, поэтому выбор можно сделать исходя из инструментов, уже используемых командой разработки.

4. Выполняйте вызовы API в главном потоке

В официальной документации API предупреждают, что все обращения к Ruby API необходимо выполнять в главном потоке. В противном случае возможны непредвиденное поведение и нестабильная работа приложения. Учитывайте это при проектировании плагина. Если вы планируете разделить рабочий процесс на отдельные части, уточните в официальной документации, как выполнять соответствующие операции.

Это требование важно не только проверить перед публикацией — его нужно учитывать при планировании разработки и тестирования. Даже если плагин выдаёт ожидаемый результат, нельзя игнорировать необходимость работы в главном потоке.

5. Запускайте тесты внутри SketchUp

В официальных материалах отмечается, что Ruby-тестов, запускаемых вне SketchUp, может быть недостаточно для проверки кода, который должен выполняться внутри приложения. TestUp решает эту задачу с помощью решения на базе Minitest и предоставляет графический интерфейс для управления тестами. Составьте сценарии, проверяющие ожидаемое поведение плагина, и оцените их в условиях работы внутри SketchUp.

Источники не содержат подробных примеров написания всех типов тестов для TestUp. Поэтому при настройке тестирования следует обращаться к описанию в официальном репозитории инструмента и обучающим материалам по API. Это поможет избежать предположений о синтаксисе тестов или автоматической установке, которые не подтверждены документацией.

6. Если нужна поддержка LayOut, проверьте объём работ

Начиная с SketchUp 2018 Ruby API также позволяет создавать и редактировать документы LayOut. Указано, что LayOut Ruby API тоже можно использовать только внутри SketchUp. Если плагину нужно работать с документами LayOut, рассматривайте эту функцию как отдельное требование и изучите документацию LayOut API Overview. Поскольку источники не приводят более подробных сведений о совместимости версий и порядке использования, за ними следует обращаться к соответствующей официальной документации.

Распространённые ошибки

• Попытка использовать API отдельно от приложения: Ruby API не является самостоятельным инструментом, который можно использовать без SketchUp.

• Игнорирование требования к главному потоку: Взаимодействие с API должно выполняться в главном потоке; иначе приложение может работать нестабильно.

• Уверенность, что тестов вне SketchUp достаточно: Для кода, работающего внутри SketchUp, рассмотрите встроенные варианты тестирования, например TestUp.

• Предположения о неописанных деталях: Проверяйте сведения о версиях, методах и совместимости в официальной документации API.

• Пропуск настройки IDE: Ruby stubs API, примеры проектов для IDE и руководства по отладке помогут подготовить среду разработки.

Что делать дальше

После создания первого плагина оцените возможность его публикации, если этого требует сценарий использования. В SketchUp Developer Center указано, что расширения можно размещать в Extension Warehouse. Если вы планируете распространять расширение за пределами Extension Warehouse, Developer Center также направляет к процессу цифровой подписи и получению сертификата безопасности.

В официальных источниках есть примеры Ruby C extensions для более сложных функций. Они представлены как вариант для реализации более сложных функций и возможного повышения производительности, но не как обязательное решение для каждого проекта. Более контролируемый процесс разработки — сначала определить пределы возможностей Ruby API, а затем изучить соответствующие примеры.

Источники и лицензия

Это руководство адаптировано на турецкий язык на основе официальной документации SketchUp Ruby API и материалов для разработчиков в SketchUp Developer Center. В источниках обе страницы отмечены как «свободные»; конкретная лицензия Creative Commons не указана.