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](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).
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. Run blender
6. Open the user preferences and switch to the "Packages" section.

The default repository can currently be changed in the addon's preferences
section (currently only accessible in the "Addons" section). You can either use
a local repository (see below), or `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.json`s of the enabled
repositories, and new packages which may have appeared on disk.