Skip to content

Commit 41312fe

Browse files
edrioukedriouk
committed
Update DEVELOPMENT.md
1 parent 2fe9800 commit 41312fe

1 file changed

Lines changed: 96 additions & 79 deletions

File tree

‎DEVELOPMENT.md‎

Lines changed: 96 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,6 @@ and follow the best practices for creating your extension.
88
Use vcpkg to install the tools as discussed in the [README](./README.md). The test-workspace
99
contains a [vcpkg-configuration.json](./test-workspace/vcpkg-configuration.json) file to do this.
1010

11-
### Arm Compiler
12-
13-
Arm Compiler is currently not available in vcpkg. Internal Arm users can download Arm Compiler
14-
builds from Warehouse at `smb://neptune.euhpc.arm.com/warehouse/Distributions/FA/ARMCompiler`.
15-
16-
For example:
17-
18-
- _Windows_: `\\neptune.euhpc.arm.com\warehouse\Distributions\FA\ARMCompiler\6.18\123\standalone-win-x86_64-rel`
19-
- _Linux_: `smb://neptune.euhpc.arm.com/warehouse/Distributions/FA/ARMCompiler/6.18/123/standalone-linux-x86_64-rel`
20-
21-
No standalone Mac build is available yet, but it is possible to hack the Mbed Studio build.
22-
Download the Mbed Studio build from e.g. `smb://neptune.euhpc.arm.com/warehouse/Distributions/FA/ARMCompiler/6.18/116/mbed-darwin-x86_64-rel`.
23-
24-
Follow these docs to set up user based licensing:
25-
[User-based licensing for tools and models](https://armh.sharepoint.com/sites/DSGToolsandModels/SitePages/User-based-licensing-for-tools-and-models.aspx).
26-
27-
In short, run this command from the extracted directory on the Arm network:
28-
29-
```sh
30-
./bin/armlm activate --server https://lls.xpe.aws.arm.com --product HWSKT-EAC0
31-
```
3211

3312
## Running the extension in development
3413

@@ -56,56 +35,12 @@ In short, run this command from the extracted directory on the Arm network:
5635
the extension in debug mode. A new VS Code window will open with the extension loaded so it can
5736
be used.
5837
59-
Notes:
60-
61-
- On Windows, Attack Surface Reduction (ASR) rules can block the use of cmsis.exe. To exclude it
62-
from the ASR rules, use the following command on PowerShell:
63-
64-
```txt
65-
Add-MpPreference -AttackSurfaceReductionOnlyExclusions "<path to cmsis.exe>"
66-
```
67-
68-
### Using Core Tools dev branch as extension's client
69-
70-
1. In the Core Tools repo, go to the `clients/js` directory. Install NPM dependencies, build and
71-
package the module.
72-
73-
```sh
74-
npm install
75-
npm run build
76-
npm pack
77-
```
78-
79-
**NB:** Protobuf compiler installation is required to build. To install `brew install protobuf@version`.
80-
81-
2. Traverse to the `cmsis-cli` directory and build the Go client.
82-
83-
```sh
84-
go build -o cmsis
85-
```
86-
87-
3. Move the built Go binary to the `tools/cmsis-core-tools` directory in `vscode-cmsis-csolution`
88-
and overwrite the existing cmsis binary. Note, if this directory doesn't exist - create it.
89-
90-
4. Install the local core tools client npm package that was created in step 1.
91-
92-
```sh
93-
npm install <path/to/tar.gz>
94-
```
95-
9638
5. Build the extension.
9739
9840
```sh
9941
npm run build
10042
```
10143
102-
### Other configurations
103-
104-
- `npm run browser` starts a VS Code web development environment similar to Codespaces.
105-
- `npm run serve` starts a file server allowing the extension to be side-loaded into vscode.dev.
106-
Run the "Developer: Install Web Extension" command in vscode.dev, then enter the URL for the
107-
running server.
108-
10944
## Run the tests
11045
11146
### Unit tests
@@ -208,27 +143,109 @@ Use the following commands:
208143
2. Update the `CHANGELOG` with the latest changes.
209144
3. Open a pull request with these updates and merge it into `main`.
210145
4. Create a new release at: https://github.com/Open-CMSIS-Pack/vscode-cmsis-solution/releases
211-
- This will trigger the `CI.yml` workflow.
146+
- This will trigger the `CI.yml` workflow.
212147
- Once the workflow completes successfully, the release artifacts will be generated automatically.
213148

214-
## Debugging in KSC
149+
## JSON-RPC Protocol (`csolution`)
215150

216-
1. Mount the extension development directory into the KSC container by adding this volume to the
217-
KSC docker-compose override file. `$EXTENSION` is the path to the root of the extension repository.
151+
The extension communicates with the `csolution` binary using [JSON-RPC 2.0](https://www.jsonrpc.org/specification). The protocol is defined in the [csolution-rpc](https://github.com/Open-CMSIS-Pack/csolution-rpc) repository.
218152

219-
```yaml
220-
volumes:
221-
- $EXTENSION:/home/studio/mbs-plugins/vscode-cmsis-csolution:ro
222-
```
153+
The generated TypeScript client interface lives in [src/json-rpc/interface/rpc-interface.ts](src/json-rpc/interface/rpc-interface.ts) — **do not edit this file manually**. The current API version is tracked in [src/json-rpc/interface/version.txt](src/json-rpc/interface/version.txt).
223154

224-
1. Restart the KSC docker container, e.g. `docker compose restart mbs-ide`.
225-
1. Start the "KSC Plugin Host (Docker)" launch configuration.
226-
1. Load the KSC frontend in a browser.
155+
### Modifying the protocol
227156

228-
## Security
157+
When a new RPC method or data type is needed:
158+
159+
1. **Update the OpenAPI schema** in the [csolution-rpc](https://github.com/Open-CMSIS-Pack/csolution-rpc) repository (`api/csolution-openapi.yml`). Use the [Swagger Editor](https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/Open-CMSIS-Pack/csolution-rpc/refs/heads/main/api/csolution-openapi.yml) to verify the schema. Follow the [naming and schema conventions](https://github.com/Open-CMSIS-Pack/csolution-rpc/blob/main/api/README.md) defined in that repository.
160+
161+
2. **Regenerate the interfaces** using [json-rpc-codegen](https://github.com/Open-CMSIS-Pack/csolution-rpc/blob/main/codegen/README.md):
162+
163+
```sh
164+
node dist/cli.js --client rpc-interface.ts --server RpcInterface.h <schema>
165+
```
166+
167+
This produces two generated files:
168+
- `rpc-interface.ts` — TypeScript client interface (consumed by this extension)
169+
- `RpcInterface.h` — C++ server header (consumed by `csolution`)
229170

230-
Security considerations for OTG's VS Code extensions are tracked in the
231-
[threat model](https://confluence.arm.com/display/IoTWeb/OTG+VS+Code+Extensions+Threat+Model).
171+
3. **Implement the server side** in [`ProjMgrRpcServer.cpp`](https://github.com/Open-CMSIS-Pack/devtools/blob/main/tools/projmgr/src/ProjMgrRpcServer.cpp) in the `devtools` repository.
172+
173+
4. **Implement the client side** in this extension:
174+
- Copy the regenerated `rpc-interface.ts` into [src/json-rpc/interface/](src/json-rpc/interface/) and update [version.txt](src/json-rpc/interface/version.txt) to the new API version.
175+
- Expose the new method via `CsolutionService` in [src/json-rpc/csolution-rpc-client.ts](src/json-rpc/csolution-rpc-client.ts).
176+
- Use the method from the relevant data source or manager in [src/data-manager/](src/data-manager/).
177+
178+
### Debugging JSON-RPC communication
179+
180+
All outgoing JSON-RPC requests are printed via `console.log` in the `transceive()` function in [src/json-rpc/csolution-rpc-client.ts](src/json-rpc/csolution-rpc-client.ts). They appear in the **Debug Console** when running the extension with F5.
181+
182+
For more verbose output from the `csolution` process, set the `CSOLUTION_ARGS` environment variable before launching the extension:
183+
184+
```sh
185+
export CSOLUTION_ARGS="--debug -v"
186+
```
187+
188+
With these flags, `csolution` produces detailed diagnostic output and writes a `csolution-rpc-log.txt` file in the target workspace folder, logging all JSON-RPC requests and responses exchanged during the session.
189+
190+
To test a specific RPC method manually, launch the `csolution` binary in RPC mode and send JSON-RPC requests over stdin:
191+
192+
```sh
193+
csolution --rpc
194+
```
195+
196+
Example request:
197+
198+
```json
199+
{"jsonrpc":"2.0","id":1,"method":"loadPacks","params":{}}
200+
```
201+
202+
### Debugging csolution server code
203+
204+
To debug the `csolution` server (C++ code) running on the backend:
205+
206+
1. **Check out and build `devtools` with debug symbols:**
207+
208+
```sh
209+
git clone https://github.com/Open-CMSIS-Pack/devtools.git
210+
cd devtools
211+
cmake --preset default
212+
cmake --build --preset default --config RelWithDebugInfo
213+
```
214+
215+
The debug executable will be in the build output directory.
216+
217+
2. **Make the debug executable available to the extension:**
218+
219+
Either copy the debug `csolution` executable to the `cmsis-toolbox/bin` directory:
220+
221+
```sh
222+
cp <devtools-build>/csolution <cmsis-toolbox/bin>/csolution
223+
```
224+
225+
Or create a symbolic link:
226+
227+
```sh
228+
ln -s <devtools-build>/csolution <cmsis-toolbox/bin>/csolution
229+
```
230+
231+
Alternatively, set the `CMSIS_SOLUTION_TOOLBOX` environment variable to point to a directory containing the toolbox structure (with `bin` and `etc` subdirectories):
232+
233+
```sh
234+
export CMSIS_SOLUTION_TOOLBOX=<toolbox-root>
235+
```
236+
237+
The debug `csolution` executable must be located at `<toolbox-root>/bin/csolution`.
238+
239+
3. **Launch the extension in debug mode:**
240+
241+
Press F5 in VS Code to start the extension with its debugger attached.
242+
243+
4. **Load a csolution project** in the extension to trigger `csolution` startup.
244+
245+
5. **Attach the native debugger** (Visual Studio Debugger or gdb/lldb) to the running `csolution` process by PID. The process will be active while the extension is communicating with it.
246+
247+
## Security
248+
For security considerations see [SECURITY.md](./SECURITY.md)
232249

233250
## Test or develop in Dev Containers
234251

0 commit comments

Comments
 (0)