Added example of integration by embedding golang

Author: cmaglie

Diff for: docs/img/CLI_Go_library_interface_screenshot.png

@@ -211,14 +211,86 @@ For more information on Arduino CLI's gRPC interface, see the [gRPC interface re
 
 Arduino CLI is written in [Golang] and the code is organized in a way that makes it easy to use it as a library by
 including the modules you need in another Golang application at compile time. Both the first and second pillars rely on
-a common Golang API, a set of functions that abstract all the functionalities offered by the Arduino CLI, so that when
-we provide a fix or a new feature, they are automatically available to both the command line and gRPC interfaces. The
-source modules implementing this API are implemented through the `commands` package, and it can be imported in other
-Golang programs to embed a full-fledged Arduino CLI. For example, this is how some backend services powering [Arduino
-Cloud] can compile sketches and manage libraries. Just to give you a taste of what it means to embed the Arduino CLI,
-here is how to search for a core using the API:
+a common Golang API, based on the gRPC protobuf definitions: a set of functions that abstract all the functionalities
+offered by the Arduino CLI, so that when we provide a fix or a new feature, they are automatically available to both the
+command line and gRPC interfaces. The source modules implementing this API are implemented through the `commands`
+package, and it can be imported in other Golang programs to embed a full-fledged Arduino CLI. For example, this is how
+some backend services powering [Arduino Cloud] can compile sketches and manage libraries. Just to give you a taste of
+what it means to embed the Arduino CLI, here is how to search for a core using the API:
 
-![Go library interface screenshot][]
+```go
+// This file is part of arduino-cli.
+//
+// Copyright 2024 ARDUINO SA (http://www.arduino.cc/)
+//
+// This software is released under the GNU General Public License version 3,
+// which covers the main part of arduino-cli.
+// The terms of this license can be found at:
+// https://www.gnu.org/licenses/gpl-3.0.en.html
+//
+// You can be released from the requirements of the above licenses by purchasing
+// a commercial license. Buying such a license is mandatory if you want to
+// modify or otherwise use the software for commercial activities involving the
+// Arduino software without disclosing the source code of your own applications.
+// To purchase a commercial license, send an email to [email protected].
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"log"
+
+	"github.com/arduino/arduino-cli/commands"
+	rpc "github.com/arduino/arduino-cli/rpc/cc/arduino/cli/commands/v1"
+	"github.com/sirupsen/logrus"
+)
+
+func main() {
+	// Create a new ArduinoCoreServer
+	srv := commands.NewArduinoCoreServer()
+
+	// Disable logging
+	logrus.SetOutput(io.Discard)
+
+	// Create a new instance in the server
+	ctx := context.Background()
+	resp, err := srv.Create(ctx, &rpc.CreateRequest{})
+	if err != nil {
+		log.Fatal("Error creating instance:", err)
+	}
+	instance := resp.GetInstance()
+
+	// Defer the destruction of the instance
+	defer func() {
+		if _, err := srv.Destroy(ctx, &rpc.DestroyRequest{Instance: instance}); err != nil {
+			log.Fatal("Error destroying instance:", err)
+		}
+		fmt.Println("Instance successfully destroyed")
+	}()
+
+	// Initialize the instance
+	initStream := commands.InitStreamResponseToCallbackFunction(ctx, func(r *rpc.InitResponse) error {
+		fmt.Println("INIT> ", r)
+		return nil
+	})
+	if err := srv.Init(&rpc.InitRequest{Instance: instance}, initStream); err != nil {
+		log.Fatal("Error during initialization:", err)
+	}
+
+	// Search for platforms and output the result
+	searchResp, err := srv.PlatformSearch(ctx, &rpc.PlatformSearchRequest{Instance: instance})
+	if err != nil {
+		log.Fatal("Error searching for platforms:", err)
+	}
+	for _, platformSummary := range searchResp.GetSearchOutput() {
+		installed := platformSummary.GetInstalledRelease()
+		meta := platformSummary.GetMetadata()
+		fmt.Printf("%30s %8s %s\n", meta.GetId(), installed.GetVersion(), installed.GetName())
+	}
+}
+```
 
 Embedding the Arduino CLI is limited to Golang applications and requires a deep knowledge of its internals. For the
 average use case, the gRPC interface might be a better alternative. Nevertheless, this remains a valid option that we
@@ -250,4 +322,3 @@ tracker] if you’ve got a use case that doesn’t fit one of the three pillars.
 [commands package]: https://github.com/arduino/arduino-cli/tree/master/commands
 [issue tracker]: https://github.com/arduino/arduino-cli/issues
 [contextual help screenshot]: img/CLI_contextual_help_screenshot.png
-[go library interface screenshot]: img/CLI_Go_library_interface_screenshot.png

Diff for: docs/integration-options.md

@@ -0,0 +1,71 @@
+// This file is part of arduino-cli.
+//
+// Copyright 2024 ARDUINO SA (http://www.arduino.cc/)
+//
+// This software is released under the GNU General Public License version 3,
+// which covers the main part of arduino-cli.
+// The terms of this license can be found at:
+// https://www.gnu.org/licenses/gpl-3.0.en.html
+//
+// You can be released from the requirements of the above licenses by purchasing
+// a commercial license. Buying such a license is mandatory if you want to
+// modify or otherwise use the software for commercial activities involving the
+// Arduino software without disclosing the source code of your own applications.
+// To purchase a commercial license, send an email to [email protected].
+
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"log"
+
+	"github.com/arduino/arduino-cli/commands"
+	rpc "github.com/arduino/arduino-cli/rpc/cc/arduino/cli/commands/v1"
+	"github.com/sirupsen/logrus"
+)
+
+func main() {
+	// Create a new ArduinoCoreServer
+	srv := commands.NewArduinoCoreServer()
+
+	// Disable logging
+	logrus.SetOutput(io.Discard)
+
+	// Create a new instance in the server
+	ctx := context.Background()
+	resp, err := srv.Create(ctx, &rpc.CreateRequest{})
+	if err != nil {
+		log.Fatal("Error creating instance:", err)
+	}
+	instance := resp.GetInstance()
+
+	// Defer the destruction of the instance
+	defer func() {
+		if _, err := srv.Destroy(ctx, &rpc.DestroyRequest{Instance: instance}); err != nil {
+			log.Fatal("Error destroying instance:", err)
+		}
+		fmt.Println("Instance successfully destroyed")
+	}()
+
+	// Initialize the instance
+	initStream := commands.InitStreamResponseToCallbackFunction(ctx, func(r *rpc.InitResponse) error {
+		fmt.Println("INIT> ", r)
+		return nil
+	})
+	if err := srv.Init(&rpc.InitRequest{Instance: instance}, initStream); err != nil {
+		log.Fatal("Error during initialization:", err)
+	}
+
+	// Search for platforms and output the result
+	searchResp, err := srv.PlatformSearch(ctx, &rpc.PlatformSearchRequest{Instance: instance})
+	if err != nil {
+		log.Fatal("Error searching for platforms:", err)
+	}
+	for _, platformSummary := range searchResp.GetSearchOutput() {
+		installed := platformSummary.GetInstalledRelease()
+		meta := platformSummary.GetMetadata()
+		fmt.Printf("%30s %8s %s\n", meta.GetId(), installed.GetVersion(), installed.GetName())
+	}
+}