Step by step guide to creating a public library / nuget / package for vvvv gamma - October 2022

tutorials
1

This is a complete step by step guide to creating a public library for vvvv gamma.
It assumes you will manage your repo and documentation on github and release the package with nuget.
Current as at 05.10.22 and tested with gamma 2021.4.10

With so many steps and parts from different vendors this is likely to get out of date quickly, but for exactly the same reason I found a step by step guide needed as the complexities can be confusing and there are a lot of sources to jump between.

Prerequisites

  • Basic understanding of what GIT is and what repos are, how to clone, add, commit, push, pull
  • Github.com account (with a username you like as this will be part of the URL to your contribution)
  • Basic understanding of what nugets are and how to install them
  • Nuget.org account
  • Intermediate vvvv gamma skills, to the level where you want to develop a library for others to use. You should have installed and used nuget contributions from others already.

1/Create a vl-libs folder for local library development, and then reference it in args when you open vvvv gamma editor

https://thegraybook.vvvv.org/reference/extending/contributing.html#source-package-repositories

  • Create a folder somewhere you want to use for library development, called vl-libs if you want to follow convention but you can call it something else.
  • Download gamma launcher here Gamma Launcher | vvvv
  • With Gamma launcher open check the settings tab
  • Under 'Package Repositories add your library development folder eg “C:\xprojects\vl-libs” and ensure it’s ticked to be active
  • Under Editable Packages add an entry the intended name of the package you want to create eg VL.MyRepo
  • Back on the Launch tab tick the ‘use repos’ checkbox
  • Launch gamma editor

2/Initial create your repo and setup the folder

  • On github.com create a new repo, name it accordingly, usually ‘VL.MyProject’

  • Recommend using github creation options to create the licence file and readme file as well.

  • Clone the repo into your vl-libs folder

  • Use the vvvv gamma editor to save your main VL file for this library into the root of the folder eg C:/
/vl-libs/VL.MyProject/VL.MyProject.vl

  • Setup subfolders as necessary according to the spec
    Creating a new Library/Package/Nuget | vvvv gamma documentation

! Note with github these days the main branch is called ‘main’ not ‘master’ by default. Much of the vvvv docs still refers to ‘master’ so feel free to swap that for ‘main’ wherever you see it.
I will use ‘main’ in the info below.

! Note2 it’s tempting to edit your readme.md on the nice github web interface but avoid doing this until the end of initial development. Web interface changes will count as a commit that you should have pulled down to your development computer and can cause merge conflicts.

3/Make helppatches and use them as your live development testing environment

  • Create a subfolder in your repo /help
    eg C:/
/vl-libs/VL.MyProject/help

  • Save new gamma patches there starting with either ‘howto bla bla’ or ‘explanation bla bla’
    eg
    ‘HowTo Flip a Pancake’
    ‘Explanation Overview Pancake Nodes’
    see the spec below for more info on this naming convention.
    Providing Help | vvvv gamma documentation

  • These helppatches will need to reference as a dependency your VL development file (VL.MyProject). Just do this the normal way through the depedencies>files>add existing
 menu

  • When you restart the gamma editor you will already see the help patches in the help browser. (The rest of the meta information shown in the helpbrowser gets added later from nuspec/nuget data)

4/(Optional) Install any underlying dependencies from nuget

  • IF you are wrapping an existing C# .net nuget then make sure it is installed now so you can develop with it.
    You just install it the same way as any nuget contribution, it does NOT go inside the project folder.

  • In your VL development file reference the nuget the usual way Dependencies>.net Nugets>

To be clear what the nuget service will do for end users who download your nuget is download your code AND download the code from any dependencies.
This means
A) the end user only has to run one nuget install command to get all nugets they need to run the contribution
B) you as the developer just reference the other nuget (in a later step) and generally don’t include someone elses code in your contribution.

5/Start coding your library


and maybe forward some things

6/Improve your help patches

  • In each help patch set help flags on the important nodes (Ctrl H) that will automatically open that helppatch when someone presses f1 on the node
    Providing Help | vvvv gamma documentation

  • You know how in the node browser there is sometimes a tool tip with a description of what a node does?
    Set those descriptions of your processes and classes by
    In each process/class press Ctrl-M to open the documentation editor. Select processed and operations and edit the descriptions for those as well. You can use the dropdown to add descriptions to operations of classes and records.

  • Test your helppatches open as expected by closing and then opening them from the helpbrowser.

  • If the view of the patch starts in a weird location right click on the patch and select layout>coordinate system. Zoom out a bit and you should see a cross on the patch, in the bottom right quadrant is the default view of a patch so ensure some helpful nodes are there

  • If you add a dependency to ‘VL.Corelib.Windows’ then you can use the node ‘SetWindowState’ to set the title of a skia renderer.

  • Use lots of frames and comments to make clear what’s going on to novice users

  • Ensure Vsync is OFF on Skia Renderers in your helppatches. Because opening many helppatches with vsync renderers can drop the FPS. (I think this is now off by default
)

  • Use up to two layers of help subfolders to automatically organise helppatches under those topics in the help browser. Note if you move helppatches between folders you may have to relink their relative path dependency to your VL.MyProject

  • There is more info in the gamma reference on ways to make the help section really nice
    Providing Help | vvvv gamma documentation

7/When you are happy with your contribution push your repo back to github

  • Remember it’s ‘git push origin main’ (not master) if you use the default git setup

8/Actually publish the nuget

We are going to use the ‘github actions’ process to do this, so it happens automatically after future pushes to the repo.
(as long as you remember to iterate the version number in the .nuspec file)

/8.1 Make nuspec file

-Both the nuspec file and the automation workflow will be files inside your repo so if you are developing over multiple machines (or you edited the readme.md on the github web interface) ensure you have pulled latest repo before you start this step

-Easiest to copy as a template from an existing vl package that has nuget, eg VL.OpenCV. .GitHub - vvvv/VL.OpenCV: A VL wrapper for OpenCVSharp. Find the nuspec file n the /deployment folder.
-Should be named ‘VL.MyProject.nuspec’
-Put under the /deployment folder
-Ensure it has these fields:
(Search any of these in the nuspec reference if you are confused .nuspec File Reference for NuGet | Microsoft Learn)

  • Tags (include VL and vvvv)
  • ID (Will be your nuget name, probably same as your github repo name VL.MyProject)
  • Version (Follow semver convention https://semver.org/)
    • !!! NOTE version of your nuget must have a ‘-pre’ suffix if any of the dependencies it uses also have a ‘-pre’ suffix.
  • Authors
  • Owners (should be your nuget username)
  • ProjectURL for the github project
  • Summary (max one line)
  • Description (max paragraph)
  • Dependencies (this is where you list other nugets and which version. Put the version number in square brackets eg [1.2.3] to pull the exact version)
    • !!! Same NOTE, if any of these dependencies have -pre suffix than you will also need -pre suffix after your contributions version. Without that suffix nuget thinks you have a stable release and this violates a rule that stable releases only reference other stable releases.
  • Licence (Eg ‘MIT’, ’ LGPL-3.0-only’, short identifiers from SPDX License List | Software Package Data Exchange (SPDX))
  • Files (by folders and wildcards, see how its done in nuspec files of others)
  • !Take out all references to Icon if you don’t have one

For an example of a minimal nuspec that wraps a nuget depdency but does not use a CSPROJ or Icon see VL.RogueSharp/deployment/VL.RogueSharp.nuspec at main · TobyKLight/VL.RogueSharp · GitHub

/8.2 Nuget web interface setup

Sign into nuget account, Create an API key for this package (Eg VL.RogueSharp) and copy out the raw API key value.

-Follow the step by step process here Publishing a NuGet | vvvv gamma documentation
-Don’t forget * in the glob field and that the key has the scope to push new packages.

!Note the API key will expire after a year by default, hopefully nuget will email you about this. However the key expiring shouldn’t break your contrib, you only have to keep the API key updated if you plan more development on this repo.

/8.3 Add the API key to your github repo secrets list

-Navigate to Github web interface>your repo>settings>secrets>actions
-Press ‘New Repository Secret’ button

Name NUGET_KEY
copy in the api key from nuget

For more info Using secrets in GitHub Actions - GitHub Docs

/8.4 setup the workflow instructions in your repo

-create root folder in your repo ‘.github’
-create workflows subfolder within that so you should have ‘.github/workflows’
-Create main.yml under .github/workflows

Full instructions on creating your main.yml here GitHub - vvvv/PublishVLNuget

-Compared to those examples you probably want to change the branch name from ‘master’ to ‘main’
-Remove references to icon if you don’t have one
-Remove references to MSBUILD and CSPROJ if you dont have a CSPROJ
-Again simplest to start with an example file and modify it
Here is a minimal example without a CSPROJ to compile, without an icon and using ‘main’ branch name instead of ‘master’
VL.RogueSharp/.github/workflows/main.yml at main · TobyKLight/VL.RogueSharp · GitHub

-ENSURE YOUR YAML FORMATTING IS CORRECT, particularly there is same correct number of spaces before each - that starts the list of items. YAML format is very finnicky about spaces.

/8.6 Push and test the action

-Add, commit and PUSH the repo to github
-Go to your repo on the github.com web interface and to the ‘actions’ page to see your action running. You can click on it to see what’s going on, see errors etc.
-If you have errors and have to push again give a commit message you can iterate (eg attempt2, attempt3) as this commit message will be the name of each run of your action. If all your commits have the same message it will be more difficult to debug.

-Once your script is successful in the actions interface it can still take 10 minutes for the library to appear on nuget.org

-Note that if your repo makes it all the way to nuget then for future updates you must iterate the version number in nuspec file or nuget will not accept it. Vice versa for a change that you do not want pushed to nuget (eg only updating readme.md) simply do not update the version number.
-Note that the YAML syntax error messages can refer to the wrong line, check the whole yaml for correct spaces etc if you get syntax errors.

/9 Test your nuget in gamma

Open your vvvv gamma WITHOUT the ‘use repos’ option in gamme launcher

  • Open nuget folder

  • delete any dependency nugets so you can check they will install correctly in the next steps

  • Go to nuget command line and type
    nuget install <package name> -version <version>
    eg
    nuget install VL.RogueSharp -Version 1.0.1-pre

  • Should now install and if you look in the help browser you get a nice looking entry with the metadata from the nuspec file.

  • Check all your helppatches work.

Troubleshooting

  • Version of your nuget must be -pre in order to reference other -pre packages.
  • Can take many minutes before nugets will be available to install. Even once the nuget web UI says listed might need 10 minutes before nuget install command works. If it says it can’t locate your version and you are sure the version is right then give it some time.

Cleanup

  • Once you have a nuget working then on nuget.org go to ‘manage package’ > listing and ‘unlist’ any earlier versions that did not work. You cannot delete on nuget so this is equivalent to deleting them. May take some time for them to unlist.

/10 Back on github finish readme.md with nuget link and install instructions

  • You can also embed images and animated gifs in readme.md. This is easiest to do with drag and drop or copy and paste from snipping tool on the github web interface.

  • You may want to pull the latest repo to your dev folder after this as readme.md updates from the github web interface count as a commit. Easy to forget if you make further improvements and then you end up with a merge conflict later.

  • Add VL as a topic of your repo in the about section

/11 inform the vvvv community with a forum post or contribution and a promotion in the chat or shoutbox.

/12 Updating Your Library

To update your library:

  • Ideally use latest stable version of gamma when updating your code
  • Start vvvv using the launcher with ‘Use Repos’ option ticked and your library in the ‘editable packages’ list
  • Assuming your development library is still in your vl-libs folder you can open those patches and make your updates. Probably for safety you want to pull your library first again anyway, in case you made a commit on the web interface or somewhere else.

You can push back to github now and if you DON"T update the nuspec version number these updates will stay parked on github and not automatically go to Nuget.org. This may be desirable if you are spending some time preparing a release.

When you are ready to push to nuget.org

  • Open the nuspec file and increment the version number
  • Update the readme.md if you have any install instructions that reference the version number.
  • Possibly include a changelog in readme.md as well. Particularly mention anything that might be a breaking change. Ideally use your semver numbers properly as well to indicate breaking changes but for alpha or pre packages it may be that you try different structural approaches early on.
  • Push your changes to github

Then it should just automagically work that when you push to github the changes go over to nuget.
However if it’s been more than a year you may need to renew the nuget API keys

Further note:
You may like to advertise the install instructions as “nuget install VL.PackageName” without specifying version number, because that command should generally get the latest version. This saves you going and updating the version number everywhere you posted about the contribution.

IF you do that be sure to unlist old versions of the nuget in the nuget web interface so only one version is listed and it should guarantee people get the latest version.
Conversely consider if you are making major breaking/structural changes that some users might prefer to access old versions and they should stay listed.

Congrats! Thanks for contributing.
Have a cuppa and a biscuit.

17 Likes
2

Maybe these instructions should go into the gray book?

2 Likes
3

This topic was automatically closed 365 days after the last reply. New replies are no longer allowed.