Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit daf0878

Browse files
per1234Roberto Sora
authored andcommittedJun 25, 2020
[skip changelog] Add documentation for library components of the gRPC interface (#692)
* [skip changelog] Add documentation for library components of the gRPC interface Comments added to the .proto files are included in the generated gRPC interface documentation. * Correct documentation re: relative vs absolute paths provided by Library message fields Co-authored-by: Roberto Sora <[email protected]> * Use preferred "platform" term in gRPC interface documentation The official term is now "platform", rather than the previous ambiguous "core". Co-authored-by: Roberto Sora <[email protected]> * Fix formatting of gRPC interface documentation * Fix incorrect documentation for task_progress field of LibraryUninstall response * Document that library version is the key of the releases map * Update gRPC interface code comments Co-authored-by: Roberto Sora <[email protected]>
1 parent ec44ad1 commit daf0878

File tree

4 files changed

+337
-104
lines changed

4 files changed

+337
-104
lines changed
 

‎rpc/commands/commands.pb.go

Lines changed: 18 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎rpc/commands/commands.proto

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,18 +96,27 @@ service ArduinoCore {
9696
// List all installed platforms.
9797
rpc PlatformList(PlatformListReq) returns (PlatformListResp);
9898

99+
// Download the archive file of an Arduino library in the libraries index to
100+
// the staging directory.
99101
rpc LibraryDownload(LibraryDownloadReq) returns (stream LibraryDownloadResp);
100102

103+
// Download and install an Arduino library from the libraries index.
101104
rpc LibraryInstall(LibraryInstallReq) returns (stream LibraryInstallResp);
102105

106+
// Uninstall an Arduino library.
103107
rpc LibraryUninstall(LibraryUninstallReq) returns (stream LibraryUninstallResp);
104108

109+
// Upgrade all installed Arduino libraries to the newest version available.
105110
rpc LibraryUpgradeAll(LibraryUpgradeAllReq) returns (stream LibraryUpgradeAllResp);
106111

112+
// List the recursive dependencies of a library, as defined by the `depends`
113+
// field of the library.properties files.
107114
rpc LibraryResolveDependencies(LibraryResolveDependenciesReq) returns (LibraryResolveDependenciesResp);
108115

116+
// Search the Arduino libraries index for libraries.
109117
rpc LibrarySearch(LibrarySearchReq) returns (LibrarySearchResp);
110118

119+
// List the installed libraries.
111120
rpc LibraryList(LibraryListReq) returns (LibraryListResp);
112121
}
113122

‎rpc/commands/lib.pb.go

Lines changed: 206 additions & 103 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎rpc/commands/lib.proto

Lines changed: 104 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,160 +22,263 @@ option go_package = "github.com/arduino/arduino-cli/rpc/commands";
2222
import "commands/common.proto";
2323

2424
message LibraryDownloadReq {
25+
// Arduino Core Service instance from the `Init` response.
2526
Instance instance = 1;
27+
// Name of the library.
2628
string name = 2;
29+
// The version of the library to download.
2730
string version = 3;
2831
}
2932

3033
message LibraryDownloadResp {
34+
// Progress of the library download.
3135
DownloadProgress progress = 1;
3236
}
3337

3438
message LibraryInstallReq {
39+
// Arduino Core Service instance from the `Init` response.
3540
Instance instance = 1;
41+
// Name of the library.
3642
string name = 2;
43+
// The version of the library to install.
3744
string version = 3;
3845
}
3946

4047
message LibraryInstallResp {
48+
// Progress of the library download.
4149
DownloadProgress progress = 1;
50+
// Description of the current stage of the installation.
4251
TaskProgress task_progress = 2;
4352
}
4453

4554
message LibraryUninstallReq {
55+
// Arduino Core Service instance from the `Init` response.
4656
Instance instance = 1;
57+
// Name of the library.
4758
string name = 2;
59+
// The version of the library to uninstall.
4860
string version = 3;
4961
}
5062

5163
message LibraryUninstallResp {
64+
// Description of the current stage of the uninstallation.
5265
TaskProgress task_progress = 1;
5366
}
5467

5568
message LibraryUpgradeAllReq {
69+
// Arduino Core Service instance from the `Init` response.
5670
Instance instance = 1;
5771
}
5872

5973
message LibraryUpgradeAllResp {
74+
// Progress of the downloads of files needed for the upgrades.
6075
DownloadProgress progress = 1;
76+
// Description of the current stage of the upgrade.
6177
TaskProgress task_progress = 2;
6278
}
6379

6480
message LibraryResolveDependenciesReq {
81+
// Arduino Core Service instance from the `Init` response.
6582
Instance instance = 1;
83+
// Name of the library.
6684
string name = 2;
85+
// The version of the library to check dependencies of. If no version is
86+
// specified, dependencies of the newest version will be listed.
6787
string version = 3;
6888
}
6989

7090
message LibraryResolveDependenciesResp {
91+
// Dependencies of the library.
7192
repeated LibraryDependencyStatus dependencies = 1;
7293
}
7394

7495
message LibraryDependencyStatus {
96+
// The name of the library dependency.
7597
string name = 1;
98+
// The required version of the library dependency.
7699
string versionRequired = 2;
100+
// Version of the library dependency currently installed.
77101
string versionInstalled = 3;
78102
}
79103

80104
message LibrarySearchReq {
105+
// Arduino Core Service instance from the `Init` response.
81106
Instance instance = 1;
107+
// The search query.
82108
string query = 2;
83109
}
84110

85111
enum LibrarySearchStatus {
112+
// No search results were found.
86113
failed = 0;
114+
// Search results were found.
87115
success = 1;
88116
}
89117

90118
message LibrarySearchResp {
119+
// The results of the search.
91120
repeated SearchedLibrary libraries = 1;
121+
// Whether the search yielded results.
92122
LibrarySearchStatus status = 2;
93123
}
94124

95125
message SearchedLibrary {
126+
// Library name.
96127
string name = 1;
128+
// The index data for the available versions of the library. The key of the
129+
// map is the library version.
97130
map<string, LibraryRelease> releases = 2;
131+
// The index data for the latest version of the library.
98132
LibraryRelease latest = 3;
99133
}
100134

101135
message LibraryRelease {
136+
// Value of the `author` field in library.properties.
102137
string author = 1;
138+
// Value of the `version` field in library.properties.
103139
string version = 2;
140+
// Value of the `maintainer` field in library.properties.
104141
string maintainer = 3;
142+
// Value of the `sentence` field in library.properties.
105143
string sentence = 4;
144+
// Value of the `paragraph` field in library.properties.
106145
string paragraph = 5;
146+
// Value of the `url` field in library.properties.
107147
string website = 6;
148+
// Value of the `category` field in library.properties.
108149
string category = 7;
150+
// Value of the `architectures` field in library.properties.
109151
repeated string architectures = 8;
152+
// The type categories of the library, as defined in the libraries index.
153+
// Possible values: `Arduino`, `Partner`, `Recommended`, `Contributed`,
154+
// `Retired`.
110155
repeated string types = 9;
156+
// Information about the library archive file.
111157
DownloadResource resources = 10;
158+
// Value of the `license` field in library.properties.
112159
string license = 11;
160+
// Value of the `includes` field in library.properties.
113161
repeated string provides_includes = 12;
162+
// The names of the library's dependencies, as defined by the 'depends'
163+
// field of library.properties.
114164
repeated LibraryDependency dependencies = 13;
115165
}
116166

117167
message LibraryDependency {
168+
// Library name of the dependency.
118169
string name = 1;
170+
// Version constraint of the dependency.
119171
string version_constraint = 2;
120172
}
121173

122174
message DownloadResource {
175+
// Download URL of the library archive.
123176
string url = 1;
177+
// Filename of the library archive.
124178
string archivefilename = 2;
179+
// Checksum of the library archive.
125180
string checksum = 3;
181+
// File size of the library archive.
126182
int64 size = 4;
183+
// The directory under the staging subdirectory of the data directory the
184+
// library archive file will be downloaded to.
127185
string cachepath = 5;
128186
}
129187

130188
message LibraryListReq {
189+
// Arduino Core Service instance from the `Init` response.
131190
Instance instance = 1;
191+
// Whether to include built-in libraries (from platforms and the Arduino
192+
// IDE) in the listing.
132193
bool all = 2;
194+
// Whether to list only libraries for which there is a newer version than
195+
// the installed version available in the libraries index.
133196
bool updatable = 3;
134197
}
135198

136199
message LibraryListResp {
200+
// List of installed libraries.
137201
repeated InstalledLibrary installed_library = 1;
138202
}
139203

140204
message InstalledLibrary {
205+
// Information about the library.
141206
Library library = 1;
207+
// When the `updatable` field of the `LibraryList` request is set to `true`,
208+
// this will contain information on the latest version of the library in the
209+
// libraries index.
142210
LibraryRelease release = 2;
143211
}
144212

145213
message Library {
214+
// The library's directory name.
146215
string name = 1;
216+
// Value of the `author` field in library.properties.
147217
string author = 2;
218+
// Value of the `maintainer` field in library.properties.
148219
string maintainer = 3;
220+
// Value of the `sentence` field in library.properties.
149221
string sentence = 4;
222+
// Value of the `paragraph` field in library.properties.
150223
string paragraph = 5;
224+
// Value of the `url` field in library.properties.
151225
string website = 6;
226+
// Value of the `category` field in library.properties.
152227
string category = 7;
228+
// Value of the `architectures` field in library.properties.
153229
repeated string architectures = 8;
230+
// The type categories of the library. Possible values: `Arduino`,
231+
// `Partner`, `Recommended`, `Contributed`, `Retired`.
154232
repeated string types = 9;
233+
// The path of the library directory.
155234
string install_dir = 10;
235+
// The location of the library's source files.
156236
string source_dir = 11;
237+
// The location of the library's `utility` directory.
157238
string utility_dir = 12;
239+
// If `location` is `platform_builtin` or `referenced_platform_builtin`, the
240+
// identifying string for the platform containing the library
241+
// (e.g., `arduino:avr@1.8.2`).
158242
string container_platform = 14;
243+
// Value of the `name` field in library.properties.
159244
string real_name = 16;
245+
// Value of the `dot_a_linkage` field in library.properties.
160246
bool dot_a_linkage = 17;
247+
// Value of the `precompiled` field in library.properties.
161248
bool precompiled = 18;
249+
// Value of the `ldflags` field in library.properties.
162250
string ld_flags = 19;
251+
// A library.properties file is not present in the library's root directory.
163252
bool is_legacy = 20;
253+
// Value of the `version` field in library.properties.
164254
string version = 21;
255+
// Value of the `license` field in library.properties.
165256
string license = 22;
257+
// The data from the library's library.properties file, including unused
258+
// fields.
166259
map<string, string> properties = 23;
260+
// The location type of the library installation.
167261
LibraryLocation location = 24;
262+
// The library format type.
168263
LibraryLayout layout = 25;
169264
}
170265

171266
enum LibraryLayout {
267+
// Library is in the 1.0 Arduino library format.
172268
flat_layout = 0;
269+
// Library is in the 1.5 Arduino library format.
173270
recursive_layout = 1;
174271
}
175272

176273
enum LibraryLocation {
274+
// In the `libraries` subdirectory of the Arduino IDE installation.
177275
ide_builtin = 0;
178-
user = 1; // (sketchbook)
276+
// In the `libraries` subdirectory of the user directory (sketchbook).
277+
user = 1;
278+
// In the `libraries` subdirectory of a platform.
179279
platform_builtin = 2;
280+
// When `LibraryLocation` is used in a context where a board is specified,
281+
// this indicates the library is in the `libraries` subdirectory of a
282+
// platform referenced by the board's platform.
180283
referenced_platform_builtin = 3;
181284
}

0 commit comments

Comments
 (0)
Please sign in to comment.