Eclipse and CDT for C/C++ Programs

• Download a-static-library-project - 7 KB
• Download an-executable-project - 2.8 KB
• Download makefile-example - 935 B

Introduction

This is a note on writing C/C++ programs with help from Eclipse and CDT.

Background

This note is not about C/C++ or makefile. It is not about object orientation. It is about IDE. It is a note on writing C/C++programs with the help from Eclipse and CDT. I will use GNU GCC/G++ and make for the examples. I will give examples in both Linux and Windows. I realize that this note becomes unnecessarily lengthy and complicated/convoluted, because all I want to do is to answer the following simple questions through the examples.

• What is needed to compile a C/C++ program?
• What are makefiles?
• Do we need an IDE for C/C++?
• What Eclipse package can I use for C/C++ development?
• How Eclipse build/compile C/C++ programs?
• What is a build configuration in Eclipse?
• What are the C/C++ project types in Eclipse?
• What are "Build Artifacts" for C/C++ projects in Eclipse?
• What is a Run/Debug launch configuration?
• How Eclipse provides intellisense when we use third party libraries that are not under Eclipse's control?
• If we use third party libraries, what we will need to tell Eclipse so it can generate the correct "makefiles" for us?
• How to reference another project from a project in the same Eclipse workspace?
• If I create a C/C++ project in Linux, can I move it over to Windows smoothly?
• From the examples, what do you think to be the most important concepts to know to use Eclipse for C/C++ development?
• How do you feel Eclipse as an IDE for C/C++ development?
• What else do you want us to know?

If you do not have enough patience, you may directly go to the summary section to see the answers. If you encounter any problems in your own projects, you may come back for the details. It may serve you some reference value in the future. All the attached example projects are created in Linux. If you want to download and try them in Windows, you may need to refer to Example 3 - Project Compatibility between Linux and Windows section. In any case, let us have the environment ready for the examples first.

Environment Setup

Linux Environment

In most Linux systems, the environment is already installed by default. But it is better to double check it. In my Linux Mint machine, I noticed that "g++" is not installed, so I installed it by sudo apt-get install g++. In an Ubuntu/Mint computer, you can issue the following commands to check if "gcc", "g++", and "make" are installed.

• which gcc
• which g++
• which make

If they are installed, the which command will tell you the installation directory. If they are not installed, you can install them by sudo apt-get install build-essential.

Windows Environment

In Windows systems, the correspondence for GNU is MinGW. You can install MinGW by following the on-line instructions. For simplicity, I installed MinGW using the provided automated GUI installer. After the installation, you need to add the C:\MinGW\bin and C:\MinGW\msys\1.0\bin (or whichever folder where you installed MinGW) to your Windows Path variable. You can check your installation by the following commands:

• gcc --help
• g++ --help
• make --help

According to the MinGW documentation, you should avoid an installation path that has spaces.

Eclipse IDE

Eclipse is a Java program. It works on both Linux and Windows. For C/C++ development, you can use Eclipse IDE for C/C++ Developers, which is packaged with CDT. You can also install CDT on other Eclipse packages using the Eclipse Marketplace. You may want to refer to this link to make sure that Eclipse is using your desired Java version. In this note, I used Eclipse IDE for C/C++ Developers Mars 1 for all the examples.

A Simple Makefile Example

In most cases, Eclipse builds C/C++ programs by makefiles. Before starting to use Eclipse, it is beneficial to manually build a makefile program. The attached makefile-example.zip is the simplest possible makefile project, which has a C++ source file, a makefile, and an empty build directory where we will be putting the compiled object file and the executable file.

#include <stdio.h>

int main() {
    printf("This is an make file example\n");
    return 0;
}

CC=g++
BUILD=build

all: $(BUILD)/makefile-example

$(BUILD)/makefile-example: $(BUILD)/main.o
    $(CC) -o $(BUILD)/makefile-example $(BUILD)/main.o

$(BUILD)/main.o: main.cpp
    $(CC) -c -o $(BUILD)/main.o main.cpp

run: $(BUILD)/makefile-example
    $(BUILD)/makefile-example    

clean:
    find $(BUILD) -type f -delete

How to use GNU make is a comprehensive subject. If you are dedicated toward C/C++ development, you will have to eventually go through this document. But for this note, you should know the following:

• In the directory where you place your makefile, if you issue a make or make all command, the object file and the executable will be built into the build folder;
• If you issue a make clean command, the object file and the executable will be deleted.

The following shows that the make run command built the project and also executed the executable file.

Example 1 - A Simple Executable Eclipse Project

As the first Eclipse example, I will create a simple executable project. From Eclipse -> File -> New -> C++ Project, we can launch the project wizard.

I will create an empty executable project. Since I am creating the project in the Linux environment, I chose Linux GCC as the toolchain. For simplicity, I added only one main.cpp file to the root directory of the project.

#include <stdio.h>

int main() {
    printf("This is a simple executable project\n");
    return 0;
}

If we now right click the project name -> Build Project, you will notice that a Debug directory is created by Eclipse. In the Debug folder, you can see the makefile (and a few .mk files associated to the makefile) and the executable file named as an-executable-project.

If we now right click the project name -> Run As -> Local C/C++ Application, you will see that the executable file is executed.

With this simple example running, we are ready to take a look at how Eclipse manages C/C++ projects to answer the following questions.

• How does Eclipse build the C/C++ programs?
• How does Eclipse run/debug the built executable file?
• How are the makefiles generated?

The Build Configurations

Let us now right click the project name -> Properties -> C/C++ Build. We can see the build settings.

The build settings tool is the main place for us to configure how Eclipse builds our applications. Click on the Manage Configurations... button, we can see that Eclipse created two build configurations for the empty executable project.

We can add, delete, rename build configurations. If we have more than one build configuration, we can set one of them to be active. The active build configuration is the build configuration being used when we right click the project name -> Build Project/Clean Project. When we add a new build configuration, we will notice the text that "The configuration name will be used as a directory name in the file system". Since the active configuration is Debug, the Debug folder is created when we build the project, which contains all the Eclipse generated makefiles, object files and the executable file related to the Debug configuration.

For the Debug configuration in the Behavior tab, you will notice that Eclipse builds the project by the make all command and clears the project by make clean command.

I want to take the chance to add an additional note on the Refresh Policy tab, which is applicable to all Eclipse projects, not just C/C++ projects.

In Eclipse, the definition of Refresh is not well documented. Generally speaking, Eclipse tries to get all the information on all the files in the project and tries to use the information to provide us as many conveniences as possible, such as syntax highlighting, intellisense, etc. This is relatively easy if all the changes go through Eclipse. But sometimes, the files may be changed outside of Eclipse. For example, the files may be changed by other programs, such as checking out some code from a source control system. The Eclipse Refresh analyses the source files and possibly other files to check if any changes were made from outside Eclipse, and if so, Eclipse will try to bring the changes into its control.

The Launch Configurations

Right click the project name -> Properties -> Run/Debug Settings. We can see the launch configurations.

After building the project when we right click the project name -> Run As -> Local C/C++ Application, Eclipse created a launch configuration an-executable-project for us. We can add, edit, and delete launch configurations.

For the an-executable-project launch configuration, we can see the following:

• If we run the project in Eclipse through the an-executable-project configuration, we will be running the an-executable-project file in the Debug directory;
• The launch configuration is associated to a build configuration. By default, when we run the project in Eclipse, it will trigger a build with the associated build configuration to rebuild the executable file in the Debug directory.

We know that each build configuration builds the executable file into its own directory. We should make sure that the executable path in the launch configuration matches the build configuration. Otherwise, you will notice that you are running the old executable file even when you have made changes to the source code. Eclipse does not automatically adjust the executable path if you change the associated build configuration for the launch configuration.

Configure How the Makefiles are Generated

In the an-executable-project, you should have noticed the Generate Makefiles automatically checkbox.

• If you create an Executable, a "Static Library", or a "Shared Library" project, this checkbox will be automatically checked;
• If you create a Makefile project, you are telling Eclipse that you will be creating the makefiles by yourself. But you can always change your mind and check this checkbox to let Eclipse to generate the makefiles for you.

If the Generate Makefiles automatically is checked, you can control how the makefiles are generated by right click the project name -> Properties -> C/C++ Build -> Settings.

For the simple an-executable-project, we do not need to make any changes to the default settings. If you take a look at the Debug build configuration, you will see that Eclipse added -g3 by default to the compile options, so that we can run the compiled executable file in the debug mode. If the default settings do not fit your need, you can always alter the settings to let Eclipse to generate your desired makefiles.

In the Build Artifact tab, you have the option to change the Artifact Type. The artifacts correspond to the project types in Eclipse. If we want to change the project type after the project is created, we can change it here. Different build commands will be added in the generated "makefiles" for different artifact types to build the project into an executable, a shared library or a static library.

For a build configuration, you can change the Build type. The makefiles will be explicitly generated in the corresponding build directory only when the "External builder" option is chosen. It is important to remember that the settings on how makefiles are generated are configured on a per build configuration base.

Example 2 - A Static Library Project and Project References

In this example, I will create a static library project. I will also create an executable project. The goal of this example is to show how to reference the static library from the executable project. Let us first create the static library project.

The Static Library Project

The static library project is named static-math-library. After the project is created, we can right click the project name -> Properties -> C/C++ Build to check out the build configurations.

We should see that Eclipse created two build configurations, and the Debug is the active configuration. If we further right click the project name -> Properties -> C/C++ Build -> Settings, we can see how the makefiles are generated.

We should see that the makefiles will be using the ar command to package the project into a static library. Now we can add a simple class. The Math.h file is added into the header directory.

#ifndef HEADER_MATH_H_
#define HEADER_MATH_H_

namespace static_math {

class Math {
public:
    Math();
    virtual ~Math();
    virtual int WeightedAdd(int i, int j);
};

}

#endif

The Math.cpp file is added to the src directory.

#include "../header/Math.h"

namespace static_math {

    Math::Math() {}
    Math::~Math() {}

    int Math::WeightedAdd(int i, int j) {
        int w = 1;

        return w * (i + j);
    }
}

Right click the project name -> Build Project, the static library libstatic-math-library.a is built into the Debug directory, since the Debug build configuration is the active build configuration.

You may want to pay some attention that the header file and the cpp file are put into different directories. This will influence how we reference the static library project from the executable project that we are going to create.

The Executable Project

In order to use the static-math-library, let us create an executable project static-math-executable. After the project is created, let us add the main.cpp file to the root directory of the project.

#include <stdio.h>
#include "Math.h"

int main() {

    static_math::Math math;
    int result = math.WeightedAdd(1, 2);

    printf("The weighted addition is %d\n", result);

    return 0;
}

After we save the main.cpp file, we will immediately see the following problems:

In order to reference the static-math-library project, we need to do the following:

• We need to tell Eclipse where to find the header file, so we can use intellisense in the text editor;
• We need to tell Eclipse where to find the header file, so the generated makefiles knows how to add the correct -I option to compile to code;
• We need to tell Eclipse where to look for the static library and the name of the library, so the generated makefiles knows how to add the correct "-L" and "-l" options to link the executable file.

Configure the Project Reference

In Eclipse, the easiest way to tell the static-math-executable project where to find the header file and the static library is to right click the project name static-math-executable -> Properties -> C/C++ General -> Paths and Symbols and open the References tab.

You can check the desired project reference. You should keep in mind that the reference is configured on a per build configuration base. For the Debug configuration in the static-math-executable project, we chose to reference the Debug configuration in the static-math-library project.

If we now take a look at the Includes tab, Eclipse automatically added the root directory of the static-math-library project in the include path after we configure the reference of the build configurations. It hopes to find all the header files in the root directory in the static-math-library project.

It also added the Debug directory of the static-math-library in the Library Paths tab, where it expects to find the static library.

And finally, Eclipse also added the static-math-library in the Libraries tab, that it will add as -l option to the makefile when it links the executable file.

Fix the "Includes" Path Manually

Since we have added the project reference, you would expect that we can build the static-math-executable. But unfortunately, when you build it, you will see the following problem.

The reason is that Eclipse added the root directory of the static-math-library project in the Includes path, but the Math.h file is in the header directory. We need to change the Includes to the header directory.

Now we can right click the project name -> Build Project to build the executable file. After the executable is built, we can right click the project name -> Run As -> Local C/C++ Application to run the executable file.

If you now make some changes to the Math.cpp, you will notice that you do not need to build the static library and the executable projects separately. You can simply run the executable project, a complete re-build will be triggered, because the project reference tells Eclipse to rebuild it all if the static-math-library is modified.

Example 3 - Project Compatibility between Linux and Windows

Until now, all the example projects are created in Linux. It will be interesting to see how they work if we copy them into Windows. In this example, I will copy the two projects, static-math-library and static-math-executable in "Example 2" into Windows.

• Before I made the copy, I ran "Clean Project" on both of the projects, and deleted all the build configuration related directories, like Debug and Release directories if they are in the project.;
• By deleting the Debug and Release directories, I force Eclipse to regenerate the makefiles for the build configurations after the projects are loaded into Eclipse;
• To try these projects in Windows, I will need to make sure the MinGW is setup in Windows.

In Windows, we can launch Eclipse using an "EMPTY" "workspace" folder. After launching Eclipse, we can import the two projects copied from Linux. Since static-math-executable project references static-math-library project, I imported the static-math-library project first. Since the projects are already Eclipse projects, I imported them by File -> Import... -> General -> Existing Projects into Workspace.

Since we will be using MinGW to compile the C/C++ code in Windows, we can right click the project name -> Properties -> C/C++ Build -> Tool Chain Editor to change the tool chain. We need to do this for both of the projects.

• The current tool chain is changed to MinGW GCC;
• The current builder is changed to Gnu Make Builder.

If we now right click the static-math-executable project -> Build Project, we can see that both projects are built successfully. Because it is on Windows, the executable file has an exe extension.

After the projects are built, we can right click the static-math-executable project -> Run As -> Local C/C++ Application to run the executable file.

Not all C/C++ projects can be moved from Linux to Windows easily. But for the example shown here, the transition is very smooth and pleasant.

Summary

We are now ready to answer the questions presented at the beginning of this note.

• What is needed to compile a C/C++ program?
  • In Linux, you can use GNU GCC/G++ and make;
  • In Windows, you can use MinGW;
  • There are other C/C++ compilers. The most noticeable one is Microsoft Visual C++, but it is not in the scope of this note.
• What are makefiles?
  • A makefile is a set of C/C++ compilation commands organized by some predefined rules;
  • Most common makefiles will have the all and clean rules to compile the C/C++ projects and to clear all the build results;
  • In most common use cases, Eclipse use all to build the projects and use clean to clear the build result.
• Do we need an IDE for C/C++?
  • The answer is "NO" and "YES";
  • A lot of C/C++ experts choose not to use an IDE, because they are experts in creating their own makefiles and they are familiar with all the commands to build/debug a C/C++ program;
  • For less experienced C/C++ programmers, an IDE can be a great help. It provides an easy overview of the C/C++ project. It provides intellisense, real-time syntax check. It provides an integrated debug environment. For less experienced C/C++ programmers, it can generate the makefiles for you;
  • Even for experienced C/C++ programmers, if you take a large chunk of code written by other people, it is good if you load it into an IDE to study and read it. It is so much easier than reading the document. In most of the cases, the document is actually not very well written;
  • From my experience, I will say "YES". We need an IDE.
• What Eclipse package can I use for C/C++ development?
  • If you only want it for C/C++ development, you can download the Eclipse IDE for C/C++ Developers;
  • You can also install CDT on other Eclipse packages using the Eclipse Marketplace;
  • All the examples in this note are created by the Eclipse IDE for C/C++ Developers.
• How Eclipse build/compile C/C++ programs?
  • Eclipse uses makefiles to build C/C++ programs;
  • You have options to provide your own makefiles or let Eclipse to generate makefiles for you;
  • If you do not explicitly change it, Eclipse will use make all command to build the projects and make clean to clear the build result;
  • If you choose to let Eclipse to generate makefiles for you. Only when you use an External builder, Eclipse will generate the makefiles explicitly.
• What is a build configuration in Eclipse?
  • A build configuration is a set of rules for you to control how Eclipse builds your projects;
  • You can have multiple build configurations for a project and you must have exactly one active configuration;
  • You can set any one of them to be the active build configuration;
  • When you build or clear the project, the one that takes effect is the active build configuration;
  • In Eclipse, the name of a build configuration corresponds to a directory/folder in the file system. Eclipse will put the generated makefiles and the build results into this directory/folder.
• What are the C/C++ project types in Eclipse?
  • From a larger view, Eclipse only provides two project types. The Makefile Project type means that you will provide the makefiles by yourself, the other types mean that you will let Eclipse to generate the makefiles for you;
  • If you choose to let Eclipse to generate makefiles, you can choose an Executable, a "Static Library", or a "Shared Library" project type.
• What are "Build Artifacts" for C/C++ projects in Eclipse?
  • If you choose to let Eclipse to generate makefiles for you, a build artifact corresponds to a project type;
  • The build artifact most affects how the makefiles are generated, because an Executable, a "Static Library", or a "Shared Library" needs different command to build.
• What is a Run/Debug launch configuration?
  • You can run/debug an Executable project in Eclipse;
  • A Run/Debug launch configuration tells Eclipse which executable file to run or debug;
  • A Run/Debug launch configuration is associated to a build configuration. If you made changes to the code, Eclipse will re-build the project using the associated build configuration before the executable is launched;
  • You can have multiple Run/Debug launch configuration, you can choose one of them to run/debug you executable file in Eclipse.
• How Eclipse provides intellisense when we use third party libraries that are not under Eclipse's control?
  • Eclipse needs to know the header files of the third party libraries to provide intellisense;
  • You can right click the project name -> Properties -> C/C++ General -> Paths and Symbols to add the header file locations to the Includes tab.
  • Even when we are referencing another project in the same Eclipse workspace, Eclipse may not have all the knowledge about the header files, you may need to add them manually if needed.
• If we use third party libraries, what we will need to tell Eclipse so it can generate the correct makefiles for us?
  • We need to tell Eclipse the header file locations;
  • We need to tell Eclipse where to find the third party library;
  • We need to tell Eclipse which file is the third party library;
  • We can do this by right click the project name -> Properties -> C/C++ General -> Paths and Symbols.
• How to reference another project from a project in the same Eclipse workspace?
  • The best way to reference another project from a project in the same Eclipse workspace is to right click the project name -> Properties -> C/C++ General -> Paths and Symbols and check the References tab;
  • The reference is configured on a build configuration, not the whole project. It references another build figuration of the other project;
  • Adding the reference may not tell all the information about the referenced project, you may need to manually change some settings.
• If I create a C/C++ project in Linux, can I move it over to Windows smoothly?
  • In the example in this note, the process is very smooth;
  • But there is no guarantee because the environment may not be compatible nicely.
• From the examples, what do you think to be the most important concepts to know to use Eclipse for C/C++ development?
  • The build configurations are the most important to know because they tell how the project will be built. It is important also because almost all the other configurations are associated to a build configuration;
  • The Run/Debug launch configurations are important because you will normally debug your code in Eclipse. It is very important to know that a launch configuration is associated to a build configuration, so you are sure exactly which executable file is running as you may have multiple of them because you may have multiple build configurations;
  • The Paths and Symbols configurations, particularly the Includes configuration is important. You need to tell Eclipse where to find all the header files, so Eclipse can provide intellisense to help you write the code;
  • If you want Eclipse to generate makefiles for you, you may want to check all the tabs in the C/C++ General -> Paths and Symbols to make sure that Eclipse generates the correct makefiles;
  • If you are comfortable to create makefiles by yourself for a large enough project, you are already a C/C++ expert and you may already have your own judgment.
• How do you feel Eclipse as an IDE for C/C++ development?
  • Generally speaking, I feel Eclipse does a decent job as a C/C++ IDE;
  • The makefiles generated by Eclipse are decent;
  • The configurations and project/third party references are manageable;
  • The learning curve to use Eclipse for C/C++ development is moderate and manageable for people who are not C/C++ experts.
  • In rare cases, you may encounter some glitches. If you are sure that you are not making any mistakes, you can normally solve the problems by cleaning the project and re-building it. Sometimes, a manual project refresh can also help.
• What else do you want us to know?
  • Instead of copying to this note, I found this stack overflow link very helpful;
  • I hope you can start to use Eclipse as your C/C++ IDE after reading this note. At least you will know where to find the fixes for the problems that you encounter.

Points of Interest

• This is a note on writing C/C++ programs with the help from Eclipse and CDT;
• The note ended up being unnecessarily lengthy and complicated/convoluted. If you do not have the patience, you do not need to read it. You can only take a look at the questions and the answers;
• All the attached projects are created in Linux. If you want to try them in Windows, you can refer to the "Example 3 - Project Compatibility between Linux and Windows" section;
• I hope you like my posts and I hope this note can help you in one way or the other.

History

• 12^th February, 2016: First revision