Linker error - undefined reference

PlatformIO IDE
,
1

In my project I neeed to embed certain files. I have the following entry in
platformio.ini file.

[env:az-delivery-devkit-v4]
platform = espressif32
board = az-delivery-devkit-v4
framework = espidf
board_build.embed_files = 
    src/main/webpage/app.css
    src/main/webpage/app.js
    src/main/webpage/favicon.ico
    src/main/webpage/index.html
    src/main/webpage/jquery-3.3.1.min.js

I also notice that in the build directory, the following assembly files are getting created.

   PS D:\Raju\Projects\Esp32\Test_projects\WiFi_Test_PIO\.pio\build\az-delivery-devkit-v4> dir *.S

    Directory: D:\Raju\Projects\Esp32\Test_projects\WiFi_Test_PIO\.pio\build\az-delivery-devkit-v4


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----         7/22/2025   9:10 PM          14604 app.css.S
-a----         7/22/2025   9:10 PM          51105 app.js.S
-a----         7/22/2025   9:10 PM        1118246 favicon.ico.S
-a----         7/22/2025   9:10 PM

But I am getting the undefined errors for the symbols available in these *.S files.

Creating esp32 image...
Merged 2 ELF sections
Successfully created esp32 image.
Linking .pio\build\az-delivery-devkit-v4\firmware.elf
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_favicon_ico_handler+0x8): undefined reference to `_binary_favicon_ico_end'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_favicon_ico_handler+0xc): undefined reference to `_binary_favicon_ico_start'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_app_js_handler+0x8): undefined reference to `_binary_app_js_end'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_app_js_handler+0xc): undefined reference to `_binary_app_js_start'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_app_css_handler+0x8): undefined reference to `_binary_app_css_end'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_app_css_handler+0xc): undefined reference to `_binary_app_css_start'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_index_html_handler+0x8): undefined reference to `_binary_index_html_end'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_index_html_handler+0xc): undefined reference to `_binary_index_html_start'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_jquery_handler+0x4): undefined reference to `_binary_jquery_3_3_1_min_js_end'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_jquery_handler+0x8): undefined reference to `_binary_jquery_3_3_1_min_js_start'
collect2.exe: error: ld returned 1 exit status
*** [.pio\build\az-delivery-devkit-v4\firmware.elf] Error 1
============================================================== [FAILED] Took 37.90 seconds ==============================================================

 *  The terminal process "C:\Users\rajus\.platformio\penv\Scripts\platformio.exe 'run', '--environment', 'az-delivery-devkit-v4'" terminated with exit code: 1. 
 *  Terminal will be reused by tasks, press any key to close it. 

 *  Executing task in folder WiFi_Test_PIO: C:\Users\rajus\.platformio\penv\Scripts\platformio.exe run --environment az-delivery-devkit-v4 

Processing az-delivery-devkit-v4 (platform: espressif32; board: az-delivery-devkit-v4; framework: espidf)
---------------------------------------------------------------------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: https://docs.platformio.org/page/boards/espressif32/az-delivery-devkit-v4.html
PLATFORM: Espressif 32 (6.11.0) > AZ-Delivery ESP-32 Dev Kit C V4
HARDWARE: ESP32 240MHz, 520KB RAM, 4MB Flash
DEBUG: Current (cmsis-dap) External (cmsis-dap, esp-bridge, esp-prog, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa)
PACKAGES:
 - framework-espidf @ 3.50401.0 (5.4.1)
 - tool-cmake @ 3.16.4
 - tool-esp-rom-elfs @ 0.0.1+20241011
 - tool-esptoolpy @ 1.40501.0 (4.5.1)
 - tool-idf @ 1.0.1
 - tool-mconf @ 1.4060000.20190628 (406.0.0)
 - tool-ninja @ 1.9.0
 - tool-riscv32-esp-elf-gdb @ 11.2.0+20220823
 - tool-xtensa-esp-elf-gdb @ 11.2.0+20230208
 - toolchain-esp32ulp @ 1.23800.240113 (2.38.0)
 - toolchain-xtensa-esp-elf @ 14.2.0+20241119
Reading CMake configuration...
Warning! Flash memory size mismatch detected. Expected 4MB, found 2MB!
Please select a proper value in your `sdkconfig.defaults` or via the `menuconfig` target!
LDF: Library Dependency Finder -> https://bit.ly/configure-pio-ldf
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 0 compatible libraries
Scanning dependencies...
No dependencies
Building in release mode
Linking .pio\build\az-delivery-devkit-v4\firmware.elf
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_favicon_ico_handler+0x8): undefined reference to `_binary_favicon_ico_end'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_favicon_ico_handler+0xc): undefined reference to `_binary_favicon_ico_start'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_app_js_handler+0x8): undefined reference to `_binary_app_js_end'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_app_js_handler+0xc): undefined reference to `_binary_app_js_start'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_app_css_handler+0x8): undefined reference to `_binary_app_css_end'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_app_css_handler+0xc): undefined reference to `_binary_app_css_start'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_index_html_handler+0x8): undefined reference to `_binary_index_html_end'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_index_html_handler+0xc): undefined reference to `_binary_index_html_start'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_jquery_handler+0x4): undefined reference to `_binary_jquery_3_3_1_min_js_end'
C:/Users/rajus/.platformio/packages/toolchain-xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/14.2.0/../../../../xtensa-esp-elf/bin/ld.exe: .pio/build/az-delivery-devkit-v4/src/main/http_server.c.o:(.literal.http_server_jquery_handler+0x8): undefined reference to `_binary_jquery_3_3_1_min_js_start'
collect2.exe: error: ld returned 1 exit status
*** [.pio\build\az-delivery-devkit-v4\firmware.elf] Error 1

Do I need to add any other settings or options, to resolve this issue ?

2

Please see embedding-binary-data

Steps to do:

  • add the files to platformio.ini (:ballot_box_with_check:)
  • add the files to your src/CMakeList.txt
  • create the necessary symbols in your source code

Also make sure the file locations and symbol naming is correct.
A file located in src/main/webpage/app.css should end up in something like this:

extern const uint8_t src_main_webpage_app_css_start[] asm("_binary_src_main_webpage_app_css_start");
extern const uint8_t src_main_webpage_app_css_end[] asm("_binary_src_main_webpage_app_css_end");
3

Thanks :slight_smile:
After adding the files into src/CMakeLists.txt, the linker error is resolved.

Blockquote
idf_component_register(SRCS ${app_sources}
EMBED_FILES main/webpage/app.css main/webpage/app.js main/webpage/favicon.ico main/webpage/index.html main/webpage/jquery-3.3.1.min.js)

1 Like