lib.proto

// This file is part of arduino-cli.
//
// Copyright 2020 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 license@arduino.cc.

syntax = "proto3";

package cc.arduino.cli.commands;

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;
    // 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;
}