Introduction

When using blender in production, you tend to integrate an ever growing list of addons.

Installing them all cluters the GUI, some are alternatives to others, some may be pined to a different version depending on the prod/asset/shot... There are many reasons why you need to "bundle" different lists of addons for different prod, tasks, departments, and sometimes even users.

Then you need to be able to run blender with the appropriate list of addons for a given context, preferably in an automated way.

Blender addons also miss a crutial feature: dependency management.

When developer needs to use a python package in their addons, they need to hack their way into installing this package. A common strategy is to discretly "pip install" this package into blender, which works until you install another addon doing the same with an incompatible dependency. Have fun debugging that ! :'(

When using python packages in production, you face the same needs:
Bundling different lists of packages depending on the context, and be able to install them on demand to run python in this curated environment.

The Pythonic solution for this to install your packages in "virtual environments" known as virtualenv, or venv.

A venv is created by a given version of python. You use it like you would use the original python installation, with the difference that the venv must be activated first. Creating several venvs with different python versions let you easily switch between python versions.

Once a venv is activated, all packages you install will reside inside this venv and the original python installation will stay untouched. Creating several venvs with the same python let you easily switch installed packages.

Installing a python package automatically install its dependencies, resolving their versions with already installed packages. Installing packages inside a venv let you easily isolate some packages if their dependencies happen to be incompatible.

basskick aims to provide the same features, addapted for blender and blender addons:

• Create blender virtual environments to bundle and isolate addons installation.
  We call this a "benv".

• Extend addons metadata with dependencies and packaging information to automate and validate their installation+activation.
  We call this a "packon".

As basskick also aims at being lightweight, it leverages existing python technologies and provides the thinnest possible layer between them and the blender usage.

basskick is available as a CLI (Command Line Interface: a shell tool) and a python API (Application Public Interface: some code tool).

The API will help you leverage basskick feature inside your pipeline/workflow/asset-management-solution, and the CLI is a nice tool to discover features and inspect their usage in production, or as a no-code solution for small teams without technical support.

Both CLI and API will let you create benvs and install packons in them. basskick also provide convenient helpers for example to manage blender versions and their benvs, run blender, convert addons into a packons, install packons, etc...

Support for "Blender Application Templates" is also planned in futur versions.

Audience

The basskick technical documentation is will be hosted on readthedocs: https://basskick.readthedocs.io (not available yet)

You will need it if you want to create addons supported by the BASS.

If all you need is to use basskick, you should be good to go after reading this page.

NB: Shell commands shown here are from a git-bash session on windows. Please adapt to your needs.

SETUP

You most likely have a "master" python environment to hold your production code. You probably create a virtualenv for each production. If not, start doing it ;)

Let's create a production virtualenv and install basskick in it:

$ cd /d/prods/
/d/prods $ mkdir my_prod
/d/prods $ cd my_prod
/d/prods/my_prod $ python -m venv my_prod.venv
/d/prods/my_prod $ source my_prod.venv/Scripts/activate
(my_prod.venv) /d/prods/my_prod $ pip install basskick
...

You should be able to use the basskick command now:

(my_prod.venv) /d/prods/my_prod $ basskick --help
[basskick::INFO] Let the BASS Kick !
[basskick.cli::INFO] Running CLI outside benv
Usage: basskick [OPTIONS] COMMAND [ARGS]...
...

SESSION

basskick needs to know a few things in order to be usefull. Such information is stored in a "session".

CLI

When using the command line interface, you store the session in a file that can be specified for each command or auto-discovered by looking up the current folder and its parent folders.

Let's create this file in our prod root folder so that any command under there is properly configured:

(my_prod.venv) /d/prods/my_prod $ basskick session create-session-file .
[basskick::INFO] Let the BASS Kick !
[basskick.cli::INFO] Running CLI outside benv
Session file saved: "D:\prod\my_prod\.basskick"

Now we can configure our session to locate our blender installations.
Let's say we have blender 2.83 and 2.90 installed in /d/installs/bl.
We will make our session aware of those with the add-install sub command:

(my_prod.venv) /d/prods/my_prod $ basskick session add-install /d/installs/bl/blender-2.83 2.83
[basskick::INFO] Let the BASS Kick !
[basskick.cli::INFO] Running CLI outside benv
[basskick.api.session::INFO] BasskickSession loaded from D:\prod\my_prod\.basskick
Added blender install: '2.83'

(my_prod.venv) /d/prods/my_prod $ basskick session add-install /d/installs/bl/blender-2.90 2.90
[basskick::INFO] Let the BASS Kick !
[basskick.cli::INFO] Running CLI outside benv
[basskick.api.session::INFO] BasskickSession loaded from D:\prod\my_prod\.basskick
Added blender install: '2.90'

Here is how we can see the list of available blender in the current session:

(my_prod.venv) /d/prods/my_prod $ basskick session list-installs
[basskick::INFO] Let the BASS Kick !
[basskick.cli::INFO] Running CLI outside benv
[basskick.api.session::INFO] BasskickSession loaded from D:\prod\my_prod\.basskick
Registered Blender Installations:
2.83: 2.83 (D:/installs/bl/blender-2.83)
2.90: 2.90 (D:/installs/bl/blender-2.90)

API

When using basskick in python code, you will use the basskick.api.session.BasskickSession() class.

It can be persisted on disk with session.save(path) and looked up from disk with session.from_path(path). You may also directly read it with session.from_file(filename)

Creating our session and declaring our blender installation would look like this:

import basskick.api.session

session = basskick.api.session.BasskickSession()
session.add_install("2.83", "2.83", "D:/installs/bl/blender-2.83")
session.add_install("2.90", "2.90", "D:/installs/bl/blender-2.90")
session.save(path)

BENV

Now that we have a configured session, we can create some benvs.

Let's say we need a set of addons for the modelers and another one for the lookev. We will create a folder to store them and a benv for each one

CLI

(my_prod.venv) /d/prods/my_prod $ mkdir benvs; cd benvs
(my_prod.venv) /d/prods/my_prod/benvs $ basskick benv create 2.83 mod
[basskick::INFO] Let the BASS Kick !
[basskick.cli::INFO] Running CLI outside benv
[basskick.api.session::INFO] BasskickSession loaded from D:\prod\my_prod\.basskick
[basskick.api.blender_install::INFO] Creating benv "mod" with blender D:/dee/bin/blender/blender-2.80\blender.exe in .

(my_prod.venv) /d/prods/my_prod/benvs $ basskick benv create 2.83 lookdev
[basskick::INFO] Let the BASS Kick !
[basskick.cli::INFO] Running CLI outside benv
[basskick.api.session::INFO] BasskickSession loaded from D:\prod\my_prod\.basskick
[basskick.api.blender_install::INFO] Creating benv "lookdev" with blender D:/dee/bin/blender/blender-2.80\blender.exe in .

Here is how we can see the list of available benvs in the current session:

(my_prod.venv) /d/prods/my_prod/benvs $ basskick benv list

[basskick::INFO] Let the BASS Kick !

[basskick.cli::INFO] Running CLI outside benv

[basskick.api.session::INFO] BasskickSession loaded from D:\prod\my_prod\.basskick

Know benvs:

mod
lookdev

API

Using the session created in the previous chapter, we can retrieve a basskick.api.BlenderInstall() and use it to create a benv.
Once created we register it in the session for convenient usage:

blender_install = session.get_install("2.83")
blender_install.create_benv("mod", benvs_folder)
session.add_benv("mod", benvs_folder)
blender_install.create_benv("lookdev", benvs_folder)
session.add_benv("lookdev", benvs_folder)
session.save()

PACKON

A packon is a blender addon packaged as a vanilla python package. It support all PyPA metadata, especially the "install_requires" field. You can manipulate a packon with any tool of the python packaging ecosystem, like pip.

The difference between a random python package and a packon is that the later always defines a "basskick.packon" entry point
When a packon is installed in a benv, blender will automatically have it enabled.

The command line will help you manage packon dev, release and deployment:

(dev.venv) /d/dev/packons/basskick.voice_ctrl $ basskick build .(dev.venv) /d/dev/packons/basskick.voice_ctrl $ basskick upload .

and happy folks will be able to install it as a regular python package:

pip install basskick.voice_ctrl

You can of course install in edit mode to get your code live into another benv:

(my_prod.venv) /d/dev/packons/basskick.voice_ctrl $ pip install -e.

more...

The command line is plugin-based and extensible.
The API is GUI friendly.
You can convert a classic addon to a packon with basskick command line.
Packons appear in Blender's preference>addons panel, but as a separated list so you know what's what.
You can also turn a Blender Application Template into a vanilla python package, and use basskick command line to run it from a benv.

And probably more... ;)