Added docs

docs/UPGRADING.md

@@ -4,6 +4,169 @@ Here you can find a list of migration guides to handle breaking changes between
 
 ## 0.36.0
 
+### gRPC Setting API important changes
+
+The Settings API has been heavily refactored. Here a quick recap of the new methods:
+
+- `SettingsGetValue` returns the value of a setting given the key. The returned value is a string encoded in JSON, or
+ YAML
+
+ ```proto
+ message SettingsGetValueRequest {
+ // The key to get
+ string key = 1;
+ // The format of the encoded_value (default is
+ // "json", allowed values are "json" and "yaml)
+ string value_format = 2;
+ }
+
+ message SettingsGetValueResponse {
+ // The value of the key (encoded)
+ string encoded_value = 1;
+ }
+ ```
+
+- `SettingsSetValue` change the value of a setting. The value may be specified in JSON, YAML, or as a command-line
+ argument. If `encoded_value` is an empty string the setting is deleted.
+
+ ```proto
+ message SettingsSetValueRequest {
+ // The key to change
+ string key = 1;
+ // The new value (encoded), no objects,
+ // only scalar, or array of scalars are
+ // allowed.
+ string encoded_value = 2;
+ // The format of the encoded_value (default is
+ // "json", allowed values are "json", "yaml",
+ // and "cli")
+ string value_format = 3;
+ }
+ ```
+
+- `SettingsEnumerate` returns all the available keys and their type (`string`, `int`, `[]string`...)
+- `ConfigurationOpen` replaces the current configuration with the one passed as argument. Differently from
+ `SettingsSetValue`, this call replaces the whole configuration.
+- `ConfigurationSave` outputs the current configuration in the specified format. The configuration is not saved in a
+ file, this call returns just the content, it's a duty of the caller to store the content in a file.
+- `ConfigurationGet` return the current configuration in a structured gRPC message `Configuration`.
+
+The previous gRPC Setting rpc call may be replaced as follows:
+
+- The old `SettingsMerge` rpc call can now be done trough `SettingsSetValue`.
+- The old `SettingsDelete` rpc call can now be done trough `SettingsSetValue` passing the `key` to delete with an empty
+ `value`.
+- The old `SettingsGetAll` rpc call has been replaced by `ConfigurationGet` that returns a structured message
+ `Configuration` with all the settings populated.
+- The old `SettingsWrite` rpc call has been removed. It is partially replaced by `ConfigurationSave` but the actual file
+ save must be performed by the caller.
+
+### golang: importing `arduino-cli` as a library now requires the creation of a gRPC service.
+
+Previously the methods implementing the Arduino business logic were available in the global namespace
+`github.com/arduino/arduino-cli/commands/*` and could be called directly.
+
+The above is no more true. All the global `commands.*` functions have been converted to methods of the
+`arduinoCoreServerImpl` struct that implements the gRPC `ArduinoCoreServer` interface. The configuration is now part of
+the server internal state. Developers may create a "daemon-less" server by calling the `commands.NewArduinoCoreServer()`
+function and can use the returned object to call all the needed gRPC functions.
+
+The methods of the `ArduinoCoreServer` are generated through the gRPC protobuf definitions, some of those methods are
+gRPC "streaming" methods and requires a streaming object to be passed as argument, we provided helper methods to create
+these objects.
+
+For example if previously we could call `commands.Init` like this:
+
+```go
+// old Init signature
+func Init(req *rpc.InitRequest, responseCallback func(r *rpc.InitResponse)) error { ... }
+
+// ...
+
+// Initialize instance
+if err := commands.Init(&rpc.InitRequest{Instance: req.GetInstance()}, respCB); err != nil {
+ return err
+}
+```
+
+now the `responseCallback` must be wrapped into an `rpc.ArduinoCoreService_InitServer`, and we provided a method exactly
+for that:
+
+```go
+// new Init method
+func (s *arduinoCoreServerImpl) Init(req *rpc.InitRequest, stream rpc.ArduinoCoreService_InitServer) error { ... }
+
+/// ...
+
+// Initialize instance
+initStream := InitStreamResponseToCallbackFunction(ctx, respCB)
+if err := srv.Init(&rpc.InitRequest{Instance: req.GetInstance()}, initStream); err != nil {
+ return err
+}
+```
+
+Each gRPC method has an helper method to obtain the corresponding `ArduinoCoreService_*Server` parameter. Here a simple,
+but complete, example:
+
+```go
+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())
+ }
+}
+```
+
 ### The gRPC `cc.arduino.cli.commands.v1.CompileRequest.export_binaries` changed type.
 
 Previously the field `export_binaries` was a `google.protobuf.BoolValue`. We used this type because it expresses this