Skip to content

GitLab

A
arduino-cli
Commit daf08780 authored by per1234's avatar per1234 Committed by umbynos
Browse files
Options

[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: default avatarRoberto Sora <r.sora@arduino.cc>

* Use preferred "platform" term in gRPC interface documentation

The official term is now "platform", rather than the previous ambiguous "core".
Co-authored-by: default avatarRoberto Sora <r.sora@arduino.cc>

* 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: default avatarRoberto Sora <r.sora@arduino.cc>
parent ec44ad12
Show whitespace changes
Inline Side-by-side
Showing with 337 additions and 104 deletions
rpc/commands/commands.pb.go
View file @ daf08780
......@@ -675,12 +675,21 @@ type ArduinoCoreClient interface {
PlatformSearch(ctx context.Context, in *PlatformSearchReq, opts ...grpc.CallOption) (*PlatformSearchResp, error)
// List all installed platforms.
PlatformList(ctx context.Context, in *PlatformListReq, opts ...grpc.CallOption) (*PlatformListResp, error)
// Download the archive file of an Arduino library in the libraries index to
// the staging directory.
LibraryDownload(ctx context.Context, in *LibraryDownloadReq, opts ...grpc.CallOption) (ArduinoCore_LibraryDownloadClient, error)
// Download and install an Arduino library from the libraries index.
LibraryInstall(ctx context.Context, in *LibraryInstallReq, opts ...grpc.CallOption) (ArduinoCore_LibraryInstallClient, error)
// Uninstall an Arduino library.
LibraryUninstall(ctx context.Context, in *LibraryUninstallReq, opts ...grpc.CallOption) (ArduinoCore_LibraryUninstallClient, error)
// Upgrade all installed Arduino libraries to the newest version available.
LibraryUpgradeAll(ctx context.Context, in *LibraryUpgradeAllReq, opts ...grpc.CallOption) (ArduinoCore_LibraryUpgradeAllClient, error)
// List the recursive dependencies of a library, as defined by the `depends`
// field of the library.properties files.
LibraryResolveDependencies(ctx context.Context, in *LibraryResolveDependenciesReq, opts ...grpc.CallOption) (*LibraryResolveDependenciesResp, error)
// Search the Arduino libraries index for libraries.
LibrarySearch(ctx context.Context, in *LibrarySearchReq, opts ...grpc.CallOption) (*LibrarySearchResp, error)
// List the installed libraries.
LibraryList(ctx context.Context, in *LibraryListReq, opts ...grpc.CallOption) (*LibraryListResp, error)
}
......@@ -1324,12 +1333,21 @@ type ArduinoCoreServer interface {
PlatformSearch(context.Context, *PlatformSearchReq) (*PlatformSearchResp, error)
// List all installed platforms.
PlatformList(context.Context, *PlatformListReq) (*PlatformListResp, error)
// Download the archive file of an Arduino library in the libraries index to
// the staging directory.
LibraryDownload(*LibraryDownloadReq, ArduinoCore_LibraryDownloadServer) error
// Download and install an Arduino library from the libraries index.
LibraryInstall(*LibraryInstallReq, ArduinoCore_LibraryInstallServer) error
// Uninstall an Arduino library.
LibraryUninstall(*LibraryUninstallReq, ArduinoCore_LibraryUninstallServer) error
// Upgrade all installed Arduino libraries to the newest version available.
LibraryUpgradeAll(*LibraryUpgradeAllReq, ArduinoCore_LibraryUpgradeAllServer) error
// List the recursive dependencies of a library, as defined by the `depends`
// field of the library.properties files.
LibraryResolveDependencies(context.Context, *LibraryResolveDependenciesReq) (*LibraryResolveDependenciesResp, error)
// Search the Arduino libraries index for libraries.
LibrarySearch(context.Context, *LibrarySearchReq) (*LibrarySearchResp, error)
// List the installed libraries.
LibraryList(context.Context, *LibraryListReq) (*LibraryListResp, error)
}
......
rpc/commands/commands.proto
View file @ daf08780
......@@ -96,18 +96,27 @@ service ArduinoCore {
// List all installed platforms.
rpc PlatformList(PlatformListReq) returns (PlatformListResp);
// Download the archive file of an Arduino library in the libraries index to
// the staging directory.
rpc LibraryDownload(LibraryDownloadReq) returns (stream LibraryDownloadResp);
// Download and install an Arduino library from the libraries index.
rpc LibraryInstall(LibraryInstallReq) returns (stream LibraryInstallResp);
// Uninstall an Arduino library.
rpc LibraryUninstall(LibraryUninstallReq) returns (stream LibraryUninstallResp);
// Upgrade all installed Arduino libraries to the newest version available.
rpc LibraryUpgradeAll(LibraryUpgradeAllReq) returns (stream LibraryUpgradeAllResp);
// List the recursive dependencies of a library, as defined by the `depends`
// field of the library.properties files.
rpc LibraryResolveDependencies(LibraryResolveDependenciesReq) returns (LibraryResolveDependenciesResp);
// Search the Arduino libraries index for libraries.
rpc LibrarySearch(LibrarySearchReq) returns (LibrarySearchResp);
// List the installed libraries.
rpc LibraryList(LibraryListReq) returns (LibraryListResp);
}
......
rpc/commands/lib.pb.go
View file @ daf08780
......@@ -23,7 +23,9 @@ const _ = proto.ProtoPackageIsVersion3 // please upgrade the proto package
type LibrarySearchStatus int32
const (
// No search results were found.
LibrarySearchStatus_failed LibrarySearchStatus = 0
// Search results were found.
LibrarySearchStatus_success LibrarySearchStatus = 1
)
......@@ -48,7 +50,9 @@ func (LibrarySearchStatus) EnumDescriptor() ([]byte, []int) {
type LibraryLayout int32
const (
// Library is in the 1.0 Arduino library format.
LibraryLayout_flat_layout LibraryLayout = 0
// Library is in the 1.5 Arduino library format.
LibraryLayout_recursive_layout LibraryLayout = 1
)
......@@ -73,9 +77,15 @@ func (LibraryLayout) EnumDescriptor() ([]byte, []int) {
type LibraryLocation int32
const (
// In the `libraries` subdirectory of the Arduino IDE installation.
LibraryLocation_ide_builtin LibraryLocation = 0
// In the `libraries` subdirectory of the user directory (sketchbook).
LibraryLocation_user LibraryLocation = 1
// In the `libraries` subdirectory of a platform.
LibraryLocation_platform_builtin LibraryLocation = 2
// When `LibraryLocation` is used in a context where a board is specified,
// this indicates the library is in the `libraries` subdirectory of a
// platform referenced by the board's platform.
LibraryLocation_referenced_platform_builtin LibraryLocation = 3
)
......@@ -102,8 +112,11 @@ func (LibraryLocation) EnumDescriptor() ([]byte, []int) {
}
type LibraryDownloadReq struct {
// Arduino Core Service instance from the `Init` response.
Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
// Name of the library.
Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
// The version of the library to download.
Version string `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -157,6 +170,7 @@ func (m *LibraryDownloadReq) GetVersion() string {
}
type LibraryDownloadResp struct {
// Progress of the library download.
Progress *DownloadProgress `protobuf:"bytes,1,opt,name=progress,proto3" json:"progress,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -196,8 +210,11 @@ func (m *LibraryDownloadResp) GetProgress() *DownloadProgress {
}
type LibraryInstallReq struct {
// Arduino Core Service instance from the `Init` response.
Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
// Name of the library.
Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
// The version of the library to install.
Version string `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -251,7 +268,9 @@ func (m *LibraryInstallReq) GetVersion() string {
}
type LibraryInstallResp struct {
// Progress of the library download.
Progress *DownloadProgress `protobuf:"bytes,1,opt,name=progress,proto3" json:"progress,omitempty"`
// Description of the current stage of the installation.
TaskProgress *TaskProgress `protobuf:"bytes,2,opt,name=task_progress,json=taskProgress,proto3" json:"task_progress,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -298,8 +317,11 @@ func (m *LibraryInstallResp) GetTaskProgress() *TaskProgress {
}
type LibraryUninstallReq struct {
// Arduino Core Service instance from the `Init` response.
Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
// Name of the library.
Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
// The version of the library to uninstall.
Version string `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -353,6 +375,7 @@ func (m *LibraryUninstallReq) GetVersion() string {
}
type LibraryUninstallResp struct {
// Description of the current stage of the uninstallation.
TaskProgress *TaskProgress `protobuf:"bytes,1,opt,name=task_progress,json=taskProgress,proto3" json:"task_progress,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -392,6 +415,7 @@ func (m *LibraryUninstallResp) GetTaskProgress() *TaskProgress {
}
type LibraryUpgradeAllReq struct {
// Arduino Core Service instance from the `Init` response.
Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -431,7 +455,9 @@ func (m *LibraryUpgradeAllReq) GetInstance() *Instance {
}
type LibraryUpgradeAllResp struct {
// Progress of the downloads of files needed for the upgrades.
Progress *DownloadProgress `protobuf:"bytes,1,opt,name=progress,proto3" json:"progress,omitempty"`
// Description of the current stage of the upgrade.
TaskProgress *TaskProgress `protobuf:"bytes,2,opt,name=task_progress,json=taskProgress,proto3" json:"task_progress,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -478,8 +504,12 @@ func (m *LibraryUpgradeAllResp) GetTaskProgress() *TaskProgress {
}
type LibraryResolveDependenciesReq struct {
// Arduino Core Service instance from the `Init` response.
Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
// Name of the library.
Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
// The version of the library to check dependencies of. If no version is
// specified, dependencies of the newest version will be listed.
Version string `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -533,6 +563,7 @@ func (m *LibraryResolveDependenciesReq) GetVersion() string {
}
type LibraryResolveDependenciesResp struct {
// Dependencies of the library.
Dependencies []*LibraryDependencyStatus `protobuf:"bytes,1,rep,name=dependencies,proto3" json:"dependencies,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -572,8 +603,11 @@ func (m *LibraryResolveDependenciesResp) GetDependencies() []*LibraryDependencyS
}
type LibraryDependencyStatus struct {
// The name of the library dependency.
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
// The required version of the library dependency.
VersionRequired string `protobuf:"bytes,2,opt,name=versionRequired,proto3" json:"versionRequired,omitempty"`
// Version of the library dependency currently installed.
VersionInstalled string `protobuf:"bytes,3,opt,name=versionInstalled,proto3" json:"versionInstalled,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -627,7 +661,9 @@ func (m *LibraryDependencyStatus) GetVersionInstalled() string {
}
type LibrarySearchReq struct {
// Arduino Core Service instance from the `Init` response.
Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
// The search query.
Query string `protobuf:"bytes,2,opt,name=query,proto3" json:"query,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -674,7 +710,9 @@ func (m *LibrarySearchReq) GetQuery() string {
}
type LibrarySearchResp struct {
// The results of the search.
Libraries []*SearchedLibrary `protobuf:"bytes,1,rep,name=libraries,proto3" json:"libraries,omitempty"`
// Whether the search yielded results.
Status LibrarySearchStatus `protobuf:"varint,2,opt,name=status,proto3,enum=cc.arduino.cli.commands.LibrarySearchStatus" json:"status,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -721,8 +759,12 @@ func (m *LibrarySearchResp) GetStatus() LibrarySearchStatus {
}
type SearchedLibrary struct {
// Library name.
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
// The index data for the available versions of the library. The key of the
// map is the library version.
Releases map[string]*LibraryRelease `protobuf:"bytes,2,rep,name=releases,proto3" json:"releases,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
// The index data for the latest version of the library.
Latest *LibraryRelease `protobuf:"bytes,3,opt,name=latest,proto3" json:"latest,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -776,18 +818,34 @@ func (m *SearchedLibrary) GetLatest() *LibraryRelease {
}
type LibraryRelease struct {
// Value of the `author` field in library.properties.
Author string `protobuf:"bytes,1,opt,name=author,proto3" json:"author,omitempty"`
// Value of the `version` field in library.properties.
Version string `protobuf:"bytes,2,opt,name=version,proto3" json:"version,omitempty"`
// Value of the `maintainer` field in library.properties.
Maintainer string `protobuf:"bytes,3,opt,name=maintainer,proto3" json:"maintainer,omitempty"`
// Value of the `sentence` field in library.properties.
Sentence string `protobuf:"bytes,4,opt,name=sentence,proto3" json:"sentence,omitempty"`
// Value of the `paragraph` field in library.properties.
Paragraph string `protobuf:"bytes,5,opt,name=paragraph,proto3" json:"paragraph,omitempty"`
// Value of the `url` field in library.properties.
Website string `protobuf:"bytes,6,opt,name=website,proto3" json:"website,omitempty"`
// Value of the `category` field in library.properties.
Category string `protobuf:"bytes,7,opt,name=category,proto3" json:"category,omitempty"`
// Value of the `architectures` field in library.properties.
Architectures []string `protobuf:"bytes,8,rep,name=architectures,proto3" json:"architectures,omitempty"`
// The type categories of the library, as defined in the libraries index.
// Possible values: `Arduino`, `Partner`, `Recommended`, `Contributed`,
// `Retired`.
Types []string `protobuf:"bytes,9,rep,name=types,proto3" json:"types,omitempty"`
// Information about the library archive file.
Resources *DownloadResource `protobuf:"bytes,10,opt,name=resources,proto3" json:"resources,omitempty"`
// Value of the `license` field in library.properties.
License string `protobuf:"bytes,11,opt,name=license,proto3" json:"license,omitempty"`
// Value of the `includes` field in library.properties.
ProvidesIncludes []string `protobuf:"bytes,12,rep,name=provides_includes,json=providesIncludes,proto3" json:"provides_includes,omitempty"`
// The names of the library's dependencies, as defined by the 'depends'
// field of library.properties.
Dependencies []*LibraryDependency `protobuf:"bytes,13,rep,name=dependencies,proto3" json:"dependencies,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -911,7 +969,9 @@ func (m *LibraryRelease) GetDependencies() []*LibraryDependency {
}
type LibraryDependency struct {
// Library name of the dependency.
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
// Version constraint of the dependency.
VersionConstraint string `protobuf:"bytes,2,opt,name=version_constraint,json=versionConstraint,proto3" json:"version_constraint,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -958,10 +1018,16 @@ func (m *LibraryDependency) GetVersionConstraint() string {
}
type DownloadResource struct {
// Download URL of the library archive.
Url string `protobuf:"bytes,1,opt,name=url,proto3" json:"url,omitempty"`
// Filename of the library archive.
Archivefilename string `protobuf:"bytes,2,opt,name=archivefilename,proto3" json:"archivefilename,omitempty"`
// Checksum of the library archive.
Checksum string `protobuf:"bytes,3,opt,name=checksum,proto3" json:"checksum,omitempty"`
// File size of the library archive.
Size int64 `protobuf:"varint,4,opt,name=size,proto3" json:"size,omitempty"`
// The directory under the staging subdirectory of the data directory the
// library archive file will be downloaded to.
Cachepath string `protobuf:"bytes,5,opt,name=cachepath,proto3" json:"cachepath,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -1029,8 +1095,13 @@ func (m *DownloadResource) GetCachepath() string {
}
type LibraryListReq struct {
// Arduino Core Service instance from the `Init` response.
Instance *Instance `protobuf:"bytes,1,opt,name=instance,proto3" json:"instance,omitempty"`
// Whether to include built-in libraries (from platforms and the Arduino
// IDE) in the listing.
All bool `protobuf:"varint,2,opt,name=all,proto3" json:"all,omitempty"`
// Whether to list only libraries for which there is a newer version than
// the installed version available in the libraries index.
Updatable bool `protobuf:"varint,3,opt,name=updatable,proto3" json:"updatable,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -1084,6 +1155,7 @@ func (m *LibraryListReq) GetUpdatable() bool {
}
type LibraryListResp struct {
// List of installed libraries.
InstalledLibrary []*InstalledLibrary `protobuf:"bytes,1,rep,name=installed_library,json=installedLibrary,proto3" json:"installed_library,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -1123,7 +1195,11 @@ func (m *LibraryListResp) GetInstalledLibrary() []*InstalledLibrary {
}
type InstalledLibrary struct {
// Information about the library.
Library *Library `protobuf:"bytes,1,opt,name=library,proto3" json:"library,omitempty"`
// When the `updatable` field of the `LibraryList` request is set to `true`,
// this will contain information on the latest version of the library in the
// libraries index.
Release *LibraryRelease `protobuf:"bytes,2,opt,name=release,proto3" json:"release,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......@@ -1170,28 +1246,55 @@ func (m *InstalledLibrary) GetRelease() *LibraryRelease {
}
type Library struct {
// The library's directory name.
Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
// Value of the `author` field in library.properties.
Author string `protobuf:"bytes,2,opt,name=author,proto3" json:"author,omitempty"`
// Value of the `maintainer` field in library.properties.
Maintainer string `protobuf:"bytes,3,opt,name=maintainer,proto3" json:"maintainer,omitempty"`
// Value of the `sentence` field in library.properties.
Sentence string `protobuf:"bytes,4,opt,name=sentence,proto3" json:"sentence,omitempty"`
// Value of the `paragraph` field in library.properties.
Paragraph string `protobuf:"bytes,5,opt,name=paragraph,proto3" json:"paragraph,omitempty"`
// Value of the `url` field in library.properties.
Website string `protobuf:"bytes,6,opt,name=website,proto3" json:"website,omitempty"`
// Value of the `category` field in library.properties.
Category string `protobuf:"bytes,7,opt,name=category,proto3" json:"category,omitempty"`
// Value of the `architectures` field in library.properties.
Architectures []string `protobuf:"bytes,8,rep,name=architectures,proto3" json:"architectures,omitempty"`
// The type categories of the library. Possible values: `Arduino`,
// `Partner`, `Recommended`, `Contributed`, `Retired`.
Types []string `protobuf:"bytes,9,rep,name=types,proto3" json:"types,omitempty"`
// The path of the library directory.
InstallDir string `protobuf:"bytes,10,opt,name=install_dir,json=installDir,proto3" json:"install_dir,omitempty"`
// The location of the library's source files.
SourceDir string `protobuf:"bytes,11,opt,name=source_dir,json=sourceDir,proto3" json:"source_dir,omitempty"`
// The location of the library's `utility` directory.
UtilityDir string `protobuf:"bytes,12,opt,name=utility_dir,json=utilityDir,proto3" json:"utility_dir,omitempty"`
// If `location` is `platform_builtin` or `referenced_platform_builtin`, the
// identifying string for the platform containing the library
// (e.g., `arduino:avr@1.8.2`).
ContainerPlatform string `protobuf:"bytes,14,opt,name=container_platform,json=containerPlatform,proto3" json:"container_platform,omitempty"`
// Value of the `name` field in library.properties.
RealName string `protobuf:"bytes,16,opt,name=real_name,json=realName,proto3" json:"real_name,omitempty"`
// Value of the `dot_a_linkage` field in library.properties.
DotALinkage bool `protobuf:"varint,17,opt,name=dot_a_linkage,json=dotALinkage,proto3" json:"dot_a_linkage,omitempty"`
// Value of the `precompiled` field in library.properties.
Precompiled bool `protobuf:"varint,18,opt,name=precompiled,proto3" json:"precompiled,omitempty"`
// Value of the `ldflags` field in library.properties.
LdFlags string `protobuf:"bytes,19,opt,name=ld_flags,json=ldFlags,proto3" json:"ld_flags,omitempty"`
// A library.properties file is not present in the library's root directory.
IsLegacy bool `protobuf:"varint,20,opt,name=is_legacy,json=isLegacy,proto3" json:"is_legacy,omitempty"`
// Value of the `version` field in library.properties.
Version string `protobuf:"bytes,21,opt,name=version,proto3" json:"version,omitempty"`
// Value of the `license` field in library.properties.
License string `protobuf:"bytes,22,opt,name=license,proto3" json:"license,omitempty"`
// The data from the library's library.properties file, including unused
// fields.
Properties map[string]string `protobuf:"bytes,23,rep,name=properties,proto3" json:"properties,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
// The location type of the library installation.
Location LibraryLocation `protobuf:"varint,24,opt,name=location,proto3,enum=cc.arduino.cli.commands.LibraryLocation" json:"location,omitempty"`
// The library format type.
Layout LibraryLayout `protobuf:"varint,25,opt,name=layout,proto3,enum=cc.arduino.cli.commands.LibraryLayout" json:"layout,omitempty"`
XXX_NoUnkeyedLiteral struct{} `json:"-"`
XXX_unrecognized []byte `json:"-"`
......
rpc/commands/lib.proto
View file @ daf08780
......@@ -22,160 +22,263 @@ option go_package = "github.com/arduino/arduino-cli/rpc/commands";
import "commands/common.proto";
message LibraryDownloadReq {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
// Name of the library.
string name = 2;
// The version of the library to download.
string version = 3;
}
message LibraryDownloadResp {
// Progress of the library download.
DownloadProgress progress = 1;
}
message LibraryInstallReq {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
// Name of the library.
string name = 2;
// The version of the library to install.
string version = 3;
}
message LibraryInstallResp {
// Progress of the library download.
DownloadProgress progress = 1;
// Description of the current stage of the installation.
TaskProgress task_progress = 2;
}
message LibraryUninstallReq {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
// Name of the library.
string name = 2;
// The version of the library to uninstall.
string version = 3;
}
message LibraryUninstallResp {
// Description of the current stage of the uninstallation.
TaskProgress task_progress = 1;
}
message LibraryUpgradeAllReq {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
}
message LibraryUpgradeAllResp {
// Progress of the downloads of files needed for the upgrades.
DownloadProgress progress = 1;
// Description of the current stage of the upgrade.
TaskProgress task_progress = 2;
}
message LibraryResolveDependenciesReq {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
// Name of the library.
string name = 2;
// The version of the library to check dependencies of. If no version is
// specified, dependencies of the newest version will be listed.
string version = 3;
}
message LibraryResolveDependenciesResp {
// Dependencies of the library.
repeated LibraryDependencyStatus dependencies = 1;
}
message LibraryDependencyStatus {
// The name of the library dependency.
string name = 1;
// The required version of the library dependency.
string versionRequired = 2;
// Version of the library dependency currently installed.
string versionInstalled = 3;
}
message LibrarySearchReq {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
// The search query.
string query = 2;
}
enum LibrarySearchStatus {
// No search results were found.
failed = 0;
// Search results were found.
success = 1;
}
message LibrarySearchResp {
// The results of the search.
repeated SearchedLibrary libraries = 1;
// Whether the search yielded results.
LibrarySearchStatus status = 2;
}
message SearchedLibrary {
// Library name.
string name = 1;
// The index data for the available versions of the library. The key of the
// map is the library version.
map<string, LibraryRelease> releases = 2;
// The index data for the latest version of the library.
LibraryRelease latest = 3;
}
message LibraryRelease {
// Value of the `author` field in library.properties.
string author = 1;
// Value of the `version` field in library.properties.
string version = 2;
// Value of the `maintainer` field in library.properties.
string maintainer = 3;
// Value of the `sentence` field in library.properties.
string sentence = 4;
// Value of the `paragraph` field in library.properties.
string paragraph = 5;
// Value of the `url` field in library.properties.
string website = 6;
// Value of the `category` field in library.properties.
string category = 7;
// Value of the `architectures` field in library.properties.
repeated string architectures = 8;
// The type categories of the library, as defined in the libraries index.
// Possible values: `Arduino`, `Partner`, `Recommended`, `Contributed`,
// `Retired`.
repeated string types = 9;
// Information about the library archive file.
DownloadResource resources = 10;
// Value of the `license` field in library.properties.
string license = 11;
// Value of the `includes` field in library.properties.
repeated string provides_includes = 12;
// The names of the library's dependencies, as defined by the 'depends'
// field of library.properties.
repeated LibraryDependency dependencies = 13;
}
message LibraryDependency {
// Library name of the dependency.
string name = 1;
// Version constraint of the dependency.
string version_constraint = 2;
}
message DownloadResource {
// Download URL of the library archive.
string url = 1;
// Filename of the library archive.
string archivefilename = 2;
// Checksum of the library archive.
string checksum = 3;
// File size of the library archive.
int64 size = 4;
// The directory under the staging subdirectory of the data directory the
// library archive file will be downloaded to.
string cachepath = 5;
}
message LibraryListReq {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
// Whether to include built-in libraries (from platforms and the Arduino
// IDE) in the listing.
bool all = 2;
// Whether to list only libraries for which there is a newer version than
// the installed version available in the libraries index.
bool updatable = 3;
}
message LibraryListResp {
// List of installed libraries.
repeated InstalledLibrary installed_library = 1;
}
message InstalledLibrary {
// Information about the library.
Library library = 1;
// When the `updatable` field of the `LibraryList` request is set to `true`,
// this will contain information on the latest version of the library in the
// libraries index.
LibraryRelease release = 2;
}
message Library {
// The library's directory name.
string name = 1;
// Value of the `author` field in library.properties.
string author = 2;
// Value of the `maintainer` field in library.properties.
string maintainer = 3;
// Value of the `sentence` field in library.properties.
string sentence = 4;
// Value of the `paragraph` field in library.properties.
string paragraph = 5;
// Value of the `url` field in library.properties.
string website = 6;
// Value of the `category` field in library.properties.
string category = 7;
// Value of the `architectures` field in library.properties.
repeated string architectures = 8;
// The type categories of the library. Possible values: `Arduino`,
// `Partner`, `Recommended`, `Contributed`, `Retired`.
repeated string types = 9;
// The path of the library directory.
string install_dir = 10;
// The location of the library's source files.
string source_dir = 11;
// The location of the library's `utility` directory.
string utility_dir = 12;
// If `location` is `platform_builtin` or `referenced_platform_builtin`, the
// identifying string for the platform containing the library
// (e.g., `arduino:avr@1.8.2`).
string container_platform = 14;
// Value of the `name` field in library.properties.
string real_name = 16;
// Value of the `dot_a_linkage` field in library.properties.
bool dot_a_linkage = 17;
// Value of the `precompiled` field in library.properties.
bool precompiled = 18;
// Value of the `ldflags` field in library.properties.
string ld_flags = 19;
// A library.properties file is not present in the library's root directory.
bool is_legacy = 20;
// Value of the `version` field in library.properties.
string version = 21;
// Value of the `license` field in library.properties.
string license = 22;
// The data from the library's library.properties file, including unused
// fields.
map<string, string> properties = 23;
// The location type of the library installation.
LibraryLocation location = 24;
// The library format type.
LibraryLayout layout = 25;
}
enum LibraryLayout {
// Library is in the 1.0 Arduino library format.
flat_layout = 0;
// Library is in the 1.5 Arduino library format.
recursive_layout = 1;
}
enum LibraryLocation {
// In the `libraries` subdirectory of the Arduino IDE installation.
ide_builtin = 0;
user = 1; // (sketchbook)
// In the `libraries` subdirectory of the user directory (sketchbook).
user = 1;
// In the `libraries` subdirectory of a platform.
platform_builtin = 2;
// When `LibraryLocation` is used in a context where a board is specified,
// this indicates the library is in the `libraries` subdirectory of a
// platform referenced by the board's platform.
referenced_platform_builtin = 3;
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment