There are many ways to organize projects and workflows, and I would say Eclipse is flexible enough for everything. As I have been asked recently how I organize my projects, I’ll share it here.
Eclipse Workspace
Eclipse has the concept of a ‘workspace’: This is what you select at starting the IDE.
Basically a ‘workspace’ is a ‘collection of projects and settings’.
A workspace folder contains the .metadata folder:
This hidden folder is used to store the workspace settings including the list of projects.
Projects
An Eclipse project is a folder with a .project file in it:
That file for example specifies the name of the project. Depending on the project type there can be other setting files like .cproject which is for a C/C++ project.
Default Project Location
During project creation the default location is the current workspace folder, but you are free to use any folder location you want:
So how do I organize projects, especially in combination with a version control system like git?
Separating Workspace and Projects
What has worked best for me is to separate the ‘workspace’ folder from the project folders. The workspace folder is *specific* to an Eclipse version and never should be shared or ‘re-used’ between different Eclipse IDEs. So my workspace folder is IDE specific. I only place ‘scratch’ projects in the workspace folder (e.g. trying out an SDK example) which I delete afterwards (‘kill-me projects’).
The ‘real’ or ‘valuable’ projects I put under version control like git. A git repository is basically a collection of files and folders, cloned on my disk somewhere.
So all the valuable projects are outside the workspace folder, but they are still listed in the ‘Project Explorer’ view because I have ‘linked‘ them.
Linking Projects
Using Drag&Drop a project folder to the MCUXpresso IDE, I can choose to link it:
Using the File > Import > Existing projects I do not copy them:
Version Control Projects
The reason for this: I have many projects in my workspace, from many different git repositories. Putting the workspace folder under version control is problematic as I have to make sure the .metadata folder is *not* put under version control (.ignore it). Having projects organized in individual git repositories I have the freedom how I want to organize them, and what I want in my workspace.
Below is an an example of my projects and where they are in a git repository:
Summary
It is really up to you how you organize things, but I hope it gives you some ideas how things can be done. I prefer to use the Eclipse Workspace folder as a scratch area and store my git projects in separate folders.
Happy EclipseGiting š
MCU on Eclipse 
Super helpful! Now if only Microsoft Studio and its derivatives (e.g. Microchip Studio) were as git friendly as Eclipse! (I’m still trying to figure out if it’s possible to link an entire directory in MS.)
LikeLiked by 1 person
Basically the same way I’ve been doing it for years. Separating projects from the workspace (when the projects are version controlled) is the route to a happy life with eclipse.
LikeLiked by 1 person
Yes, I do the same for many years, and teach that to students too. It should be an obvious way to work with projects and git, and still I see many not following that best practice.
LikeLike
It’s worth mentioning that the way Eclipse gathers projects together into a workspace has consequences for the referencing of files and folders between projects. Projects should not assume that they are peers with other projects at the filesystem level. For example, a CDT managed build executable project which uses an object library provided by another project should set the include path and library search path using the workspace_loc dynamic build variable to ensure that the project is fully portable.
Portable: ${workspace_loc:/myLibraryProject/include}
Not portable: ../../myLibraryProject/include
LikeLiked by 1 person
Hi John,
good point!
If the project location is outside the workspace then using a workspace variable or workspace relative path does not work. Project relative path to other pieces of the project which *are* indeed relative to the project (e.g. common folder between projects) are a good thing. If there are dependencies between independent projects or libraries, then I recommend using Eclipse Build Variables: https://mcuoneclipse.com/2013/12/22/eclipse-build-variables/
LikeLiked by 1 person
To be clear, ${workspace_loc} with no argument resolves to the absolute workspace location (not usually very useful), but when specifying an Eclipse resource as an argument such as ${workspace_loc:/myLibraryProject/include} the dynamic build variable resolves to the absolute location of the specified resource which might be anywhere on the file system (not necessarily under the workspace folder). So we can reference files or folders in one project from another project without any knowledge of their relative or absolute locations on the underlying filesystem.
LikeLiked by 2 people
Hi John,
ah, I see now. So yes, this is useful in that case. But one need to be careful with these absolute (potentially long) paths, as you can easily run into the 8K path/command line limit which to my knowledge still exists on Windows. So it makes sense to use relative paths to everything inside the project itself.
LikeLiked by 1 person
Thanks for the tip, Erich!
Have you weighed the trade-offs between locating projects on a network server vs. on your c: drive? There can be a significant difference in access times when working from home over VPN. Obviously using your c: drive makes you responsible for backups and I wonder if you have any experience-based advice on trade-offs.
LikeLiked by 2 people
Hi Gary,
I *never* files on a low latency device (network server, etc). It is not only much slower but can lead strange problems, especially if placing the workspace itself into such locations. I have seen many cases where students did place their project or workspaces in to ‘shared’ locations with dramatic consequences.
The true answer is: use git! I mean git with a remote repository and a local clone. This is the big benefit of git: you can work locally with the maximum speed while having the ‘backup’ automatically synced with the one on the server. So using Git (with the distributed repo) is what I recommend and what I’m using: it solves all these problems and gives you backups, tracking, versioning, ….
LikeLiked by 1 person
Many times I have projects that must be built for different boards. If the MCU part is always the same, it’s not so difficult to change build process with preprocessor macro (BOARD_BASIC, BOARD_FULL, BOARD_BRAND1, BOARD_BRAND2).
The problems arise when the boards mount different MCUs. Just to simplify, suppose they are all NXP MCUs, but different. For what I know, you need a different MCUXpresso/Eclipse project for each MCU part.
In this situation, you have some common code (that is the biggest part) and some MCU-specific code.
How do you organize this scenario with Eclipse and Git? I don’t like to have different git repo for common part and for each MCU specific part. I think it’s smarter to have a single repo for all the builds.
Two possibilities come to my mind.
FIRST POSSIBILITY
myproject/
.git
.gitignore/
.metadata/
mcu_lpc546xx/
.cproject
.project
*.launch
src/
Debug/
Release/
mcu_lpc178x/
.cproject
.project
*.launch
src/
Debug/
Release/
src_common/
main.c
gui.c
gui.h
…
.gitignore content
.metadata/
# …maybe other folders generated by IDE, such as FreeRTOS_TAD_logs, …
mcu_lpc546xx/Debug/
mcu_lpc546xx/Release/
mcu_lpc178x/Debug/
mcu_lpc178x/Release/
myproject is the Eclipse workspace for this project.
mcu_lpc546xx and mcu_lpc178x porjects are added to the workspace in standard way (no link).
src_common/* files are added to every project as link files.
SECOND POSSIBILITY
myproject/
.git
.gitignore/
workspace/
.metadata/
mcu_lpc546xx/
.cproject
.project
*.launch
src/
Debug/
Release/
mcu_lpc178x/
.cproject
.project
*.launch
src/
Debug/
Release/
src_common/
main.c
gui.c
gui.h
…
.gitignore content
workspace/
mcu_lpc546xx/Debug/
mcu_lpc546xx/Release/
mcu_lpc178x/Debug/
mcu_lpc178x/Release/
myproject/workspace is the Eclipse workspace for this project.
mcu_lpc546xx and mcu_lpc178x projects are added to the workspace as link projects, because they are located at a different level.
Any other suggestions?
LikeLiked by 1 person
I’m sorry, many tabs and spaces in the folders tree were lost after posting.
LikeLiked by 1 person
I see that you have the .metadata (workspace information) in your git repository, along with derived files like Debug/Release? Or at least in your directory structure. Make sure your project(s) are *outside* the workspace folder, keep them separate.
As for using common parts with projects in git (actually, this does not really matter, it is about directory structure and configuration, not git per se at its heart): have a look at https://mcuoneclipse.com/2019/02/23/different-ways-of-software-configuration/.
Or see https://github.com/ErichStyger/mcuoneclipse/tree/master/Examples/MCUXpresso/tinyK22/tinyK22_RaspberryPi_UPS which uses a common McuLib in https://github.com/ErichStyger/mcuoneclipse/tree/master/Examples/MCUXpresso/McuLib which is shared across projects.
I hope this helps?
LikeLike
> I see that you have the .metadata (workspace information) in your git repository,
> along with derived files like Debug/Release? Or at least in your directory structure.
In my comment, I tried to write the working tree, not git repository (unfortunately, spaces and tabs are not friends in the comments).
In the first approach, projects folders (mcu_lpc178x/ and mcu_lpc178x/) are inside workspace folder; in the second approach, they are outside. In both cases, .metadata and Debug/Release folders are ignored in .gitignore.
FIRST APPROACH
myproject/
-> .git
-> .gitignore/
-> .metadata/ mcu_lpc546xx/
-> -> .cproject
-> -> .project
-> -> *.launch
-> -> src/
-> -> Debug/ -> Release/ mcu_lpc178x/
-> -> .cproject
-> -> .project
-> -> *.launch
-> -> src/
-> -> Debug/ -> Release/ src_common/
-> -> main.c
-> -> gui.c
-> -> gui.h
-> -> ā¦
SECOND APPROACH
myproject/
-> .git
-> .gitignore
-> workspace/ -> .metadata/
-> mcu_lpc546xx/
-> -> .cproject
-> -> .project
-> -> *.launch
-> -> src/
-> -> Debug/ -> Release/ mcu_lpc178x/
-> -> .cproject
-> -> .project
-> -> *.launch
-> -> src/
-> -> Debug/ -> Release/ src_common/
-> -> main.c
-> -> gui.c
-> -> gui.h
ā¦
> Make sure your project(s) are *outside* the workspace folder, keep them separate.
So you suggest the second approach.
Another trouble is to reuse common code for different MCUs of one series. I usually start making some code on EVB (maybe starting from SDK examples). The final board often will use a different part in the series. For example, I have LPC54628 EVB but the final board will have LPC54618.
In this case, I’m forced to have two different Eclipse projects (one that targets the EVB and the other that targets the custom board), because I can’t have two MCU parts in one project.
However the code base for both MCUs are identical.
LikeLiked by 1 person
Yes, I recommend separating workspace folder and projects. This makes dealing with version control repositories much easier. And code between projects can be shared with git subprojects/repos or with linked files and folders in Eclipse: https://mcuoneclipse.com/2014/08/15/link-to-files-and-folders-in-eclipse/
LikeLike
For sure this will be quite basic question but how do you manage to have both projects and workspaces in the project directory (Left side pane) ? As you have to select a workspace to launch the Eclipse, all other Workspace you might add from then would be included within the original one you selected inheritiing the .metadata file as well. Thanks!
LikeLike
Hi Martin,
not sure if I understand, but: you really don’t want to have the ‘workspace’ in a version control folder. You want the project there, but not the .metadata folder, as it is derived.
LikeLike
Ok I see. I was referencing the picture you put in the “‘Separating Workspace and Projects” section , i thought that project explorer view was showing both projects and workspaces. But is just showing project folders right?
So ideally you should have one workspace folder per IDE version and not per board right ?
LikeLiked by 1 person
Hi Martin,
yes, the Project Explorer view shows the Projects present in the workspace. But the workspace is much more: settings of colors, editor settings, etc, basically everything you have in the settings. The Projects shown in the Project Explorer view is a list of projects added, and the folders can be everywhere on your disk. By default they are in the ‘workspace’ folder (the one with the .metadata folder in it), but really you should think of the the .metadata folder like the .git folder in GIT: it keeps the internal data.
And yes, you absolutely want to have its own .metadata/workspace folder for each IDE. The projects can be in a git folder somewhere else: just link to them, e.g. Drag&Drop them folder into the Project Explorer and confirm ‘link’, see https://mcuoneclipse.com/2020/07/12/eclipse-gems-tips-tricks-importing-projects/
LikeLike
Thanks Erich. Would this separation work for older NXP boards? LPC1769 for instance, to run a project on this board you need to work with several project folders from the LPC OPEN 2_10 library, you dont just have 1 project folder to import. Thansk !!
LikeLiked by 1 person
Hi Martin,
I have not used LPC-Open, but it sounds like these projects are not correctly setup? But you always can use linked folders with the correct setting of CDT build variables, so there is no need to have things based on physical folder locations. I know that NXP did that mistake with the older SDK v1.x, were they assumed (hard-coded) relative paths to the project location, but luckily they changed that with the projects using the SK v2.x. So it seems to me that LPC-Open has the same flaw. But with some work it should be possible to organize the project better so it is better suited for Git?
LikeLike
Forgot to mention that when trying to create a project within the workspace but linking to another directory ( repo) the IDE forces me to copy into workspace the library folders
LikeLiked by 1 person
I don’t understand why you need to copy them into the workspace?
LikeLike
Since when I tried to do drag and drop an LPC1769 project i found this issue with the several project folder division i thought i could just try creating a brand new LPC1769 project from scratch in an all in one project folder from my git repo .
So i went ahead and opened the “create project wizard” for a LPC1769 board. The wizard makes you point to the LPC OPEN library and then it prevents you from unselecting the “copy files to workspace ” box (shaded in grey), you cannot create the project without copying all the library projects into the workspace
LikeLike