Installation of the development version¶
Getting the code¶
The development of the Two!Ears Auditory Model happens independently for its different modules. All of them are hosted as git repositories on github. For an overview go to https://github.com/TWOEARS.
Note
Internally the Two!Ears development happens at https://dev.qu.tu-berlin.de. The repositories on github are mirrors of our internal ones, excluding code or data that cannot be made public.
In order to get started you should familarize yourself with git and then start to clone the repository you would like to change the code. First you have to start with getting the main repository as all other modules need this as a basis:
$ git clone https://github.com/TWOEARS/main.git
Working on the whole Two!Ears model¶
Let us now assume you want to take part in the development of the complete
Two!Ears Auditory Model. What you have to do then is the following. In the main
repository you will find the file TwoEars.xml
which defines all
modules that are part of the Two!Ears Auditory Model:
<?xml version="1.0" encoding="utf-8"?>
<!-- Configure which parts of the Two!Ears model should be started -->
<requirements>
<TwoEarsPart sub="src" startup="startBinauralSimulator">binaural-simulator</TwoEarsPart>
<TwoEarsPart sub="API_MO" startup="SOFAstart">sofa</TwoEarsPart>
<TwoEarsPart startup="startAuditoryFrontEnd">auditory-front-end</TwoEarsPart>
<TwoEarsPart startup="startBlackboardSystem">blackboard-system</TwoEarsPart>
</requirements>
So first clone of off the necessary repositories:
$ mkdir git
$ mkdir git/twoears/
$ cd git/twoears
$ git clone https://github.com/TWOEARS/main.git
$ git clone https://github.com/TWOEARS/binaural-simulator.git
$ git clone https://github.com/TWOEARS/SOFA.git
$ git clone https://github.com/TWOEARS/auditory-front-end.git
$ git clone https://github.com/TWOEARS/blackboard-system.git
Then you have to define the paths of the single modules. In the main
repository copy the file TwoEarsPaths_Example.xml
to
TwoEarsPaths.xml
and adjust it to the used paths, in our case the
default settings, which is:
<?xml version="1.0" encoding="utf-8"?>
<!-- Configuration file for the Two!Ears auditory model -->
<repoPaths>
<!-- https://github.com/TWOEARS/binaural-simulator -->
<binaural-simulator>~/git/twoears/binaural-simulator</binaural-simulator>
<!-- https://github.com/TWOEARS/auditory-front-end -->
<auditory-front-end>~/git/twoears/auditory-front-end</auditory-front-end>
<!-- https://github.com/TWOEARS/blackboard-system -->
<blackboard-system>~/git/twoears/blackboard-system</blackboard-system>
<!-- https://github.com/TWOEARS/SOFA -->
<sofa>~/git/twoears/SOFA</sofa>
</repoPaths>
After that you can simply run the following command in the folder of the main repository in order to work with the model:
>> startTwoEars;
Working on a single module¶
If you would like to work only on a single module you need only to get its
repository as well as all its dependencies. If you not sure what are the
dependencies, you can have a look at its XML configuration file. For example,
in the case of the Binaural simulator it is stored in the file
BinauralSimulator.xml
in its main directory of the binaural-simulator
repository:
<?xml version="1.0" encoding="utf-8"?>
<!-- Configure dependency of Two!Ears modules for the Binaural Simulator -->
<!-- Start the Two!Ears Binaural Simulator with
startTwoEars('BinauralSimulator.xml'); -->
<requirements>
<TwoEarsPart sub="src"
startup="startBinauralSimulator">binaural-simulator</TwoEarsPart>
<TwoEarsPart sub="API_MO"
startup="SOFAstart">sofa</TwoEarsPart>
</requirements>
This means in this case you have to clone the sofa repository in order to use the Binaural simulator:
$ mkdir git
$ mkdir git/twoears
$ cd git/twoears
$ git clone https://github.com/TWOEARS/main.git
$ git clone https://github.com/TWOEARS/SOFA.git
After that you can start the Binaural simulator in Matlab with the following command in order to test it:
>> startTwoEars('BinauralSimulator.xml');
Setting up dependencies on particular branches¶
Git allows to ease software development by using branches. During the development of the whole model it could happen that you have dependencies to particular branches of other modules. You can specify those dependencies also in the XML configuration files, for example:
<?xml version="1.0" encoding="utf-8"?>
<!-- Configure which parts of the Two!Ears model should be started -->
<requirements>
<TwoEarsPart branch="master"
sub="src"
startup="startBinauralSimulator">binaural-simulator</TwoEarsPart>
<TwoEarsPart branch="feature1"
sub="API_MO"
startup="SOFAstart">sofa</TwoEarsPart>
<TwoEarsPart branch="feature1"
startup="startAuditoryFrontEnd">auditory-front-end</TwoEarsPart>
<TwoEarsPart branch="master"
startup="startBlackboardSystem">blackboard-system</TwoEarsPart>
</requirements>
The startTwoEars
function will then check if you have all the modules
checked out at the correct branches. Of course you have to have git installed in
order to use this feature. Even if you are using only the master branches you
are encouraged to use the branch
setting as it ensures that other people
testing your code are also using the master branch and not another one.
Note
Under Windows it is most likely that Matlab complains that git cannot be
found in the system path, when executing startTwoEars
. To fix this you
have to add git to your system paths, see for example this tutorial.
Another feature of the startTwoEars
script is the setting sub-all
instead of sub
which will include the specified path, as sub
will do,
but also all of its sub-folders.