Downloading and Setting Up Zeffiro

Requirements

For a complete installation, Zeffiro Interface (ZI) relies on Git, even if you choose to use the Zeffiro downloader approach below. Installation of the core functionality can be achieved by downloading the repository as a ZIP file, as instructed below.

MATLAB versions prior to R2020b will need to install the Git command line program separately, but MATLAB versions newer than that should package their own version of Git. See the MATLAB documentation for instructions on installing Git on your machine, if you are using an older MATLAB version (docs).

Of MATLAB's toolboxes, at least Parallel Computing Toolbox and Statistics and Machine Learning Toolbox are used often by ZI. Installing those before first running the scripts will ensure that there will be no interruptions. Otherwise, MATLAB will request downloading those, when they are called by the scripts. Using MATLAB R2020b or later is recommendable.

Installing via Git from MATLAB command line

The simplest way to download and install ZI is to run the following command on the MATLAB command line, replacing <wanted branch> and <local folder> with suitable values, such as main_development_branch and zeffiro_interface, respectively:

! git clone --recurse-submodules -b <wanted branch> --depth 1 https://github.com/sampsapursiainen/zeffiro_interface.git <local folder>

This will download the specified <wanted branch> (e.g. main_development_branch) of ZI into the <local folder> on your computer. The switch --recurse-submodules can be left out, if one only wishes to use the core functionality of ZI. It is some of the plugins that rely on the external packages given in the .gitmodules file in the project root. The flag --depth 1 can also be omitted, if one does not mind waiting for the entire development history of ZI to be downloaded onto the local machine.

Using urlwrite and zeffiro_downloader

Another way of downloading ZI is to first download the installation function zeffiro_downloader.m via MATLAB, and then invoke it with the keyword arguments that it provides:

urlwrite('https://tinyurl.com/zeffiro','zeffiro_downloader.m');
zeffiro_downloader(<kwargs>);

where <kwargs> are given as pairs of keys and values "key", value. Type

help zeffiro_downloader

or

doc zeffiro_downloader

in the MATLAB console to find out the possible keyword arguments. Another option is to read the script file in a text editor of your choice.

Downloading the project as a ZIP file

One can navigate to the project GitHub page, click on the Code button and choose Download ZIP to download the project into a folder of their choosing. One can also download the ZIP from the MATLAB command line by replacing <branch> in the below url with an actual existing branch on the GitHub server, such as main_development_branch:

filename = "zeffiro_interface.zip" ;
url = "https://github.com/sampsapursiainen/archive/refs/heads/<branch>.zip" ;
websave ( filename, url ) ;

However, downloading the project this way will not allow you to use any of the external packages needed by some of the plugins. Git is still needed for downloading the external submodules, unless of course one is willing to manually download the projects listed in the .gitmodules file of the project into the external/ folder.

.gitmodules and .gitignore

The .gitmodules file lists the external plugins used by ZI, and their startup scripts. The file is utilized by zeffiro_setup in downloading the dependencies of Zeffiro's plugins. This file must be in a valid Git config format, and will not work otherwise. To avoid breakage, one should probably not edit this file manually, and instead use the git submodule and git config commands to make any edits. The commands will prevent the user from making syntactically incorrect additions to the file.

Also, if one wishes to add new submodules to the project, the folder of the new submodule needs to be allowed in the .gitignore file of the project. This is done by adding a new line

!external/<submodule>

next to the other similar lines in the .gitignore file. Here <submodule> is the name of the folder where one wishes to save the new submodule.

To add new Git submodules to the project, navigate to the Zeffiro Interface installation folder, allow the module addition as described above and then type

! git submodule add -b <branch> <Git URL> external/<submodule>

on the MATLAB command line. Here <branch> is the branch you wish the submodule to subscribe to, <Git URL> is the URL that one would otherwise use to clone the submodule directly from GitHub, and <submodule> is the name you wish to give to the submodule folder under the external/ folder.

To modify the branch which the submodule subscribes to by default after adding it, type

! git config -f .gitmodules submodule.external/<submodule>.branch <branch>

where <branch> is the name of the branch you wish to subscribe to. Startup scripts are specified similarly, via the key startupscript:

! git config -f .gitmodules submodule.external/<submodule>.startupscript external/<submodule>/<script name>.m

Deletion of startup scripts or branches from .gitmodules is done just like adding them, except that the flag --unset is added after the -f .gitmodules part of the command, and no value is provided after the submodule.external/<submodule>.key part:

! git config -f .gitmodules --unset submodule.external/<submodule>.key

Note that removing the path or url keys from a submodule will break the .gitmodules file.