cmake: add helpers for setting board runners

This helps by letting us add checks for when the runner has already been set. There is documentation saying you can set -DBOARD_DEBUG_RUNNER at the command line and have it take effect, which turns out not to be true for a large number of boards. A status message helps the user debug. (We'll address the existing in-tree boards in the next patch.) Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
2019-05-31 17:51:31 -06:00 · 2019-05-31 17:51:31 -06:00 · 1717332c7a
parent 9f851cc2dc
commit 1717332c7a
41 changed files with 148 additions and 88 deletions
--- a/boards/arc/arduino_101_sss/board.cmake
+++ b/boards/arc/arduino_101_sss/board.cmake
@ -1,12 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0

 if(DEFINED ENV{ZEPHYR_FLASH_OVER_DFU})
-  set(BOARD_FLASH_RUNNER dfu-util)
+  board_set_flasher(dfu-util)
 else()
-  set(BOARD_FLASH_RUNNER openocd)
+  board_set_flasher(openocd)
 endif()

-set(BOARD_DEBUG_RUNNER openocd)
+board_set_debugger(openocd)

 board_runner_args(dfu-util "--pid=8087:0aba" "--alt=sensor_core")
 board_runner_args(openocd --cmd-pre-load "targets 1" "--gdb-port=3334")
--- a/boards/arc/em_starterkit/board.cmake
+++ b/boards/arc/em_starterkit/board.cmake
@ -1,6 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0

 # TODO: can this board just use the usual openocd runner?
-set(BOARD_FLASH_RUNNER em-starterkit)
-set(BOARD_DEBUG_RUNNER em-starterkit)
+board_set_flasher(em-starterkit)
+board_set_debugger(em-starterkit)
 board_finalize_runner_args(em-starterkit)
--- a/boards/arc/iotdk/board.cmake
+++ b/boards/arc/iotdk/board.cmake
@ -1,6 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0

 # TODO: can this board just use the usual openocd runner?
-set(BOARD_FLASH_RUNNER em-starterkit)
-set(BOARD_DEBUG_RUNNER em-starterkit)
+board_set_flasher(em-starterkit)
+board_set_debugger(em-starterkit)
 board_finalize_runner_args(em-starterkit)
--- a/boards/arc/nsim/board.cmake
+++ b/boards/arc/nsim/board.cmake
@ -2,8 +2,8 @@

 set(EMU_PLATFORM nsim)

-set(BOARD_FLASH_RUNNER arc-nsim)
-set(BOARD_DEBUG_RUNNER arc-nsim)
+board_set_flasher(arc-nsim)
+board_set_debugger(arc-nsim)

 if(${CONFIG_SOC_NSIM_EM})
 board_runner_args(arc-nsim "--props=nsim_em.props")
--- a/boards/arm/frdm_k64f/board.cmake
+++ b/boards/arm/frdm_k64f/board.cmake
@ -3,11 +3,11 @@
 set_ifndef(OPENSDA_FW daplink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 elseif(OPENSDA_FW STREQUAL daplink)
-  set_ifndef(BOARD_DEBUG_RUNNER pyocd)
-  set_ifndef(BOARD_FLASH_RUNNER pyocd)
+  board_set_debugger_ifnset(pyocd)
+  board_set_flasher_ifnset(pyocd)
 endif()

 board_runner_args(jlink "--device=MK64FN1M0xxx12")
--- a/boards/arm/frdm_kl25z/board.cmake
+++ b/boards/arm/frdm_kl25z/board.cmake
@ -3,11 +3,11 @@
 set_ifndef(OPENSDA_FW daplink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 elseif(OPENSDA_FW STREQUAL daplink)
-  set_ifndef(BOARD_DEBUG_RUNNER pyocd)
-  set_ifndef(BOARD_FLASH_RUNNER pyocd)
+  board_set_debugger_ifnset(pyocd)
+  board_set_flasher_ifnset(pyocd)
 endif()

 board_runner_args(jlink "--device=MKL25Z128xxx4")
--- a/boards/arm/frdm_kw41z/board.cmake
+++ b/boards/arm/frdm_kw41z/board.cmake
@ -3,11 +3,11 @@
 set_ifndef(OPENSDA_FW daplink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 elseif(OPENSDA_FW STREQUAL daplink)
-  set_ifndef(BOARD_DEBUG_RUNNER pyocd)
-  set_ifndef(BOARD_FLASH_RUNNER pyocd)
+  board_set_debugger_ifnset(pyocd)
+  board_set_flasher_ifnset(pyocd)
 endif()

 board_runner_args(jlink "--device=MKW41Z512xxx4")
--- a/boards/arm/hexiwear_k64/board.cmake
+++ b/boards/arm/hexiwear_k64/board.cmake
@ -3,11 +3,11 @@
 set_ifndef(OPENSDA_FW jlink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 elseif(OPENSDA_FW STREQUAL daplink)
-  set_ifndef(BOARD_DEBUG_RUNNER pyocd)
-  set_ifndef(BOARD_FLASH_RUNNER pyocd)
+  board_set_debugger_ifnset(pyocd)
+  board_set_flasher_ifnset(pyocd)
 endif()

 board_runner_args(pyocd "--target=k64f")
--- a/boards/arm/hexiwear_kw40z/board.cmake
+++ b/boards/arm/hexiwear_kw40z/board.cmake
@ -3,11 +3,11 @@
 set_ifndef(OPENSDA_FW jlink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 elseif(OPENSDA_FW STREQUAL daplink)
-  set_ifndef(BOARD_DEBUG_RUNNER pyocd)
-  set_ifndef(BOARD_FLASH_RUNNER pyocd)
+  board_set_debugger_ifnset(pyocd)
+  board_set_flasher_ifnset(pyocd)
 endif()

 board_runner_args(jlink "--device=MKW40Z160xxx4")
--- a/boards/arm/lpcxpresso54114/board.cmake
+++ b/boards/arm/lpcxpresso54114/board.cmake
@ -7,8 +7,8 @@
 set_ifndef(LPCLINK_FW jlink)

 if(LPCLINK_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 endif()

 if(CONFIG_BOARD_LPCXPRESSO54114_M4)
--- a/boards/arm/lpcxpresso55s69/board.cmake
+++ b/boards/arm/lpcxpresso55s69/board.cmake
@ -11,8 +11,8 @@
 set_ifndef(OPENSDA_FW jlink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 endif()

 if(CONFIG_BOARD_LPCXPRESSO55S69_CPU0)
--- a/boards/arm/mimxrt1015_evk/board.cmake
+++ b/boards/arm/mimxrt1015_evk/board.cmake
@ -6,8 +6,8 @@
 set_ifndef(OPENSDA_FW jlink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 endif()

 board_runner_args(jlink "--device=MIMXRT1015")
--- a/boards/arm/mimxrt1020_evk/board.cmake
+++ b/boards/arm/mimxrt1020_evk/board.cmake
@ -7,11 +7,11 @@
 set_ifndef(OPENSDA_FW jlink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 elseif(OPENSDA_FW STREQUAL daplink)
-  set_ifndef(BOARD_DEBUG_RUNNER pyocd)
-  set_ifndef(BOARD_FLASH_RUNNER pyocd)
+  board_set_debugger_ifnset(pyocd)
+  board_set_flasher_ifnset(pyocd)
 endif()

 board_runner_args(pyocd "--target=mimxrt1020")
--- a/boards/arm/mimxrt1050_evk/board.cmake
+++ b/boards/arm/mimxrt1050_evk/board.cmake
@ -7,11 +7,11 @@
 set_ifndef(OPENSDA_FW jlink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 elseif(OPENSDA_FW STREQUAL daplink)
-  set_ifndef(BOARD_DEBUG_RUNNER pyocd)
-  set_ifndef(BOARD_FLASH_RUNNER pyocd)
+  board_set_debugger_ifnset(pyocd)
+  board_set_flasher_ifnset(pyocd)
 endif()

 board_runner_args(pyocd "--target=mimxrt1050_hyperflash")
--- a/boards/arm/mimxrt1060_evk/board.cmake
+++ b/boards/arm/mimxrt1060_evk/board.cmake
@ -7,11 +7,11 @@
 set_ifndef(OPENSDA_FW jlink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 elseif(OPENSDA_FW STREQUAL daplink)
-  set_ifndef(BOARD_DEBUG_RUNNER pyocd)
-  set_ifndef(BOARD_FLASH_RUNNER pyocd)
+  board_set_debugger_ifnset(pyocd)
+  board_set_flasher_ifnset(pyocd)
 endif()

 board_runner_args(pyocd "--target=cortex_m")
--- a/boards/arm/mimxrt1064_evk/board.cmake
+++ b/boards/arm/mimxrt1064_evk/board.cmake
@ -7,11 +7,11 @@
 set_ifndef(OPENSDA_FW jlink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 elseif(OPENSDA_FW STREQUAL daplink)
-  set_ifndef(BOARD_DEBUG_RUNNER pyocd)
-  set_ifndef(BOARD_FLASH_RUNNER pyocd)
+  board_set_debugger_ifnset(pyocd)
+  board_set_flasher_ifnset(pyocd)
 endif()

 board_runner_args(pyocd "--target=cortex_m")
--- a/boards/arm/mps2_an385/board.cmake
+++ b/boards/arm/mps2_an385/board.cmake
@ -10,4 +10,4 @@ set(QEMU_FLAGS_${ARCH}
  -vga none
  )

-set(BOARD_DEBUG_RUNNER qemu)
+board_set_debugger(qemu)
--- a/boards/arm/nrf52_sparkfun/board.cmake
+++ b/boards/arm/nrf52_sparkfun/board.cmake
@ -1,7 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0

-set(BOARD_FLASH_RUNNER pyocd.sh)
-set(BOARD_DEBUG_RUNNER pyocd.sh)
+board_set_flasher(pyocd.sh)
+board_set_debugger(pyocd.sh)

 set(PYOCD_TARGET nrf52)

--- a/boards/arm/qemu_cortex_m3/board.cmake
+++ b/boards/arm/qemu_cortex_m3/board.cmake
@ -10,4 +10,4 @@ set(QEMU_FLAGS_${ARCH}
  -vga none
  )

-set(BOARD_DEBUG_RUNNER qemu)
+board_set_debugger(qemu)
--- a/boards/arm/twr_ke18f/board.cmake
+++ b/boards/arm/twr_ke18f/board.cmake
@ -3,11 +3,11 @@
 set_ifndef(OPENSDA_FW daplink)

 if(OPENSDA_FW STREQUAL jlink)
-  set_ifndef(BOARD_DEBUG_RUNNER jlink)
-  set_ifndef(BOARD_FLASH_RUNNER jlink)
+  board_set_debugger_ifnset(jlink)
+  board_set_flasher_ifnset(jlink)
 elseif(OPENSDA_FW STREQUAL daplink)
-  set_ifndef(BOARD_DEBUG_RUNNER pyocd)
-  set_ifndef(BOARD_FLASH_RUNNER pyocd)
+  board_set_debugger_ifnset(pyocd)
+  board_set_flasher_ifnset(pyocd)
 endif()

 board_runner_args(jlink "--device=MKE18F512xxx16")
--- a/boards/arm/v2m_beetle/board.cmake
+++ b/boards/arm/v2m_beetle/board.cmake
@ -1,3 +1,3 @@
 # SPDX-License-Identifier: Apache-2.0

-set(BOARD_DEBUG_RUNNER openocd)
+board_set_debugger(openocd)
--- a/boards/common/blackmagicprobe.board.cmake
+++ b/boards/common/blackmagicprobe.board.cmake
@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0

-set_ifndef(BOARD_FLASH_RUNNER blackmagicprobe)
-set_ifndef(BOARD_DEBUG_RUNNER blackmagicprobe)
+board_set_flasher_ifnset(blackmagicprobe)
+board_set_debugger_ifnset(blackmagicprobe)
 board_finalize_runner_args(blackmagicprobe) # No default arguments to provide
--- a/boards/common/bossac.board.cmake
+++ b/boards/common/bossac.board.cmake
@ -1,4 +1,4 @@
 # SPDX-License-Identifier: Apache-2.0

-set_ifndef(BOARD_FLASH_RUNNER bossac)
+board_set_flasher_ifnset(bossac)
 board_finalize_runner_args(bossac "--bossac=${BOSSAC}")
--- a/boards/common/dfu-util.board.cmake
+++ b/boards/common/dfu-util.board.cmake
@ -1,4 +1,4 @@
 # SPDX-License-Identifier: Apache-2.0

-set_ifndef(BOARD_FLASH_RUNNER dfu-util)
+board_set_flasher_ifnset(dfu-util)
 board_finalize_runner_args(dfu-util) # No default arguments to provide.
--- a/boards/common/esp32.board.cmake
+++ b/boards/common/esp32.board.cmake
@ -1,6 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0

-set(BOARD_FLASH_RUNNER esp32)
+board_set_flasher(esp32)

 if(NOT DEFINED ESP_IDF_PATH)
  if(DEFINED ENV{ESP_IDF_PATH})
--- a/boards/common/jlink.board.cmake
+++ b/boards/common/jlink.board.cmake
@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0

-set_ifndef(BOARD_FLASH_RUNNER jlink)
-set_ifndef(BOARD_DEBUG_RUNNER jlink)
+board_set_flasher_ifnset(jlink)
+board_set_debugger_ifnset(jlink)
 board_finalize_runner_args(jlink "--dt-flash=y")
--- a/boards/common/nios2.board.cmake
+++ b/boards/common/nios2.board.cmake
@ -1,7 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0

-set_ifndef(BOARD_FLASH_RUNNER nios2)
-set_ifndef(BOARD_DEBUG_RUNNER nios2)
+board_set_flasher_ifnset(nios2)
+board_set_debugger_ifnset(nios2)

 board_finalize_runner_args(nios2
  # TODO: merge this script into nios2.py
--- a/boards/common/nrfjprog.board.cmake
+++ b/boards/common/nrfjprog.board.cmake
@ -1,4 +1,4 @@
 # SPDX-License-Identifier: Apache-2.0

-set_ifndef(BOARD_FLASH_RUNNER nrfjprog)
+board_set_flasher_ifnset(nrfjprog)
 board_finalize_runner_args(nrfjprog) # No default arguments to provide.
--- a/boards/common/openocd.board.cmake
+++ b/boards/common/openocd.board.cmake
@ -1,7 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0

-set_ifndef(BOARD_FLASH_RUNNER openocd)
-set_ifndef(BOARD_DEBUG_RUNNER openocd)
+board_set_flasher_ifnset(openocd)
+board_set_debugger_ifnset(openocd)

 # "load_image" or "flash write_image erase"?
 if(CONFIG_X86 OR CONFIG_ARC)
--- a/boards/common/pyocd.board.cmake
+++ b/boards/common/pyocd.board.cmake
@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0

-set_ifndef(BOARD_FLASH_RUNNER pyocd)
-set_ifndef(BOARD_DEBUG_RUNNER pyocd)
+board_set_flasher_ifnset(pyocd)
+board_set_debugger_ifnset(pyocd)
 board_finalize_runner_args(pyocd "--dt-flash=y")
--- a/boards/nios2/qemu_nios2/board.cmake
+++ b/boards/nios2/qemu_nios2/board.cmake
@ -9,4 +9,4 @@ set(QEMU_FLAGS_${ARCH}
  -nographic
  )

-set(BOARD_DEBUG_RUNNER qemu)
+board_set_debugger(qemu)
--- a/boards/riscv32/hifive1/board.cmake
+++ b/boards/riscv32/hifive1/board.cmake
@ -9,6 +9,6 @@ set(QEMU_FLAGS_${ARCH}
  -machine sifive_e
  )

-set(BOARD_DEBUG_RUNNER qemu)
-set(BOARD_FLASH_RUNNER hifive1)
+board_set_debugger(qemu)
+board_set_flasher(hifive1)
 board_finalize_runner_args(hifive1)
--- a/boards/riscv32/qemu_riscv32/board.cmake
+++ b/boards/riscv32/qemu_riscv32/board.cmake
@ -9,4 +9,4 @@ set(QEMU_FLAGS_${ARCH}
  -machine sifive_e
  )

-set(BOARD_DEBUG_RUNNER qemu)
+board_set_debugger(qemu)
--- a/boards/x86/arduino_101/board.cmake
+++ b/boards/x86/arduino_101/board.cmake
@ -1,10 +1,10 @@
 # SPDX-License-Identifier: Apache-2.0

 if(DEFINED ENV{ZEPHYR_FLASH_OVER_DFU})
-  set(BOARD_FLASH_RUNNER dfu-util)
+  board_set_flasher(dfu-util)
 endif()

-set(BOARD_DEBUG_RUNNER openocd)
+board_set_debugger(openocd)

 board_runner_args(dfu-util "--pid=8087:0aba" "--alt=x86_app")
 board_runner_args(openocd --cmd-pre-load "targets 1")
--- a/boards/x86/qemu_x86/board.cmake
+++ b/boards/x86/qemu_x86/board.cmake
@ -17,6 +17,6 @@ set(QEMU_FLAGS_${ARCH}
  )

 # TODO: Support debug
-# set(BOARD_DEBUG_RUNNER qemu)
+# board_set_debugger(qemu)
 # debugserver: QEMU_EXTRA_FLAGS += -s -S
 # debugserver: qemu
--- a/boards/x86/tinytile/board.cmake
+++ b/boards/x86/tinytile/board.cmake
@ -1,10 +1,10 @@
 # SPDX-License-Identifier: Apache-2.0

 if(DEFINED ENV{ZEPHYR_FLASH_OVER_DFU})
-  set(BOARD_FLASH_RUNNER dfu-util)
+  board_set_flasher(dfu-util)
 endif()

-set(BOARD_DEBUG_RUNNER openocd)
+board_set_debugger(openocd)

 board_runner_args(dfu-util "--pid=8087:0aba" "--alt=x86_app")
 board_runner_args(openocd --cmd-pre-load "targets 1")
--- a/boards/x86/x86_jailhouse/board.cmake
+++ b/boards/x86/x86_jailhouse/board.cmake
@ -37,6 +37,6 @@ set(QEMU_FLAGS_${ARCH}
  )

 # TODO: Support debug
-# set(BOARD_DEBUG_RUNNER qemu)
+# board_set_debugger(qemu)
 # debugserver: QEMU_EXTRA_FLAGS += -s -S
 # debugserver: qemu
--- a/boards/xtensa/intel_s1000_crb/board.cmake
+++ b/boards/xtensa/intel_s1000_crb/board.cmake
@ -1,7 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0

-set(BOARD_FLASH_RUNNER intel_s1000)
-set(BOARD_DEBUG_RUNNER intel_s1000)
+board_set_flasher(intel_s1000)
+board_set_debugger(intel_s1000)

 board_finalize_runner_args(intel_s1000
  "--xt-ocd-dir=/opt/tensilica/xocd-12.0.4/xt-ocd"
--- a/boards/xtensa/qemu_xtensa/board.cmake
+++ b/boards/xtensa/qemu_xtensa/board.cmake
@ -9,6 +9,6 @@ set(QEMU_FLAGS_${ARCH}
  )

 # TODO: Support debug
-# set(BOARD_DEBUG_RUNNER qemu)
+# board_set_debugger(qemu)
 # debugserver: QEMU_EXTRA_FLAGS += -s -S
 # debugserver: qemu
--- a/boards/xtensa/xt-sim/board.cmake
+++ b/boards/xtensa/xt-sim/board.cmake
@ -1,3 +1,3 @@
 # SPDX-License-Identifier: Apache-2.0

-set(BOARD_DEBUG_RUNNER xtensa)
+board_set_debugger(xtensa)
--- a/cmake/extensions.cmake
+++ b/cmake/extensions.cmake
@ -559,6 +559,66 @@ endfunction()
 # This section provides glue between CMake and the Python code that
 # manages the runners.

+function(_board_check_runner_type type) # private helper
+  if (NOT (("${type}" STREQUAL "FLASH") OR ("${type}" STREQUAL "DEBUG")))
+    message(FATAL_ERROR "invalid type ${type}; should be FLASH or DEBUG")
+  endif()
+endfunction()
+
+# This function sets the runner for the board unconditionally.  It's
+# meant to be used from application CMakeLists.txt files.
+#
+# NOTE: Usually board_set_xxx_ifnset() is best in board.cmake files.
+#       This lets the user set the runner at cmake time, or in their
+#       own application's CMakeLists.txt.
+#
+# Usage:
+#   board_set_runner(FLASH pyocd)
+#
+# This would set the board's flash runner to "pyocd".
+#
+# In general, "type" is FLASH or DEBUG, and "runner" is the name of a
+# runner.
+function(board_set_runner type runner)
+  _board_check_runner_type(${type})
+  if (DEFINED BOARD_${type}_RUNNER)
+    message(STATUS "overriding ${type} runner ${BOARD_${type}_RUNNER}; it's now ${runner}")
+  endif()
+  set(BOARD_${type}_RUNNER ${runner} PARENT_SCOPE)
+endfunction()
+
+# This macro is like board_set_runner(), but will only make a change
+# if that runner is currently not set.
+#
+# See also board_set_flasher_ifnset() and board_set_debugger_ifnset().
+macro(board_set_runner_ifnset type runner)
+  _board_check_runner_type(${type})
+  # This is a macro because set_ifndef() works at parent scope.
+  # If this were a function, that would be this function's scope,
+  # which wouldn't work.
+  set_ifndef(BOARD_${type}_RUNNER ${runner})
+endmacro()
+
+# A convenience macro for board_set_runner(FLASH ${runner}).
+macro(board_set_flasher runner)
+  board_set_runner(FLASH ${runner})
+endmacro()
+
+# A convenience macro for board_set_runner(DEBUG ${runner}).
+macro(board_set_debugger runner)
+  board_set_runner(DEBUG ${runner})
+endmacro()
+
+# A convenience macro for board_set_runner_ifnset(FLASH ${runner}).
+macro(board_set_flasher_ifnset runner)
+  board_set_runner_ifnset(FLASH ${runner})
+endmacro()
+
+# A convenience macro for board_set_runner_ifnset(DEBUG ${runner}).
+macro(board_set_debugger_ifnset runner)
+  board_set_runner_ifnset(DEBUG ${runner})
+endmacro()
+
 # This function is intended for board.cmake files and application
 # CMakeLists.txt files.
 #