feat(doc): document empty vendor and arch in FQBN (#2550)

The spec should be aligned with the implementation; empty `vendor` and `architecture` parts are allowed in the FQBN. Signed-off-by: dankeboy36 <[email protected]>
arduino · Feb 29, 2024 · fcb2670 · fcb2670
1 parent af0b60e
commit fcb2670
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 6 deletions.
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -12,8 +12,9 @@ When you run [`arduino-cli board list`][arduino cli board list], your board does
 FQBN stands for Fully Qualified Board Name. It has the following format:
 `VENDOR:ARCHITECTURE:BOARD_ID[:MENU_ID=OPTION_ID[,MENU2_ID=OPTION_ID ...]]`, with each `MENU_ID=OPTION_ID` being an
 optional key-value pair configuration. Each field accepts letters (`A-Z` or `a-z`), numbers (`0-9`), underscores (`_`),
-dashes(`-`) and dots(`.`). The special character `=` is accepted in the configuration value. For a deeper understanding
-of how FQBN works, you should understand the [Arduino platform specification][0].
+dashes(`-`) and dots(`.`). The special character `=` is accepted in the configuration value. The `VENDOR` and
+`ARCHITECTURE` parts can be empty. For a deeper understanding of how FQBN works, you should understand the [Arduino
+platform specification][0].
 
 ## How to set multiple board options?
 

diff --git a/internal/arduino/cores/fqbn_test.go b/internal/arduino/cores/fqbn_test.go
@@ -30,7 +30,7 @@ func TestFQBN(t *testing.T) {
 	require.Equal(t, a.BoardID, "uno")
 	require.Zero(t, a.Configs.Size())
 
-	// Allow empty plaforms or packages
+	// Allow empty platforms or packages (aka. vendors + architectures)
 	b1, err := ParseFQBN("arduino::uno")
 	require.Equal(t, "arduino::uno", b1.String())
 	require.NoError(t, err)
@@ -65,10 +65,24 @@ func TestFQBN(t *testing.T) {
 	_, err = ParseFQBN("arduino:avr")
 	require.Error(t, err)
 
-	// Sort keys in fbqn config
-	s, err := ParseFQBN("arduino:avr:uno:d=x,b=x,a=x,e=x,c=x")
+	// Keeps the config keys order
+	s1, err := ParseFQBN("arduino:avr:uno:d=x,b=x,a=x,e=x,c=x")
 	require.NoError(t, err)
-	require.Equal(t, "arduino:avr:uno:d=x,b=x,a=x,e=x,c=x", s.String())
+	require.Equal(t, "arduino:avr:uno:d=x,b=x,a=x,e=x,c=x", s1.String())
+	require.Equal(t,
+		"properties.Map{\n  \"d\": \"x\",\n  \"b\": \"x\",\n  \"a\": \"x\",\n  \"e\": \"x\",\n  \"c\": \"x\",\n}",
+		s1.Configs.Dump())
+
+	s2, err := ParseFQBN("arduino:avr:uno:a=x,b=x,c=x,d=x,e=x")
+	require.NoError(t, err)
+	require.Equal(t, "arduino:avr:uno:a=x,b=x,c=x,d=x,e=x", s2.String())
+	require.Equal(t,
+		"properties.Map{\n  \"a\": \"x\",\n  \"b\": \"x\",\n  \"c\": \"x\",\n  \"d\": \"x\",\n  \"e\": \"x\",\n}",
+		s2.Configs.Dump())
+
+	// The config keys order is insignificant when comparing two FQBNs
+	require.True(t, s1.Match(s2))
+	require.NotEqual(t, s1.String(), s2.String())
 
 	// Test configs
 	c, err := ParseFQBN("arduino:avr:uno:cpu=atmega")
@@ -90,6 +104,8 @@ func TestFQBN(t *testing.T) {
 	// Do not allow empty keys or missing values in config
 	_, err = ParseFQBN("arduino:avr:uno:")
 	require.Error(t, err)
+	_, err = ParseFQBN("arduino:avr:uno,")
+	require.Error(t, err)
 	_, err = ParseFQBN("arduino:avr:uno:cpu")
 	require.Error(t, err)
 	_, err = ParseFQBN("arduino:avr:uno:=atmega")