-
Notifications
You must be signed in to change notification settings - Fork 18
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.
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
Updated documentation for upcoming VSCode extension release #288
base: main
Are you sure you want to change the base?
Changes from 2 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
@@ -3,7 +3,7 @@ title: VS Code Extension | |||||||||
description: Visual Studio Code Extension for Lingua Franca. | ||||||||||
--- | ||||||||||
|
||||||||||
The Lingua Franca extension for Visual Studio Code (VS Code) provides syntax-directed editing capability, compilation, and diagram synthesis for Lingua Franca programs. | ||||||||||
The Lingua Franca extension for Visual Studio Code (VS Code) provides syntax-directed editing capability, compilation, diagram synthesis and a packages explorer for Lingua Franca programs. | ||||||||||
|
||||||||||
## Usage | ||||||||||
|
||||||||||
|
@@ -18,6 +18,22 @@ src/ | |||||||||
src-gen/Foo | ||||||||||
``` | ||||||||||
|
||||||||||
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: | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
|
||||||||||
```shell | ||||||||||
├── root | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This stuff should be mentioned before the "creating a new file" stuff and should probably mention |
||||||||||
│ ├── bin/ | ||||||||||
│ ├── build/ # directory containing packages installed by Lingo Package Manager | ||||||||||
│ │ ├── lfc_include/ # Directory for storing reusable reactors | ||||||||||
│ │ │ ├── installed_library/ | ||||||||||
│ ├── include/ | ||||||||||
│ ├── src/ | ||||||||||
│ │ ├── lib/ # Directory for storing reusable reactors | ||||||||||
│ │ │ ├── Input.lf # Ex: reactor capturing external inputs (e.g., Microphone, Camera) | ||||||||||
│ │ │ └── ComputerVision.lf # Ex: reactor performing computer vision tasks (e.g., object detection, face recognition) | ||||||||||
└── └── Lingo.toml # Configuration file for Lingo Package Manager | ||||||||||
``` | ||||||||||
|
||||||||||
### Rendering diagrams | ||||||||||
|
||||||||||
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 | |||||||||
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`. | ||||||||||
Running the code can also be done from the VS Code terminal by executing the generated file in `./bin`. | ||||||||||
|
||||||||||
### Packages Explorer | ||||||||||
|
||||||||||
The **Lingua Franca Packages Explorer** can be accessed by clicking on the **LF icon** in the activity bar on the left side of the screen. Once opened, the **Packages Explorer** displays a **Tree View** with the following structure: | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
|
||||||||||
```shell | ||||||||||
├── LF Project | ||||||||||
│ ├── Installed Packages | ||||||||||
│ ├── Local Libraries | ||||||||||
└── └── Source Files | ||||||||||
``` | ||||||||||
|
||||||||||
- [**Installed Packages**](#installed-packages): Lists libraries installed via the Lingo Package Manager, located in the `build/lfc_include` directory (if any). | ||||||||||
|
||||||||||
- [**Local Libraries**](#local-libraries): Displays locally defined libraries (e.g., reusable reactors), located in the `src/lib` directory. | ||||||||||
|
||||||||||
- [**Source Files**](#source-files): Contains the LF source files created by the developer, located in the `src` directory. | ||||||||||
|
||||||||||
The **Source Files** section is always present as it reflects the main LF files in the project. However, the **Installed Packages** and **Local Libraries** sections appear only if the respective directories and files exist in the workspace. | ||||||||||
|
||||||||||
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. | ||||||||||
|
||||||||||
#### Installed Packages | ||||||||||
|
||||||||||
The **Installed 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). | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||||||||||
|
||||||||||
To install libraries: | ||||||||||
1. Configure the `Lingo.toml` file with the desired libraries. | ||||||||||
2. Run `lingo build` to download the specified dependencies. | ||||||||||
|
||||||||||
Once the libraries are installed, they will appear in the `{project_name}/build/lfc_include/` directory. The **Installed Packages** section will then be structured as follows: | ||||||||||
|
||||||||||
```shell | ||||||||||
vinzbarbuto marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
├── LF Project | ||||||||||
│ ├── Installed Packages | ||||||||||
│ │ ├── installed_library/ | ||||||||||
│ │ │ ├── File_1.lf | ||||||||||
│ │ │ │ ├── Rusable_Reactor_1.lf | ||||||||||
│ │ │ │ ├── Rusable_Reactor_2.lf | ||||||||||
│ │ │ ├── File_2.lf | ||||||||||
│ │ │ │ ├── Rusable_Reactor_1.lf | ||||||||||
│ │ │ │ ├── Rusable_Reactor_2.lf | ||||||||||
... | ||||||||||
``` | ||||||||||
|
||||||||||
In this structure: | ||||||||||
- **LF Project**: Represents the root folder of the main project. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It seems like we mix the term "package" and "project" a lot. Maybe we should only use one? |
||||||||||
- **installed_library**: Represents each library listed in `Lingo.toml`, which contains one or more LF programs featuring reusable reactors. | ||||||||||
|
||||||||||
The image below shows a visual representation of the **Installed 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. | ||||||||||
|
||||||||||
![Installed Packages section](../assets/images/vs_code/lingo_packages.svg) | ||||||||||
|
||||||||||
The hierarchy categorizes tree items into the following types: | ||||||||||
|
||||||||||
1. **`library-root`**: Refers to the root folder of each downloaded library. | ||||||||||
2. **`file`**: Represents an LF program within the library. | ||||||||||
3. **`reactor`**: Refers to individual reactors within the LF program. | ||||||||||
|
||||||||||
When focusing on the **Installed 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 **Installed Packages** section: | ||||||||||
|
||||||||||
- For **file** items (from right to left): | ||||||||||
- **Open in Split View**: Opens the file in a split editor view. | ||||||||||
- **Go To File**: Navigates to the file in the editor. | ||||||||||
|
||||||||||
- For **reactor** items (from right to left): | ||||||||||
- **Import Selected Reactor**: Imports the selected reactor into the active LF program. | ||||||||||
- **Go To File**: Opens the file where the reactor is defined. | ||||||||||
- **Open in Split View**: Opens the file in a split editor view (accessible by right-clicking the item). | ||||||||||
|
||||||||||
> **Note**: The **Import Selected Reactor** option is available only if an LF program is open in the editor. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
|
||||||||||
#### Local Libraries | ||||||||||
|
||||||||||
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: | ||||||||||
|
||||||||||
```shell | ||||||||||
├── LF Project | ||||||||||
... | ||||||||||
│ ├── Local Libraries | ||||||||||
│ │ ├── File_1.lf | ||||||||||
│ │ │ ├── Rusable_Reactor_1.lf | ||||||||||
│ │ │ ├── Rusable_Reactor_2.lf | ||||||||||
│ │ ├── File_2.lf | ||||||||||
│ │ │ │ ├── Rusable_Reactor_1.lf | ||||||||||
│ │ │ │ ├── Rusable_Reactor_2.lf | ||||||||||
... | ||||||||||
``` | ||||||||||
|
||||||||||
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. | ||||||||||
|
||||||||||
![Local Libraries section](../assets/images/vs_code/local_libraries.svg) | ||||||||||
|
||||||||||
The hierarchy categorizes tree items into two types: | ||||||||||
|
||||||||||
1. **`file`**: Represents the LF program. | ||||||||||
2. **`reactor`**: Represents a reactor within the LF program. | ||||||||||
|
||||||||||
Actions for **Local Libraries** are similar to those in the [**Installed Packages**](#installed-packages) section: | ||||||||||
|
||||||||||
- For **file** items (from right to left): | ||||||||||
- **Open in Split View**: Opens the file in a split editor view. | ||||||||||
- **Go To File**: Navigates to the file in the editor. | ||||||||||
|
||||||||||
- For **reactor** items (from right to left): | ||||||||||
- **Import Selected Reactor**: Imports the selected reactor into the active LF program. | ||||||||||
- **Go To File**: Opens the file where the reactor is defined. | ||||||||||
- **Open in Split View**: Opens the file in a split editor view (accessible by right-clicking the item). | ||||||||||
|
||||||||||
> **Note**: The **Import Selected Reactor** option is available only if an LF program is open in the editor. | ||||||||||
|
||||||||||
#### Source Files | ||||||||||
|
||||||||||
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: | ||||||||||
|
||||||||||
```shell | ||||||||||
├── LF Project | ||||||||||
... | ||||||||||
│ ├── Local Libraries | ||||||||||
│ │ ├── File_1.lf | ||||||||||
│ │ ├── File_1.lf | ||||||||||
│ │ ├── File_1.lf | ||||||||||
... | ||||||||||
``` | ||||||||||
|
||||||||||
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. | ||||||||||
|
||||||||||
#### Correctness of Project Structure | ||||||||||
|
||||||||||
If the project structure deviates from the expected format, an error message will appear: | ||||||||||
|
||||||||||
![Project structure error](../assets/images/vs_code/error_message.svg) | ||||||||||
|
||||||||||
To avoid errors, follow the [project structure guidelines](#creating-a-new-file). | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This should probably refer to a "creating a new project" paragraph |
||||||||||
|
||||||||||
## Notes | ||||||||||
|
||||||||||
### For Python Users | ||||||||||
|
||||||||||
Users who edit LF programs with a Python target will benefit the most from Python linting by installing Pylint 2.12.2 or later. | ||||||||||
Users who edit LF programs with a Python target will benefit the most from Python linting by installing Pylint 2.12.2 or later. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.