Skip to content

Commit b45b77b

Browse files
vinzbarbutovinzbarbuto
committed
Updated VSCode extention docs
1 parent f4335ec commit b45b77b

File tree

4 files changed

+152
-2
lines changed

4 files changed

+152
-2
lines changed

‎docs/assets/images/vs_code/error_message.png‎

19.4 KB
Loading

‎docs/assets/images/vs_code/lingo_packages.png‎

30.7 KB
Loading

‎docs/assets/images/vs_code/local_libraries.png‎

28.4 KB
Loading

‎docs/tools/code-extension.mdx‎

Lines changed: 152 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: VS Code Extension
33
description: Visual Studio Code Extension for Lingua Franca.
44
---
55

6-
The Lingua Franca extension for Visual Studio Code (VS Code) provides syntax-directed editing capability, compilation, and diagram synthesis for Lingua Franca programs.
6+
The Lingua Franca extension for Visual Studio Code (VS Code) provides syntax-directed editing capability, compilation, diagram synthesis and a project explorer for Lingua Franca programs.
77

88
## Usage
99

@@ -18,6 +18,22 @@ src/
1818
src-gen/Foo
1919
```
2020

21+
Overall, we encourage you to open your project in VS Code using the following structure to fully leverage the features of the VS Code extension:
22+
23+
```shell
24+
├── root
25+
│ ├── bin/
26+
│ ├── build/ # directory containing lingo packages
27+
│ │ ├── lfc_include/ # Directory for storing reusable reactors
28+
│ │ │ ├── lingo_library/
29+
│ ├── include/
30+
│ ├── src/
31+
│ │ ├── lib/ # Directory for storing reusable reactors
32+
│ │ │ ├── Input.lf # Ex: reactor capturing external inputs (e.g., Microphone, Camera)
33+
│ │ │ └── ComputerVision.lf # Ex: reactor performing computer vision tasks (e.g., object detection, face recognition)
34+
└── └── Lingo.toml # Configuration file for Lingo Package Manager
35+
```
36+
2137
### Rendering diagrams
2238

2339
To show the diagram for the currently active Lingua Franca file, click on the diagrams icon at the upper right:
@@ -31,8 +47,142 @@ To compile the `.lf` source, open the command palette (<kbd>Ctrl</kbd> + <kbd>Sh
3147
You can also build and immediately afterwards run your code by opening the command palette (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>) and then entering `Lingua Franca: Build and Run`.
3248
Running the code can also be done from the VS Code terminal by executing the generated file in `./bin`.
3349

50+
### Project Explorer
51+
52+
The **Lingua Franca Project Explorer** can be accessed by clicking on the **LF icon** in the activity bar on the left side of the screen. Once opened, the **Project Explorer** displays a **Tree View** with the following structure:
53+
54+
```shell
55+
├── LF Project
56+
│ ├── Lingo Packages
57+
│ ├── Local Libraries
58+
└── └── Source Files
59+
```
60+
61+
- **Lingo Packages**: Lists libraries installed via the Lingo Package Manager, located in the `build/lfc_include` directory (if any).
62+
63+
- **Local Libraries**: Displays locally defined libraries (e.g., reusable reactors), located in the `src/lib` directory.
64+
65+
- **Source Files**: Contains the LF source files created by the developer, located in the `src` directory.
66+
67+
The **Source Files** section is always present as it reflects the main LF files in the project. However, the **Lingo Packages** and **Local Libraries** sections appear only if the respective directories and files exist in the workspace.
68+
69+
Hovering over the **LF Project** item reveals a terminal icon. Clicking this icon opens a terminal window at the project's root directory, allowing you to execute commands directly within that directory.
70+
71+
#### Lingo Packages
72+
73+
The **Lingo Packages** section lists libraries installed using the [Lingo Package Manager](https://github.com/lf-lang/lingo). Developers can use the Lingo Package Manager to retrieve and install LF programs from repositories such as the [Lingua Franca Community Organization](https://github.com/LF-Community).
74+
75+
To install libraries:
76+
1. Configure the `Lingo.toml` file with the desired libraries.
77+
2. Run `lingo build` to download the specified dependencies.
78+
79+
Once the libraries are installed, they will appear in the `{project_name}/build/lfc_include/` directory. The **Lingo Packages** section will then be structured as follows:
80+
81+
```shell
82+
├── LF Project
83+
│ ├── Lingo Packages
84+
│ │ ├── lingo_library/
85+
│ │ │ ├── File_1.lf
86+
│ │ │ │ ├── Rusable_Reactor_1.lf
87+
│ │ │ │ ├── Rusable_Reactor_2.lf
88+
│ │ │ ├── File_2.lf
89+
│ │ │ │ ├── Rusable_Reactor_1.lf
90+
│ │ │ │ ├── Rusable_Reactor_2.lf
91+
...
92+
```
93+
94+
In this structure:
95+
- **LF Project**: Represents the root folder of the main project.
96+
- **lingo_library**: Represents each library listed in `Lingo.toml`, which contains one or more LF programs featuring reusable reactors.
97+
98+
The image below shows a visual representation of the **Lingo Packages** section. The **project** icon indicates the LF Project folder (e.g., `AudioClassification`), while the **root-folder** icon represents the downloaded libraries (e.g., the `edgeai` library in the example). The **code file** icon denotes an LF program within a library, and the **bracket** icon represents individual reactors inside the LF program.
99+
100+
![Lingo Packages section](../assets/images/vs_code/lingo_packages.png)
101+
102+
The hierarchy categorizes tree items into the following types:
103+
104+
1. **`library-root`**: Refers to the root folder of each downloaded library.
105+
2. **`file`**: Represents an LF program within the library.
106+
3. **`reactor`**: Refers to individual reactors within the LF program.
107+
108+
When focusing on the **Lingo Packages** section, an `edit` command becomes available. Clicking it opens the `Lingo.toml` file in the editor for configuration changes. The following actions are available for items in the **Lingo Packages** section:
109+
110+
- For **file** items (from right to left):
111+
- **Open in Split View**: Opens the file in a split editor view.
112+
- **Go To File**: Navigates to the file in the editor.
113+
114+
- For **reactor** items (from right to left):
115+
- **Import Selected Reactor**: Imports the selected reactor into the active LF program.
116+
- **Go To File**: Opens the file where the reactor is defined.
117+
- **Open in Split View**: Opens the file in a split editor view (accessible by right-clicking the item).
118+
119+
> **Note**: The **Import Selected Reactor** option is available only if an LF program is open in the editor.
120+
121+
#### Local Libraries
122+
123+
The **Local Libraries** section lists LF programs created by the developer, located in the `{project_name}/src/lib/` directory. These programs serve as local libraries, containing reusable reactors. The directory structure follows this format:
124+
125+
```shell
126+
├── LF Project
127+
...
128+
│ ├── Local Libraries
129+
│ │ ├── File_1.lf
130+
│ │ │ ├── Rusable_Reactor_1.lf
131+
│ │ │ ├── Rusable_Reactor_2.lf
132+
│ │ ├── File_2.lf
133+
│ │ │ │ ├── Rusable_Reactor_1.lf
134+
│ │ │ │ ├── Rusable_Reactor_2.lf
135+
...
136+
```
137+
138+
The image below illustrates the **Local Libraries** section. In this depiction, the **"project"** icon represents the LF project folder, while the **"code file"** icon represents the LF program, and the **"bracket"** icon denotes individual reactors within the LF program.
139+
140+
![Local Libraries section](../assets/images/vs_code/local_libraries.png)
141+
142+
The hierarchy categorizes tree items into two types:
143+
144+
1. **`file`**: Represents the LF program.
145+
2. **`reactor`**: Represents a reactor within the LF program.
146+
147+
Actions for **Local Libraries** are similar to those in the [**Lingo Packages**](#lingo-packages) section:
148+
149+
- For **file** items (from right to left):
150+
- **Open in Split View**: Opens the file in a split editor view.
151+
- **Go To File**: Navigates to the file in the editor.
152+
153+
- For **reactor** items (from right to left):
154+
- **Import Selected Reactor**: Imports the selected reactor into the active LF program.
155+
- **Go To File**: Opens the file where the reactor is defined.
156+
- **Open in Split View**: Opens the file in a split editor view (accessible by right-clicking the item).
157+
158+
> **Note**: The **Import Selected Reactor** option is available only if an LF program is open in the editor.
159+
160+
#### Source Files
161+
162+
The **Source Files** section lists all LF programs in the `{project_name}/src/` directory. This section provides direct access to the main source files of the project. The hierarchy for this view is straightforward:
163+
164+
```shell
165+
├── LF Project
166+
...
167+
│ ├── Local Libraries
168+
│ │ ├── File_1.lf
169+
│ │ ├── File_1.lf
170+
│ │ ├── File_1.lf
171+
...
172+
```
173+
174+
Clicking on any of the files will open the corresponding LF program in the editor, allowing developers to quickly navigate to and edit the source code of their project.
175+
176+
#### Correctness of Project Structure
177+
178+
If the project structure deviates from the expected format, an error message will appear:
179+
180+
![Project structure error](../assets/images/vs_code/error_message.png)
181+
182+
To avoid errors, follow the [project structure guidelines](#creating-a-new-file).
183+
34184
## Notes
35185

36186
### For Python Users
37187

38-
Users who edit LF programs with a Python target will benefit the most from Python linting by installing Pylint 2.12.2 or later.
188+
Users who edit LF programs with a Python target will benefit the most from Python linting by installing Pylint 2.12.2 or later.

0 commit comments

Comments
 (0)