WIP: Blender Extensions Project #106254

This is a design document proposing the Blender extensions platform.

Online Extensions

The online-extensions platform is a separate project,
however it is expected that the Blender integration will be able to use online repositories to
list and install extensions.

This proposal works under the assumption that blender.org will maintain a list of add-ons,
where the majority of add-ons currently included with Blender will be moved to.

These add-ons will be maintained by their respective authors, instead of having to maintain them centrally.

Communities are free to setup their own lists of add-ons although Blender will only enable the
official blender.org repository by default.

Including other repositories will be supported with minimal hassle with the understanding users
are trusting the judgment of the people who setup such lists.

Initial Proposal

Requirements

Support for multiple extension repositories (repos).

Studios and individual users should be able to host their own extensions.
Support both online repos as well as local (file-system) based repositories,

useful for developers, studios as well as running automated tests.
Support for multiple extension types (add-ons, apps, themes).
Building and updating extensions must be automated,
where a change to an extension can be published without tedious web-UI's.
Support being disabled entirely.

There is no requirement that external extensions must be used.
It should be possible to opt-out of using extensions.

As long as automated updates are off by default, there is no need to use extensions unless users explicitly do so.

Non-Goals

Support for large multi-gigabyte extensions.

Very large repositories (typically used for assets) are outside the scope of this project.

Extensions may be re-downloading during an update for example.
Providing rich text and setting ratings etc from within Blender's UI.
Automatic updates (initially), while this can be supported the initial version will require manual updates.

Components

extension-builder

A tool that validates metadata and packages the extension into an archive
(perhaps an archive and generated metadata).

Also used for generating a repository listing
(which would be downloaded by the client to show candidates for installation).
extension-publish (not part of MVP)

Handles uploading the extension, authentication.
May also do sanity checks - such as versions never decreasing.
extension-validate

Used by the builder and server to validate packages.

Checks could include:
- Versions always increase and follow semver spec.
- Code checks (Python code byte-code compiles for e.g.).
- Warn on inclusion of __pycache__, *.blend1 files (for e.g.).
- Warn on inclusion of modified files or files not under version control.
extension-client

This utility would be responsible for adding/removing extensions,
listing extensions from a repository.

This is responsible for gracefully handling errors & cleaning up in the event of failure
(network-error, disk-full ... etc).
blender-integration

Blender would integrate with by communicating with the extension-client.

This will be a new a new section in the user-preferences.
- List repos (add/remove support).
- List extensions (add/remove support).
- Update extensions.

Dependencies

Packages must bundle any 3rd party modules they depend on as WHEEL's.
The package manager is responsible for installing the WHEEL's & uninstalling when they are no longer used (most likely the package meta-data includes bundled WHEEL's and their versions).
Multiple packages may include the same WHEEL, in this case only one of them will be used (as the same WHEEL at the same version should be compatible).
There is no complex dependency handling, in the event two packages use different version of the same WHEEL, there is a conflict - only one of the packages can be installed.

Notes:

Prefer WHEEL's over PIP, since PIP is it's own package manager, it may compile code or do advanced operations that a Blender package manager can't reasonably manage - failures with PIP are likely to require command line access, OK for Python developers but not regular users.
We might consider allowing some minor difference in package versions, as a general rule though - supporting different versions and handling their possible incompatibilities is not a goal.
To avoid unnecessary version-mismatches, we may wish to have a rule of thumb for using the versions of packages available at Blender's release date for e.g.

Implementation

The extension-client will be managed by Blender as an external process.

This avoids common problems integrating non-blocking logic into Blender interfering with Python's internal state
and allows for (upgrading multiple extensions at once for e.g.).
It also allows simplifies writing tests, allowing TDD.
The extension-client has no stored state (all configuration is passed to it on activation).

Again, simplifies running multiple instances at once.
Local extension directories are to be entirely maintained by the extension manager.

Meaning users should never manually copy files into this path.
Removal of these files upon updating is not considered a bug.

To Be Decided

Details of meta-data formats, expected fields ... etc.

An extension meta-data (likely a separate file)
should contain enough information to display an entry in the interface
(name, author(s), description, type, compatibility information).
Details of extension storage, archive format ... etc.
Details of compatibility (only compatible with certain Blender versions),
support for multiple Blender versions at once.
It should be possible to install an extension from a URL,
providing that URL references a repo currently in use.

We might support drag & drop URL's into Blender's to install preferences, details TBD.
Support multiple versions of the same extension (development, stable... etc).
Handling of extensions which include compiled modules.
Support for listing extensions directly from GIT repositories.

Note that this is more on the online infrastructure side of things.

GIT repositories could be scanned and have their packages automatically built.
This could be an experimental option - for users who also run daily builds.
Name-spacing
- We may want to namespace extensions so each author has a top-level identifier.
- How add-ons handle name spacing needs some investigation, e.g. bl_addons.{repo}.{add_on}.
Storage
- The local extension should not store configuration as we want to be able to uninstall/reinstall
  without loosing anything of value to the user.
- We may want to support a generic API for extensions to have a storage location for their own persistent data.

Further Work

Automatic updates (optional).

This requires some investigation, even if updating can be automatic - the thing that's updated may be in-use.
So user interaction may be required to explicitly disable the add-on, update and enable it.
Security (see below).
Installing/upgrading extensions from the command line,
e.g. blender --extensions-upgrade-all.

Security

From discussion with Brecht and Francesco,
we had some initial discussion around security, this is a summary of what we thought made sense.

Domain allow-listing
- Blender will maintain a list of accepted domains and provide a Python API to access this list.
- Add-ons are expected to check with this list before accessing online content
  (we may have a way to accept accessing a domain in the UI).
- While we cannot enforce rules around accessing online content (such attempts are easy to by-pass).
  Intentionally bypassing these checks may result in the add-on being explicitly blocked.
  
  Note that we might have some limited enforcement of accepted URL's for common API's (requests for e.g.)
  that a developer would have to intentionally subvert - however this not a core requirement.
Malicious extension blocking

As part of updating blender.org extensions, a list of known malicious extensions will be checked,
where Blender reserves the right to disable an extension that is known to be malicious.

Repositories can maintian their own malicious extension list as well.

The user will be notified of this with a message for why the extension of what was disabled.

Examples of malicious extensions include but are not limited to:
- Extensions that install viruses/malware.
- Extensions that bypass network access mechanisms (phone home without user consent).
Malicious repo blocking

We may also want to support this.

Proposed Layout:

   ~/.config/blender/3.6/extensions
   /usr/share/blender/3.6/extensions

   Example Layout:

   ~/.config/blender/3.6/extensions/
   ├── shared-studio-addons.txt (supports multiple OSs)
   ├── fsiddi-local-addons.txt
   ├── localhost/
   │   ├── addons
   │   ├── keymaps
   │   ├── themes
   │   └── assets
   ├── blender.org/
   │   ├── addons/
   │   │   ├── light_utils
   │   │   ├── cycles_powerdrill
   │   │   └── animation_shelf
   │   ├── themes/
   │   │   ├── blue
   │   │   ├── nitro
   │   │   └── flatty-lite
   │   └── assets
   └── blendermarket.com/
       └── addons/
           └── retopo_flow

This is a design document proposing the Blender extensions platform. Online Extensions ================= The online-extensions platform is a separate project, however it is expected that the Blender integration will be able to use online repositories to list and install extensions. This proposal works under the assumption that ``blender.org`` will maintain a list of add-ons, where the majority of add-ons currently included with Blender will be moved to. These add-ons will be maintained by their respective authors, instead of having to maintain them centrally. Communities are free to setup their own lists of add-ons although Blender will only enable the official ``blender.org`` repository by default. Including other repositories will be supported with minimal hassle with the understanding users are trusting the judgment of the people who setup such lists. Initial Proposal ================ Requirements ------------ - Support for multiple extension repositories (repos). Studios and individual users should be able to host their own extensions. - Support both online repos as well as local (file-system) based repositories, useful for developers, studios as well as running automated tests. - Support for multiple extension types (add-ons, apps, themes). - Building and updating extensions must be automated, where a change to an extension can be published without tedious web-UI's. - Support being disabled entirely. There is no requirement that external extensions must be used. It should be possible to opt-out of using extensions. *As long as automated updates are off by default, there is no need to use extensions unless users explicitly do so.* Non-Goals --------- - Support for large multi-gigabyte extensions. Very large repositories (typically used for assets) are outside the scope of this project. Extensions may be re-downloading during an update for example. - Providing rich text and setting ratings etc from within Blender's UI. - Automatic updates (initially), while this can be supported the initial version will require manual updates. Components ---------- - extension-builder A tool that validates metadata and packages the extension into an archive (perhaps an archive and generated metadata). Also used for generating a repository listing (which would be downloaded by the client to show candidates for installation). - extension-publish (not part of MVP) Handles uploading the extension, authentication. May also do sanity checks - such as versions never decreasing. - extension-validate Used by the builder and server to validate packages. Checks could include: - Versions always increase and follow ``semver`` spec. - Code checks (Python code byte-code compiles for e.g.). - Warn on inclusion of `__pycache__`, `*.blend1` files (for e.g.). - Warn on inclusion of modified files or files not under version control. - extension-client This utility would be responsible for adding/removing extensions, listing extensions from a repository. This is responsible for gracefully handling errors & cleaning up in the event of failure (network-error, disk-full ... etc). - blender-integration Blender would integrate with by communicating with the extension-client. This will be a new a new section in the user-preferences. - List repos (add/remove support). - List extensions (add/remove support). - Update extensions. Dependencies ------------ - Packages must bundle any 3rd party modules they depend on as WHEEL's. - The package manager is responsible for installing the WHEEL's & uninstalling when they are no longer used (most likely the package meta-data includes bundled WHEEL's and their versions). - Multiple packages may include the same WHEEL, in this case only one of them will be used (as the same WHEEL at the same version should be compatible). - There is no complex dependency handling, in the event two packages use different version of the same WHEEL, there is a conflict - only one of the packages can be installed. Notes: - Prefer WHEEL's over PIP, since PIP is it's own package manager, it may compile code or do advanced operations that a Blender package manager can't reasonably manage - failures with PIP are likely to require command line access, OK for Python developers but not regular users. - We might consider allowing some minor difference in package versions, as a general rule though - supporting different versions and handling their possible incompatibilities is not a goal. - To avoid unnecessary version-mismatches, we may wish to have a rule of thumb for using the versions of packages available at Blender's release date for e.g. Implementation -------------- - The extension-client will be managed by Blender as an external process. This avoids common problems integrating non-blocking logic into Blender interfering with Python's internal state and allows for (upgrading multiple extensions at once for e.g.). It also allows simplifies writing tests, allowing TDD. - The extension-client has no stored state (all configuration is passed to it on activation). Again, simplifies running multiple instances at once. - Local extension directories are to be entirely maintained by the extension manager. Meaning users should never manually copy files into this path. Removal of these files upon updating is not considered a bug. To Be Decided ============= - Details of meta-data formats, expected fields ... etc. An extension meta-data (likely a separate file) should contain enough information to display an entry in the interface (name, author(s), description, type, compatibility information). - Details of extension storage, archive format ... etc. - Details of compatibility (only compatible with certain Blender versions), support for multiple Blender versions at once. - It should be possible to install an extension from a URL, providing that URL references a repo currently in use. We might support drag & drop URL's into Blender's to install preferences, details TBD. - Support multiple versions of the same extension (development, stable... etc). - Handling of extensions which include compiled modules. - Support for listing extensions directly from GIT repositories. Note that this is more on the online infrastructure side of things. GIT repositories could be scanned and have their packages automatically built. This could be an experimental option - for users who also run daily builds. - Name-spacing - We may want to namespace extensions so each author has a top-level identifier. - How add-ons handle name spacing needs some investigation, e.g. ``bl_addons.{repo}.{add_on}``. - Storage - The local extension should not store configuration as we want to be able to uninstall/reinstall without loosing anything of value to the user. - We may want to support a generic API for extensions to have a storage location for their own persistent data. Further Work ============ - Automatic updates (optional). This requires some investigation, even if updating can be automatic - the thing that's updated may be in-use. So user interaction may be required to explicitly disable the add-on, update and enable it. - Security (see below). - Installing/upgrading extensions from the command line, e.g. ``blender --extensions-upgrade-all``. Security -------- From discussion with Brecht and Francesco, we had some initial discussion around security, this is a summary of what we thought made sense. - Domain allow-listing - Blender will maintain a list of accepted domains and provide a Python API to access this list. - Add-ons are expected to check with this list before accessing online content (we may have a way to accept accessing a domain in the UI). - While we cannot enforce rules around accessing online content (such attempts are easy to by-pass). Intentionally bypassing these checks may result in the add-on being explicitly blocked. Note that we might have some limited enforcement of accepted URL's for common API's (requests for e.g.) that a developer would have to intentionally subvert - however this not a core requirement. - Malicious extension blocking As part of updating ``blender.org`` extensions, a list of known malicious extensions will be checked, where Blender reserves the right to disable an extension that is known to be malicious. Repositories can maintian their own malicious extension list as well. The user will be notified of this with a message for why the extension of what was disabled. Examples of malicious extensions include but are not limited to: - Extensions that install viruses/malware. - Extensions that bypass network access mechanisms (phone home without user consent). - Malicious repo blocking We may also want to support this. --- Proposed Layout: ``` ~/.config/blender/3.6/extensions /usr/share/blender/3.6/extensions Example Layout: ~/.config/blender/3.6/extensions/ ├── shared-studio-addons.txt (supports multiple OSs) ├── fsiddi-local-addons.txt ├── localhost/ │ ├── addons │ ├── keymaps │ ├── themes │ └── assets ├── blender.org/ │ ├── addons/ │ │ ├── light_utils │ │ ├── cycles_powerdrill │ │ └── animation_shelf │ ├── themes/ │ │ ├── blue │ │ ├── nitro │ │ └── flatty-lite │ └── assets └── blendermarket.com/ └── addons/ └── retopo_flow ```

Plugget

I've made an add-on that does something very similar, that might be an interesting reference.

packages/manifests hosted in a repo, anyone can create a PR to add a manifest.
Then the user can get & install content from packages (add-ons, icons, ...) with a add-on with simple UI

This was inspired by unity package manager, which makes it very modular to install extensions.
For more discussion see the blenderartists thread

Overlap with Blender Extensions

IMO your proposal has not yet addressed:

the ability to work with existing add-ons.
it seems it would only work after it went through the "extension-publish" step.
But ideally you can point to a repo from an existing add-on (there are hundreds out there) and it will just work, lowering the barrier for adopting this.
any mention of dependencies. Powerfull add-ons require python modules installed through pip. Not something you want the end user be responsible for. It also would be great to support dependencies between extensions.

If packaging is required, adoption likely will be slow, just like how unity's package adoption is slow. Since there's an additional technical step of packaging.
Moving the responsibility to a package repo means a dev can release an add-on. And package enthousiasts can create the manifest.

i'm really excited to see this work with 3rd party hosts, since you mentioned e.g. blendermarket in your example

#### Plugget I've made an add-on that does something very similar, that might be an interesting reference. - packages/manifests hosted in [a repo](https://github.com/hannesdelbeke/plugget-pkgs/tree/main/blender), anyone can create a PR to add a manifest. - Then the user can get & install content from packages (add-ons, icons, ...) with a [add-on with simple UI](https://github.com/hannesdelbeke/plugget-blender-addon) This was inspired by unity package manager, which makes it very modular to install extensions. For more discussion see [the blenderartists thread](https://blenderartists.org/t/plugget-install-add-ons-with-1-click/1456558/8) #### Overlap with Blender Extensions IMO your proposal has not yet addressed: - the ability to work with existing add-ons. it seems it would only work after it went through the "extension-publish" step. But ideally you can point to a repo from an existing add-on (there are hundreds out there) and it will just work, lowering the barrier for adopting this. - any mention of dependencies. Powerfull add-ons require python modules installed through pip. Not something you want the end user be responsible for. It also would be great to support dependencies between extensions. If packaging is required, adoption likely will be slow, just like how unity's package adoption is slow. Since there's an additional technical step of packaging. Moving the responsibility to a package repo means a dev can release an add-on. And package enthousiasts can create the manifest. i'm really excited to see this work with 3rd party hosts, since you mentioned e.g. blendermarket in your example

@h4nnes thanks for the feedback.

The ability to work with existing add-ons isn't a goal, instead, the intent is to support relocating add-ons in a more flexible way.
Added a second on dependencies. As Blender runs a single Python instance we can't have overlapping modules (multiple versions of the same module), so the proposal is that extensions include all necessary modules as wheels, which the package manager can handle.

@h4nnes thanks for the feedback. - The ability to work with existing add-ons isn't a goal, instead, the intent is to support relocating add-ons in a more flexible way. - Added a second on dependencies. As Blender runs a single Python instance we can't have overlapping modules (multiple versions of the same module), so the proposal is that extensions include all necessary modules as wheels, which the package manager can handle.

Thanks for writing up the proposal!

I think this is very promising. I am particularly happy that the intention is that people can add non-official sources as their provider for extensions.

Dependency

The Dependency section highlights a particularly difficult problem. I think users will expect to be able to click and install whatever packages they see. Conflicting dependencies between packages is not something they will like to think about. It could significantly impact the usability of this solution.

As you mentioned, expecting developers to pin to certain versions of packages might be a solution but its not a full solution. Python packages will have security fixes and then developers will have to decide between maintaining compatibility or receiving the security patch.

I wonder if we could write a tool that rewrites all dependent modules to be fully namespaced. So if I was publishing an extension named foo and dependent on python modules A and B. The tool will actually rewrite all imports and move the modules to foo.A and foo.B. This way bar can depend on a different versions of module A and B. Clearly this is not trivial to build. Additionally, this probably falls apart as soon as someone depends on any compiled/binary artifacts.

Security

I didn't follow the motivation for having a domain allow-list. I thought the goal was that anyone could match the provider API and become a provider for extension lists. And if a user is interested in the provider, they just have to add an extra provider URL.

Does the allow-list mean that any provider (even people internal to companies) will have to first get approval from Blender?

Thanks for writing up the proposal! I think this is very promising. I am particularly happy that the intention is that people can add non-official sources as their provider for extensions. ### Dependency The _Dependency_ section highlights a particularly difficult problem. I think users will expect to be able to click and install whatever packages they see. Conflicting dependencies between packages is not something they will like to think about. It could significantly impact the usability of this solution. As you mentioned, expecting developers to pin to certain versions of packages might be a solution but its not a full solution. Python packages will have security fixes and then developers will have to decide between maintaining compatibility or receiving the security patch. I wonder if we could write a tool that rewrites all dependent modules to be fully namespaced. So if I was publishing an extension named `foo` and dependent on python modules `A` and `B`. The tool will actually rewrite all imports and move the modules to `foo.A` and `foo.B`. This way `bar` can depend on a different versions of module `A` and `B`. Clearly this is not trivial to build. Additionally, this probably falls apart as soon as someone depends on any compiled/binary artifacts. ### Security I didn't follow the motivation for having a domain allow-list. I thought the goal was that anyone could match the provider API and become a provider for extension lists. And if a user is interested in the provider, they just have to add an extra provider URL. Does the allow-list mean that any provider (even people internal to companies) will have to first get approval from Blender?

Regarding the dependency problem, I spent some time researching and getting feedback from other Python folks. Some of the ideas proposed for this problem:

Require add-on developers to fully vendorize their dependency tree. There is a tool called python-vendorize that will rewrite all the import statements in the project (and in your dependencies) so that you import from within your module instead of outside. AuditWheel will do the same thing for c-extensions that a project depends on.
Change how Blender invokes the add-ons. If the modules are invoked in a separate subprocess or even a subinterpreter then we can provide isolation between each add-on.

I think both ideas will require work. python-vendorize is probably not very battle-tested and auditwheel only supports linux right now. Changing how Blender interacts with add-ons without breaking interfaces is obviously a major lift as well.

Regarding the dependency problem, I spent some time researching and getting feedback from other Python folks. Some of the ideas proposed for this problem: - Require add-on developers to fully vendorize their dependency tree. There is a tool called [python-vendorize](https://github.com/mwilliamson/python-vendorize) that will rewrite all the import statements in the project (and in your dependencies) so that you import from within your module instead of outside. [AuditWheel](https://github.com/pypa/auditwheel) will do the same thing for c-extensions that a project depends on. - Change how Blender invokes the add-ons. If the modules are invoked in a separate subprocess or even a [subinterpreter](https://docs.python.org/3/c-api/init.html#sub-interpreter-support) then we can provide isolation between each add-on. I think both ideas will require work. python-vendorize is probably not very battle-tested and auditwheel only supports linux right now. Changing how Blender interacts with add-ons without breaking interfaces is obviously a major lift as well.

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Labels Milestones

WIP: Blender Extensions Project #106254

Online Extensions

Initial Proposal

Requirements

Non-Goals

Components

Dependencies

Implementation

To Be Decided

Further Work

Security

Plugget

Overlap with Blender Extensions

Dependency

Security