How to create "complex" project structures in esp-idf?


I am practically a newbie in the esp32 world and i am starting with esp-idf.

I am trying to learn make, cmake and esp-idf projects structure at least 2 weeks and i couldn’t make the “complex structure” project compile on esp-idf yet.

The hello_world and sdio/host example provided by espressif compile just fine, and i was even able to integrate esp-idf into visual studio code.
Until jtag, openocd, gdb i managed to make it work inside the visual studio code and in my hardware.
All “process” below are working fine:
“build app”
“clean app”
“flash app”

At the beginning off all these learning curve, i was mixing document version(esp-idf, tools, etc), because i download the stable version v3.2.2 and i was searching by googling, which led me to different espressif documentation pages in each new search(latest idf version for example).
So i was mixing with CMakeLists.txt.

After the penny has dropped(i understant), i uninstalled all the old files of version v3.2.2 and all other tools and started a new installation from scratch with the latest version: v4.1-dev-141-ga7e8d87d3.

I am only using now the latest documentation on espressif site link:, and trying to follow the project structure, but the documentation is complicated to me, because dont have examples.
I dont know what write inside the CMakeLists.txt(beyond the minimum) or in if i need yet this file.
The link site show “commands” but dont show command sintax with examples and where applicable, etc.
The hello_world example has a CMakeLists.txt in the main directory, but in the link above don’t exists this file in project structure.
I am very confused.

I download a component (littlevGL) and i am trying to adapter this component inside the espressif suggested structure.
The littlevGL component has a “little long” subdirectory structure that makes sense to me.

How to tell the compiler the path or files to add to the compiling ?
There is a simple command like: add all subdirectory from “x” path ?

I need files yet or only CMakeLists.txt or i need both files in the project(dir and/or subdir) ?
Where to put this files and what write on them ?

Attached follows my entire project without the build directory.
(i try to attach, but “new users” cannot attach files).

PS: i asked the same question on the espressif forum.



I think that my problem now is linking LittlevGL with esp-idf.

I am using esp-idf version: v4.1-dev-141-ga7e8d87d3 which uses CMakeLists.txt concept.

I dont know if i need all yet to link/compile the project(i know if i’m not going to use all the i need some other way to set the build flags, maybe using what espressif documentation indicate: “Each component may also include a Kconfig file defining the component configuration options that can be set via menuconfig”, that seems very interesting to me).

Can anybody help me with the compiling ?

I can attach my entire project here, if Gabor Kiss-Vamosi release my attachments in the forum :slight_smile:.



Have you seen this project?
The required files are provided, you just need to copy and rename them as it is shown the README.

Hi kisvegabor,

Yes, i download and follow file.

When i try to compiling show this message:
CMakeLists.txt not found in project directory c:\esp32projects\esp32_ili9341-mastertest

Espressif now use Cmake and no more GNU Make.
Your original project are based on GNU Make i think.

I am trying to migrated the project to CMake.

I change a lot of include in all files to stop include files problem(not so good but looks like it worked).

Now i think that only problem is linking because only such messages appear:
undefined reference to lv_tick_inc'. undefined reference toili9341_flush’
undefined reference to `disp_spi_init’

I would like to send my project for you to review and tell me what i need to do.
So i can also contribute to the LittlevGl project by migrating it from GNU MAKE to CMake.

PS: I’m new to these build tools including the GIT version controller, although i’m a computer engineer.

Thank’s in advance.

@Carlos_Diaz do you have experience with the new build system of ESP?

I tried CMake with other graphics library and it works good. Maybe it will help.

In the project directory with Makefile, there is a CMakeLists.txt as below:

cmake_minimum_required(VERSION 3.5)


In the main folder, with main.c there is another CMakeLists.txt:

idf_component_register(SRCS "main.c"
                       INCLUDE_DIRS ".")

In library folder, the CMakeLists.txt is like:

file(GLOB private_lib Src_A/*.c Src_B/*.c Src_C/*.c)

#needs IDF V4.x because we are using the clause <REQUIRES>
#if you are using IDF V3.x and idf_register() instead, we need to use "set(COMPONENT_REQUIRES fatfs sdmmc)" 
idf_component_register(	SRCS ${private_lib}
						INCLUDE_DIRS Src_A Src_B Src_C 
						REQUIRES fatfs sdmmc) #suppose we need fatfs and sdmmc for file system

The project folder structure as follows:


@techtoys Thank you for the hint! It looks helpful!

@Baldhead Can you make it work according to example of @techtoys?


Existing example from my iPod Nano blog compiles only with MSYS2 (ie Legacy GNU Make). I have attached two examples for CMake in this post. They compile in my environment without problem with ESP-IDF CMake. Not test it with hardware yet because it will involve jumper wires, EVK setup etc.

(1) More simple demo is the i2s_8080_lcd without littlevgl.
(2) The next demo “littlevgl_port” is the complete project with LCD + CTP+Littlevgl.

The first demo should compile with both Legacy GNU Make and CMake.
However, the second one will only compile with CMake now because somehow, I have to change each code in /main folder e.g. for cat.c,

#include "lvgl/lv_draw/lv_draw_img.h" > #include "lv_draw_img.h"

Should be something about new rules for CMake with REQUIRES and I have set REQUIRES lvgl for CMakeLists.txt in /littlevgl_port/main.

To compile, launch ESP-IDF Command Prompt from Windows Start menu to make sure Python path and ESP-IDF is added to path. Copy the project to C:/Littlevgl/projects or something.

Note: I tried D:/Littlevgl/projects but it didn’t work. Don’t know why.

Because user cannot upload file to this Forum, I need to use Dropbox:
Project at :

Hope it helps.


I manually increased your trust level, so hopefully you can upload next time.

Hello people,

In espressif forum link i created same question, and have a discussion about the same problem:

I will try to continue testing today, with all suggestion(here and espressif forum).

I attached the full project too, here and in espressif link above.
I try to attach the project here, but i can’t upload files in the forum yet(new user message).

Thank’s for the help.

Hi techtoys,

Really their programs build, but i still couldn’t make the program example “” build with only cmake.

I’m almost giving up.

Thank’s for the help.

Hello people,

I started doing the tests step by step.
I took the example “hello_world” and went removing files one by one and checking if it compiled, until the minimum necessary to compile only using CMake.

After this step, i added the components folder to “hello_world” project and follow the tips of this discussion and the espressif discussion.
After a lot of “trial and error” i made the project compile.

The next step is to change lib littlevgl (i want to make it as clean as possible) to compile using cmake only.
I will try to change all includes, in all files, and try to make the path as short as possible.

In annex follow the two projects with the minimum requirements to compile on cmake.

After i compile the project with the littlevgl component, if anyone wants to upload it to littevgl git, they feel free to.
I will post the code here, when i finish. (4.8 KB)
hello_world-Cmake project (1.9 KB)


Awesome! I’ve almost started to play with that but good to see that you’ve already made great progress. It’d be great the update project on GitHub.

Waiting for the updates. :slight_smile:

Hello people,

I am try to create a folder inside components folder ie:

Yes “projectFolder/components/ui” are working, only check on this project i posted above.

In folder “.global_conf” i put all *.h files that i consider LittleVgl config and other things like:

“.global_conf” folder

  • lv_conf.h
  • lv_conf_checker.h
  • lv_conf_template.h
  • lv_ex_conf.h
  • lv_ex_conf_templ.h
  • lv_examples.h
  • lv_test.h
  • lv_version.h
  • lvgl.h

My problem are how to register these folder(that only has *.h files) on Cmake espressif structuring.

I already trying to add this folder like a component folder(so i could use requires on the others components that needed the files in this folder) but not works.
I tried other things too, but no luck.

I’m following a part of the techtoys project structure.

Any suggestion ???

Below follows the project: (537.8 KB)


Hi kisvegabor,

I was able to make( CMake :slight_smile: ) the project compile.

In annex follow the project with the minimum Cmake requirements i think.

You need to check the project flags in files that no longer exist more.

I added a folder in project root named “.Project-Files” as a suggestion to put “.git” folder, assembly images, readme and so on.

I changed all include in all files, too.
Now the includes are all “simple” like #include “lvgl.h”

I have a doubt:
I need to register the .bin files ?
I need to register the .jpg and .png files ? I dont know if some of these files are invoked from some .c files.
idf_component_register( SRCS
) (2.4 MB)


Great news!

I was planning to make it possible to switch between lvgl/lvgl.h and lvgl.h. Good to know that it’s required for the ESP project too.

As they are not complied just read as files run time I suppose it’s not required to add them.

Could you send a Pull request?

Hi Kisvegabor,

I never worked with github. I think i requested a pull request on the git link:


There is no pull request open on that repository. It looks like it didn’t work.


I will try tomorrow.


I have a question about the example program

I flash the code on hardware, first without touch, ie, only display. Everything is OK. The page scrolls between write, list and chart.

After i added the touch screen. The page still scrolls, and the touch respond in a bad way.

What can it be ?
Any suggestions?
Do I need to configure anything ?
Is that because of the “” files i delete, because they had some configuration flags.