In this tutorial we will explain how you to set up your development environment.
First of all, the Java Development Kit (a.k.a. the JDK) needs to be installed. The EF-Pi is developed in Java version 1.6 (also refered to as version 6), so at least version 1.6 of the JDK needs to be present. Later versions also work fine, so you can just install the latest version for your operating system.
To check if you have installed the JDK you can execute the command javac -version on the command line. Windows users can access the command line through Start menu, press Run, type cmd and click the OK button. If the JDK is installed you should see the version number. If the JDK is not installed you should get a warning indicating that the command could not be found.
Windows and Mac users can download the JDK from http://www.oracle.com/technetwork/java/javase/downloads/index.html. Linux users can install Java through their package manager. OpenJDK also works fine. For example, Ubuntu users can install the JDK with the following commands:
sudo apt-get update
sudo apt-get install openjdk-7-jdk
The preferred IDE for developing apps for EF-Pi is Eclipse, currently at version Luna. The EF-Pi heavily uses bnd for developing OSGi-bundles, and Eclipse has an excellent plug-in for bnd.
The latest version of Eclipse can be downloaded from http://www.eclipse.org/downloads/. The Standard Eclipse distribution or the Eclipse IDE for Java Developers version is preferred. Be careful to select the right version for your platform. Eclipse is provided as a zip archive. It doesn't have an installer. Just extract Eclipse to a location which is convenient for you.
For more information see http://www.eclipse.org.
There are several ways can use Git. You could use the GitHub Desktop Client (Windows or Mac OS X), Git from command line (Git Bash) or the Eclipse EGit plug-in. In this tutorial we will assume you use Git Bash. You can download it for your platform on http://git-scm.com/downloads (or use the package manager for your Operating System).
For more details on using Git we recommend reading the Git Pro book. You can read it online for free.
In this guide we will use the fpai-examples repository (please note our repositories are not up2date yet with our recent name change from FPAI -> EF-Pi). This repository contains simple examples of Apps for the EF-Pi. You can find the repository on GitHub.
First of all, there are two ways of using the Git repository. If you only want to fiddle around with the examples, you can just check out the repository with HTTPS. This way you don't have to create a Github account. Changes you make to the code will only stay on your machine.
You can also decide to fork the repository. This way you make a private copy of the repository on Github. You can push your changes to Github and share them with other users. This requires you to create a Github account, upload your SSH keys, fork the repository and checking out the repository over SSH. For this tutorial it doesn't really matter which method you choose.
On the right side of the repository page you can find the clone URL. When you don't have a Github account this should be https://github.com/flexiblepower/EF-Pi-examples.git. Now we have to open up Git Bash and go the directory where you want your source code. Let's assume you have created this directory at C:\Code\EF-Pi. Since Bash is designed for Linux, you can use forward slashes instead of back slashes and use /c/ instead of C:\. You can change the directory with the cd (change directory) command. In order to go to the right directory you have to type in the following command and press enter:
cd /c/Code/EF-Pi
Now we have to clone the Git repository into this directory. You can use the git clone command with the clone URL:
(please note our repositories are not up2date yet with our recent name change from FPAI -> EF-Pi)
git clone https://github.com/flexiblepower/fpai-examples.git
Git will create a directory named git-examples inside the C:\Code\EF-Pi directory with the source code.
In the EF-Pi projects we use git submodules to share some files with several repositories. In order to be able to use these files you have first have to go inside your repository directory, and then execute two commands for initializing the submodule:
cd fpai-examples
git submodule init
git submodule update
It might take some time to download these additional files. When these task are done you should also have a cnf.shared directory in your repository.
Now it is time to start Eclipes. The first thing Eclipse asks is the location of your workspace. For the EF-Pi, each repository is also a workspace. So select the directory you just checked out (C:\Code\EF-Pi\fpai-examples).
When you start Eclipse for the first time it will show you the Welcome page. You can close it.
Tip: Are you using a lot of workspaces? When Eclipse starts, it asks you which workspace you want to use. Eclipse only remembers the last five workspaces you have used. Once you have opened up a workspace, you can increase this number by going to 'Window', 'Preferences' and then 'General', 'Startup and Shutdown'. Here you can manage the known workspaces and change the number of recent workspaces to remember.
The Eclipse plugin for bnd, called Bndtools, must be installed first. EF-Pi currently works best with Bndtools version 3.5.0.
In Eclipes, go to Help and then to Install New Software.... Click on the Add... button, and fill in the name Bndtools 3.5.0 and the Location https://dl.bintray.com/bndtools/bndtools/3.5.0/. Then mark Bndtools for installation and click the Next > button. Follow the installation wizard in order to install Bndtools.
For more information see http://bndtools.org. There is also a general tutorial available at http://bndtools.org/tutorial.html.
The repository you checked out already contains some projects. We have to tell Eclipse to search for those repositories first. You can do this by going to File and then Import. Select Existing Projects into Workspace from the General directory and click the Next button.
Click on the Browse button on top of the screen. It will automatically go to the your workspace directory. Click OK to select your workspace directory. Select all the projects and click Finish. Eclipse will add the projects to the Package explorer on the left of the screen.
Finally, we have to select the Bndtools perspective. A perspective is a configuration of the Eclipse user interface which is made for a specific tasks. You can select a perspective by clicking Window, Open perspective and then Other.... Double click on Bndtools to open the Bndtools perspective. You can close the welcome window of eclipse, and tick the box not to show again.