search

compas-dev / compas-actions.ghpython_components

Trying to make Grasshopper development version-control friendlier since 1337.
MIT License
39 stars 6 forks source link

readme

GHPython Componentizer

A github action to make Grasshopper development 165% [1] version-control friendlier and 83% more pleasant.

Imagine if you could write your grasshopper components in Python code (both IronPython for RhinoV7 and less, or CPython for RhinoV8) in an actual text file with a powerful editor? Git wouldn't hate you and life would be so much beautiful. 🐵

Well, here's an action for you then! 🦸‍♀️

Usage

Usage from Github Actions

The recommended way to use this tool is as a Github Action. It needs to be run on a windows runner and IronPython/NuGet or Python3/pythonnet/Nuget depending of which component you want to build, needs to be pre-installed.

Copy the following workflow code into a .github/workflows/main.yml file in your repository. Make sure you have the components definition (see below for details) stored in a source folder. Replace the source and target to match your folder structure. To specify the interpreter to use, you can define the action parameter interpreter to either ironpython or python3 (by default it is ironpython).

For IronPython (RhinoV7 and less):

on: [push]

jobs:
  build_ipy_ghuser_components:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v2
      - uses: NuGet/setup-nuget@v1.0.5

      - name: Install IronPython
        run: |
          choco install ironpython --version=2.7.8.1

      - uses: compas-dev/compas-actions.ghpython_components@v5
        with:
          source: components
          target: build

      # The components have been built at this step.
      # Now you can choose what to do with them, e.g.:
      # upload them as artifacts:
      - uses: actions/upload-artifact@v2
        with:
          name: ipy_ghuser-components
          path: build

For Python3 (RhinoV8):

on: [push]

jobs:
  build_cpy_ghuser_components:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v2
      - uses: NuGet/setup-nuget@v1.0.5

      - name: Install CPython and pythonnet package
        run: |
          choco install python --version=3.9.10
          python -m pip install pythonnet==3.0.3

      - uses: compas-dev/compas-actions.ghpython_components@v5
        with:
          source: components
          target: build
          interpreter: cpython  # optional, defaults to ironpython

      - uses: actions/upload-artifact@v2
        with:
          name: cpy_ghuser-components
          path: build

Commit, push and enjoy! 🍿

Usage on the command line

Alternatively, you can also use this tool directly from the command line. Make sure to have IronPython or Python3/pythonnet installed and the GH_IO.dll assembly available. Then start the script pointing it to a source and target folder, e.g.:

ipy componentize_ipy.py examples/ipy build
python componentize_cpy.py examples/cpy build

Optionally, tag it with a version:

ipy componentize_ipy.py examples/ipy build --version 0.1.2
python componentize_cpy.py examples/cpy build --version 0.1.2

An optional name prefix can help tell components apart from other similarly named ones:

ipy componentize_ipy.py examples/ipy build --prefix "(PACKAGE-NAME)"
python componentize_cpy.py examples/cpy build --prefix "(PACKAGE-NAME)"

How to create components

  1. Create a folder to contain your components
  2. Each component goes into its own folder
  3. The name of the folder determines the name of the .ghuser file created
  4. Inside the component folder:
    1. Create a metadata.json file containing all required details of the component
    2. Add a lovely icon named icon.png (24x24)
    3. Add a code.py file with the Python script of the component
  5. Use this action setting source and target folder inputs
  6. Be happy 🎈

Where are the generated components?

This action stores the generated components under the target folder, but these files only exist for the duration of the build. After that -if no further steps are taken- they will be automatically deleted.

The simplest option to keep the generated files is to use the actions/upload-artifact@v2 action and upload them as artifacts. Check this for more details and in particular, the details about where to find the uploaded artifacts.

An alternative is to include them in your packaging steps, e.g. calling python setup.py clean --all sdist bdist_wheel right after having generated the components (and assuming your setup is configured accordingly, will pick up the components and add them to the pip package. This is a very convenient way that ensures the components are always released from a clean state. An example of this is available on the release workflow of COMPAS.

Specification

Icon

Python code

Supports a small set of templated variables that can be used in code:

Metadata

Caveats

GHUser components have one important limitation: once used in a document, they forget who they are. The don't know they were created out of a ghuser component, they will be simple GHPython components. This has an important consequence: if you update the ghuser components, those already in use will NOT be automatically updated.

License

This package is maintained by Gramazio Kohler Research @gramaziokohler and it is published under an MIT License.

[1] Like, totally scientifically proven. word.