diff --git a/docs/development-instructions.rst b/docs/development-instructions.rst index de3ee20a..3f4d7ce8 100644 --- a/docs/development-instructions.rst +++ b/docs/development-instructions.rst @@ -124,6 +124,26 @@ Tests are located in ``tests/arduino-core-tests`` and included as submodule in t If you need to run these tests locally, you'll also need to download `GNU Make `_ . +Debugging (VS Code) +^^^^^^^^^^^^^^^^^^^^ +Debugging support described here is for Visual Studio Code. The Arduino IDE already provides a built-in debugger for supported boards. + +#. Install the `Cortex-Debug` extension in VS Code. +#. Copy the `task_xmc.json` file from `tools/vscode-profile` to the `.vscode` directory and rename to `tasks.json` in your project root. +#. In VS Code, run the task: **Generate launch.json for debug (XMC)**. +#. Required parameters for this task: + * **fqbn**: Fully Qualified Board Name (e.g., `arduino-git:xmc:kit_xmc47_relax`) + * **build path**: Directory where the `.elf` file will be placed + * **example path**: Path to the sketch (`.ino` file) to debug (for arduino-core-tests make sure it has been built at least once to generate the required build.ino) +#. Optional parameters: + * **boards.txt path**: Path to a custom `boards.txt` file + * **gdb path**: Path to a custom GDB executable + +Refer to the documentation of your chosen debugger and scripts in the `tools/` folder for more details. + +.. note:: + If you encounter an error indicating that ``libncurses.so.5`` or a similar library cannot be found, please search online and install the appropriate package for your environment. + Release --------- Add a git tag in the format `Vx.y.z` (e.g. V3.3.0) to trigger the release process. diff --git a/tools/gen_launch.sh b/tools/gen_launch.sh new file mode 100755 index 00000000..b522f6e4 --- /dev/null +++ b/tools/gen_launch.sh @@ -0,0 +1,149 @@ +#!/bin/bash +# gen_launch.sh: Compile and generate launch.json for XMC or PSoC6 boards +# Usage: ./gen_launch.sh [boards.txt] [gdb_path] +# : Fully Qualified Board Name (e.g. infineon:psoc6:CY8CKIT_062S2_AI or arduino-git:xmc:kit_xmc47_relax) +# : Directory where the .elf file will be placed +# : Path to the sketch (.ino) file +# [boards.txt] : (Optional) Path to boards.txt (default: inferred based on device) +# [gdb_path] : (Optional) Path to GDB executable (default: inferred based on device) + +set -e + +FQBN_FULL="$1" +BUILD_PATH="$2" +SKETCH_PATH="$3" + +if [[ -z "$FQBN_FULL" || -z "$BUILD_PATH" || -z "$SKETCH_PATH" ]]; then + echo "Usage: $0 [boards.txt] [gdb_path]" + exit 1 +fi + +# Get the script directory and package root +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PACKAGE_DIR="$(dirname "$SCRIPT_DIR")" + +# Detect device type based on FQBN +if [[ "$FQBN_FULL" == infineon:psoc6:* ]]; then + DEVICE_TYPE="psoc6" + BOARDS_TXT="${4:-$PACKAGE_DIR/boards.txt}" + GDB_PATH="${5:-$HOME/.arduino15/packages/infineon/tools/mtb-gcc-arm-none-eabi/11.3.1.67/bin/arm-none-eabi-gdb}" +elif [[ "$FQBN_FULL" == arduino-git:xmc:* ]]; then + DEVICE_TYPE="xmc" + XMC_DIR="$(dirname "$SCRIPT_DIR")" + BOARDS_TXT="${4:-$XMC_DIR/boards.txt}" + GDB_PATH="${5:-$HOME/.arduino15/packages/infineon/tools/arm-none-eabi-gcc/10.3-2021.10/bin/arm-none-eabi-gdb}" +else + echo "Unsupported device type in FQBN: $FQBN_FULL" + exit 1 +fi + +# Extract board name from FQBN +BOARD_NAME=$(echo "$FQBN_FULL" | awk -F: '{print $NF}') + +# Compile the sketch +arduino-cli compile -b "${FQBN_FULL}" --build-path "${BUILD_PATH}" "${SKETCH_PATH}" || exit 1 + +# Parse boards.txt for variant and other parameters +VARIANT=$(grep "^${BOARD_NAME}\.build\.variant=" "$BOARDS_TXT" | cut -d= -f2) +if [[ -z "$VARIANT" ]]; then + echo "Could not find variant for $BOARD_NAME in $BOARDS_TXT" + exit 2 +fi + +if [[ "$DEVICE_TYPE" == "xmc" ]]; then + BOARD_V=$(grep "^${BOARD_NAME}\.build\.board\.v=" "$BOARDS_TXT" | cut -d= -f2) + if [[ -z "$BOARD_V" ]]; then + echo "Could not find board.v for $BOARD_NAME in $BOARDS_TXT" + exit 2 + fi + DEVICE="${VARIANT}-${BOARD_V}" +else + DEVICE="${VARIANT}" +fi + +# Find the .elf executable +EXECUTABLE=$(find "${BUILD_PATH}" -maxdepth 1 -type f -name "*.elf" | head -n 1) +if [[ -z "$EXECUTABLE" ]]; then + echo "No .elf executable found in $BUILD_PATH." + exit 3 +fi + +# Create the .vscode directory and generate launch.json +LAUNCH_DIR="$PACKAGE_DIR/.vscode" +if [ ! -d "$LAUNCH_DIR" ]; then + mkdir -p "$LAUNCH_DIR" +fi +if [ -f "$LAUNCH_DIR/launch.json" ]; then + rm "$LAUNCH_DIR/launch.json" +fi + +if [[ "$DEVICE_TYPE" == "psoc6" ]]; then + # Generate launch.json for PSoC6 + cat > "$LAUNCH_DIR/launch.json" < "$LAUNCH_DIR/launch.json" <