goal: "how to structure your project, while keeping the IDE happy and the build functionality simple"

When you're working with the Pico C SDK, you can add a library, like SPI, UART, … That will (seemingly) automatically add its include files to the path, and will compile its source files at build time. Very convenient, but how they do that? It's simple. If your project uses SPI, you usually add this to your CMake file:

target_link_libraries(<YOURPROJECT> pico_stdlib hardware_spi)

And this will take care that SPI libraries are linked into your firmware, but also that if you include #include "hardware/spi.h" in your source files, the build (and even a good IDE like VSCode) will actually find the header file.

This mechanism is used a lot in the C SDK and Pico examples. You can use it for your own projects too, to easily group functionality in subfolders, and to create your own utility libraries. In this post, I'm going to show how you can locate some functionality of your firmware in a subdirectory, and have the same functionality to simply add both sources and headers to your development setup. You will need a CMake file in the subdirectory, to make it self-registering. And two entries in the main CMake file of your project.

Example: M25XX Serial Flash submodule

My firmware will use a Micron M25P16 SPI flash IC. I want to put all m25 logic in a subdirectory, while trying to keep my build and IDE structure simple. This is a good starting point to start learning CMake modularity. I created a m25 subdirectory in my project. And created a header and c file in it, together with aCMakeList.txt file.

This example m25 lib will be very simple on purpose.

m25/m25.h

#ifndef _M25_H
#define _M25_H

int return25();

#endif // _MM25_H

The module m25/m25.c file:

#include "m25.h"

int return25() {
    return 25;
}

As you can see, this is the simplest possible C API - only intended as example.

The m25/CMakeList.txt file:

add_library( m25
    m25.h
    m25.c
    )

target_include_directories(m25 PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}")

This will take care that the main CMake file knows what's part of the directory.

Using the M25XX submodule

Let's now use this subdirectory in our project. First add it to the ./CMakeList.txt file:

cmake_minimum_required(VERSION 3.13)

# Pull in SDK (must be before project)
include(pico_sdk_import.cmake)

project(myproject C CXX ASM)
set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)

pico_sdk_init()

add_subdirectory(m25)

add_executable(myproject
        main.c
        )

target_link_libraries(myproject pico_stdlib m25)


pico_add_extra_outputs(myproject)

Now the main.c file:

#include "m25.h"

int main() {
    return return25();
}

Both the build system and the IDE will know what to do with the .h and .c file, and where they are. Your editor will be able to provide auto-complete, and show the API parameters and source. When you build it, the m25 sources will be included and linked. Your CMake main file does not have to know how your subdirectory is constructed and how many source files are in there. A value you'll get to appreciate when your project grows bigger.