Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated docs to match new and updated templates #193

Merged
merged 16 commits into from
Sep 23, 2024
Merged

Updated docs to match new and updated templates #193

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
7c04765
Removed setting up Debug steps
clicketyclackety Sep 5, 2024
0ad8b0e
Added footer to your first plugin windows
clicketyclackety Sep 5, 2024
47f9a34
Added -sample to args
clicketyclackety Sep 5, 2024
6f01558
VSCode formatting
clicketyclackety Sep 5, 2024
792beba
Added Footer to Your First Plugin Mac
clicketyclackety Sep 5, 2024
532804e
Updated Guide with better images to suit using -sample
clicketyclackety Sep 5, 2024
55e32f1
Improved Stop debugging step
clicketyclackety Sep 5, 2024
94c64d1
Updated Your First Plugin to use -sample code
clicketyclackety Sep 5, 2024
cec59c6
Updated incorrect step, and updated numbers
clicketyclackety Sep 23, 2024
56fb974
Fixed some incorrect instructions and improved Stop instruction
clicketyclackety Sep 23, 2024
adbacd6
Corrections for Windows
clicketyclackety Sep 23, 2024
cd79523
Updated screenshot in windows guide
clicketyclackety Sep 23, 2024
49cc88a
Updated settings screenshot for new addon
clicketyclackety Sep 23, 2024
2908b71
Updated the Component Anatomy
clicketyclackety Sep 23, 2024
ed63269
Updated list numbers
clicketyclackety Sep 23, 2024
4d9f0f8
Merge branch 'main' into callum/remove-vscode
clicketyclackety Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 47 additions & 127 deletions content/en/guides/grasshopper/your-first-component-mac/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,187 +30,107 @@ toc_type = "single"
## Prerequisites

It is presumed you already have the necessary tools installed and are ready to go. If you are not there yet, see [Installing Tools (Mac)](/guides/rhinocommon/installing-tools-mac).



## HelloGrasshopper

We will use Visual Studio Code and the dotnet Rhino Grasshopper template to create a new, basic, Grasshopper component called *HelloGrasshopper*.

If you are familiar with Visual Studio Code, these step-by-step instructions may be overly detailed for you. The executive summary: create a new Solution using the Grasshopper Component dotnet template, build and run, and then make a change.

We are presuming you have never used Xamarin Studio before, so we'll go through this one step at a time.
We will use Visual Studio Code and the dotnet Rhino Grasshopper template to create a new, basic, Grasshopper component called _HelloGrasshopper_.

If you are familiar with Visual Studio Code, these step-by-step instructions may be overly detailed for you. The executive summary: create a new Solution using the Grasshopper Component dotnet template, build and run, and then make a change.

We are presuming you have never used Visual Studio Code before, so we'll go through this one step at a time.

### Download the required template

1. Launch Visual Studio Code.
1. Open *Visual Studio Code's Terminal* via *Terminal (menu entry)* > *New Terminal*, or using the command palette _(⌘ ⇧ P)_ and search for "Terminal".
1. Open _Visual Studio Code's Terminal_ via _Terminal (menu entry)_ > _New Terminal_, or using the command palette _(⌘ ⇧ P)_ and search for "Terminal".
1. Inside Terminal, run:
``` pwsh
dotnet new install Rhino.Templates
```

```pwsh
dotnet new install Rhino.Templates
```

### Starting the Project

1. Create a folder on your mac where you would like your project to live. Name the folder `HelloGrasshopper`.
1. If you have not done so already, *launch Visual Studio Code*.
1. Now we can open our new folder, navigate to *File* > *Open Folder* and choose the folder we just created.
1. Open Terminal via *Terminal* > *New Terminal*, or using the command palette _(⌘ ⇧ P)_ and search for "Terminal".
1. If you have not done so already, _launch Visual Studio Code_.
1. Now we can open our new folder, navigate to _File_ > _Open Folder_ and choose the folder we just created.
1. Open Terminal via _Terminal_ > _New Terminal_, or using the command palette _(⌘ ⇧ P)_ and search for "Terminal".
1. Enter the following command into the Terminal:
``` pwsh
dotnet new grasshopper --version 8
```
6. In our Folder explorer, we should see the project appear as Visual Studio Code discovers the files.
```pwsh
dotnet new grasshopper --version 8 -sample
```
1. In our Folder explorer, we should see the project appear as Visual Studio Code discovers the files.
1. Expand the Solution Explorer, this is the best way to interact with C# projects on Mac in Visual Studio Code.



### Setting up Debug

1. Create a folder called *.vscode* in the solution directory.
{{< call-out hint "Can't see the folder?" >}}
If you cannot see the *.vscode* folder, toggle hidden folders in Finder: click on your Desktop and press _⌘ ⇧ ._ (`command` + `shift` + `period`)
{{< /call-out >}}
1. We will need to create three new files in the *.vscode* new folder: *settings.json*, *tasks.json*, and *launch.json*...
1. Create *settings.json* with the following contents:
``` json
{
// This file will specify the solution we use to build
"dotnet.defaultSolution": "HelloGrasshopper.sln"
}
```
4. Create *tasks.json* with the following contents:
``` json
{
"version": "2.0.0",
"tasks": [
{
"label": "build-plugin-netcore",
// This will ensure the project is built before we try to debug it
"command": "dotnet build ${workspaceFolder}/*.csproj -f net7.0",
"type": "shell",
"args": [],
"problemMatcher": [
"$msCompile"
],
"presentation": {
"reveal": "always"
},
"group": "build"
}
]
}
```
5. Create *launch.json* with the following contents:
``` json
{
"version": "0.2.0",
"configurations": [
{
"name": "Run GH 8 (Mac)",
"type": "coreclr",
"request": "launch",
"preLaunchTask": "build-plugin-netcore",
// Launches Rhino for us
"program": "/Applications/Rhino 8.app/Contents/MacOS/Rhinoceros",
// See : http://docs.mcneel.com/rhino/8mac/help/en-us/index.htm#information/startingrhino.htm
"args": ["-runscript=_Grasshopper"],
"cwd": "${workspaceFolder}",
"stopAtEntry": false,
"console": "internalConsole",
// RHINO_PACKAGE_DIRS is required for Multi-Targeted plugins
// This is what enables Rhino to register our Plug-in
"env": {
"RHINO_PACKAGE_DIRS": "${workspaceFolder}/bin/Debug/"
}
},
],
"compounds": []
}
```
6. The Folder Explorer should look like below (Note that we cannot see *.vscode* in the Solution Explorer)

![New Project](/images/your-first-plugin-mac-02.png)



### Boilerplate Build

{{< call-out hint "Build Issue?" >}}
Older Rhino Templates do not have System.Drawing.Common referenced.
To add them to your project run the command **dotnet add package System.Drawing.Common -v 7.0.0** in the terminal.
{{< /call-out >}}

1. Before we do anything, let's *Run and Debug* HelloGrasshopper to make sure everything is working as expected. We'll just build the boilerplate Plugin template. Click the *Run and Debug* button on the left hand side of Visual Studio Code and then the green play button in the newly opened panel.
1. Before we do anything, let's _Run and Debug_ HelloGrasshopper to make sure everything is working as expected. We'll just build the boilerplate Plugin template. Click the _Run and Debug_ button on the left hand side of Visual Studio Code and then the green play button in the newly opened panel.

![New Project](/images/your-first-component-mac-01.png)
![New Project](/images/your-first-component-mac-01.png)

1. *Rhinoceros and Grasshopper* launch.
1. _Rhinoceros and Grasshopper_ launch.
1. We will find the HelloGrasshopper Component under **Category / SubCategory**

![Solution Anatomy](/images/your-first-component-mac-02.png)

4. Adding the component to the canvas will perform no action
![Solution Anatomy](/images/your-first-component-mac-02.png)

![Solution Anatomy](/images/your-first-component-mac-03.png)

5. *Quit* Rhinoceros. This stops the session. Go back to *Visual Studio Code*. Let's take a look at the Plugin Anatomy.
4. Adding the component to the canvas will run the component and output some interesting geometry in the Rhino Viewport

![Solution Anatomy](/images/your-first-component-mac-03.png)

5. Press Stop Debugging _(⇧ F5)_, in Visual Studio Code, signified by the Red Square in the debug toolbar. This stops the debugging session. Now let's n take a look at the Plugin Anatomy.

### Component Anatomy
Use the **Solution Explorer** to expand the **Solution** (*.sln*) so that it looks like this...

![Solution Anatomy](/images/your-first-component-mac-04.png)

1. The **HelloGrasshopper** solution (*.sln*)
1. The **HelloGrasshopper** project (*.csproj*) has the same name as its parent solution...this is the project that was created for us by the template earlier.
1. **References**: Just as with most projects, you will be referencing other libraries. The template added the necessary references to create a basic Grasshopper component.
1. **Grasshopper** is the Rhino for Mac main grasshopper DLL. Classes in this DLL are subclassed and used by your custom component.
1. **HelloGrasshopperComponent.cs** is where a custom `Grasshopper.Kernal.GH_Component` subclass is defined. Your project may contain multiple subclasses of GH_Component if you want to ship multiple components in a single *gha*.
1. **HelloGrasshopperInfo.cs** defines general information about this *gha*.
Use the **Solution Explorer** to expand the **Solution** (_.sln_) so that it looks like this...

![Solution Anatomy](/images/your-first-component-mac-04.png)

1. The **HelloGrasshopper** solution (_.sln_)
1. The **HelloGrasshopper** project (_.csproj_) has the same name as its parent solution...this is the project that was created for us by the template earlier.
1. **References**: Just as with most projects, you will be referencing other libraries. The template added the necessary references to create a basic Grasshopper component.
1. **Grasshopper** is the Rhino for Mac main grasshopper DLL. Classes in this DLL are subclassed and used by your custom component.
1. **HelloGrasshopperComponent.cs** is where a custom `Grasshopper.Kernal.GH_Component` subclass is defined. Your project may contain multiple subclasses of GH*Component if you want to ship multiple components in a single \_gha*.
1. **HelloGrasshopperInfo.cs** defines general information about this _gha_.

### Debugging

1. Add a semicolon to line 47 of *HelloGrasshopperComponent.cs*, and set a breakpoint on it. You set breakpoints in Visual Studio Code by clicking in the gutter to the left of the line numbers.
![Set a breakpoint](/images/your-first-component-mac-05.png)
1. *Run and Debug*. our project. The breakpoint will become an empty circle, this is because our code has not been loaded yet. Once we hit the breakpoint once and continue, the code will be loaded until we end our Debug session.
![Set a breakpoint](/images/your-first-component-mac-06.png)
1. Click New Model. And then run our *HelloDrawLine* command. Create the two points and as soon as you do, you should hit your breakpoint and rhino will pause
![Hit a breakpoint](/images/your-first-component-mac-07.png)
1. With Rhino paused, in *Visual Studio Code* we will see *Locals* under *Variables*. You can inspect all of the values for the variables in your component.
![Locals panel](/images/your-first-component-mac-08.png)
4. Let's Continue Execution in Rhino by pressing the Green *Play* button in the Debug Bar
1. Control is passed back to *Rhino* and your command finishes. *Quit* Rhino or *Stop* the debugging session.
1. Add a breakpoint to line 75 of _HelloGrasshopperComponent.cs_. You set breakpoints in Visual Studio Code by clicking in the gutter to the left of the line numbers.
![Set a breakpoint](/images/your-first-component-mac-05.png)
1. _Run and Debug_. our project. The breakpoint will become an empty circle, this is because our code has not been loaded yet. Once we hit the breakpoint once and continue, the code will be loaded until we end our Debug session.
![Set a breakpoint](/images/your-first-component-mac-06.png)
1. Rhino and Grasshopper should open, if Grasshopper does not open, click "New Model" and run the _Grasshopper_ command.
1. Place our sample component _HelloGrasshopperComponent_ and as soon as you do, you should hit your breakpoint and rhino/Grasshopper will pause (You may need to drag the Grasshopper window out of the way to see Visual Studio Code)
![Hit a breakpoint](/images/your-first-component-mac-07.png)
1. With Rhino/Grasshopper paused, in _Visual Studio Code_ we will see _Locals_ under _Variables_. You can inspect all of the values for the variables in your component.
![Locals panel](/images/your-first-component-mac-08.png)
1. Let's Continue Execution in Rhino and Grasshopper by pressing the Green _Play_ button in the Debug Bar
1. Control is passed back to _Rhino / Grasshopper_ and your command finishes. Now _Stop_ _(⇧ F5)_ the debugging session as before.
1. **Remove** the breakpoint you created above by clicking on it in the gutter.

**Congratulations!** You have just built your first Grasshopper component for Rhino for Mac. **Now what?**


**Congratulations!** You have just built your first Grasshopper component for Rhino for Mac. **Now what?**

## Next Steps

### Adding components

A single gha can contain more than one [GH_Component](https://mcneel.github.io/grasshopper-api-docs/api/grasshopper/html/T_Grasshopper_Kernel_GH_Component.htm) derived class (and commonly does). Dotnet has support for adding more custom components to your project.

1. Open *Visual Studio Code's Terminal* via *Terminal (menu entry)* > *New Terminal*, or using the command palette _(⌘ ⇧ P)_ and search for "Terminal".
1. Open _Visual Studio Code's Terminal_ via _Terminal (menu entry)_ > _New Terminal_, or using the command palette _(⌘ ⇧ P)_ and search for "Terminal".
1. Inside Terminal, run:

``` pwsh
dotnet new ghcomponent -n "NewComponent"
```
```pwsh
dotnet new ghcomponent -n "NewComponent"
```

1. A new component will appear called *NewComponent*
1. A new component will appear called _NewComponent_

## Related topics

This article is focused on initial setup and debugging a Grasshopper component in Rhino for Mac. For further reading on customizing your component please see:
This article is focused on initial setup and debugging a Grasshopper component in Rhino for Mac. For further reading on customizing your component please see:

- [Grasshopper](/guides/grasshopper/csharp-essentials/)
- [Distributing your Plugin](/guides/yak/creating-a-rhino-plugin-package/)
Loading