Installation

Versions and Branching

Development of Phobos takes place on the master branch. While we try to keep it stable, please be aware that this is a bleeding edge version of Phobos, which we do not recommend for production use. If you need the latest features and want to use master, we kindly ask you to submit issues if you encounter problems. If you prefer a stable version, choose the latest release version, which we continue to support with bug fixes.

The basic structure of the Phobos repository.

Dependencies

Blender

As of release 1.0 of Phobos, we only support Blender 2.79b. This is an older version of Blender that can easily be obtained from Blender's website and installed locally by unpacking the zip/tarball. This method will work on any operating system supported by Blender. At the time of writing (May 2020), this is the direct link to the downloads: https://download.blender.org/release/Blender2.79/

Blender 2.8 introduced major changes in its scripting API, data management and GUI that are not compatible with Phobos. If you install Blender using your operating system's package manager, you will most likely obtain a version > 2.8 and thus not be able to run Phobos with it. We therefore highly recommend installing Blender locally by downloading the appropriate version (2.79b) from Blender's website as described above.

Python

Blender ships with its own Python 3 environment and different versions of Blender use different versions of Python. However, it does not include a number of libraries Phobos (namely YAML) requires, which is why Phobos will install its dependencies when the setup script is run. This script requires Python to be installed.

Note that you should install a Python version higher than 3. A guide for installing Python on different platforms can be found here.

If you want to find out which version of Python is running in Blender, switch to the scripting environment:

and check the Python version in the console:

Phobos

Getting Phobos

To get Phobos, clone its git repository on GitHub:

$ git clone https://github.com/dfki-ric/phobos.git

Then checkout the release version you want to use (in this example version 1.0):

$ git checkout release-1.0

In case you want to switch to a different release version use the same syntax to switch to the respective release branch. Alternatively, you can download the individual release version as a zip file from GitHub.

After downloading (and eventually uncompressing the archive file) to a local folder on your computer, you need to run the Python file setup.py in the top level directory:

Please note: The install script will ask you to enter the version of Blender you'd like to use Phobos with. This is important as you might have several versions installed on your system (e.g. for backwards-compatibility) and they use different folders for add-ons. As your answers are saved in a file called python_dist_packages.conf, installing Phobos to a different Blender version requires changing or deleting this file (prior to a reinstall).

$ python3 setup.py

or, depending on your system's Python configuration:

$ python3.5 setup.py

On Windows you need to make sure that you run Python version 3. py -3 setup.py should work. Otherwise, check this ressource. The installation file will automatically check the required yaml installation and configure the Phobos installation.

As an alternative, you can use GNU make to install Phobos: make init and make install This has not yet been tested thoroughly and uses the python3 command to run setup.py, so make sure it worked properly.

The script will ask you for the folder Blender has been installed to. This is only required once, as the configuration of your installation will be written to the installation.conf file. Alternatively, you can use the --blender option of the setup script to provide the folder on the commandline.

We also recommend to install our Phobos GUI preset which contains only the most important Blender screens at startup, so you can get started way faster. Install it with the additional parameter for setup.py:

$ python3 setup.py --startup-preset

This might overwrite an existing custom preset, so make sure you keep a backup if you customized Blender earlier.

If in doubt about the options of the setup.py script, just run python3 setup.py -h.

MacOS

Gathering the information where to install Phobos might be a bit tricky on macOS.

Our intended way to install Phobos is with the python installation script, because this makes use of the Blender internal python and we do not need to mess with paths.

• When asked for the Blender installation folder check out the path below. It should contain a subfolder with the Blender version you are using (e.g. 2.79). Provide the path below to continue installation. /Applications/Blender/blender.app/Contents/Resources
• The setup script will install pip and yaml using the internal Blender Python.
• it might happen, that the Blender executable will not be found by the script, but for now it is not really needed, so you can ignore this warning. (In case you want to set it, just edit the installation.conf file after the setup script finishes and rerun it. Most likely you will find the executable here: /Applications/Blender/blender.app/Contents/MacOS/blender)

A workaround to the automatic installation is to create the 'installation.conf' manually within the Phosos folder containing the following information:

dist_package_path path_where_to_find_blender_addons python_executable blender_executable python_version blender_version

An example and maybe regular MacOS configuration is:

/Applications/Blender/blender.app/Contents/Resources/python/lib/python3.5/site-packages # Python package installation path /Applications/Blender/blender.app/Contents/Resources # Blender installation path /Applications/Blender/blender.app/Contents/Resources/2.79/python/bin/python3.5m # python executable /Applications/Blender/blender.app/Contents/Resources/MacOS/blender # Blender executable 3.5 # Python version 2.79 # Blender version

Note, however that this might not be supported in the future.

Activating Phobos in Blender

To activate Phobos in Blender, go to Files -> User Preferences -> Addons and search for 'Phobos' (it should be in the 'Development' category). Then tick its checkbox to activate Phobos and save your user settings in the lower left corner (if you don't save, Phobos won't be loaded for the next Blender startup). If Blender displays any errors at this point, you might want to check if you got the above steps right.

Find Phobos in Blender's user preferences

This is also a good moment to configure Phobos properly. Follow the steps here , to setup the folders, logging etc.

If everything worked fine you can now find the Phobos toolbar as a tab in the left toolbar panel. If you don't see the panel, hit T.

The Phobos tab in the toolbar of Blender

Updating

To update your current installation you just need to pull changes for the release you are working on and run the installation script again:

git pull
python3 setup.py

This method only works, however, if you are using a release that is still maintained, i.e. receives bugfixes or updates. If this is not the case and you have no specific reason to keep your current release, consider switching to a different release.

Switching to a different release

To switch to a new release, you need to first update your local copy of Phobos and then checkout the respective release branch (NEWERVERSION, eg. 1.0):

git fetch
git checkout release-NEWERVERSION
python3 setup.py

After you switched to the different release follow the instructions in updating.

Depending on the severeness of the new changes for the release it might be necessary to completely reset the Phobos folders. To do this, delete the Phobos installation from your Blender addon folder, as well as the configuration folder of Phobos. Make sure you keep backups of your custom definitions and resources before doing so.