Environment setup ================= This document will lead you through the setup so one can run the code on a local machine. Binder ------ `Binder `__ is a service in which lets you use computational resources from big tech companies free of charge and without any registering or setup. Click `here `__ to use a *Binder* instance where everything is set up for you. Please have in mind that these machines are free of charge and therefore the resources are quite limited and some computations will not work because we will rely on some heavy computation. .. todo:: Currently SuperCollider is not working in this environment as this requires a headless version of SuperCollider in Docker which is not trivial at this point. If somebody knows how to set this up please open a Pull Request. Repository setup ---------------- To copy the course material to the local machine we will use `git `_. For the install procedure please refer to the `official website `_. After one has setup git we now need to `clone `_ the `repository `_ by opening a new shell window and head to a directory in which you want to copy the course material and execute the command .. code-block:: shell git clone https://github.com/capital-G/musikinformatik-sose2021.git If you know what *SSH*, have a GitHub account and you want to participate in the creation of the course one should use SSH instead so the command becomes .. code-block:: shell git clone git@github.com:capital-G/musikinformatik-sose2021.git Now as we have cloned the course material to a local directory we want to switch to the directory which we just created by cloning the repository .. code-block:: shell cd musikinformatik_sose2021 .. admonition:: Convention We will refer to this folder as *the root folder of the repository*. Most commands will be executed in this folder and we will always work relative to this path. Please make sure if you e.g. re-start *Jupyter Lab* or you activate the virtual environment you are in this directory before entering the commands. SuperCollider setup ------------------- Please refer to the `SuperCollider download page `_ for the install instructions of SuperCollider. When working with macOS we assume that you have installed SuperCollider in ``/Applications/SuperCollider`` so the following command should yield the version number of SuperCollider .. code-block:: shell /Applications/SuperCollider.app/Contents/MacOS/sclang -v If you have installed SuperCollider in a different location you can set the environment variable ``SCLANG_PATH`` to the path where your *sclang* executable is located. Python setup ------------ Installing Python ^^^^^^^^^^^^^^^^^ Please make sure you have installed *Python 3.8*, *pip3* and *virtualenv* on your machine. A good guide on how to install *Python* on your machine can be found `here `__. .. warning:: Please refrain from *Python 3.9* as this is `not supported by Tensorflow yet `_. The default homebrew setup will install the latest Python version which is 3.9 which will not work for our experiments. If you use `Homebrew `_ on macOS you can install version 3.8 by executing .. code-block:: shell brew install python@3.8 .. _virtualenv-install: Installing *virtualenv* ^^^^^^^^^^^^^^^^^^^^^^^ Python is a language that relies on libraries - e.g. the parsing of MIDI files is not build-in to the language but `there is a collection of MIDI libraries `__ that allows Python to work with MIDI files. It turns out that it is a good practice to not mix too many libraries as they are maybe not compatible to each other - maybe library *A* relies on version 0.2 of library *B* but library *C* relies on version 1.2 of library *B* - welcome to `dependency hell `__. The solution to this is to create an isolated environment for each project - so the clashing of incompatible versions does not occur. It is also possible to determine which version of Python we want to use for our project which is relevant to us. *virtualenv* provides us with such a functionality and we can install it by running .. code-block:: shell pip3 install virtualenv in a terminal. We use ``pip3`` for installation of *virtualenv* which is a `package manager `__ for python libraries. After a successful installation please check that you have the following .. code-block:: shell python3 --version # Python 3.8.x # macOS users who installed python 3.8 via homebrew should check # /usr/local/opt/python@3.8/bin/python3 --version pip3 --version # pip 21.0.1 from /usr/local/lib/python3.8/site-packages/pip # just about any pip3 version will be fine virtualenv --version # virtualenv 20.4.2 from /usr/local/lib/python3.8/site-packages/virtualenv/__init__.py # just about any virtualenv version will be fine - make sure that it refers to your # python3 folder from above and not to e.g. python2 .. _virtualenv-create: Creating a new virtual environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After we have installed virtualenv (see :ref:`virtualenv-install`) we now use it to create a new virtual environment for our project. Go to the root folder of the repository (see :ref:`Repository setup`) with a shell and execute the command in this folder to create a new virtual environment in the folder ``venv`` .. code-block:: shell virtualenv venv .. warning:: macOS users who installed python 3.8 with homebrew should instead call .. code-block:: shell virtualenv --python=/usr/local/opt/python@3.8/bin/python3 venv .. _virtualenv-activate: Activating the virtual environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After we have installed the virtual environment it is now time to activate it so we install the necessary libraries (such as e.g. *Jupyter Lab*) to the isolated environment and not to the *global* Python installation on your machine. Assuming you are in the root folder of the repository (see :ref:`Repository setup`) and created a virtual environment (see :ref:`virtualenv-install`) it is as simple as executing the command .. code-block:: shell # on linux/macOS source venv/bin/activate # on windows .\venv\Scripts\activate After the virtual environment has been successfully activated something ``(venv)`` will be shown in the command prompt. .. _install-dependencies: Installing dependencies ^^^^^^^^^^^^^^^^^^^^^^^ After we have activated the virtual environment (see :ref:`virtualenv-activate`) we can now install all necessary libraries for our project by running. .. code-block:: shell pip3 install -r requirements.txt .. _start-jupyter: Start *Jupyter Lab* ^^^^^^^^^^^^^^^^^^^ After we have installed all necessary libraries (see :ref:`Installing dependencies`) it is now time to start *Jupyter Lab* which is a coding environment for our browser in which we can code Python and SuperCollider. Please make sure you have activated the virtual environment (see :ref:`virtualenv-activate`) and execute the command .. code-block:: shell jupyter lab To shut down the *Jupyter Lab* server enter the keyboard combination of `` + c`` in the shell window in which the Jupyter server is running. A prompt will appear in which one has to verify that one wants to shut down the server by entering ``y``. Documentation ^^^^^^^^^^^^^ .. admonition:: Note This is only an optional step if you want to participate in improving the course material. In order to build the documentation locally one also needs to install its dependencies by executing the following command in the root directory of the repository (see :ref:`Repository setup`) .. code-block:: shell pip3 install -r requirements-docs.txt After this the documentation can be build by executing the shell script .. code-block:: shell ./build_docs.sh from the root directory of this repository. .. admonition:: Convention If you want to open the documentation in a browser after it has been build you can set the environment variable .. code-block:: shell export OPEN_BROWSER_AFTER_TEST=true when using the ``./build_docs.sh`` script. Remember that this has to be set every time you open a shell or you add it to your ``~/.zshrc`` or else. Setup via Docker ---------------- Alternatively, if one has `Docker `_ installed, one can also run the notebooks in a docker container by executing .. code-block:: shell docker build -t musikinformatik . && docker run -p 8888:8888 -v ${PWD}:/home/musikinformatik musikinformatik while being in the root directory of the repository and click on the appearing link. .. todo:: Currently it is difficult to run SuperCollider in an headless environment such as Docker, therefore SuperCollider is omitted in the docker image. Any help on this is appreciated. Docker Compose ^^^^^^^^^^^^^^ If you have `docker-compose `_ installed on your machine you can also simply run .. code-block:: shell docker-compose up and access the jupyter notebook via `http://localhost:8888 `_. Updating and working with the repository ---------------------------------------- The course material is stored and distributed via `git `__. As there are constantly updates on the course material there will be conflicts when we have worked locally on a notebook. This is because *git* does not know how to resolve the local changes with the remote updates - this is commonly known as `merge conflicts `__. Probably the best way is to save the notebook on which you work locally to a new notebook - this can be done by clicking on the *Save Notebook As ...* button under the *File* menu in the upper left corner of Jupyter Lab. .. figure:: notebook-save-as.png :alt: Save notebook as :scale: 50 % Save a notebook under a new name to avoid any problems when updating the course material. Updating the course material ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Assuming that you have saved all the changes you want to keep in a new notebook and you are in the root repository of repository, the following commands will update the course material .. code-block:: shell # remove any changes from existing files git reset --hard # get newest changes git pull It may be necessary that new dependencies got introduced during the update, so its always a good idea to quickly install any new dependencies - see :ref:`Installing dependencies` on how to do this.