Monday, January 23, 2012

Getting started with Eclipse and Cygwin

Asking someone how they set up their development environment is a little like asking someone how they like their eggs cooked: generally they're very particular, and they want it the exact same way every time, but that may not be the way you like it.

After months struggling with Microsoft Visual Studio, one day I just couldn't take it anymore. Unfortunately there are a lot of options for C++ compilers in Windows, but no clear winners. I ended up using Cygwin, which is a UNIX emulator for windows. It has windows binaries of the classic UNIX development tools like make, gcc, g++, gdb and so on. This is nice because this scheme makes it faster than emulating UNIX with a program like VMware. On the other hand, some of the utilities work better than others. In my experience the critical development programs are fine, but some of the other utilities like gprof leave something to be desired. (More on that later.)

So now you've picked a builder, compiler, linker, and debugger. Some diehards are perfectly happy using a bare bones text editor to do their coding, but I need something with at least syntax highlighting. With the amount of complexity in my code, it's nice to have a graphical interface for the debugger too. I use Eclipse, which has both of these and most of the standard Visual Studio features too. If Visual Studio is what you're familiar with, Eclipse should look familiar enough.

The next step is to start downloading these two (FREE!) programs. Be forewarned, the cygwin download takes a long time, even if you can do it over internet2 from your university. To start, download the latest Cygwin setup file from http://www.cygwin.org/cygwin/ Run setup. Click “Next>” at the startup screen. Choose “Install from Internet” and “Next>”. Enter the desired install location (the default is fine) and click “Next>”. Select a local package directory where the downloads will be saved and click “Next>”. Choose “Direct Connection” and click “Next>”. Select a mirror geographically close to your location. (gatech.edu is good for the east coast.) A progress bar will fill while cygwin downloads the list of available packages.


Click “Next>” using the default package selections.

The latest version at the time of this writing (1.5.25-15 ) included the gnu development utilities (binutils, gcc, gcc-core, gcc-g++, gcc-mingw-core, gcc-mingw-g++ gdb, libgcc1, and make) and the x-server by default. You can check to see if these packages are installed by running “cygcheck -c | grep -e '^bin' -e '^gc' -e '^gc' -e '^make' ”.


If packages are missing, you can run setup.exe again to select and download them. You may want to move setup.exe to the desktop for easy access when installing more packages.


Goto www.eclipse.org and download Eclipse for C/C++ developers from the downloads section.


Extract the zip file and copy the files to the desired location. (You may want to create a directory for this purpose such as “c:\program files\eclipse”) It's also useful to create a shortcut for eclipse. Right click on eclipse.exe and select “Create Shortcut”. Copy this shortcut to the desktop.


Add cygwin binaries to the system path in control panel>system>advanced>environment variables. In the bottom “system variables” section, there should be a variable called “Path”. (I'm still on Windows XP, so your control panel will probably look a little different if you're using Vista.)


Select this variable and click “Edit...”. Add a semicolon to the end and then “c:\cygwin\bin”. Make sure directories are separated by semicolons, but no spaces.


Check the cygwin home directory by launching cygwin and typing “ls” to list the files in the directory. These files should match with the username directory in windows. If the files don't match, add a user variable to the environment variables. Go to control panel>system>advanced>environment variables again and in the “User variables for [username]” click “New...”. Make the variable name “HOME” and the variable value “c:\users\[username]” or wherever it is convenient for cygwin to start (like \workspaces, \My Documents\ etc.)


Check the compiler setup by creating a new project. (File>New>C++ project>Executable) Choose “Hello World C++ Project”, just to test. Give the project a name (like “testing”), select “Cygwin GCC” under “Toolchain:” and click “Next”
(This can vary between versions of Eclipse, but you get the idea.)


Fill in author info or just click “Next”. In the “Select Configurations” window, click “Advanced settings...”.



Under the Tool Chain Editor category, change Current builder to CDT Internal Builder. (There are some bugs in cygwin's implementation of make that will prevent it from working properly with the makefiles eclipse generates. Specifically, when running there will be a “multiple target patterns” error.)


If you don't see "CDT Internal Builder" make sure that you selected "Executable" as the project type.

Goto Window>Preferences...>C/C++>Debug>"Common Source Lookup Path" add new path mapping. As compilation path you should use Unix like path (e.g. /cygdrive/c), as local system path you should use Windows like path (e.g. “c:\”). Without this mapping, the program will not debug or run in eclipse. (You should only have to do this once, after you install Eclipse.)



In newer versions of Cygwin g++ (3.4.4-999 and beyond – you can check this by running setup.exe) g++ is a shortcut to the application, not the binary itself. This will cause the build command in eclipse to produce an error like “g++ cannot be launched.” To make this compatible with eclipse, change “Project properties > settings > Cygwin C++ Compiler” and “...>Cygwin C++ Linker” “Command:” to be g++-3 instead of g++.



This shortcut problem is actually really pervasive, so you'll need to modify the Discovery Options as well. Uncheck both "enable..." boxes under "Discovery profile options". Then go to "Cygwin C++ complier" under tools and do it again.


Older versions of Eclipse used to include the Cygwin headers automatically, but Indigo doesn't seem to do that anymore. They may be in similarly named directories, or if your cygwin setup doesn't match mine, you can search for "iostream" in the cygwin folder in windows explorer and find out what yours are called.

This is enough to get my "Hello, World!" running, but you may need more if you're using stdio.h or some of the other common headers that should be built-in.

Hopefully if you changed all those settings, there should be no errors or warnings listed in the "problems" tab at the bottom.


If you do still have errors, check that the project explorer (above image, left) lists the cygwin include directories. If your errors are along the lines of "command not found", see the above instructions for changing g++ to g++-3 and turning off the discovery options.

Hopefully at this point you have no errors or warnings. Now type some text in between the quotes in your main() function and go to project>build project to build your binaries. Provided that went smoothly, click the arrow on the green Run button on the top toolbar and your text should appear in the console tab at the bottom of the screen.


Clearly there's a lot of overhead involved in setting up your first C++ project in Eclipse. If you're like me, though, the vast majority of your work will be with the same project. So the good news is that you'll only have to go through this once. This system isn't perfect, but there are a lot of other Eclipse and Cygwin users out there. Eclipse.org has a great community forum, so if you're still having problems often a quick Google search will reveal that someone else has already gotten whatever cryptic error you have and solved it. And if not, there's always Visual Studio.