Post navigation

Renaming Eclipse CDT Projects

When I create a project in Eclipse (e.g. in Kinetis Design Studio with the GNU ARM Eclipse plugins), I have to specify the name of the project during creation time:

Project Name in Eclipse

But what if I change my mind later on and want to use a different name? How to rename the project?

Outline

Renaming a project requires some knowledge about the internals how Eclipse (CDT, actually) works with project names. This post explains how the work together and how to rename a project.

Where is the Name?

First, lets have a look where the project name (in my case ‘MyProject’ is visible and used in the Eclipse Project Explorer. The following is for an ARM Cortex-M4 project (Freescale/NXP Kinetis K20 device):

MyProject Example

All these name references are defined by the program or wizard creating that project. So they are not that much Eclipse specific, but specific to the tool creating that project.

As shown in the above example, the project name is used basically in three places:

The project name and project folder on disk

The output files of the linker (.elf file and linker map file)

The names of the debugger launch configuration files

Project Name and Project Folder

The first thing to learn is where Eclipse knows the project name.

In the Eclipse Project Explorer my project shows up like this:

Project Name in Project Explorer

You might think that this name comes from the folder name on disk. Indeed, the project folder on the disk has the same name: ‘MyProject’:

Eclipse project on Disk

There are two important files:

.cproject contain all the project settings and compiler options (Eclipse CDT level, notice the ‘c’ in the file name for ‘C/C++’)

.project has the information about the project (Eclipse level)

The .project file is usually filtered in the Eclipse Project view. If I open it in a text editor it has this content:

The project name is defined by the <name> tag on line 3. So technically I *could* use a different project name than the folder name, although this is more for expert users. My recommendation is to keep the folder name on disk in sync with the project name for Eclipse.

Renaming the folder *and* the project name in that .project file can be done with the Rename menu:

Project Rename Menu Item

With a dialog I can rename that ‘Resource’:

Rename Resource Dialog in Eclipse

The above is a *Core Eclipse* (or Framework) function and unfortunately is not aware of the Eclipse CDT. So it only changes the folder name on disk and the <name> entry in the .project file. Everything else remains the same:

Renamed Project Folder

💡 This separation of the Eclipse framework and the CDT (or JDT) makes Eclipse very modular, but not user friendly as each part does not know much about each other. I would say that’s one of the pains of Eclipse for years, and probably will not go away in the near future :-(.

In the next steps I’m going to update the changed project name on the CDT part.

Build Output

The build output file (.elf file) is named ‘artifact’ in CDT. The setting for it is in the project properties, C/C++ Build > Settings > Build Artifact:

Build Artifact Name

I can change the name to anything I want. If I want to keep the name in sync with the Eclipse project name, I can use one of the Eclipse build variables:

${ProjName}

Project Name Variable

Now my .elf artifact will be always named after the project name :-).

After such a change, I should do a Project > Clean to make sure that it will do a full build. To make a ‘clean-clean’ I even recommend to delete the output folder (‘Debug’ in my case) and then do a build.

That way, my new binary has the new name too:

Renamed Build Output Files

What remains is the part about the debugger…

Debugger Launch Files

What I said above between the separation of the Eclipse Framework and the Eclipse CDT Build system is true as well for the Debug system in Eclipse: Changing the build output does not tell the debugger that the file name has changed :-(. So we need to do do some changes for the debugger too.

The debugger configurations are stored in other XML (text) files with .lauch extension. They are for the debug ‘lauch’ configurations.

Debugger Launch Configuration Files

The first obvious thing would be to rename the .launch files to match my new project name. I easily can do this again with the ‘rename’ context menu:

Renamed Launch Configuration Files

But this will only rename the file name, nothing else. The debugger in Eclipse CDT only scans for the .launch file name extension, and does not care about the file name itself. What it cares about what is inside the file.

Opening such a lauch file with a text editor will show something like this and there are several lines still referring to my old project name:

Summary

Renaming an Eclipse CDT project is not a ‘single step’ things: it requires some understanding how Eclipse works. Unfortunately the Eclipse Framework is not very well-connected to the Eclipse CDT and Debugger about the project name. So it requires not only to change the project name on the Framework level, but as well to update the CDT/Debugger settings.

I hope with this now things are easier to handle, and renaming projects is not that hard any more.

About Erich Styger

2 thoughts on “Renaming Eclipse CDT Projects”

Artifact name:
The “Artifact name” issue has been solved in CDT (https://bugs.eclipse.org/bugs/show_bug.cgi?id=230165) so if you’re using a new Eclipse version (> 2010) new projects will automatically use the ${ProjName} variable. This will still be a problem for legacy projects and as you suggest the project name literal should be replaced with ${ProjName}.

Debugger Launch Files:
SOMNIUM is currently working on a new feature to “sniff” out issues like this and offer to solve them automatically, along with other usability improvements. This will be available in a future release.

Thanks a lot for this. What I am used to doing after I screw up a project by renaming it is create a new one, copy the source files into the new ones and delete the old. This understanding of how eclipse works helps a lot. Especially the use of defined variables ${ProjName}