Speckle | SketchUp

Speckle is the first AEC data hub that connects with your favorite AEC tools. Speckle exists to overcome the challenges of working in a fragmented industry where communication, creative workflows, and the exchange of data are often hindered by siloed software and processes. It is here to make the industry better.

Connector for SketchUp

Repo structure

This is the beginning of the Speckle SketchUp Connector. It is still in very early development and is not ready for general use. This repo is split into three parts:

1. Speckle Connector extension

Includes the ruby source files to run extension on SketchUp environment. SketchUp Extensions are composed of a .rb file as entry and folder that .rb file refers to. In our case entry file is speckle_connector.rb that responsible to register Speckle Connector extension to SketchUp and also it shows address to where extension will start to read extension. Source folder is speckle_connector.

2. User Interface

Includes the Vue frontend lives in the ui folder.

3. SketchUp Sqlite3 extension submodule

Includes source codes of base SQLite3 C/C++ library and ruby compiler files to be able to run SQLite3 functionality on SketchUp in the same ruby module like SpeckleConnector::Sqlite3::Database. By this way we use extensions as native part of the source ruby code.

After building sqlite3.sln file, compiled sqlite3.so (for Windows) and sqlite3.bundle (for OSX) dynamic library files are created by solution to place them into source code into speckle_connector/src/ext. Building this project should be only happen when SketchUp starts to support newer Ruby versions (currently it is 2.7).

Other repos

Make sure to also check and ⭐️ these other Speckle next generation repositories:

• speckle-sharp-connectors: .NET connectors and desktop UI
• speckle-sharp-sdk: our .NET SDK for next gen connectors and development
• speckle-powerbi: PowerBi connector
• and more connectors & tooling!

Contribution Guide

Before start to contribute, it is better to understand how align with other contributors. It will make easier job of reviewer when you submit an issue or PR. If it is your first repo to contribute Speckle environment make sure that you read Contribution Guideline.

Additionally as mentioned on Repo Structure, this repo includes a submodule. Contributions on this source files should be done on the sketchup-sqlite by creating issues and PRs on it. If it is your first time works with submodules, please read git docs briefly to get some insight about it.

Development

The following instructions are for development in Windows (not WSL) using Visual Studio Code. If you would like to contribute instructions for other development environments, feel free to submit a PR.

Environment Setup

Ruby can be installed on Windows using the installer here. Install it with the DevKit and complete the full installation as per instructions.

This should have also have set up the package installer gem and interactive ruby irb. Double check that everything has been installed correctly.

ruby -v
gem -v
irb -v

Let's also install our first gem bundler which is a package manager that will help us with development.

gem install bundler

Editor Setup

Clone this repo and run:

bundler install

This will install all the necessary packages for the connector.

Next, install the Sketchup Ruby Debugger. You can find installation instructions here. This will involve downloading the dll and copying it into the SketchUp installation directory:

C:\Program Files\SketchUp\SketchUp 20XX\

You can now open up the repo in VS Code or you can use JetBrains' tools RubyMine and Webstorm.

If you will use VS Code, make sure you've installed the Ruby extension for VS Code.

Loading the Speckle Connector Plugin

1. Find already prepared speckle_connector_loader.rb file on the _tools folder.
2. Copy this Ruby file into your SketchUp Plugins directory. You will likely find this at: C:\Users\{YOU}\AppData\Roaming\SketchUp\SketchUp 20XX\SketchUp\Plugins
3. Update below line on the copied file with your local git file.

    speckle_path = File.join(home_folder, 'Git', 'Speckle', 'speckle-sketchup')
   

   By this way SketchUp will directly read your local repository. Do not forget, this file also loads additional tools on the _tools folder. Those are will be only available on dev mode.

Due to the fact that Ruby is interpreted language, so you can reload your file(s) when you changed them. There are different kinds of ways to reload them.

1. To reload the whole plugin files while SketchUp is running, open up the Ruby console and run the following:

   SpeckleConnector.reload
   

2. To reload only specific files, use jf ruby toolbar plugin that already available on SketchUp toolbar.

User Interface

If it is your first time you cloned the project and willing to see Speckle UI, you should make sure that you compiled the vue.js project in the ui folder.

To run the ui, create a .env based on .env-example and paste in your Speckle token. Then:

cd ui
npm run serve

Debugging

To run SketchUp in debug mode, you will run the task specified in tasks.json. Before you do this, make sure your integrated shell for tasks is using powershell. You can specify this by adding the following option to your workspace's settings.json

"terminal.integrated.automationShell.windows": "powershell.exe",

To start the task, use the keyboard shortcut ctrl + shift + p to open up the Command Palette. Search for Tasks: Run Task and select it:

Then choose the Debug Sketchup 2021 task to run it:

Once Sketchup has launched, start the Listen for rdebug-ide debug configuration. Once the debugger has connected, you'll be able to debug the connector normally.

Make sure you run the ui before starting the SketchUp Connector

cd ui
npm run serve

Code Quality

Tracking your code quality before merging any code to main branch might not seem at the first time crucial, but when repo became huge, you might have many spaghetti code and technical depth. It is always better to keep your work tough from the beginning. For this reason some workflows have already setup on CI, those workflows must be passed before considering to merge.

To track your code quality locally,

1. Make sure that you do not have any RuboCop issue, run below

   bundle exec rake 
   

2. To check overall state of repository by RubyCritic, run below

   rake rubycritic