Primeros pasos para desarrollar extensiones con la API Ruby de SketchUp: guía paso a paso

¿Qué aprenderás en esta guía?

La API Ruby de SketchUp es una interfaz que permite interactuar con los modelos y la aplicación SketchUp. Según la documentación oficial de SketchUp, la API puede utilizarse dentro de la aplicación; no es una herramienta independiente. Por eso, el primer paso para empezar a desarrollar es decidir cómo convertir en una extensión de SketchUp la tarea que se quiere automatizar.

Esta guía se centra en conocer los límites de la API, elegir los recursos oficiales adecuados para empezar, preparar el IDE y la depuración y, después, configurar el proceso de pruebas. Como las fuentes no detallan la compatibilidad de la API ni los pasos de instalación para una versión concreta de SketchUp, aquí no se presuponen versiones ni rutas de menú.

Requisitos y preparativos

• SketchUp: La API Ruby se ejecuta dentro de SketchUp y no puede utilizarse por sí sola. Por tanto, se necesita la aplicación SketchUp para desarrollar y probar.

• Conocimientos de Ruby: Las fuentes describen la API como una interfaz para Ruby. No indican que se necesiten conocimientos avanzados de Ruby, pero el código de la extensión que se desarrolle utilizará este lenguaje.

• Recursos para desarrolladores: La documentación oficial de la API Ruby de SketchUp, Ruby API Overview y SketchUp Developer Center son algunos de los recursos disponibles para empezar.

• IDE y depuración: SketchUp proporciona una interfaz de depuración que puede utilizarse con IDE y editores compatibles con el protocolo Ruby Debug. Se ofrece un ejemplo de configuración para RubyMine y un ejemplo de proyecto para VSCode.

• Pruebas: Puede resultar difícil probar código que se ejecuta dentro de SketchUp con los flujos de pruebas estándar, diseñados para la consola de Ruby fuera de SketchUp. Para este uso, TestUp ofrece un wrapper basado en Minitest y una interfaz gráfica para gestionar las pruebas.

Las fuentes no especifican precios, requisitos de cuenta ni una tabla de compatibilidad con todas las versiones de SketchUp. Por eso, antes de empezar un proyecto, conviene consultar también la documentación y los ejemplos oficiales de la API para la versión de SketchUp prevista.

Pasos para desarrollar con la API Ruby de SketchUp

1. Define la tarea que quieres automatizar

Primero, concreta qué tarea repetitiva facilitará la extensión. SketchUp Developer Center señala que las extensiones pueden automatizar flujos de trabajo e integrarse con datos externos. Es un punto de partida útil para definir el alcance del proyecto; sin embargo, hay que consultar la documentación correspondiente para confirmar qué métodos de la API permiten realizar la operación prevista.

Mantener el alcance reducido al principio facilita determinar qué entradas recibirá la extensión y qué resultados ofrecerá al usuario. Se trata de una recomendación para planificar el proyecto, no de una función específica de la API ni de un paso de menú de SketchUp.

2. Empieza por la guía general y los ejemplos oficiales

Ruby API Overview, dentro de la documentación de la API Ruby de SketchUp, es un punto de referencia fundamental. La documentación oficial también enlaza con ejemplos y tutoriales que explican conceptos y casos de uso habituales. Para tu primera implementación, revisa los ejemplos y selecciona los que se relacionen con el objetivo de la extensión; en lugar de dar por sentada una clase, un método o un comportamiento que no aparezca en la documentación, comprueba su descripción.

SketchUp Developer Center reúne también contenidos introductorios, extensiones de ejemplo y recursos sobre la API. Estos materiales pueden ayudar a entender cómo ofrecer nuevas herramientas y funciones en SketchUp mediante una extensión. Si quieres compartir la extensión con otras personas, Developer Center también contempla la opción de publicarla en Extension Warehouse.

3. Prepara tu IDE para la API

Los stubs de la API Ruby están disponibles para ayudar al entorno de desarrollo a reconocer la API de SketchUp. Las fuentes oficiales incluyen instrucciones para preparar un proyecto en RubyMine y un ejemplo de proyecto para VSCode. Elige el ejemplo adecuado para el IDE que utilizas y sigue los pasos de configuración documentados.

También se puede utilizar la interfaz SketchUp Ruby Debugger para depurar. Está diseñada para funcionar con las funciones de depuración de editores e IDE compatibles con el protocolo Ruby Debug. Las fuentes no exigen el uso de un IDE específico, así que puedes elegirlo en función de las herramientas que ya utilice el equipo de desarrollo.

4. Ejecuta las llamadas a la API en el hilo principal

La documentación oficial de la API advierte que todas las interacciones realizadas con la API Ruby deben ejecutarse en el hilo principal. De lo contrario, pueden producirse comportamientos inesperados e inestabilidad en la aplicación. Ten en cuenta este requisito al diseñar la extensión; sobre todo, si planeas dividir el flujo de trabajo en distintas partes, consulta la documentación oficial para confirmar cómo deben ejecutarse las operaciones correspondientes.

Esta advertencia no es un detalle que solo haya que revisar antes de publicar: debe formar parte del plan de desarrollo y pruebas. Aunque la extensión produzca el resultado esperado, no se debe ignorar el requisito del hilo principal.

5. Ejecuta las pruebas dentro de SketchUp

La fuente oficial señala que las pruebas de Ruby ejecutadas fuera de SketchUp pueden no ser suficientes para probar código que debe ejecutarse dentro de la aplicación. TestUp responde a esta necesidad con una solución basada en Minitest y una interfaz gráfica para gestionar las pruebas. Crea casos de prueba que permitan verificar el comportamiento previsto de la extensión y evalúalos en las condiciones de uso dentro de SketchUp.

Como las fuentes no incluyen ejemplos detallados de cómo escribir cada tipo de prueba en TestUp, al configurar la infraestructura de pruebas conviene seguir la información del repositorio oficial de la herramienta y los tutoriales de la API. Así se evita presuponer una sintaxis de pruebas o un paso de instalación automática que no aparezca en la documentación.

6. Verifica el alcance si necesitas compatibilidad con LayOut

Desde SketchUp 2018, la API Ruby también permite crear y editar documentos de LayOut. Se indica asimismo que la API Ruby de LayOut solo puede utilizarse dentro de SketchUp. Si la extensión debe interactuar con documentos de LayOut, considera esta función como un requisito independiente y consulta la documentación LayOut API Overview. Como las fuentes no proporcionan más detalles sobre compatibilidad entre versiones ni instrucciones de uso, es necesario acudir a la documentación oficial correspondiente.

Errores frecuentes

• Intentar ejecutar la API de forma independiente: La API Ruby no es una herramienta independiente que pueda utilizarse sin SketchUp.

• Pasar por alto la advertencia sobre el hilo principal: Las interacciones con la API deben realizarse en el hilo principal; hacerlo de otro modo puede causar inestabilidad en la aplicación.

• Considerar suficientes las pruebas fuera de SketchUp: Para el código que se ejecuta dentro de SketchUp, evalúa opciones de prueba dentro de la aplicación, como TestUp.

• Dar por sentados detalles no documentados: Comprueba la documentación oficial de la API para consultar versiones, métodos y compatibilidad.

• Omitir la configuración del IDE: Hay stubs de la API, ejemplos para IDE y guías de depuración disponibles para preparar el entorno de desarrollo.

Próximos pasos

Cuando hayas terminado la primera extensión, considera las opciones de publicación si se ajustan a tu objetivo de uso. SketchUp Developer Center indica que las extensiones se pueden compartir en Extension Warehouse. Si planeas distribuirla fuera de Extension Warehouse, Developer Center también ofrece orientación sobre el proceso de firma digital y el certificado de seguridad.

Para funciones más complejas, las fuentes oficiales incluyen ejemplos de extensiones Ruby C. Se presentan como una opción para funciones más complejas y posibles mejoras de rendimiento; no se indica que sean necesarias en todos los proyectos. Primero, determina los límites de una solución con la API Ruby y, después, consulta los ejemplos pertinentes para seguir un proceso de desarrollo más controlado.

Fuentes y licencia

Esta guía se ha adaptado al turco a partir de la documentación oficial de la API Ruby de SketchUp y de los recursos para desarrolladores de SketchUp Developer Center. En los registros de las fuentes, ambas páginas aparecen marcadas como “libres”; no se especifica ninguna licencia Creative Commons.