doc: Documentation issue in 'develop/application/index'

[ConnorRigby]

Describe the bug

Basic example-application Usage

The easiest way to get started with the example-application repository within an existing Zephyr workspace is to follow these steps:

cd <home>/zephyrproject
git clone https://github.com/zephyrproject-rtos/example-application my-app

The directory name my-app above is arbitrary: change it as needed. You can now go into this directory and adapt its contents to suit your needs. Since you are using an existing Zephyr workspace, you can use west build or any other west commands to build, flash, and debug.

I am trying to build the example application without any changes according to this guide above. I get this error message:

[omitted]
/home/connorrigby/zephyrproject/my-app/app/prj.conf:7: warning: attempt to assign the value 'y' to the undefined symbol BLINK

I downgraded the repo to the latest tag as a wild guess. it gets me a little further but still fails:

(.venv) ➜  my-app git:(v3.6.0) west build -p always -b nucleo_f302r8 app
-- west build: making build dir /home/connorrigby/zephyrproject/my-app/build pristine
-- west build: generating a build system
Loading Zephyr default modules (Zephyr base).
-- Application: /home/connorrigby/zephyrproject/my-app/app
-- CMake version: 3.25.1
-- Found Python3: /home/connorrigby/zephyrproject/.venv/bin/python3 (found suitable version "3.10.12", minimum required is "3.8") found components: Interpreter 
-- Cache files will be written to: /home/connorrigby/.cache/zephyr
-- Zephyr version: 3.6.99 (/home/connorrigby/zephyrproject/zephyr)
-- Found west (found suitable version "1.2.0", minimum required is "0.14.0")
-- Board: nucleo_f302r8, qualifiers: stm32f302x8
-- ZEPHYR_TOOLCHAIN_VARIANT not set, trying to locate Zephyr SDK
-- Found host-tools: zephyr 0.16.5 (/home/connorrigby/zephyr-sdk-0.16.5-1)
-- Found toolchain: zephyr 0.16.5 (/home/connorrigby/zephyr-sdk-0.16.5-1)
-- Found Dtc: /home/connorrigby/zephyr-sdk-0.16.5-1/sysroots/x86_64-pokysdk-linux/usr/bin/dtc (found suitable version "1.6.0", minimum required is "1.4.6") 
-- Found BOARD.dts: /home/connorrigby/zephyrproject/zephyr/boards/st/nucleo_f302r8/nucleo_f302r8.dts
-- Found devicetree overlay: /home/connorrigby/zephyrproject/my-app/app/boards/nucleo_f302r8.overlay
-- Generated zephyr.dts: /home/connorrigby/zephyrproject/my-app/build/zephyr/zephyr.dts
-- Generated devicetree_generated.h: /home/connorrigby/zephyrproject/my-app/build/zephyr/include/generated/devicetree_generated.h
-- Including generated dts.cmake file: /home/connorrigby/zephyrproject/my-app/build/zephyr/dts.cmake
Parsing /home/connorrigby/zephyrproject/my-app/app/Kconfig
Loaded configuration '/home/connorrigby/zephyrproject/zephyr/boards/st/nucleo_f302r8/nucleo_f302r8_defconfig'
Merged configuration '/home/connorrigby/zephyrproject/my-app/app/prj.conf'
Configuration saved to '/home/connorrigby/zephyrproject/my-app/build/zephyr/.config'
Kconfig header saved to '/home/connorrigby/zephyrproject/my-app/build/zephyr/include/generated/autoconf.h'
-- Found GnuLd: /home/connorrigby/zephyr-sdk-0.16.5-1/arm-zephyr-eabi/bin/../lib/gcc/arm-zephyr-eabi/12.2.0/../../../../arm-zephyr-eabi/bin/ld.bfd (found version "2.38") 
-- The C compiler identification is GNU 12.2.0
-- The CXX compiler identification is GNU 12.2.0
-- The ASM compiler identification is GNU
-- Found assembler: /home/connorrigby/zephyr-sdk-0.16.5-1/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
-- Using ccache: /usr/bin/ccache
-- Configuring done
-- Generating done
-- Build files have been written to: /home/connorrigby/zephyrproject/my-app/build
-- west build: building application
[1/127] Preparing syscall dependency handling

[3/127] Generating include/generated/version.h
-- Zephyr version: 3.6.99 (/home/connorrigby/zephyrproject/zephyr), build: v3.6.0-2294-g9f0cd47c784e
[122/127] Linking C executable zephyr/zephyr_pre0.elf
FAILED: zephyr/zephyr_pre0.elf zephyr/zephyr_pre0.map /home/connorrigby/zephyrproject/my-app/build/zephyr/zephyr_pre0.map 
: && ccache /home/connorrigby/zephyr-sdk-0.16.5-1/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc  -gdwarf-4 zephyr/CMakeFiles/zephyr_pre0.dir/misc/empty_file.c.obj -o zephyr/zephyr_pre0.elf  zephyr/CMakeFiles/offsets.dir/./arch/arm/core/offsets/offsets.c.obj  -fuse-ld=bfd  -T  zephyr/linker_zephyr_pre0.cmd  -Wl,-Map=/home/connorrigby/zephyrproject/my-app/build/zephyr/zephyr_pre0.map  -Wl,--whole-archive  app/libapp.a  zephyr/libzephyr.a  zephyr/arch/common/libarch__common.a  zephyr/arch/arch/arm/core/libarch__arm__core.a  zephyr/arch/arch/arm/core/cortex_m/libarch__arm__core__cortex_m.a  zephyr/lib/libc/picolibc/liblib__libc__picolibc.a  zephyr/lib/libc/common/liblib__libc__common.a  zephyr/drivers/interrupt_controller/libdrivers__interrupt_controller.a  zephyr/drivers/clock_control/libdrivers__clock_control.a  zephyr/drivers/console/libdrivers__console.a  zephyr/drivers/gpio/libdrivers__gpio.a  zephyr/drivers/pinctrl/libdrivers__pinctrl.a  zephyr/drivers/reset/libdrivers__reset.a  zephyr/drivers/serial/libdrivers__serial.a  zephyr/drivers/timer/libdrivers__timer.a  modules/stm32/stm32cube/lib..__modules__hal__stm32__stm32cube.a  -Wl,--no-whole-archive  zephyr/kernel/libkernel.a  -L"/home/connorrigby/zephyr-sdk-0.16.5-1/arm-zephyr-eabi/bin/../lib/gcc/arm-zephyr-eabi/12.2.0/thumb/v7e-m/nofp"  -L/home/connorrigby/zephyrproject/my-app/build/zephyr  -lgcc  zephyr/arch/common/libisr_tables.a  -mcpu=cortex-m4  -mthumb  -mabi=aapcs  -mfp16-format=ieee  -mtp=soft  -Wl,--gc-sections  -Wl,--build-id=none  -Wl,--sort-common=descending  -Wl,--sort-section=alignment  -Wl,-u,_OffsetAbsSyms  -Wl,-u,_ConfigAbsSyms  -nostdlib  -static  -Wl,-X  -Wl,-N  -Wl,--orphan-handling=warn  -Wl,-no-pie  -DPICOLIBC_LONG_LONG_PRINTF_SCANF  --specs=picolibc.specs  -lc  -lgcc && cd /home/connorrigby/zephyrproject/my-app/build/zephyr && /usr/bin/cmake -E true
/home/connorrigby/zephyr-sdk-0.16.5-1/arm-zephyr-eabi/bin/../lib/gcc/arm-zephyr-eabi/12.2.0/../../../../arm-zephyr-eabi/bin/ld.bfd: app/libapp.a(main.c.obj): in function `main':
/home/connorrigby/zephyrproject/my-app/app/src/main.c:47: undefined reference to `__device_dts_ord_14'
collect2: error: ld returned 1 exit status
ninja: build stopped: subcommand failed.
FATAL ERROR: command exited with status 1: /usr/bin/cmake --build /home/connorrigby/zephyrproject/my-app/build

Environment

• Page: develop/application/index
• Version: main
• SHA-1: bd68ec9

[github-actions[bot]]

Hi @ConnorRigby! We appreciate you submitting your first issue for our open-source project. 🌟

Even though I'm a bot, I can assure you that the whole community is genuinely grateful for your time and effort. 🤖💙

[nordicjm]

Additional context for above: git clone is wrong, should be updated to use west init instead, the example repo is a west module itself so a git clone into an existing repo will not work

[aescolar]

@ConnorRigby I pressume @nordicjm helped you, so I will close this issue/discussion. If you still have doubts please comment.

[mrcoolycool]

Could you improve documentation instead of just closing this issue. I faced the same "attempt to assign the value 'y' to the undefined symbol BLINK" issue as original reporter by following the same guide.

The example-application repository suggests to use "west init" approach but I don't get that working either. If running it inside zephyrproject workspace i get error that I'm already inside workspace:

FATAL ERROR: already initialized in /home/anssi/zephyrproject, aborting.
  Hint: if you do not want a workspace there, 
  remove this directory and re-run this command:

  /home/anssi/zephyrproject/.west

[mrcoolycool]

apparently i was not supposed to run the "west init" instructed by "Zephyr's getting started guide". Instead at that stage use the "west init -m https://github.com/zephyrproject-rtos/example-application --mr main my-workspace" instructed by example-application repository Readme. And in that command replace the "my-workspace" with "zephyrproject" created by following Zephyr's guide. This could be written out to instructions more clearly as now it's really confusing.

There's also dependency to "pyelftools" and installing that could be added to instructions or to requirements.txt.