Skip to content

Commit acae985

Browse files
dankeboy36dankeboy36
committed
feat(api)!: exposed the build_properties API
 - keep the state in the memory, - derived API types from the CLI's API, - replaced `buildPath` with `compileSummary`, and - updated the readme. Signed-off-by: dankeboy36 <[email protected]>
1 parent 50ab124 commit acae985

11 files changed

+408
-133
lines changed

‎README.md

+28-26
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,22 @@
11
# vscode-arduino-api
22

3-
Arduino API for [Arduino IDE](https://github.com/arduino/arduino-ide) external tools developers using VS Code extensions.
3+
Arduino API for [Arduino IDE 2.x](https://github.com/arduino/arduino-ide) external tools developers using VS Code extensions.
44

5-
This VS Code extensions does not provide any functionality, but a bridge between the Arduino IDE and external tools implemented as a VS Code extension. Please reference [arduino/arduino-ide#58](https://github.com/arduino/arduino-ide/issues/58) why this VSIX has been created. This extension has nothing to do with the [Visual Studio Code extension for Arduino](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.vscode-arduino). This extension does not work in VS Code.
5+
This VS Code extension does not provide any functionality but a bridge between the Arduino IDE 2.x and external tools implemented as a VS Code extension. Please reference [arduino/arduino-ide#58](https://github.com/arduino/arduino-ide/issues/58) to explain why this VSIX has been created. This extension has nothing to do with the [Visual Studio Code extension for Arduino](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.vscode-arduino). This extension does not work in VS Code.
66

7-
## Features
7+
## API
88

99
Exposes the Arduino context for VS Code extensions:
1010

11-
| Name | Description | Type | Note |
12-
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------- |
13-
| `sketchPath` | Absolute filesystem path of the sketch folder. | `string` |
14-
| `buildPath` | The absolute filesystem path to the build folder of the sketch. When the `sketchPath` is available but the sketch has not been verified (compiled), the `buildPath` can be `undefined`. | `string` | ⚠️ `@alpha` |
15-
| `fqbn` | The Fully Qualified Board Name (FQBN) of the currently selected board in the Arduino IDE. | `string` |
16-
| `boardDetails` | Lightweight representation of the board's detail. This information is [provided by the Arduino CLI](https://arduino.github.io/arduino-cli/latest/rpc/commands/#cc.arduino.cli.commands.v1.BoardDetailsResponse) for the currently selected board. It can be `undefined` if the `fqbn` is defined but the platform is not installed. | `BoardDetails` | ⚠️ `@alpha` |
17-
| `port` | The currently selected port in the Arduino IDE. | [`Port`](https://arduino.github.io/arduino-cli/latest/rpc/commands/#port) |
18-
| `userDirPath` | Filesystem path to the [`directories.user`](https://arduino.github.io/arduino-cli/latest/configuration/#configuration-keys) location. This is the sketchbook path. | `string` |
19-
| `dataDirPath` | Filesystem path to the [`directories.data`](https://arduino.github.io/arduino-cli/latest/configuration/#configuration-keys) location | `string` |
11+
| Name | Description | Type | Note |
12+
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ----------- |
13+
| `sketchPath` | Absolute filesystem path of the sketch folder. | `string` |
14+
| `compileSummary` | The summary of the latest sketch compilation. When the `sketchPath` is available, but the sketch has not been verified (compiled), the `buildPath` can be `undefined`. | `CompileSummary` | ⚠️ `@alpha` |
15+
| `fqbn` | The Fully Qualified Board Name (FQBN) of the currently selected board in the Arduino IDE. | `string` |
16+
| `boardDetails` | Lightweight representation of the board's detail. This information is [provided by the Arduino CLI](https://arduino.github.io/arduino-cli/latest/rpc/commands/#cc.arduino.cli.commands.v1.BoardDetailsResponse) for the currently selected board. It can be `undefined` if the `fqbn` is defined, but the platform is not installed. | `BoardDetails` | ⚠️ `@alpha` |
17+
| `port` | The currently selected port in the Arduino IDE. | [`Port`](https://arduino.github.io/arduino-cli/latest/rpc/commands/#port) |
18+
| `userDirPath` | Filesystem path to the [`directories.user`](https://arduino.github.io/arduino-cli/latest/configuration/#configuration-keys) location. This is the sketchbook path. | `string` | ⚠️ `@alpha` |
19+
| `dataDirPath` | Filesystem path to the [`directories.data`](https://arduino.github.io/arduino-cli/latest/configuration/#configuration-keys) location | `string` | ⚠️ `@alpha` |
2020

2121
## How to Use
2222

@@ -25,19 +25,11 @@ If you're developing an external tool for the Arduino IDE, this extension will b
2525
If you want to use the Arduino APIs, you have to do the followings:
2626

2727
1. Install the [Arduino API types](https://www.npmjs.com/package/vscode-arduino-api) from `npm`:
28+
2829
```shell
29-
npm i -S vscode-arduino-api
30-
```
31-
1. Add this VSIX as an `extensionDependencies` in your `package.json`:
32-
33-
```jsonc
34-
{
35-
"extensionDependencies": [
36-
"dankeboy36.vscode-arduino-api",
37-
// other dependencies
38-
],
39-
}
30+
npm install vscode-arduino-api --save
4031
```
32+
4133
1. Consume the `ArduinoContext` extension API in your VS Code extension:
4234

4335
```ts
@@ -60,10 +52,20 @@ If you want to use the Arduino APIs, you have to do the followings:
6052
6153
---
6254
55+
- Q: What does `@alpha` mean?
56+
- A: This API is in an alpha state and might change. The initial idea of this project was to establish a bare minimum layer and help Arduino IDE 2.x tool developers start with something. I make breaking changes only when necessary, keep it backward compatible, or provide a migration guide in the future. Please prepare for breaking changes.
57+
58+
---
59+
6360
- Q: Why do I have to install `vscode-arduino-api` from `npm`.
64-
- A: `vscode-arduino-api` only contains types for the API. The actual code wil be part of the VS Code extension.
61+
- A: `vscode-arduino-api` only contains types for the API. The actual code will be part of the VS Code extension.
62+
63+
---
64+
65+
- Q: I cannot find the `dankeboy36.vscode-arduino-api` extension in neither the [VS Code Marketplace](https://marketplace.visualstudio.com/vscode) nor [Open VSX Registry](https://open-vsx.org/).
66+
- A: Correct. This solution targets the [Arduino IDE](https://github.com/arduino/arduino-ide) 2.x. The IDE will contain this VSIX at runtime and will activate it before your tool VSIX. You do not even have to add `dankeboy36.vscode-arduino-api` to the `extensionDependencies`. I might publish the VSIX later when it works in VS Code. By the way, the VSIX is signed by a verified publisher. You can get the latest version from the GitHub [release page](https://github.com/dankeboy36/vscode-arduino-api/releases/latest).
6567
6668
---
6769
68-
- Q: I cannot find the `dankeboy36.vscode-arduino-api` extension in the [VS Code Marketplace](https://marketplace.visualstudio.com/vscode).
69-
- A: Correct. This solution targets the [Arduino IDE](https://github.com/arduino/arduino-ide). I will publish the VSIX later, when it works in VS Code. By the way, the VSIX is signed with a verified published.
70+
- Q: Are there plans to support it in VS Code?
71+
- A: Sure.

0 commit comments

Comments
 (0)