IGVC Developer's Guide

This page is intended for our IGVC team's driver developers. This tutorial walks the developer through the installation and configuration of Fedora Linux, Player/Stage, and checkout of our codebase.

Get Fedora
The first step for development of our software is to get a Linux distribution on your computer. Our club uses Fedora for all linux development. To get started, download either the Live CD or the Installation DVD from the Fedora download page.

The download page contains a link for the Installation Guide, which can be used to answer any questions. If you plan to dual-boot your system, you need to partition your disk before installing Fedora.

Fedora 13's installer includes an option to shrink an existing partition during the install process, which obviates the need for the below directions. If you're using Fedora 12 or lower, you can use the GParted LiveCD or the Fedora LiveCD to resize Windows partitions. The following steps are required to perform a dual-boot installation.

For GParted LiveCD:
 * Back up your data
 * Shut down windows cleanly
 * Boot with the Gparted LiveCD
 * Right click on your Windows partition and select Resize
 * Slide the right edge of the partition to the left, leaving about 15 or more GB of space for Fedora
 * Apply the changes, reboot, and boot into Windows
 * Shut down the computer, boot from the Fedora Install media of your choice

For Fedora LiveCD:
 * Back up your data
 * Shut down windows cleanly (do not hibernate or shut down with the power button)
 * Boot with the LiveCD
 * Connect to the internet
 * Open a terminal, and run the command: su -c "yum install gparted"
 * Open GParted, right click on your windows partition, and select Resize
 * Slide the right edge of the partition to the left, leaving about 15 or more GB of space for Fedora
 * Apply the changes, reboot, and boot back into Windows (to allow Windows to run chkdsk on boot)
 * Shut down the computer, boot from the Fedora LiveCD, double click on "Install" icon on Desktop, and follow the onscreen directions

During the installation of Fedora, you will be prompted to select where on your hard drive to install Fedora. Choose the "Use All Free Space" option, and continue with the installation process.

Installing Player from Repositories
As of March 2010, versions of Gearbox, Player, and Stage are included in Fedora's repositories by default. The installation process is as simple as running the following command: su -c "yum install player player-doc player-examples player-devel gearbox-devel stage stage-devel stage-playerplugin"

This command will download Player and Stage, as well as all of the dependencies and development libraries required to program for and run Player. To compile our code, you'll need a few extra programs. The following packages should provide the rest of the dependancies needed for our code.

su -c "yum install cmake opencv-devel gtk2-devel gearbox-devel"

Preparing for Player
'''Note: Only complete this section if you do not have a recent Fedora system. Otherwise, use the directions above'''

Once Fedora is installed, a few more steps must be taken to install Player correctly. The fastest way to do this is by using the Terminal, but graphical tools are available to accomplish the same tasks. Connect to the internet, then go to Applications -> System Tools, and open the Terminal Program. Once you have a prompt, enter the command su and enter the root password you chose when installing the system. This elevates your privileges to the 'root' user, which has the power to change all files on the system. You need this to install additional software to your computer. First enter the command yum upgrade to update all of the software on your system. Generally, software on installation media is out of date. After this process completes, enter the command yum install eclipse-cdt eclipse-subclipse\ gtk2-devel libtool-ltdl-devel opencv-devel cmake\ kernel-devel kernel-headers libdc1394-devel\ libraw1394-devel nautilus-open-terminal This command installs several software packages and the associated dependencies required to build and run Player. This should also take a while to download and complete. Once this process finishes, you should restart your computer.

Getting Gearbox
We use the Gearbox library to connect to serial ports with Player and Stage. Download the latest release of Gearbox from the Gearbox download page. Once it's downloaded, extract the code from the archive into a directory of your choice. Open the Terminal, and navigate to the directory that the Gearbox source was extracted to. Enter the commands mkdir build cd build cmake -DCMAKE_INSTALL_PREFIX=/usr ..

This configures Gearbox, searches to make sure you have the necessary requirements to build it, and generates the appropriate makefiles and build scripts. At this point, enter the commands make su -c "make install" make will compile the programs and libraries, then make install will install them so you can use them.

We're not done yet. Gearbox installs its shared libraries outside of the system's standard search path. Enter the command nano ~/.bash_profile to edit your terminal preferences. If you do not have the "nano" text editor installed, you may use another text editor (gedit, vim, kedit, etc.) or use yum to install nano

At the bottom of the file, add the following two lines LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/gearbox export LD_LIBRARY_PATH These will set the LD_LIBRARY_PATH environment variable each time you log in/open a terminal. LD_LIBRARY_PATH will append the directories you specify to the system's library search path. The system will now be able to find the gearbox libraries when you run a program linked against them.

Finally, enter the command source ~/.bash_profile su -c "ldconfig" to apply these changes.

Getting Player and Stage
Download the latest releases of Player and Stage to your computer from the Player Download page. Extract both archives, preferably to somewhere in your home directory (/home/username). Navigate first to the Player source directory, then the Stage source directory in the Terminal. In each, execute the commands mkdir build cd build cmake -DCMAKE_INSTALL_PREFIX=/usr .. make su -c "make install"

This configures, builds, and installs Player to your system. Player and Stage both come with a file labeled INSTALL that contains detailed instructions. Refer to that file for more details.

Setting up the Development Environment
The IGVC developers use Eclipse as their primary IDE (Integrated Development Environment). To install Eclipse in Fedora, run the following command: su -c "yum install eclipse eclipse-cdt eclipse-subclipse"

This will install Eclipse, the C Development Tools, and the Eclipse Subversion plug-in.

Launch Eclipse, and click on the "Go to Workspace" button if it doesn't automatically take you there (it won't if it's the first time you're running it.) Left click in the white Project Explorer pane, and select Import. In the Import window, choose Import from SVN option, and click next. Choose to enter a new location, and click next again. In the URL bar, enter 'http://svn.psurobotics.org/IGVC10', select the "trunk" folder, then hit Next. Enter IGVC10 as the project name, if it's not already there, and click Finish.

Once you have the code, check the upper right corner of the Eclipse window to make sure you're in the C/C++ perspective. Generally, Eclipse defaults to the Resource perspective, you click on it and change it to C/C++.

In the C/C++ perspective, there should be a column to the right of the Editor, with a tab option called Make Targets (its icon looks like a green bull's eye.) Select the tab, expand the IGVC10 target, right click on the "Run CMake" option, and select "Build Target." The build system will then go through its initial configuration, and the project should be ready to build by hitting CTRL+B. Click on the "console" tab on the lower pane to view the buildsystem output.

Checking out the code manually
If you're not using Eclipse, you may also check out the code manually. To get the code for our project, navigate to the folder you'd like to download the source to, then run the command svn checkout http://svn.psurobotics.org/IGVC10/trunk IGVC10 This command downloads our source tree into a folder called IGVC10. Navigate into IGVC10/build, and then run the commands ccmake ../ make to compile the drivers. You shouldn't get any errors.

What's next
Now that you have the environment and codebase set up, read through the Writing a Player Plugin article to learn more about how these plugin drivers work.