Skip to content

feat: exposed the build_properties from the CLI #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 11, 2023
Merged

feat: exposed the build_properties from the CLI #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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