View source for Using Visual Studio Code for ARM Development – Build Tasks

__NOTOC__

== CMake: Configure==
We are going to use [https://cmake.org/ CMake] with [https://www.gnu.org/software/make/ Make] to build the project.  [https://cmake.org/ CMake] needs some information where to find the tools. How does CMake know which compiler to use? It checks the '''CC''' and '''CXX''' environment variables. They define what is the default compiler in the system. If we manually set '''CC''' or '''CXX''' to different values, then CMake will use these new settings as default compilers. After successful detection, CMake stores info about the current toolchain in the following variables:<br />

 CMAKE_C_COMPILER,
 CMAKE_CXX_COMPILER.<br />

They contain paths to the C and C++ compilers respectively.

When we cross-compile to another platform, we have to specify completely different toolchain both in terms of name and location of the binaries. This can be done in two ways:

# pass values for the toolchain variables from the command line,
# specify toolchain file.


First option is very explicit thus easy to understand, but big number of arguments makes it harder to use CMake in terminal:

 cmake .. -DCMAKE_C_COMPILER=<path_to_c_compiler> -DCMAKE_CXX_COMPILER=<path_to_cxx_compiler> -DCMAKE_AR=<path_to_ar> -DCMAKE_LINKER=<path_to_linker> etc...


Second option is more elegant and is the preferred way of choosing the toolchain. All we need to do is to put toolchain variables into a separate file (e.g. ''<toolchain_name>.cmake'') and set '''CMAKE_TOOLCHAIN_FILE''' variable to the path of that file. This can be done both in the command line or in '''CMakeLists.txt''' before ''project()'' command:


A simple and easy way is to to add the following file to the project. I have named it '''''arm-toolchain.cmake''''' and placed it in the project root folder.

=== CMake: Toolchain File ===

<syntaxhighlight lang="cmake" line start="1">
# File: arm-toolchain.cmake
# Toolchain file for arm-none-eabi-gcc

set(CMAKE_SYSTEM_NAME Generic)
set(CMAKE_SYSTEM_PROCESSOR ARM)
set(CMAKE_CROSSCOMPILING "TRUE")

# Set system depended extensions
if(WIN32)
  set(ARM_TOOLCHAIN_EXT ".exe" )
else()
  set(ARM_TOOLCHAIN_EXT "" )
endif()

if(WIN32)
    set(ARM_TOOLCHAIN_DIR "C:/ProgramData/chocolatey/bin")
else()
    set(ARM_TOOLCHAIN_DIR "/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin")
endif()

set(BINUTILS_PATH ${ARM_TOOLCHAIN_DIR}) 

set(TOOLCHAIN_PREFIX ${ARM_TOOLCHAIN_DIR}/arm-none-eabi-)

set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)

set(CMAKE_C_COMPILER "${TOOLCHAIN_PREFIX}gcc${ARM_TOOLCHAIN_EXT}")
set(CMAKE_ASM_COMPILER ${CMAKE_C_COMPILER})
set(CMAKE_CXX_COMPILER "${TOOLCHAIN_PREFIX}g++${ARM_TOOLCHAIN_EXT}")

set(CMAKE_OBJCOPY ${TOOLCHAIN_PREFIX}objcopy CACHE INTERNAL "objcopy tool")
set(CMAKE_SIZE_UTIL ${TOOLCHAIN_PREFIX}size CACHE INTERNAL "size tool")

set(CMAKE_FIND_ROOT_PATH ${BINUTILS_PATH})
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
</syntaxhighlight>


'''ARM_TOOLCHAIN_DIR''' specifies the compiler to be used. Additionally it defines extra tools as size and objcopy.

=== CMake: CMakeLists.txt ===
To tell CMake what to do, create a file named '''CMakeList.txt''' in the project root.

<syntaxhighlight lang="cmake" line start="1">
# File: CMakeList.txt
# CMake file for tm4c123gxl

cmake_minimum_required(VERSION 3.15.3)

# Optional: print out extra messages to see what is going on. Comment it to have less verbose messages
set(CMAKE_VERBOSE_MAKEFILE ON)

# Path to toolchain file. This one has to be before 'project()' below
set(CMAKE_TOOLCHAIN_FILE ${CMAKE_SOURCE_DIR}/arm-toolchain.cmake)

# Setup project, output and linker file
project(blinky VERSION 0.1)
set(EXECUTABLE ${PROJECT_NAME}.elf)
set(LINKER_FILE ${CMAKE_SOURCE_DIR}/ld/tm4c123gh6pm.ld)

enable_language(C ASM)
set(CMAKE_C_STANDARD 99)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_C_EXTENSIONS OFF)

# Optional: issue a message to be sure it uses the correct toolchain file.
message(STATUS "CMAKE_TOOLCHAIN_FILE is: ${CMAKE_TOOLCHAIN_FILE}")

# List of source files
set(SRC_FILES
        src/main.c
        src/tm4c_startup.c
        inc/tm4c_startup.h
    )

# Build the executable based on the source files
add_executable(${EXECUTABLE} ${SRC_FILES})

# List of compiler defines, prefix with -D compiler option
target_compile_definitions(${EXECUTABLE} PRIVATE -DPART_TM4C123GH6PM)

# List of include directories
target_include_directories(${EXECUTABLE} PRIVATE
        src 
        inc
if(WIN32)        
        "E:/ti/TivaWare_C_Series-2.2.0.295"
else()
        "/home/jshankar/ti/TivaWare_C_Series-2.2.0.295"
endif()
        )

# Compiler options
target_compile_options(${EXECUTABLE} PRIVATE
        -mcpu=cortex-m4
        -mthumb
        -mfpu=fpv4-sp-d16
        -mfloat-abi=hard

        -fdata-sections
        -ffunction-sections

        -Wall
        -O0
        -g3
        )

# Linker options
target_link_options(${EXECUTABLE} PRIVATE
        -T${LINKER_FILE}
        -mcpu=cortex-m4
        -mthumb
        -mfpu=fpv4-sp-d16
        -mfloat-abi=hard
        -specs=nano.specs
        -specs=nosys.specs
        -lc
        -lm
        -Wl,-Map=${PROJECT_NAME}.map,--cref
        -Wl,--gc-sections
        -Xlinker -print-memory-usage -Xlinker
        )

# Optional: Print executable size as part of the post build process
add_custom_command(TARGET ${EXECUTABLE}
        POST_BUILD
        COMMAND ${CMAKE_SIZE_UTIL} ${EXECUTABLE})

# Optional: Create hex, bin and S-Record files after the build
add_custom_command(TARGET ${EXECUTABLE}
        POST_BUILD
        COMMAND ${CMAKE_OBJCOPY} -O srec --srec-len=64 ${EXECUTABLE} ${PROJECT_NAME}.s19
        COMMAND ${CMAKE_OBJCOPY} -O ihex ${EXECUTABLE} ${PROJECT_NAME}.hex
        COMMAND ${CMAKE_OBJCOPY} -O binary ${EXECUTABLE} ${PROJECT_NAME}.bin)
</syntaxhighlight>


The most important sections/entries are:

* '''project'''(<your project name here>): Give your project a name
* set'''(LINKER_FILE''' <your linker file here>): specify the linker file name
* set'''(SRC_FILES''' <your source files here>): list of source files to compile
* '''target_compile_definitions'''(${EXECUTABLE} PRIVATE  <compiler defines here>): list of compiler #defines
* '''target_include_directories'''(${EXECUTABLE} PRIVATE <list of include dir>): list of include directories
* '''target_compile_options'''(${EXECUTABLE} PRIVATE <compiler options>): list of compiler options
* '''target_link_options'''(${EXECUTABLE} PRIVATE <linker options>): list of linker options


This completes setting up the configuration for the build.

=== Configure ===
Next we are going to build it. Actually we need to ‘'''configure’''' it first. With CMake it is a two stage process: running CMake to create (or configure) the make files and then we use ‘'''make'''’ to build it.

* Close VSCode and Restart again
* Open Command Palette ... (CTL+SHIFT+P)
* Select '''CMake:Delete cache and Reconfigure'''

[[image:vscode_cmake_delete-cache-reconfigure.png|center|700px]]

=== CMake: Config Output ===
<pre>
[variant] Loaded new set of variants
[kit] Successfully loaded 3 kits from /home/jshankar/.local/share/CMakeTools/cmake-tools-kits.json
[proc] Executing command: /opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc -v
[cmakefileapi-driver] This version of CMake does not support the "toolchains" object kind. Compiler paths will be determined by reading CMakeCache.txt.
[main] Configuring folder: blinky 
[proc] Executing command: /usr/bin/cmake --no-warn-unused-cli -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE -DCMAKE_BUILD_TYPE:STRING=Debug -DCMAKE_C_COMPILER:FILEPATH=/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc -DCMAKE_CXX_COMPILER:FILEPATH=/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-g++ -S/home/jshankar/codeprojects/tm4c123gxl/blinky -B/home/jshankar/codeprojects/tm4c123gxl/blinky/build -G "Unix Makefiles"
[cmake] Not searching for unused variables given on the command line.
[cmake] -- CMAKE_TOOLCHAIN_FILE is: /home/jshankar/codeprojects/tm4c123gxl/blinky/arm-toolchain.cmake
[cmake] -- Configuring done
[cmake] -- Generating done
[cmake] -- Build files have been written to: /home/jshankar/codeprojects/tm4c123gxl/blinky/build
</pre>

=== Build it with make ===
Open a terminal in the build output folder:<br />
<big>View-->Terminal</big><br />
 cd build 
 make


Instead of calling ‘make’ inside the build folder, following can be used which does the one or the other:<br >

 cmake --build .

* The advantage of doing it this way is that if there has been a change in the CMakeList.txt it will run a configuration step first too. 
* If doing changes in the structure: make sure you do a configure to make sure things are correctly set up.

==== Cleaning ====
A ‘clean’ is to delete all the files inside the build folder. But CMake has a ‘clean’ command too:
 
 cd build
 cmake --build . --target clean
 make


To do a ‘clean followed by a build’ use the following:
 
 
cd build
 cmake --build . --clean-first

=== Make: Build Output ===
<pre>
/usr/bin/cmake -S/home/jshankar/codeprojects/tm4c123gxl/blinky -B/home/jshankar/codeprojects/tm4c123gxl/blinky/build --check-build-system CMakeFiles/Makefile.cmake 0
/usr/bin/cmake -E cmake_progress_start /home/jshankar/codeprojects/tm4c123gxl/blinky/build/CMakeFiles /home/jshankar/codeprojects/tm4c123gxl/blinky/build/CMakeFiles/progress.marks
make -f CMakeFiles/Makefile2 all
make[1]: Entering directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
make -f CMakeFiles/blinky.elf.dir/build.make CMakeFiles/blinky.elf.dir/depend
make[2]: Entering directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
cd /home/jshankar/codeprojects/tm4c123gxl/blinky/build && /usr/bin/cmake -E cmake_depends "Unix Makefiles" /home/jshankar/codeprojects/tm4c123gxl/blinky /home/jshankar/codeprojects/tm4c123gxl/blinky /home/jshankar/codeprojects/tm4c123gxl/blinky/build /home/jshankar/codeprojects/tm4c123gxl/blinky/build /home/jshankar/codeprojects/tm4c123gxl/blinky/build/CMakeFiles/blinky.elf.dir/DependInfo.cmake --color=
make[2]: Leaving directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
make -f CMakeFiles/blinky.elf.dir/build.make CMakeFiles/blinky.elf.dir/build
make[2]: Entering directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
[ 33%] Building C object CMakeFiles/blinky.elf.dir/src/main.c.obj
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc -DPART_TM4C123GH6PM -I/home/jshankar/codeprojects/tm4c123gxl/blinky/src -I/home/jshankar/codeprojects/tm4c123gxl/blinky/inc -I/home/jshankar/codeprojects/tm4c123gxl/blinky/if -I"/home/jshankar/codeprojects/tm4c123gxl/blinky/(" -I/home/jshankar/codeprojects/tm4c123gxl/blinky/WIN32 -I"/home/jshankar/codeprojects/tm4c123gxl/blinky/)" -I/home/jshankar/codeprojects/tm4c123gxl/blinky/E:/ti/TivaWare_C_Series-2.2.0.295 -I/home/jshankar/codeprojects/tm4c123gxl/blinky/else -I/home/jshankar/ti/TivaWare_C_Series-2.1.4.178 -I/home/jshankar/codeprojects/tm4c123gxl/blinky/endif  -g   -mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard -fdata-sections -ffunction-sections -Wall -O0 -g3 -std=c99 -o CMakeFiles/blinky.elf.dir/src/main.c.obj   -c /home/jshankar/codeprojects/tm4c123gxl/blinky/src/main.c
[ 66%] Building C object CMakeFiles/blinky.elf.dir/src/tm4c_startup.c.obj
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc -DPART_TM4C123GH6PM -I/home/jshankar/codeprojects/tm4c123gxl/blinky/src -I/home/jshankar/codeprojects/tm4c123gxl/blinky/inc -I/home/jshankar/codeprojects/tm4c123gxl/blinky/if -I"/home/jshankar/codeprojects/tm4c123gxl/blinky/(" -I/home/jshankar/codeprojects/tm4c123gxl/blinky/WIN32 -I"/home/jshankar/codeprojects/tm4c123gxl/blinky/)" -I/home/jshankar/codeprojects/tm4c123gxl/blinky/E:/ti/TivaWare_C_Series-2.2.0.295 -I/home/jshankar/codeprojects/tm4c123gxl/blinky/else -I/home/jshankar/ti/TivaWare_C_Series-2.1.4.178 -I/home/jshankar/codeprojects/tm4c123gxl/blinky/endif  -g   -mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard -fdata-sections -ffunction-sections -Wall -O0 -g3 -std=c99 -o CMakeFiles/blinky.elf.dir/src/tm4c_startup.c.obj   -c /home/jshankar/codeprojects/tm4c123gxl/blinky/src/tm4c_startup.c
[100%] Linking C executable blinky.elf
/usr/bin/cmake -E cmake_link_script CMakeFiles/blinky.elf.dir/link.txt --verbose=1
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gcc -g  -T/home/jshankar/codeprojects/tm4c123gxl/blinky/ld/tm4c123gh6pm.ld -mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard -specs=nano.specs -specs=nosys.specs -lc -lm -Wl,-Map=blinky.map,--cref -Wl,--gc-sections -Xlinker -print-memory-usage CMakeFiles/blinky.elf.dir/src/main.c.obj CMakeFiles/blinky.elf.dir/src/tm4c_startup.c.obj  -o blinky.elf 
Memory region         Used Size  Region Size  %age Used
           FLASH:         980 B       256 KB      0.37%
            SRAM:         540 B        32 KB      1.65%
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-size blinky.elf
   text    data     bss     dec     hex filename
    980       0     540    1520     5f0 blinky.elf
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-objcopy -O srec --srec-len=64 blinky.elf blinky.s19
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-objcopy -O ihex blinky.elf blinky.hex
/opt/toolchains/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-objcopy -O binary blinky.elf blinky.bin
make[2]: Leaving directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
[100%] Built target blinky.elf
make[1]: Leaving directory '/home/jshankar/codeprojects/tm4c123gxl/blinky/build'
/usr/bin/cmake -E cmake_progress_start /home/jshankar/codeprojects/tm4c123gxl/blinky/build/CMakeFiles 0
</pre>


==== Sample Project ====
<big>You can download sample project from</big> [{{SERVER}}/emsys/vscode/vscode-tm4c-blinky.zip <big>here</big>]


=== References ===
* [https://code.visualstudio.com/docs/cpp/cmake-linux Get started with CMake Tools on Linux]
* [https://github.com/microsoft/vscode-cmake-tools/blob/main/docs/README.md CMake Tools for Visual Studio Code]