Skip to content

Commit

Permalink
feat(api)!: exposed the build_properties API
Browse files Browse the repository at this point in the history 
 - 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]>
  • Loading branch information
@dankeboy36
dankeboy36 committed Jun 11, 2023
1 parent 50ab124 commit b42e8ca
Show file tree
Hide file tree
Showing 16 changed files with 834 additions and 234 deletions.
2 changes: 2 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,5 @@ dist
node_modules
.vscode-test/
*.vsix
src/test/test-workspace/*
!src/test/test-workspace/.gitkeep
4 changes: 4 additions & 0 deletions .vscode/launch.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,13 @@
"type": "extensionHost",
"request": "launch",
"args": [
"${workspaceFolder}/src/test/test-workspace",
"--extensionDevelopmentPath=${workspaceFolder}",
"--extensionTestsPath=${workspaceFolder}/out/test/suite/index"
],
"env": {
"NO_TEST_TIMEOUT": "true"
},
"outFiles": [
"${workspaceFolder}/out/**/*.js",
"${workspaceFolder}/dist/**/*.js"
Expand Down
4 changes: 3 additions & 1 deletion .vscodeignore
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
.github/**
.vscode/**
.vscode-test/**
out/**
node_modules/**
src/**
.gitignore
.yarnrc
.prettierignore
CHANGELOG.md
webpack.config.js
vsc-extension-quickstart.md
**/tsconfig.json
Expand Down
79 changes: 50 additions & 29 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# vscode-arduino-api

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

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.
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.

## Features
## API

Exposes the Arduino context for VS Code extensions:

| Name | Description | Type | Note |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------- |
| `sketchPath` | Absolute filesystem path of the sketch folder. | `string` |
| `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` |
| `fqbn` | The Fully Qualified Board Name (FQBN) of the currently selected board in the Arduino IDE. | `string` |
| `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` |
| `port` | The currently selected port in the Arduino IDE. | [`Port`](https://arduino.github.io/arduino-cli/latest/rpc/commands/#port) |
| `userDirPath` | Filesystem path to the [`directories.user`](https://arduino.github.io/arduino-cli/latest/configuration/#configuration-keys) location. This is the sketchbook path. | `string` |
| `dataDirPath` | Filesystem path to the [`directories.data`](https://arduino.github.io/arduino-cli/latest/configuration/#configuration-keys) location | `string` |
| Name | Description | Type | Note |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ----------- |
| `sketchPath` | Absolute filesystem path of the sketch folder. | `string` |
| `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` |
| `fqbn` | The Fully Qualified Board Name (FQBN) of the currently selected board in the Arduino IDE. | `string` |
| `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` |
| `port` | The currently selected port in the Arduino IDE. | [`Port`](https://arduino.github.io/arduino-cli/latest/rpc/commands/#port) |
| `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` |
| `dataDirPath` | Filesystem path to the [`directories.data`](https://arduino.github.io/arduino-cli/latest/configuration/#configuration-keys) location | `string` | ⚠️ `@alpha` |

## How to Use

Expand All @@ -25,45 +25,66 @@ If you're developing an external tool for the Arduino IDE, this extension will b
If you want to use the Arduino APIs, you have to do the followings:

1. Install the [Arduino API types](https://www.npmjs.com/package/vscode-arduino-api) from `npm`:

```shell
npm i -S vscode-arduino-api
```
1. Add this VSIX as an `extensionDependencies` in your `package.json`:

```jsonc
{
"extensionDependencies": [
"dankeboy36.vscode-arduino-api",
// other dependencies
],
}
npm install vscode-arduino-api --save
```

1. Consume the `ArduinoContext` extension API in your VS Code extension:

```ts
import * as vscode from 'vscode';
import type { ArduinoContext } from 'vscode-arduino-api';
function activate(context: vscode.ExtensionContext) {
export function activate(context: vscode.ExtensionContext) {
const arduinoContext: ArduinoContext = vscode.extensions.getExtension(
'dankeboy36.vscode-arduino-api'
)?.exports;
if (!arduinoContext) {
// failed to load the Arduino API
// Failed to load the Arduino API.
return;
}
// use the Arduino API in your VS Code extension...
// Use the Arduino API in your VS Code extension.
// Read the state.
// Register a command to access the sketch path and show it as an information message.
context.subscriptions.push(
vscode.commands.registerCommand('myExtension.showSketchPath', () => {
vscode.window.showInformationMessage(
`Sketch path: ${arduinoContext.sketchPath}`
);
})
);
// Listen on state change.
// Register a listener to show the FQBN of the currently selected board as an information message.
context.subscriptions.push(
arduinoContext.onDidChange('fqbn')((fqbn) =>
vscode.window.showInformationMessage(`FQBN: ${fqbn}`)
)
);
}
```
## FAQs
---
- Q: What does `@alpha` mean?
- 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.
---
- Q: Why do I have to install `vscode-arduino-api` from `npm`.
- A: `vscode-arduino-api` only contains types for the API. The actual code wil be part of the VS Code extension.
- A: `vscode-arduino-api` only contains types for the API. The actual code will be part of the VS Code extension.
---
- 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/).
- 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).
---
- Q: I cannot find the `dankeboy36.vscode-arduino-api` extension in the [VS Code Marketplace](https://marketplace.visualstudio.com/vscode).
- 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.
- Q: Are there plans to support it in VS Code?
- A: Sure.
Loading

0 comments on commit b42e8ca

Please sign in to comment.