120 lines
4.4 KiB
Markdown
120 lines
4.4 KiB
Markdown
# 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](https://developer.blender.org/diffusion/B/browse/soc-2017-package_manager/).
|
|
|
|
git clone git://git.blender.org/blender.git
|
|
git checkout soc-2017-package_manager
|
|
|
|
2. [Compile](https://wiki.blender.org/index.php/Dev:Doc/Building_Blender).
|
|
2. You may want to build without addons (or delete them from `<build dir>/bin/<version>/scripts/addons*` afterwards).
|
|
This is because system addons typically can't be altered by the user (permissions), so the package manager won't be able to uninstall/update them.
|
|
Plus, the test repo only contains official addons, so if left as is, all addons will be installed already.
|
|
3. Clone the [package manager addon repository](https://developer.blender.org/diffusion/BPMA/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. Start blender and enable the addon (it's in the "Testing" support level")
|
|
6. Add a repository in *User Preferences > Packages > Repositories* by clicking the "plus" icon. You can use a local repository (see below), or the one I set up for testing: `http://blendermonkey.com/bpkg`.
|
|
Currently only one repository is allowed, but this will change.
|
|
|
|
|
|
### Repository creation
|
|
|
|
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
|
|
* 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
|
|
|
|
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.json`s of the enabled
|
|
repositories, and new packages which may have appeared on disk.
|
|
|