blender-package-manager-addon/README.md

BlenderPackage, the Blender Package Manager (wip)

This is work-in-progress documentation for the work-in-progress package manager (the name is also a work-in-progress) As such, everything here is subject to change.

Installation and Testing

1. Clone blender and checkout the soc-2017-package_manager branch.

   git clone git://git.blender.org/blender.git git checkout soc-2017-package_manager

2. Compile.

3. Clone the package manager addon repository:

   git clone git://git.blender.org/blender-package-manager-addon.git

4. Install the addon. Copy (or symlink) the package_manager directory contained within the cloned repository into /path/to/blender/build/bin/2.78/scripts/addons/

5. Run blender

6. Open the user preferences and switch to the "Packages" section.

7. Add a repository (currently only one is allowed, but this will change). You can use a local repository (see below), or the one I set up for testing: http://blendermonkey.com/bpkg.

A local repository can be generated with the generate_repository script found in the addon repository. Example usage:

./generate_repository /path/to/packages --baseurl 'http://localhost/'

This will produce a repo.json file in the current directory, which can then be copied to the server. The baseurl is prepended to the filename of each package to form the package's url (so for example, http://localhost/node_wrangler.py).

Known limitations

Things which are known to be bad, but are planned to get better

• No progress display
• No installed/available/upgradeable filtering
• Asynchronous operators can be run multiple times at once
• Not more than one repository can be used at once
• Only the latest version of a package can be installed and uninstalled

Notes

Packages which are installed on disk but aren't present in a known repository are listed as 'installed' without an option to uninstall. This is so that it's always possible to undo an uninstall. My intention is to eventually make uninstalls undo-able until blender is restarted by moving the uninstalled files to a cache directory which is flushed on startup and/or exit.

Packages are identified by their name. This could of course cause issues if two different packages end up with the same name. As it seems 2.8 will break many addons anyway, perhaps we can add a required metadata field that allows for more reliable unique identification?

Terminology

Package

A package consists of a single file, or a zip archive containing files to be installed.

Note:
I think it would be good to always store bl_info metadata with the package, but how best to do this while being compatible with existing addons and future non-addons remains an open question (perhaps we can always include an __init__.py even in non-addon packages?)

Repository

A repository consists of a directory containing a "repo.json" file. This repo.json file contains metadata describing each package (bl_info) and where it may be retrieved from.

A repo.json file may currently be generated from a directory of addons by running blenderpack.py <path/to/addon/dir>.

Client

Clients "use" a repository by including its repo.json in packages listed in Clients can be configured to use multiple repositories at once.

In addition, the client maintains it's own "local repository", which is a repo.json containing installed packages.

Clients can take the following actions:

Install

Installing means downloading a single package, adding it to the local repository, and extracting/copying the package's file(s) to their destination(s).

Uninstall

Uninstalling means deleting a single package's files, then removing it from the local repository.

Note:
If some packages store user-created data (e.g. preferences), we may want to preserve that somehow.

Upgrade

Upgrading means looking for and installing newer addons with the same names as installed addons.

Refresh

Refreshing means checking for modifications to the repo.jsons of the enabled repositories, and new packages which may have appeared on disk.