@@ -4,6 +4,102 @@ Here you can find a list of migration guides to handle breaking changes between
4
4
5
5
## Unreleased
6
6
7
+ ### Change of behaviour of gRPC ` Init ` function
8
+
9
+ Previously the ` Init ` function was used to both create a new ` CoreInstance ` and initialize it, so that the internal
10
+ package and library managers were already populated with all the information available from ` *_index.json ` files,
11
+ installed platforms and libraries and so on.
12
+
13
+ Now the initialization phase is split into two, first the client must create a new ` CoreInstance ` with the ` Create `
14
+ function, that does mainly two things:
15
+
16
+ - create all folders necessary to correctly run the CLI if not already existing
17
+ - create and return a new ` CoreInstance `
18
+
19
+ The ` Create ` function will only fail if folders creation is not successful.
20
+
21
+ The returned instance is relatively unusable since no library and no platform is loaded, some functions that don't need
22
+ that information can still be called though.
23
+
24
+ The ` Init ` function has been greatly overhauled and it doesn't fail completely if one or more platforms or libraries
25
+ fail to load now.
26
+
27
+ Also the option ` library_manager_only ` has been removed, the package manager is always initialized and platforms are
28
+ loaded.
29
+
30
+ The ` Init ` was already a server-side streaming function but it would always return one and only one response, this has
31
+ been modified so that each response is either an error or a notification on the initialization process so that it works
32
+ more like an actual stream of information.
33
+
34
+ Previously a client would call the function like so:
35
+
36
+ ``` typescript
37
+ const initReq = new InitRequest ()
38
+ initReq .setLibraryManagerOnly (false )
39
+ const initResp = await new Promise <InitResponse >((resolve , reject ) => {
40
+ let resp: InitResponse | undefined = undefined
41
+ const stream = client .init (initReq )
42
+ stream .on (" data" , (data : InitResponse ) => (resp = data ))
43
+ stream .on (" end" , () => resolve (resp ! ))
44
+ stream .on (" error" , (err ) => reject (err ))
45
+ })
46
+
47
+ const instance = initResp .getInstance ()
48
+ if (! instance ) {
49
+ throw new Error (" Could not retrieve instance from the initialize response." )
50
+ }
51
+ ```
52
+
53
+ Now something similar should be done.
54
+
55
+ ``` typescript
56
+ const createReq = new CreateRequest ()
57
+ const instance = client .create (createReq )
58
+
59
+ if (! instance ) {
60
+ throw new Error (" Could not retrieve instance from the initialize response." )
61
+ }
62
+
63
+ const initReq = new InitRequest ()
64
+ initReq .setInstance (instance )
65
+ const initResp = client .init (initReq )
66
+ initResp .on (" data" , (o : InitResponse ) => {
67
+ const downloadProgress = o .getDownloadProgress ()
68
+ if (downloadProgress ) {
69
+ // Handle download progress
70
+ }
71
+ const taskProgress = o .getTaskProgress ()
72
+ if (taskProgress ) {
73
+ // Handle task progress
74
+ }
75
+ const err = o .getError ()
76
+ if (err ) {
77
+ // Handle error
78
+ }
79
+ })
80
+
81
+ await new Promise <void >((resolve , reject ) => {
82
+ initResp .on (" error" , (err ) => reject (err ))
83
+ initResp .on (" end" , resolve )
84
+ })
85
+ ```
86
+
87
+ Previously if even one platform or library failed to load everything else would fail too, that doesn't happen anymore.
88
+ Now it's easier for both the CLI and the gRPC clients to handle gracefully platforms or libraries updates that might
89
+ break the initialization step and make everything unusable.
90
+
91
+ ### Removal of gRPC ` Rescan ` function
92
+
93
+ The ` Rescan ` function has been removed, in its place the ` Init ` function must be used.
94
+
95
+ ### Change of behaviour of gRPC ` UpdateIndex ` and ` UpdateLibrariesIndex ` functions
96
+
97
+ Previously both ` UpdateIndex ` and ` UpdateLibrariesIndex ` functions implicitly called ` Rescan ` so that the internal
98
+ ` CoreInstance ` was updated with the eventual new information obtained in the update.
99
+
100
+ This behaviour is now removed and the internal ` CoreInstance ` must be explicitly updated by the gRPC client using the
101
+ ` Init ` function.
102
+
7
103
### Removed rarely used golang API
8
104
9
105
The following function from the ` github.com/arduino/arduino-cli/arduino/libraries ` module is no longer available:
0 commit comments