Skip to content

Commit 9bfc0ec

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, - basic configuration support, - replaced `buildPath` with `compileSummary`, and - updated the readme. Signed-off-by: dankeboy36 <[email protected]>
1 parent 50ab124 commit 9bfc0ec

16 files changed

+800
-238
lines changed

Diff for: ‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,5 @@ dist
33
node_modules
44
.vscode-test/
55
*.vsix
6+
src/test/test-workspace/*
7+
!src/test/test-workspace/.gitkeep

Diff for: ‎.vscode/launch.json

+4
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,13 @@
1414
"type": "extensionHost",
1515
"request": "launch",
1616
"args": [
17+
"${workspaceFolder}/src/test/test-workspace", // open workspace in VS Code
1718
"--extensionDevelopmentPath=${workspaceFolder}",
1819
"--extensionTestsPath=${workspaceFolder}/out/test/suite/index"
1920
],
21+
"env": {
22+
"NO_TEST_TIMEOUT": "true"
23+
},
2024
"outFiles": [
2125
"${workspaceFolder}/out/**/*.js",
2226
"${workspaceFolder}/dist/**/*.js"

Diff for: ‎.vscodeignore

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1+
.github/**
12
.vscode/**
23
.vscode-test/**
34
out/**
45
node_modules/**
56
src/**
67
.gitignore
7-
.yarnrc
8+
.prettierignore
9+
CHANGELOG.md
810
webpack.config.js
911
vsc-extension-quickstart.md
1012
**/tsconfig.json

Diff for: ‎README.md

+50-29
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,45 +25,66 @@ 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
4436
import * as vscode from 'vscode';
4537
import type { ArduinoContext } from 'vscode-arduino-api';
4638
47-
function activate(context: vscode.ExtensionContext) {
39+
export function activate(context: vscode.ExtensionContext) {
4840
const arduinoContext: ArduinoContext = vscode.extensions.getExtension(
4941
'dankeboy36.vscode-arduino-api'
5042
)?.exports;
5143
if (!arduinoContext) {
52-
// failed to load the Arduino API
44+
// Failed to load the Arduino API.
5345
return;
5446
}
55-
// use the Arduino API in your VS Code extension...
47+
48+
// Use the Arduino API in your VS Code extension.
49+
50+
// Read the state.
51+
// Register a command to access the sketch path and show it as an information message.
52+
context.subscriptions.push(
53+
vscode.commands.registerCommand('myExtension.showSketchPath', () => {
54+
vscode.window.showInformationMessage(
55+
`Sketch path: ${arduinoContext.sketchPath}`
56+
);
57+
})
58+
);
59+
60+
// Listen on state change.
61+
// Register a listener to show the FQBN of the currently selected board as an information message.
62+
context.subscriptions.push(
63+
arduinoContext.onDidChange('fqbn')((fqbn) =>
64+
vscode.window.showInformationMessage(`FQBN: ${fqbn}`)
65+
)
66+
);
5667
}
5768
```
5869
5970
## FAQs
6071
6172
---
6273
74+
- Q: What does `@alpha` mean?
75+
- 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.
76+
77+
---
78+
6379
- 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.
80+
- A: `vscode-arduino-api` only contains types for the API. The actual code will be part of the VS Code extension.
81+
82+
---
83+
84+
- 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/).
85+
- 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).
6586
6687
---
6788
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.
89+
- Q: Are there plans to support it in VS Code?
90+
- A: Sure.

0 commit comments

Comments
 (0)