» vvvv sdk
This site relies heavily on Javascript. You should enable it if you want the full experience. Learn more.

vvvv sdk

The vvvv-sdk is the one-stop solution that allows you to contribute stuff to the addonpack. It includes all of vvvv's open source code and the source code of all contributed addons. As it comes as a git repository it allows you to conveniently stay uptodate with latest developments and always build your addons against the latest alpha builds.

If you just want to browse through the code you can do so at the vvvv-sdk github page. There are 3 reasons that would make you want to follow the instructions below:

  • you want to improve help patches/modules/effects/freeframes/plugins
  • you want to contribute your addons to the addonpack
  • you're a h4kc0r
Note that for simple dynamic plugins, effects or modules development you don't need the following.

The following steps will get you going:

Install git

There are countless ways to work with git repositories on windows. In order to keep this guide clean we recommend using the Git Extensions GUI which served us very well. During its installation make sure to check installing both:

  • MsysGit
  • KDiff3

The first is the actual git engine (to which Git Extensions is only the GUI) and the second is a nice diff tool that helps you compare files when it comes to merge-conflicts.

When running Git Extensions for the first time you'll have to enter your name and email address that will be used for your commits. Just follow the instructions there..

If at some point you need/want to know more about working with git your best starting point is the official git website with all its documentation and reference material.

Now install git credential winstore which will pop-up and ask for your github credentials when you want to push commits to github, which you'll want to do at some point. (This is the easier alternative to dealing with ssh-keys, if you've heard of those).

Fork vvvv-sdk on github

The vvvv-sdk git repository is hosted onhttp://github.com (which is just one of many git-repository hosting services). In order to be able to contribute back to that repository one day you'll have to fork it. Here are the steps to do so:

Clone your fork to your local disk

Now on github you have your own "forked" version of the vvvv-sdk repository which you'll be mainly working with. Clone this repository to your local disk using Git Extensions like so:

This will take a while as it now makes a local copy (ie. clone) of the specified repository.

Initialize the repository

This is a step that is specific to vvvvs repository and you have to do it only once. In Git Extensions go to the Menu

 Git -> Git bash (Ctrl + G)

to open the bash. In the bash navigate to the directory you cloned to, eg:

 cd /c/dev/vvvv-sdk

then type

 ./init

to run the initialization script.

The script will install a post checkout hook to your local git repository which in turn will try to fetch the best matching alpha-build of vvvv.exe whenever you pull from upstream or checkout a new branch.
The script output should look something like this:

 Running post-checkout hook ...
 Fetching (/daily/binaries/binaries-*.tar.bz2)
 ...
 Extracting binaries-*.tar.bz2
 tar: Record size = 2 blocks
 vvvv45/vvvv.exe

The repository layout

By cloning the repository you got a local copy that should look like this:

 \common
 \Hoster
 \scripts
 \tools
 \vvvv45

Now don't worry about \common \Hoster and \scripts and navigate to the \vvvv45 directory. What you see here is essentially the same directory layout you get when downloading vvvv as an enduser (except the \src and \tests directories which are not in the enduser download).

 \addonpack
 \girlpower
 \lib
 \licenses
 \src
 \tests

Navigate to the \addonpack directory which is where you will work. It contains 4 directories as follows:

 \girlpower
 \lib
 \licenses
 \src

The \src directory contains addons that need to be compiled before being useful (ie. plugins) while the \lib directory contains addons that will be shippped in the pack as they are (ie. modules, effects).

So depending on what kind of addon you're working on you put your nodes in the respective subdirectories:

 \src\nodes\plugins 
 \lib\nodes\effects
 \lib\nodes\modules

Build Core and Addonpack

At this point you'll need either the free SharpDevelop 4 (SD4) or Visual Studio 2010 (VS2010). Before running vvvv.exe from your \vvvv45 directory (which is the latest available alpha build of vvvvs closed sources) you need to build the opensource parts. including the whole addonpack so you have all the plugins from the pack available while working from this setup.

The addonpack is split into 2 solutions:

  • \vvvv45\addonpack\src\Addonpack.sln
  • \vvvv45\addonpack\src\AddonpackCPP.sln

The first of which contains managed plugins only (which is the biggest part of the addonpack) and is likely to compile without any issues.

The second one contains mixed managed/unmanaged plugins that can be a bit more tricky to get built and definitely needs Windows SDK 7.1 to be installed.

Using SharpDevelop 4

  • open Addonpack.sln
  • make sure: Build -> Set Platform is set to x86
  • build it (F8)

Using Visual Studio 2010

  • open Addonpack.sln
  • make sure: Build -> Configuration Manager -> Active Build Platform is set to x86
  • build it (F8)

Building may take a while and is supposed to return with "Build Successfull. 0 Errors" in which case you're done and can close the solution. If the build fails, you best contact us on irc.

Integrate your plugins to the Addonpack.sln

Now you're ready to work on your own code. For this open the Addonpack.sln and add your project. Now in order to get your project built from within that solution you need to do one step manually:

  • open your project file with a text editor
  • insert the following line:

<Import Project="..\..\Default.Plugin.Project.settings" />

  • remove all the conditional property groups:

<PropertyGroup Condition="...">...</PropertyGroup>

You can have a look at the project file of another plugin in the addonpack for an example of how your project file should look like.

Managed Dependencies

If your project has thirdparty .dll dependencies put them in a directory called

 \dependencies

in your project directory and reference them from there.

If your project depends on platform dependent assemblies put them in

 \dependencies\x86
 \dependencies\x64

open the project file with a text editor and write something like this:

  <Reference Include="AssemblyName">
    <HintPath>dependencies\$(Platform)\AssemblyName.dll</HintPath>
  </Reference>

Unmanaged Dependencies

If your project references unmanaged .dlls you also put them in your local

 \dependencies\PLATFORM 

directory but instead of adding them as reference to your project (which is not possible) you do as follows:

  • enable the "Show All Files" icon in the solution explorer
  • right click the newly shown up dependencies folder in your project and select the "Include in project" entry
  • select all the native dependencies, right click and select Properties
  • in the properties set Copy to ouptut directory to Copy if newer.

This only needs to be done for such linked native .dlls since for ordinary references Local copy = true is the default anyway.
When you compile your project you'll see that those native dependencies will get copied to the output directory including their relative path name. In order to be found at runtime we need to add this relative path name to the PATH environment variable once our plugin gets loaded. To do that add a static constructor to your plugin and put in the following lines of code:

public class MyPlugin ...
{
  // Static constructor
  static MyPlugin
  {
    var platform = IntPtr.Size == 4 ? "x86" : "x64";
    var pathToThisAssembly = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location);
    var pathToBinFolder = Path.Combine(pathToThisAssembly, "dependencies", platform);
    var envPath = Environment.GetEnvironmentVariable("PATH");
    envPath = string.Format("{0};{1}", envPath, pathToBinFolder);
    Environment.SetEnvironmentVariable("PATH", envPath);
  }
}

License

Place a file called

 license-MYPLUG.txt 

directly in the directory of your plugin. From there it will be automatically collected and put in the common \addonpack\licenses directory after the build.

Helppatch

Don't forget to provide a helppatch for your plugin. Put helppatches directly into the

 \addonpack\lib\nodes\plugins

directory. This is a bit of a mess, we know. Please come complain on irc.

Update your clone of the vvvv-sdk

The git pull command is used to fetch (and merge) code from a remote repository. By default when you pull in your repository you'll update your local code from your remote code. But in order to get the freshest bits from the vvvv-sdk you need to pull from the original repository.

For this you have to add the original repo as an extra remote to your repository. In the Git Extensions menu go to:

 Remotes -> Manage remote repositories

and add a new remote giving it the name "upstream" and the url:

Now you can pull from either of your two remotes:

  • origin: the remote repo of your fork on github
  • upstream: the remote repo of the official vvvv-sdk.

Pulling upstream will get you the latest changes to the vvvv-sdk with a suitable new vvvv.exe alpha build. And whenever you do so make sure to rebuild the Addonpack.sln in order for the vvvv.exe you got to be compatible with the latest codechanges.

Like this you can also add even more remotes, eg. of other people's vvvv-sdk forks. Like this you can test changes those people made to their fork before they were incorporated into the official sources.

Contribute your stuff to the vvvv-sdk

You added a project to the addonpack and want it to be distributed with the official addonpack download? Send us a pull request.

vvvv is following this branching model.

Please make sure to follow Conventions.CodingStyle and Conventions.NodeAndPinNaming.

64bit builds

Building the solutions as 64bit only works with Visual Studio 2010 for now since SharpDevelop 4 still ignores some settings in the Addonpack.sln and fails.

When building the pack as 64bit you'll also need the according 64bit alpha of vvvv.exe which you can get by manually calling:

 scripts/fetch-binaries --platform x64

from the bash (remember: Ctrl+G in GitExtensions).