Bela

h1. Compiling Bela projects in Eclipse

This document contains information on how to compile the Bela software and upload it onto the BeagleBone Black.

h2. Required tools

This document assumes you have the following tools installed:

h3. On Linux

Requires:
* Working Linux system, either running natively or on a virtual machine
* Mercurial version control system (http://mercurial.selenic.com). Available as a package in most Linux distributions.
* arm-gcc hardfp compiler toolchain (i.e. @arm-linux-gnueabihf-gcc@ and similar. On Ubuntu, these can be installed from packages:
<pre>
sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
</pre>
* Eclipse IDE (http://www.eclipse.org), including the C/C++ development tools
* xenomai libraries and include files are already on the BBB's SD card. You can copy them over to your machine as follows:
<pre>
cd ~
ssh root@192.168.7.2 "cd /usr/; tar -zcvf ~/xenomai.tar.gz xenomai"
rsync -avz --remove-source-files root@192.168.7.2:xenomai.tar.gz .
cd /usr/arm-linux-gnueabihf/include/
sudo tar -xvf ~/xenomai.tar.gz
rm ~/xenomai.tar.gz
</pre>

* Make sure that the following line is in your Eclipse project's includes
<pre>/usr/arm-linux-gnueabihf/include/xenomai/include</pre>
and the following line is in your Eclipse project's libraries search path
<pre>/usr/arm-linux-gnueabihf/include/xenomai/lib</pre>



h3. On a 64bit MacOS X

* You can get the arm cross-compiler toolchain from here http://www.welzels.de/blog/projekte/arm-cross-toolchain/, which will place the binaries into your /usr/local/linaro/arm-linux-gnueabihf/bin/ folder
* xenomai libraries and include files are already on the BBB's SD card. You can copy them over to your machine as follows:
<pre>
cd ~ &&\
ssh root@192.168.7.2 "cd /usr/; tar -zcvf ~/xenomai.tar.gz xenomai/include xenomai/lib include/ne10" &&\
rsync -avz --remove-source-files root@192.168.7.2:xenomai.tar.gz . &&\
cd /usr/local/linaro/arm-linux-gnueabihf/include &&\
sudo tar -xvf ~/xenomai.tar.gz &&\
sudo mv include/ne10 ./ &&\
sudo rm -rf ./include &&\
rm ~/xenomai.tar.gz
</pre>

* Make sure that the following lines are in your Eclipse project's includes
<pre>/usr/local/linaro/arm-linux-gnueabihf/include/xenomai/include
/usr/local/linaro/arm-linux-gnueabihf/include/ne10/</pre>
and the following line is in your Eclipse project's libraries search path
<pre>/usr/local/linaro/arm-linux-gnueabihf/include/xenomai/lib/</pre>



h3. Other operating systems

You have several options:
# find your own way and share it here
# use the Ubuntu VirtualBox image provided [ask for link].
# compile on the board: [[ Compiling Bela projects on the board]]

h2. Getting started

# Make sure you own a copy of the Bela files, if you do not already:
<pre>
hg clone https://code.soundsoftware.ac.uk/hg/beaglert https://code.soundsoftware.ac.uk/hg/BeagleRT
</pre>
# Launch Eclipse and select a workspace (creating one if necessary).
# In the Eclipse menu bar, choose _File -> Import..._. Within the dialog box that appears, choose _General -> Existing Projects into Workspace_. Click _Next_.
# Click the button _Select root directory_ and choose the path to the Bela repository you just cloned.
# Make sure the @Bela@ project is selected, and under Options, untick _Copy projects into workspace_. Click _Finish_ to complete the project import.

h2. Compiling the Bela project

# In Eclipse, right-click on the @Bela@ project folder in the left-hand column, and choose _Build Project_. (If you don't see the list of projects, make sure the C/C++ Perspective is active in Eclipse, and choose _Window -> Show View -> Project Explorer_.)
# The project should compile without errors, and the results should be visible in the Console tab (typically in the bottom pane of the window)
# If any errors arise, check that you have all the dependencies installed, both header files and libraries.

h2. Copying Bela projects to the BeagleBone Black

Once the project has compiled, Eclipse should automatically copy it over to the Beaglebone in the ~/BeagleRT folder, prompting you twice for the password in case you did not set up the ssh keys.
If the project is not copied automatically:
# open a terminal window and @cd@ to the directory where the binary was compiled. For example, if you installed Bela in your home directory: @cd ~/BeagleRT/Release@
# Copy the Bela executable to the BeagleBone Black using @scp@ (entering your BeagleBone Black password when prompted; you may need to create the @Bela@ directory first):
<pre>
scp BeagleRT root@192.168.7.2:~/BeagleRT/
</pre>

h2. Selecting different Bela examples within the Eclipse project

The Eclipse project contains several examples within the @projects@ directory. Follow these steps to choose which one to compile:

# Only one of the folders within @projects@ should be enabled at a time. This one will be in solid black text; the remainder will be grey.
# Right-click on the folder which is currently enabled (solid black). Choose _Resource Configurations -> Exclude from Build..._
# Click _Select All_ to disable the code in this folder. Click _OK_.
# Now right-click on the folder which you want to enable. Choose _Resource Configurations -> Exclude from Build..._
# Click _Deselect All_ to enable the code in this folder. Click _OK_.

h2. Creating a new executable within the Bela project

Duplicate one of the existing project folders using the following steps:

# Right-click the project folder you want to duplicate and select _Copy_.
# Right-click on the @projects@ folder and select _Paste_. It will ask you to type in a new name.
# Follow the steps above (_Resource Configurations_) to enable compiling this new project rather than any of the others.