Using Eclipse with CDT

This is a tutorial to get you started on creating C and C++ programs in Eclipse.

Programming in C/C++ in Eclipse requires the CDT (C/C++ Development Tooling) plug-in and a C/C++ compiler.

Note that this guide describes a Windows version of a C/C++ compiler. If you are using a Mac or Linux, you will require a different compiler set up. The Eclipse instructions remain mostly the same.

There are a number of different compilers available to you, depending on your computer's operating system and requirements. For Windows, there is:

All of these are versions of the GNU Compiler Collection (gcc). Whether using Windows, Mac, or Linux, so long as the compiler is gcc compatible, you should have no problem writing and executing programs for this course. Eclipse, of course, runs on Windows, Macs, and Linux.

Linux installations normally come with gcc installed. For Windows we recommend the installation of some version of Cygwin.

NOTE: the compiler collection installation folder must not have spaces in its name. For Windows, Cygwin recommends installing it in C:\cygwin64. After installation the C:\cygwin64\bin must be added to the system path. See the installation instructions at: How to Install and Configure Cygwin in Windows Environment.

NOTE: the Cygwin installation process on Windows can take a long time!

(If you experiment with other installations, please let us know how things turn out.)

The university computers have Cygwin installed.

The Eclipse CDT plug-in allows you to create and execute C and C++ programs in Eclipse in ways similar to how the PyDev and Java plug-ins work. The CDT plug-in is installed in the Physics & Computer Science labs as well as the WLU public computer labs. You may install it on your own computers as well. CDT works with Cygwin gcc and a wide range of other C/C++ compilers.

The simplest way to install CDT is through the software repository install process. From the Eclipse menu, choose Help / Install New Software…, which brings up the Install dialog box:

Available Software Dialog
install_empty (24K)

The software repository as of this writing is http://download.eclipse.org/tools/cdt/releases/9.8. (Check the CDT Downloads page for the latest URL.) Press to bring up the Add Repository dialog box to add this URL to your list of available Eclipse software sources:

Add Software Repository Dialog
add_repository (5K)

Pressing OK connects you to the software repository, and lists the CDT packages available:

Available Software Dialog
install_available (24K)

For now you need only select the C/C++ Development Tools. There are a number of optional features that you may find useful later on - install them in the same way you install the main features. Press to review the installation details:

Install Details Dialog
install_details (27K)

Press and accept the license:

Review License Dialog
install_license (22K)

Press to complete the installation. Restart Eclipse if necessary.

Whether using Cygwin or another gcc compiler, you can verify that CDT recognizes it. From the Eclipse menu choose Window / Preferences (on the Mac choose Eclipse / Preferences), and select C/C++ / New C/C++ Project Wizard:

Preferences Dialog
preferences_project_wizard (42K)

This dialog box lists all the compiler toolchains that CDT recognizes, and you can limit the list to only the ones available on your computer. Highlight the toolchain(s) you prefer to use, and press .

There are number of other formatting and editing options available. We require your C code to be nicely formatted. From C/C++ / Editor / Save Actions select the options as shown:

Save Actions Dialog
preferences_save_actions (20K)

Press to complete the CDT customization.

CDT can help you add rich documentation to functions and code. From C/C++ / Editor / Documentation Tool Comments set the Workspace default to Doxygen:

Editor Dialog
C/C++ templates

We also require you to set up default comments for your files. From C/C++ / Code Style / Code Templates / Comments / File:

Code Templates Dialog
C/C++ templates

Choose to open the Edit Template dialog:

Edit Template Dialog
C/C++ templates

and copy and paste the following text (replacing the appropriate values) to the template:

/*
-------------------------------------
File:    ${file_name}
Project: ${project_name}
file description
-------------------------------------
Author:  your name here
ID:      your ID here
Email:   your Laurier email here
Version  ${id:date('yyyy-MM-dd')}
-------------------------------------
 */

Press to save the changes.

These comments will be added to the top of every source code and header file you create in CDT.

Different plug-ins provide different looks, or 'perspectives' to Eclipse, and it is best for working with CDT if Eclipse is running in the C/C++ perspective. From the main menu, choose Window / Perspective / Open Perspective / Other and click on the C/C++ perspective:

Open Perspective Dialog
open_perspective (11K)

Right-click in the Project Explorer and choose New / Project. (If the menu shows a C project as an option, you may skip the following dialog box.) From this dialog choose a C project:

New Project Dialog
new_project (22K)

This brings up the Templates for New C/C++ Project dialog box. Select the C Managed Build template:

C Project Templates
c_project (25K)

This brings up the C Project dialog box. Give the project a name and choose Hello World ANSI C Project. (Note that the toolchain should already be selected.):

C Project Dialog
c_project (25K)

The Hello World ANSI C Project provides the code to create a simple "Hello World" program. This gives you immediately working code that you change to whatever actual code you wish. Press to complete the project set-up.

This creates a project entry in the Eclipse Project Explorer pane and opens the "Hello World" C source code file:

Editor Window
hello_c (33K)

From here you may enter your C code, add files and folders, format your code, etc.

Add new header and source code files to a project by right-clicking on the src folder and choosing the appropriate type from the pop-up menu:

Adding a File
add_new (28K)

If you don't see the type of item you want to add, choose Other… and select what you need from the complete list of available items.

By default, a project looks in the project folder and the Cygwin include folder for these files. Library header files are included by using the <…> syntax; header files that you write in your src folder are included by using the "…" syntax. Thus:

#include <stdio.h>

includes the stdio library header in your program, while:

#include "lab01.h"

includes the lab01.h header file from the project src folder in your program.

Compile and link (build) the project by choosing Project / Build All from the Eclipse main menu. The console show the result:

22:52:26 **** Incremental Build of configuration Debug for project dbrown_lab01 ****
Info: Internal Builder is used for build
gcc -O0 -g3 -Wall -c -fmessage-length=0 -o "src\\dbrown_lab01.o" "..\\src\\dbrown_lab01.c"
gcc -o dbrown_lab01.exe "src\\dbrown_lab01.o"

22:52:26 Build Finished (took 374ms)

Eclipse/CDT takes care of adding appropriate libraries, etc. to the gcc compiler and linker calls.

Should project source code have errors, they are displayed in the Editor window, listed in both the Console and Problems tabs if you attempt to compile the code. For example, leaving the semi-colon off the print statement in the Hello World program not only displays warnings and errors in the editor and the Problems tab:

Sample Errors
editor_warnings (23K)

Attempting to compile this code displays the following errors in the Console tab:

23:02:36 **** Rebuild of configuration Debug for project dbrown_lab01 ****
Info: Internal Builder is used for build
gcc -O0 -g3 -Wall -c -fmessage-length=0 -o "src\\dbrown_lab01.o" "..\\src\\dbrown_lab01.c"
..\src\dbrown_lab01.c: In function 'main':
..\src\dbrown_lab01.c:17:2: error: expected ';' before 'return'
  return EXIT_SUCCESS;
  ^
..\src\dbrown_lab01.c:18:1: warning: control reaches end of non-void function [-Wreturn-type]
 }
 ^

23:02:36 Build Finished (took 156ms)

Errors and warnings often persist until the code is rebuilt. To guarantee that there are no lingering problems from previous builds, choose Project / Clean… from the Eclipse main menu. This clears out all errors and warnings and deletes any previously compiled object files. You must rebuild the code after a clean.

After a successful build, Eclipse creates object files (*.o) and an executable file (*.exe) in the Debug folder of the project. The executable file is also listed under Binaries, although there is no actual Binaries folder created on disk. The project contents may look like this:

Project Explorer Dialog
project_build (12K)

Right click on the source code, project name, or the project binary in the Project Explorer and choose Run As / Local C/C++ Application to execute your program.The working cube executable produces the following output:

!!!Hello World!!!

in the Console tab.

A graphics program opens a new window in Eclipse.

The following code may not behave quite the way you want in C:

#include <stdio.h>
#include <stdlib.h>

int main(int argc, char *argv[]) {
    int number = 0;
    printf("Enter a number: ");
    scanf("%d", &number);
    printf("The number you entered is %d\n", number);
    return 0;
}

The program execution under Windows and Eclipse ends up as:

7
Enter a number: The number you entered is 7

which is not quite what we had in mind. This is due to a buffering problem: In C, output is buffered, simply meaning that output is held back from the console until specific events happen, such as printing an end of line (\n). However, even adding the end of line as:

    …
    printf("Enter a number: \n");
    …

does not correct the problem in this case.

The simple fix is to turn off output buffering entirely:

#include <stdio.h>
#include <stdlib.h>

int main(int argc, char *argv[]) {
    setbuf(stdout, NULL); // turns standard output buffering off
    int number = 0;
    printf("Enter a number: ");
    scanf("%d", &number);
    printf("The number you entered is %d\n", number);
    return (0);
}

Note that output buffering must be turned off at the beginning of the program before any output has taken place.

Note that on some compilers the buffering is turned off by default. Even if this is the case with your compiler, put the setbuf line in anyways, as your code must be compatible with our compiler for marking purposes.

This approach produces the desired output:

Enter a number: 7
The number you entered is 7

By default, C executables that are run from Eclipse do so without any command line parameters. To add parameters to the execution, from the Eclipse main menu choose Run / Run Configurations. This brings up the Run Configurations dialog box:

Run Configurations Dialog
run_configurations (42K)

The left side of the dialog box lists the types of programs your copy of Eclipse supports. Clicking on the cross to the left of C/C++ Application lists all the C programs currently compiled and ready to run. Click on the executable you wish to run. After selecting your executable, the right side of the dialog box lists the options you may apply to the executable. Click on the (x)= Arguments tab. You may now enter your execution parameters into the Program arguments: box. Click on to execute your program with the command line arguments. The program runs in the Eclipse console as usual.

If the Run Configuration dialog box lists no configurations, simply right-click on the C/C++ Application option and click on New. You may then select both the project and the executable you wish to run by pressing the appropriate in the Main tab. Note that the project must be compiled and an executable file exist before this works.

You may remove old run configurations by right-clicking on them and choosing Delete.

The CDT debugger allows you to walk through your program's source code line-by-line, and view the contents of it variables as the code is executing. Your code must be compiled and linked without errors in order for the debugger to work.

To start the debugger, right-clock on the project's executable file in the Project Explorer and choose Debug As. (You may click on the file in either the Binaries or the Debug folder - they refer to the same file):

Debug As menu
debug_right_click (42K)

(The first time you do this a dialog box will pop up, asking if you wish to switch to the Debug perspective, and if you wish to do so every time you debug. Say yes to both.)

Choose Local C/C++ Application if your program does not require command-line parameters, and Debug Configurations… if it does. (See the previous section on Command Line Parameters if necessary.)

You may now walk through your code line-by-line, or by setting breakpoints and executing multiple lines. At each step you can see the current values of your variables in the Variables tab, and your program output as usual in the standard Console pane. The Editor pane shows you what line in your program is currently being executed. (Be aware that the Editor pane will allow you to edit your code, but be aware that none of your source code changes will execute until you have left the debugger and re-compiled your program.) Eclipse will now look something like this:

Debug Dialog
debugging (84K)

In this example, the line setting the integer constant DIFF has already been executed, and its name, type, and value (32) appears in the Variables tab. The line calling the setbuf function is highlighted, indicating it will be executed next.

Code can be executed a number of different ways. The Run menu and the menu bar provide the following options:

Breakpoints are simply points in a program where you can pause its execution, allowing you to examine the current state of the running program. Breakpoints are executable lines in the source code where you choose to have the program execution stop until you allow it to continue executing. Breakpoints are extremely helpful in tracing a program's execution and finding errors in that execution.

Breakpoints are set in the program source code. To set a breakpoint on a given line of source code, move to that line and right-click on the blue bar at the far left of the editor pane. If the right-click context menu has the option greyed-out, you must set the breakpoint type. (You should only have to do this once per debug session.) From the context menu choose Breakpoint Types / C/C++ Breakpoints:

Available Software Dialog
breakpoint_types (22K)

Now that the breakpoint types are set, right-click on the blue bar again and choose Toggle Breakpoint:

breakpoint_toggle (13K)
Breakpoints Menu

This puts a small breakpoint mark into the blue bar to the left of the source code statement that now has a breakpoint:

Breakpoints Menu
breakpoint_mark (2K)

Now when you use Resume to execute the program, execution pauses at every breakpoint set. Thus setting a breakpoint inside a loop allows you to examine the state of a variable as it changes with every step of the loop execution.

When finished debugging, terminate the debugger and return to the normal C view from the menu Window / Perspective / Open Perspective / C/C++:

Breakpoint Example
perspective (21K)

It is very helpful to have your code nicely formatted at all times. C does not require its code to follow any particular formatting rules, but you can set Eclipse up to format your code automatically.

Eclipse provides a set of different possible formats - we suggest you use the K&R formatting. From the main menu choose Window / Preferences and go to C/C++ / Code Style / Formatter:

Formatter Dialog
formatter

and select the K&R [built-in] Active Profile.

You can format your code any time from the editor by choosing Source / Format from the main menu.

A better approach is to instruct Eclipse to format your source code file every time it is saved. To set this up, choose Window / Preferences from the main menu, and go to C/C++ / Editor / Save Actions:

Save Actions Dialog
save_actions

Check all of the checkboxes. Now, whenever you save your C code, it will automatically be formatted.

CDT can help you add rich documentation to functions and code. From C/C++ / Editor / Documentation Tool Comments set the Workspace default to Doxygen.

Setting the Dialect

C comes in a number of dialects, the details of which usually don't matter for us. Upon occasion you may need to use a particular dialect to meet some requirement. To set the dialect for a particular project, right-click on the project name and choose Properties / C/C++ Build / Settings / Dialect and choose the required dialect from the language standard drop-down box:

Settings: Dialect Dialog
dialect

The Eclipse home page: http://www.eclipse.org/

The Eclipse CDT plug-in: http://www.eclipse.org/cdt/

The Cygwin home page: https://www.cygwin.com/