Package Restore in Grasshopper

by Will Pearson (Last updated:  Wednesday, October 10, 2020)

Overview

For starters, this is less of a developer guide and more of a description of how this feature works, so that you, the developer, can better understand how your package and plug-in needs to be set up in order to leverage it.

It can be frustrating to open a Grasshopper definition only to find that the required plug-ins aren’t installed on the system. The package manager can help by streamlining the process of satisfying those dependencies.

Since Rhino 6, the “Unrecognized Objects” dialog presents the user with an option to download and install missing plug-ins. This feature is called Package Restore.

Grasshopper package restore

Package Restore uses the name, ID and version of the missing plug-ins to search the package server. If any packages match the search query then they will be installed and, if possible, loaded prior to opening the definition1.

Matching

Naming

Ideally, the name of the Grasshopper plug-in and the package will match. In case this isn’t possible – due to either the constraints of the package naming scheme2 or the fact that there are multiple plug-ins in a package each with a different name – the correct package can also be identified by the plug-in ID.

For each .gha file, the plug-in ID is extracted and added to the manifest.yml when you run yak build.

Version numbers

Package version numbers can either follow the Semantic Versioning 2.0.0 (SemVer) spec or they can be four-digits3, as per System.Version. See the package server guide for more details on the allowed version number formats.

The server allows both SemVer and four-digit because some Grasshopper plug-ins will specify their version number as a string in a class derived from GH_AssemblyInfo whereas others will rely on the AssemblyVersionAttribute.

While restoring packages, if a package exists on the server that matches either the name or ID of the missing plug-in, but the exact version doesn’t exist, the latest stable version will be installed.

  1. Added to Grasshopper in December 2019. On-the-fly loading is only possible if another version of the Grasshopper library is not already installed and loaded. Otherwise, Rhino will need to be restarted to load the new version of the library. ↩︎

  2. Package names are pretty strict. They only allow letters, numbers, hyphens and underscores. ↩︎

  3. Support for four-digit (System.Version) version numbers was added in Yak 0.8. ↩︎