[skip-changelog] debugger: some improvements in configuration handling (#2364)

* Allow non-sequential properties list

* Command 'debug info' choose between "script" and "scripts" configs exclusively

* Updated docs

* Added test for mixed old and new-style openocd script definition

* Update docs/platform-specification.md
Co-authored-by: Umberto Baldi <34278123+umbynos@users.noreply.github.com>

---------
Co-authored-by: Umberto Baldi <34278123+umbynos@users.noreply.github.com>

.licenses/go/github.com/arduino/go-properties-orderedmap.dep.yml

 ---
 name: github.com/arduino/go-properties-orderedmap
-version: v1.7.1
+version: v1.8.0
 type: go
 summary: Package properties is a library for handling maps of hierarchical properties.
 homepage: https://pkg.go.dev/github.com/arduino/go-properties-orderedmap

commands/debug/debug_info.go

@@ -159,8 +159,8 @@ func getDebugProperties(req *rpc.GetDebugConfigRequest, pme *packagemanager.Expl
 	case "openocd":
 		openocdProperties := debugProperties.SubTree("server." + server)
 		scripts := openocdProperties.ExtractSubIndexLists("scripts")
-		if s := openocdProperties.Get("script"); s != "" {
-			// backward compatibility
+		if s := openocdProperties.Get("script"); s != "" && len(scripts) == 0 {
+			// backward compatibility: use "script" property if there are no "scipts.N"
 			scripts = append(scripts, s)
 		}
 		openocdConf := &rpc.DebugOpenOCDServerConfiguration{

docs/platform-specification.md

@@ -1361,7 +1361,10 @@ OpenOCD server specific configurations:
 
 - `debug.server.openocd.path`: is the absolute path to the OpenOCD directory
 - `debug.server.openocd.scripts_dir`: is the absolute path to the OpenOCD scripts directory
-- `debug.server.openocd.scripts.N`: is a list of OpenOCD scripts to run (where N is a number starting from 0)
+- `debug.server.openocd.scripts.N`: is a list of OpenOCD script files to run, where N is a number (a sequence of
+  non-consecutive numbers is allowed)
+- `debug.server.openocd.script`: if there is only one OpenOCD script to run, this directive con be used instead of the
+  `debug.server.openocd.scripts.N` (this directive is ignored if `debug.server.openocd.scripts.N` is present)
 
 ### Custom config for Cortext-debug plugin for Arduino IDE
 

go.mod

@@ -8,7 +8,7 @@ replace github.com/mailru/easyjson => github.com/cmaglie/easyjson v0.8.1
 require (
 	github.com/ProtonMail/go-crypto v0.0.0-20230828082145-3c4c8a2d2371
 	github.com/arduino/go-paths-helper v1.9.0
-	github.com/arduino/go-properties-orderedmap v1.7.1
+	github.com/arduino/go-properties-orderedmap v1.8.0
 	github.com/arduino/go-timeutils v0.0.0-20171220113728-d1dd9e313b1b
 	github.com/arduino/go-win32-utils v1.0.0
 	github.com/cmaglie/pb v1.0.27

go.sum

@@ -49,8 +49,8 @@ github.com/antihax/optional v1.0.0/go.mod h1:uupD/76wgC+ih3iEmQUL+0Ugr19nfwCT1kd
 github.com/arduino/go-paths-helper v1.0.1/go.mod h1:HpxtKph+g238EJHq4geEPv9p+gl3v5YYu35Yb+w31Ck=
 github.com/arduino/go-paths-helper v1.9.0 h1:IjWhDSF24n5bK/30NyApmzoVH9brWzc52KNPpBsRmMc=
 github.com/arduino/go-paths-helper v1.9.0/go.mod h1:V82BWgAAp4IbmlybxQdk9Bpkz8M4Qyx+RAFKaG9NuvU=
-github.com/arduino/go-properties-orderedmap v1.7.1 h1:HQ9Pn/mk3+XyfrE39EEvaZwJkrvgiVSY5Oq3JSEfOR4=
-github.com/arduino/go-properties-orderedmap v1.7.1/go.mod h1:DKjD2VXY/NZmlingh4lSFMEYCVubfeArCsGPGDwb2yk=
+github.com/arduino/go-properties-orderedmap v1.8.0 h1:wEfa6hHdpezrVOh787OmClsf/Kd8qB+zE3P2Xbrn0CQ=
+github.com/arduino/go-properties-orderedmap v1.8.0/go.mod h1:DKjD2VXY/NZmlingh4lSFMEYCVubfeArCsGPGDwb2yk=
 github.com/arduino/go-timeutils v0.0.0-20171220113728-d1dd9e313b1b h1:9hDi4F2st6dbLC3y4i02zFT5quS4X6iioWifGlVwfy4=
 github.com/arduino/go-timeutils v0.0.0-20171220113728-d1dd9e313b1b/go.mod h1:uwGy5PpN4lqW97FiLnbcx+xx8jly5YuPMJWfVwwjJiQ=
 github.com/arduino/go-win32-utils v1.0.0 h1:/cXB86sOJxOsCHP7sQmXGLkdValwJt56mIwOHYxgQjQ=

internal/integrationtest/debug/debug_test.go

@@ -106,13 +106,12 @@ func testAllDebugInformation(t *testing.T, env *integrationtest.Environment, cli
 	require.NoError(t, err)
 
 	// Build sketch
-	fqbn := "my:samd:my"
-	_, _, err = cli.Run("compile", "-b", fqbn, sketchPath.String(), "--format", "json")
+	_, _, err = cli.Run("compile", "-b", "my:samd:my", sketchPath.String(), "--format", "json")
 	require.NoError(t, err)
 
 	{
 		// Starts debugger
-		jsonDebugOut, _, err := cli.Run("debug", "-b", fqbn, "-P", "atmel_ice", sketchPath.String(), "--info", "--format", "json")
+		jsonDebugOut, _, err := cli.Run("debug", "-b", "my:samd:my", "-P", "atmel_ice", sketchPath.String(), "--info", "--format", "json")
 		require.NoError(t, err)
 		debugOut := requirejson.Parse(t, jsonDebugOut)
 		debugOut.MustContain(`
@@ -128,7 +127,8 @@ func testAllDebugInformation(t *testing.T, env *integrationtest.Environment, cli
 				"scripts": [
 					"first",
 					"second",
-					"third"
+					"third",
+					"fourth"
 				]
 			},
 			"svd_file": "svd-file",
@@ -153,7 +153,7 @@ func testAllDebugInformation(t *testing.T, env *integrationtest.Environment, cli
 
 	// Starts debugger with another programmer
 	{
-		jsonDebugOut, _, err := cli.Run("debug", "-b", fqbn, "-P", "my_cold_ice", sketchPath.String(), "--info", "--format", "json")
+		jsonDebugOut, _, err := cli.Run("debug", "-b", "my:samd:my", "-P", "my_cold_ice", sketchPath.String(), "--info", "--format", "json")
 		require.NoError(t, err)
 		debugOut := requirejson.Parse(t, jsonDebugOut)
 		debugOut.MustContain(`
@@ -169,7 +169,8 @@ func testAllDebugInformation(t *testing.T, env *integrationtest.Environment, cli
 				"scripts": [
 					"first",
 					"second",
-					"cold_ice_script"
+					"cold_ice_script",
+					"fourth"
 				]
 			},
 			"svd_file": "svd-file",
@@ -190,5 +191,52 @@ func testAllDebugInformation(t *testing.T, env *integrationtest.Environment, cli
 				]
 			}
 		}`)
+
+		{
+			// Starts debugger with an old-style openocd script definition
+			jsonDebugOut, _, err := cli.Run("debug", "-b", "my:samd:my2", "-P", "atmel_ice", sketchPath.String(), "--info", "--format", "json")
+			require.NoError(t, err)
+			debugOut := requirejson.Parse(t, jsonDebugOut)
+			debugOut.MustContain(`
+			{
+				"toolchain": "gcc",
+				"toolchain_path": "gcc-path",
+				"toolchain_prefix": "gcc-prefix",
+				"server": "openocd",
+				"server_path": "openocd-path",
+				"server_configuration": {
+					"path": "openocd-path",
+					"scripts_dir": "openocd-scripts-dir",
+					"scripts": [
+						"single-script"
+					]
+				},
+				"svd_file": "svd-file"
+			}`)
+		}
+
+		{
+			// Starts debugger with mixed old and new-style openocd script definition
+			jsonDebugOut, _, err := cli.Run("debug", "-b", "my:samd:my2", "-P", "my_cold_ice", sketchPath.String(), "--info", "--format", "json")
+			require.NoError(t, err)
+			debugOut := requirejson.Parse(t, jsonDebugOut)
+			debugOut.MustContain(`
+			{
+				"toolchain": "gcc",
+				"toolchain_path": "gcc-path",
+				"toolchain_prefix": "gcc-prefix",
+				"server": "openocd",
+				"server_path": "openocd-path",
+				"server_configuration": {
+					"path": "openocd-path",
+					"scripts_dir": "openocd-scripts-dir",
+					"scripts": [
+						"cold_ice_script"
+					]
+				},
+				"svd_file": "svd-file"
+			}`)
+		}
+
 	}
 }

internal/integrationtest/debug/testdata/hardware/my/samd/boards.txt

@@ -33,6 +33,7 @@ my.debug.server.openocd.script=
 my.debug.server.openocd.scripts.0=first
 my.debug.server.openocd.scripts.1=second
 my.debug.server.openocd.scripts.2=third
+my.debug.server.openocd.scripts.5=fourth
 my.debug.cortex-debug.custom.postAttachCommands.0=set remote hardware-watchpoint-limit 2
 my.debug.cortex-debug.custom.postAttachCommands.1=monitor reset halt
 my.debug.cortex-debug.custom.postAttachCommands.2=monitor gdb_sync
@@ -44,3 +45,37 @@ my.debug.cortex-debug.custom.overrideRestartCommands.2=thb setup
 my.debug.cortex-debug.custom.overrideRestartCommands.3=c
 my.debug.cortex-debug.custom.anotherStringParamer=hellooo
 my.debug.svd_file=svd-file
+
+my2.name=My Cool Board
+my2.vid.0=0x2341
+my2.pid.0=0x804e
+my2.upload_port.0.vid=0x2341
+my2.upload_port.0.pid=0x804e
+my2.upload.tool=bossac
+my2.upload.tool.default=bossac
+my2.upload.tool.network=arduino_ota
+my2.upload.protocol=sam-ba
+my2.upload.maximum_size=262144
+my2.upload.maximum_data_size=32768
+my2.upload.use_1200bps_touch=true
+my2.upload.wait_for_upload_port=true
+my2.upload.native_usb=true
+my2.build.mcu=cortex-m0plus
+my2.build.f_cpu=48000000L
+my2.build.usb_product="Arduino MKR1000"
+my2.build.usb_manufacturer="Arduino LLC"
+my2.build.board=SAMD_MY
+my2.build.core=arduino:arduino
+my2.build.extra_flags=-DUSE_ARDUINO_MKR_PIN_LAYOUT -D__SAMD21G18A__ {build.usb_flags}
+my2.build.ldscript=linker_scripts/gcc/flash_with_bootloader.ld
+my2.build.openocdscript=openocd_scripts/arduino_zero.cfg
+my2.build.variant=arduino:mkr1000
+my2.build.vid=0x2341
+my2.build.pid=0x804e
+
+my2.debug.toolchain.path=gcc-path
+my2.debug.toolchain.prefix=gcc-prefix
+my2.debug.server.openocd.path=openocd-path
+my2.debug.server.openocd.scripts_dir=openocd-scripts-dir
+my2.debug.server.openocd.script=single-script
+my2.debug.svd_file=svd-file