How-to setup Eclipse for YAFARAY development

 

Disclaimer: I am not an Eclipse guru, as a matter of fact, I wrote this how-to because I didn't knew any of this stuff before I started and I don't want anybody loosing the same amount of time as I did. Hope this helps you!

Index

 

ECLIPSE AND PLUGINS INSTALL

First thing first. We need to download Eclipse, In my case I downloaded it from from Ubuntu repositories. You need to install both eclipse-platform and eclipse-pde, or you won't be able to install eclipse plugins.

sudo aptitude install eclipse-platform eclipse-pde

Now, your eclipse at its current state is rather useles for C/C++ development, so we need to fix that. We will also install some other plugins for our environment to be a complete YafaRay development environment.

Run Eclipse, set your workspace folder and then go to "Help->Install New Software..." menu option. Then, click on 'Available Software Sites'.

 

Install New Software WindowsInstall New Software Windows

 

In there, we need to enable CDT (C/C++ Development Tools) provider. Put CDT on the filter textbox, there will be just one provider, select it and press enable.

Now add Egit (for git version control) and CMake Editor (for editing CMake files), press the "Add..." button and put the following locations: http://download.eclipse.org/egit/updates and http://cmakeed.sourceforge.net/eclipse/. Give them a name, so you remeber next time why they were added.

 

Add SiteAdd Site

 

Press "OK" button to go back to "Install" window. First, let install CDT. Choose it from the "Work with" droplist, then press the checkboxes to select the plugins you want (if unsure select them all, with the following exception). When you choose from the plugin list, uncheck the "Eclipse CDT p2 Toolchain Installer" one, if you don't there is the posibility that your entire Eclipse install gets corrupted, and believe me, you don't want that!

 

Installing CDT - DangerInstalling CDT - Danger

 

Press "Next" and go with the flow. Do the same for Egit (I didn't select Jgit plugin) and CMake Editor.

Congratulation!, your Eclipse install is ready to roll. Now we need to make it work with Yafaray.

 

CREATING THE PROJECT(S)

Close the "Welcome" page, if you didn't already. Go to "File" menu, "import..." option. Select "Git Repository", press next. In the URI textbox put "http://github.com/DarkTide/YafaRay.git" or one of your choice. You should see something like:

 

Importing Darktide gitImporting Darktide git

 

Press "Next", select your favorite branches ("master" by default), "Next" again. Select your destination folder. For a couple of reasons that I'll explain later, put them on a folder in your workspace, In this tutorial I will use mine as example, "/home/glaskows/workspace/YafaRay-src" (from now on SOURCE_PATH). Be sure to uncheck "Import projects after clone", because, at least Darktide repository doesn't have an Eclipse project file.

 

Importing Darktide git: destination folderImporting Darktide git: destination folder

 

Press "Finish" and wait. You should see everything exactly as in the beginning. That is because we didn't create an Eclipse project, to do this we have several options. I will use CMake Eclipse generator. Before we continue I need to explain what CMake is. Quoting their mainpage [2]:

CMake is a family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. CMake generates native makefiles and workspaces that can be used in the compiler environment of your choice.

So, inside the files you just downloaded, there are CMake files that will generate Make files for your environment. In one of this files there is a string that specifies where Make is going to install the executables and libraries compiled. By default, they are installed in "/usr/local", but this present us some troubles. Maybe, you are working on a computer where you don't have privileged access or maybe you don't want to run Eclipse in super user mode. In my case, I would like to have the stable version in "/usr/local" and several development ones inside my workspace folder. To do this, we need first to copy "SOURCE_PATH/CMakeConfig/UserConfig.template" to "SOURCE_PATH/CMakeConfig/UserConfig.txt". Then change

#set(USER_INSTALL_PREFFIX /usr/local)

to

set(USER_INSTALL_PREFFIX BUILD_PATH/install)

Where BUILD_PATH is the path to a new folder in our workspace. In my case BUILD_PATH is equal to "/home/glaskows/workspace/YafaRay-build". It is not a good idea to put the build folder inside the source one. Quoting another source [1]:

Eclipse has advanced support for editing C/C++ sources, including code navigation, autocompletion etc. For that to work the sources must be inside the project. The Eclipse project generator therefore creates a linked resource to the source tree in the Eclipse project. This makes the C/C++ features work.
This linked resource isn't created if the build directory is a subdirectory of the source directory because Eclipse doesn't allow to load projects which have linked resources pointing to a parent directory. So we recommend to create your build directories not as children, but as siblings to the source directory.

Another detail about Eclipse is that for version control to work we need that the project file be at the root of the source tree, so we are going to create another project just for git. So, we need to execute CMake twice, one for the proyect on each folder. Go to BUILD_PATH and execute:

cmake -G"Eclipse CDT4 - Unix Makefiles" -D DEBUG_BUILD=ON SOURCE_PATH

DEBUG_BUILD can be "ON" or "OFF", for development choose "ON" (...or not, it's your choice). We now have a working project, before we go to Eclipse, lets create the controlled version project.

cmake -G"Eclipse CDT4 - Unix Makefiles" -DECLIPSE_CDT4_GENERATE_SOURCE_PROJECT=TRUE SOURCE_PATH

Congratulation!, now you have the projects created.

Now, we need to tell Eclipse to start using the projects. Open Eclipse and go to "File->Import...". There, select "General->Existing Projects into Workspace". Press "Next". On "Select root directory" put your BUILD_PATH. On the "Projects" list there should be an entry, select it and press "Finish". On Eclipses "window console" you should see a lot of activity, it's okay, just wait it to finish. If after that you don't see a "Make Targets" window (in my configuration it is on the right) is because you are on the Java perspective. Go to "Window->Open Perspective->Other...", choose "C/C++". You should see now the "Make Targets" window, just like in the following picture (note that you can change the perspective by pressing on the its icon)

 

Perspectives and Make TargetsPerspectives and Make Targets

 

SETTING UP RUN AND DEBUG CONFIGURATIONS

At this moment you can build and install YafaRay by clicking the correct entry on the "Make Targets" window. But what if you want to execute yafaray-xml  or debug it. For that, you need a "run (and debug) configuration".

Go to "Run->Run Configurations...". There, give this configuration a name, select your build project and then browse for the yafaray-xml file (in BUILD_PATH/install/bin). Go to "Arguments" tab and put the arguments you want, in my case "-f hdr -t 2 -dp -nz /home/glaskows/Desktop/yafaray/yafarayRender.xml out". We now need to tell the executable where to find his libs. Go to "Environment" tab, create a new one, "LD_LIBRARY_PATH" as its name and "install/lib" as its value. Press "Run" to check that it works.

For the debug configuration, go to "Run->Debug Configurations...", choose "gdb/mi" as debugger. Press on "Select other..." and select "Standard Create Process Launcher". Press "Close".

Now we are all setup, you can pull source from git, change te code, compile, run and debug it.

If there is a better or easier way to do any of these, please comment it so we can make a better tutorial!

 

Reference:

  1. http://www.vtk.org/Wiki/Eclipse_CDT4_Generator
  2. http://www.cmake.org/