Linking files means telling STM32CubeIDE where to find source code, headers, and libraries your project needs

When you create a new STM32CubeIDE project, the IDE starts with a basic folder structure. If you have existing code files — whether they're drivers you wrote before, third-party libraries, or code from another project — you need to tell STM32CubeIDE where those files live and how to use them. This is called linking. You can link files by copying them into your project folder, by creating references to files outside the project, or by adding library paths to your build settings.

The method you choose depends on whether you want the IDE to manage the files or whether you want to keep them in a separate location and just point to them. Most beginners copy files directly into the project; more experienced developers often link to external libraries to avoid duplication across multiple projects.

Key Takeaways

  • The simplest way to link files is to copy them into your project's source or include folders, then add them to your build configuration.
  • You can also link to files outside your project folder by adding their paths to the C/C++ Build settings under Include Paths and Source Locations.
  • Header files (.h) go in include paths; source files (.c) must be added to the build explicitly or placed in a folder the IDE scans automatically.
  • After linking files, rebuild your project to check for missing dependencies and compilation errors.
  • If the linker reports undefined references, the source file containing that function was not added to the build, or its path is incorrect.

Copy files directly into your project folder

The most straightforward approach is to place the files you need inside your STM32CubeIDE project directory. Open your project folder in Windows Explorer, macOS Finder, or your file manager. Create a new folder called Drivers, Libraries, or External — whatever name makes sense for what you're storing. Copy your .c and .h files into this folder.

Next, open STM32CubeIDE and right-click on your project name in the Project Explorer panel on the left. Select Refresh (or press F5). The IDE will scan your project folder and discover the new files. You should see them appear in the Project Explorer tree. If you don't see them, make sure you created the folder inside the project root, not somewhere else on your computer.

Now you need to tell the IDE to compile these files. Right-click on your project and select Properties. Navigate to C/C++ Build → Settings. Under the Tool Settings tab, find MCU GCC Compiler → Include Paths. Click the green plus icon and add the path to your new folder — for example, ${ProjDirPath}/Drivers. The ${ProjDirPath} variable means "the root of this project," so the path will work even if you move the project later.

Add source files to the build configuration

Copying files into your project folder and adding include paths tells the IDE where to find header files, but it does not automatically compile .c source files. You must explicitly add them to the build. Right-click on your project and select Properties again. Go to C/C++ Build → Settings → Tool Settings → MCU GCC Compiler → Source Locations.

Click the green plus icon and add the folder containing your .c files. For example, if you created a Drivers folder, add ${ProjDirPath}/Drivers. The IDE will now scan this folder for all .c files and include them in the build. If you want to add only specific files instead of an entire folder, you can do this through the build configuration, but adding a folder is faster for most projects.

After you add source locations, click Apply and Close. The IDE will re-index your project. You may see warnings or errors appear in the Problems panel — this is normal while the IDE processes the new files. Wait a few seconds for indexing to complete, then rebuild your project by pressing Ctrl+B (or Cmd+B on macOS).

Link to files outside your project folder

If you have a library or set of drivers stored elsewhere on your computer — perhaps in a shared folder or a separate repository — you can link to them without copying. This keeps your project folder smaller and lets you update the external files without duplicating them across multiple projects.

Right-click on your project and select Properties. Go to C/C++ Build → Settings → Tool Settings → MCU GCC Compiler → Include Paths. Click the green plus icon. Instead of using a relative path like ${ProjDirPath}/Drivers, enter the full path to the external folder. On Windows, this might be C:\Users\YourName\Libraries\STM32Drivers. On macOS or Linux, it might be /Users/YourName/Libraries/STM32Drivers.

For source files in the external location, add the same path to Source Locations. The IDE will compile files from that folder just as if they were inside your project. If you move the external folder later, you will need to update these paths manually. Using relative paths or environment variables can help avoid this problem, but absolute paths are simpler when you're starting out.

Handle missing header files and linker errors

After you link files, rebuild your project. If the compiler reports that it cannot find a header file — an error like "fatal error: myheader.h: No such file or directory" — the include path is wrong or incomplete. Check that the path you added in Include Paths actually contains the file. Use your file manager to navigate to the folder and verify the .h file is there.

If the linker reports an undefined reference — an error like "undefined reference to `myFunction`" — the source file containing that function was not added to the build. Check that the .c file is in a folder you added to Source Locations, or add it explicitly. Make sure the file name does not start with a dot (hidden files are ignored). If the file is there and the error persists, rebuild your project from scratch: select Project → Clean, then rebuild.

Another common issue is circular includes, where header files reference each other in a loop. If you see errors about redefinition or conflicting types, check your .h files for include guards. Every header file should start with #ifndef MYHEADER_H, #define MYHEADER_H, and end with #endif. This prevents the same header from being included twice in a single compilation.

Use STM32CubeIDE's built-in library manager for HAL and middleware

STM32CubeIDE includes a library manager for official STM32 HAL (Hardware Abstraction Layer) libraries and middleware like FreeRTOS or LWIP. If you need to add one of these, you do not have to link files manually. Open your project and select Project → STM32CubeMX (or double-click the .ioc file in your project). The STM32CubeMX configuration tool opens.

In STM32CubeMX, navigate to the Software Packs tab or the middleware section, depending on what you need. Select the library or middleware you want to add and click OK. STM32CubeMX will generate the necessary configuration files and add the library to your project automatically. Save and close STM32CubeMX, and the IDE will update your project. This method is cleaner than manual linking because the IDE handles all the paths and dependencies for you.

Verify your links with a test build

After you link files, always rebuild your project to catch errors early. Press Ctrl+B (or Cmd+B on macOS) to start a clean build. Watch the Console panel at the bottom of the IDE for compiler and linker output. If the build succeeds, you will see "Build Finished" with no errors. If there are errors, read them carefully — they usually tell you exactly which file is missing or which path is wrong.

A successful build means all your files are linked correctly and the IDE can find everything it needs. If you add more files later, repeat this process: add the path to Include Paths if it's a new folder with headers, add it to Source Locations if it contains .c files, and rebuild to verify. Over time, this becomes automatic, and you will recognize the most common errors at a glance.

Frequently Asked Questions

What is the difference between Include Paths and Source Locations?

Include Paths tell the compiler where to find header files (.h) when it sees an #include statement. Source Locations tell the compiler which folders contain .c files to compile. You need both for external code to work.

Can I link the same file to multiple projects?

Yes. Use external linking (absolute or relative paths) instead of copying. This way, if you update the file, all projects that link to it see the changes. Be careful not to edit the file in two projects at the same time, or you will lose work.

Why does my project still not compile after I add files?

The most common reasons are: the path is wrong (check it in your file manager), the file is hidden (starts with a dot), or you added a header path but forgot to add the source file to Source Locations. Rebuild after each change and read the error messages carefully.

Do I need to add every .h file individually?

No. Add the folder containing the headers to Include Paths once, and the compiler will find all .h files in that folder. You only need to add individual files if they are scattered across different folders.

What does the error "undefined reference" mean?

It means the linker found a call to a function but could not find the .c file that defines it. Make sure the .c file is in a folder you added to Source Locations, or add it explicitly to the build. Check that the function name matches exactly (C is case-sensitive).