Organizing Projects with Eclipse and Git

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 and Project Location with Git

Eclipse Workspace

Eclipse has the concept of a ‘workspace’: This is what you select at starting the IDE.

Workspace Selection

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:

Default project location

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:

Linking Project with Drag&Drop

Using the File > Import > Existing projects I do not copy them:

Link Imported Projects

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 🙂

Links

23 thoughts on “Organizing Projects with Eclipse and Git

  1. 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.)

    Liked by 1 person

  2. 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.

    Liked 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.

      Like

  3. 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

    Liked 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/

      Liked 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.

        Liked 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.

          Liked by 1 person

  4. 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.

    Liked 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, ….

      Liked by 1 person

  5. 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?

    Liked 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?

      Like

      • > 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.

        Liked by 1 person

  6. 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!

    Like

    • 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.

      Like

      • 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 ?

        Liked 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/

          Like

        • 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 !!

          Liked 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?

          Like

  7. 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

    Liked by 1 person

      • 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

        Like

What do you think?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.