Skip to content

Commit 1de4aff

Browse files
lhstrhlhstrh
authored
Merge pull request #288 from vinzbarbuto/main
Updated documentation for upcoming VSCode extension release
2 parents 2e88d6a + d4ccc94 commit 1de4aff

File tree

6 files changed

+238
-8
lines changed

6 files changed

+238
-8
lines changed

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

34.4 KB
Loading

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

47.4 KB
Loading

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

45.7 KB
Loading

‎docs/glossary/glossary.mdx

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: Glossary
3+
description: Glossary of terms used in the Lingua Franca documentation.
4+
---
5+
6+
# Glossary
7+
8+
Glossary of terms used in the Lingua Franca (LF) documentation.
9+
10+
### LF File
11+
A source file with the `.lf` extension, representing a Lingua Franca (LF) program.
12+
13+
### Library File
14+
An LF file containing one or more reactors intended for reuse, designed to be imported into other LF files.
15+
16+
### Package
17+
A collection of LF source files and directories, along with a `Lingo.toml` manifest file that defines the package configuration. Every package must include an `src/` directory containing the LF source files.
18+
19+
### Package Manager
20+
A software tool that automates the installation, configuration, and management of packages. In the LF ecosystem, the `lingo` package manager is used to manage LF packages and dependencies.
21+
22+
### Package Root
23+
The **package root** is the top-level directory of a package where both the `Lingo.toml` file and the `src/` directory reside.
24+
25+
### Project
26+
Another term for a [package](#package) that is under development. Each [LF file](#lf-file) is assumed to reside in a package, meaning it is located somewhere in the file system in a directory called `src`, in some directory that serves as the (package root)[#package-root].
27+
28+
### Project Structure
29+
The structure of an LF project should follow the directory layout below:
30+
31+
```
32+
├── .
33+
│ ├── bin/ # Directory for storing binary executables
34+
│ ├── build/ # Directory containing packages installed by the Lingo Package Manager
35+
│ │ ├── lfc_include/ # Directory for storing reusable reactors
36+
│ │ └── <Installed Package>/ # Directory containing the installed package
37+
│ ├── include/ # Directory for storing header files
38+
│ ├── src/ # Directory containing LF source files
39+
│ │ ├── lib/ # Directory for storing reusable reactors
40+
│ │ │ ├── Input.lf # Ex: reactor capturing external inputs (e.g., Microphone, Camera)
41+
│ │ │ └── ComputerVision.lf # Ex: reactor performing computer vision tasks (e.g., object detection, face recognition)
42+
│ │ └── Main.lf # Ex: main source file
43+
│ ├── fed-gen/ # Directory for storing generated code for federated programs
44+
│ ├── src-gen/ # Directory for storing generated code for single-process programs
45+
└── └── Lingo.toml # Configuration file for Lingo Package Manager
46+
```
47+
48+
- **Mandatory Directories and Files:**
49+
- `src/`: This folder must contain at least one `.lf` source file.
50+
- `Lingo.toml`: This is the required configuration file.
51+
52+
- **Automatically Generated Directories:**
53+
- `bin/`: Created during the build process to store binary executables.
54+
- `build/`: Generated automatically when installing packages managed by the Lingo Package Manager.
55+
- `include/`: Autogenerated to store header files.
56+
- `src-gen/` (or `fed-gen` for federated programs): Autogenerated to store generated code.
57+
58+
- **User-Created Directory:**
59+
- `src/lib/`: This folder is for library files and should be created by the user as necessary.
60+
61+
This directory structure is essential for enabling the Package Explorer feature in the [VS Code Extension](tools/code-extension.mdx#package-explorer), streamlining project management and development processes.

‎docs/sidebars.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,10 @@ const sidebars: SidebarsConfig = {
237237
"id": "developer/website-development"
238238
}
239239
]
240+
},
241+
{
242+
"type": "doc",
243+
"id": "glossary/glossary"
240244
}
241245
]
242246
};

‎docs/tools/code-extension.mdx

Lines changed: 173 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,57 @@ 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+
import Image from '@theme/IdealImage';
7+
import lingo_packages from '../assets/images/vs_code/lingo_packages.png';
8+
import local_libraries from '../assets/images/vs_code/local_libraries.png';
9+
import error_message from '../assets/images/vs_code/error_message.png';
10+
11+
The Lingua Franca extension for Visual Studio Code (VS Code) provides syntax-directed editing capability, compilation, diagram synthesis and a package explorer for Lingua Franca programs.
712

813
## Usage
914

10-
### Creating a new file
15+
### Creating a New Project
16+
17+
You can create a new LF [project](../glossary/glossary.mdx#project) either manually by creating an LF file or by using the [Lingo Package Manager](https://github.com/lf-lang/lingo).
18+
19+
#### Option 1: Create a Project Using the Lingo Package Manager
20+
1. After [installing the Lingo Package Manager](https://www.lf-lang.org/docs/installation#lingo), create an empty directory to serve as the root of your new package.
21+
2. Open the folder in VS Code.
22+
3. Open the terminal in this folder and run the <kbd>lingo init</kbd> command.
23+
24+
This will set up a new LF package with the following structure:
25+
26+
```
27+
├── .
28+
│ ├── src/
29+
│ │ └── Main.lf
30+
└── └── Lingo.toml # Configuration file for current package
31+
```
1132

12-
To create a new LF file, go to <kbd>File > New File...</kbd> and select `New Lingua Franca File`. When saving the file, save it in a directory called `src` to make sure that generated code is placed conveniently in an adjacent `src-gen` directory. For instance, for a file called `Foo.lf`, the directory structure after building should look something like this:
33+
#### Option 2: Create a New [LF File](../glossary/glossary.mdx#lf-file)
34+
1. Go to <kbd>File > New File...</kbd> and select `New Lingua Franca File`.
35+
2. Save the file in a directory called `src` to ensure that generated code is placed in a parallel `src-gen` directory. For example, if your file is called `Foo.lf`, the directory structure after building will look like this:
1336

1437
```
15-
bin/Foo
16-
src/
17-
└ Foo.lf
18-
src-gen/Foo
38+
├── .
39+
│ ├── bin/
40+
│ │ └── Foo
41+
│ ├── src/
42+
│ │ └── Foo.lf
43+
│ ├── src-gen/
44+
│ │ └── Foo/
45+
...
1946
```
2047

21-
### Rendering diagrams
48+
If you manually create the `Lingo.toml` file, place it adjacent to the `src` folder in the root directory of the package. This file serves as a configuration for the package, allowing you to specify the package name, version, and other metadata, including any dependencies you want to install.
49+
50+
### Opening an Existing LF Project
51+
52+
To open an existing LF project in VS Code, select the [package root](../glossary/glossary.mdx#package-root) as your workspace. Ensure that the selected project adheres to the correct [project structure](../glossary/glossary.mdx#project-structure) to enable the [Package Explorer](#package-explorer). If the workspace is not recognized as a valid Lingua Franca package, an error message will appear when you attempt to open the Package Explorer:
53+
54+
<Image img={error_message} style={{maxWidth: 400}} />
55+
56+
### Rendering Diagrams
2257

2358
To show the diagram for the currently active Lingua Franca file, click on the diagrams icon at the upper right:
2459

@@ -31,6 +66,136 @@ To compile the `.lf` source, open the command palette (<kbd>Ctrl</kbd> + <kbd>Sh
3166
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`.
3267
Running the code can also be done from the VS Code terminal by executing the generated file in `./bin`.
3368

69+
### Package Explorer
70+
71+
The **Lingua Franca Package Explorer** can be accessed by clicking on the **LF icon** in the activity bar on the left side of the screen. Once opened, the **Package Explorer** displays a **Tree View** with the following structure:
72+
73+
```
74+
├── <Package Name>
75+
│ ├── Installed Packages
76+
│ ├── Local Libraries
77+
└── └── Source Files
78+
```
79+
80+
- [**Installed Packages**](#installed-packages): Lists packages installed via the Lingo Package Manager, located in the `./build/lfc_include` directory (if any).
81+
82+
- [**Local Libraries**](#local-libraries): Displays locally defined [library files](../glossary/glossary.mdx#library-file) (e.g., reusable reactors), located in the `./src/lib` directory.
83+
84+
- [**Source Files**](#source-files): Contains the LF source files created by the developer, located in the `./src/` directory.
85+
86+
The **Source Files** section is always present as it reflects the main LF files in the package. However, the **Installed Packages** and **Local Libraries** sections appear only if the respective directories and files exist in the workspace.
87+
88+
Hovering over the **\<Package Name\>** item reveals a terminal icon. Clicking this icon opens a terminal window at the package's root directory, allowing you to execute commands directly within that directory.
89+
90+
#### Installed Packages
91+
92+
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 arbitrary GitHub repositories. A collection of useful packages can be found in the [Lingua Franca Packages](https://github.com/lf-pkgs) GitHub organization.
93+
94+
To install packages:
95+
1. Configure the `Lingo.toml` file with the desired package.
96+
2. Run <kbd>lingo build</kbd> in the terminal from the current directory to download the specified dependencies.
97+
98+
Once the packages are installed, they will appear in the `./build/lfc_include/` directory. The **Installed Packages** section will then be structured as follows:
99+
100+
```
101+
├── <Package Name>
102+
│ ├── Installed Packages
103+
│ │ ├── <Installed Package>
104+
│ │ │ ├── File_1.lf
105+
│ │ │ │ ├── Rusable_Reactor_1.lf
106+
│ │ │ │ ├── Rusable_Reactor_2.lf
107+
│ │ │ ├── File_2.lf
108+
│ │ │ │ ├── Rusable_Reactor_1.lf
109+
│ │ │ │ ├── Rusable_Reactor_2.lf
110+
...
111+
```
112+
113+
In this structure:
114+
- **\<Package Name\>**: Represents the root folder of the main package.
115+
- **\<Installed Package\>**: Represents each package listed in `Lingo.toml`, which contains one or more LF projects featuring reusable reactors.
116+
117+
The image below shows a visual representation of the **Installed Packages** section. The **project** icon indicates the LF Package folder (e.g., `AudioClassification`), while the **root-folder** icon represents the downloaded package (e.g., the `edgeai` package in the example). The **code file** icon denotes an LF program within a package, and the **bracket** icon represents individual reactors inside the LF program.
118+
119+
<Image img={lingo_packages} style={{maxWidth: 400}} />
120+
121+
The hierarchy categorizes tree items into the following types:
122+
123+
1. **package root**: Refers to the root folder of each downloaded package.
124+
2. **file**: Represents an LF file within the package.
125+
3. **reactor**: Refers to individual reactors within the LF file.
126+
127+
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:
128+
129+
- For **file** items (from right to left):
130+
- **Open in Split View**: Opens the file in a split editor view.
131+
- **Go To File**: Navigates to the file in the editor.
132+
133+
- For **reactor** items (from right to left):
134+
- **Import Selected Reactor**: Imports the selected reactor into the active LF program.
135+
- **Go To File**: Opens the file where the reactor is defined.
136+
- **Open in Split View**: Opens the file in a split editor view (accessible by right-clicking the item).
137+
138+
:::note
139+
The **Import Selected Reactor** option is available only if an LF program is open in the editor.
140+
:::
141+
142+
#### Local Libraries
143+
144+
The **Local Libraries** section lists LF programs created by the developer, located in the `./src/lib/` directory. These programs serve as local libraries, containing reusable reactors. The directory structure follows this format:
145+
146+
```
147+
├── <Package Name>
148+
...
149+
│ ├── Local Libraries
150+
│ │ ├── File_1.lf
151+
│ │ │ ├── Rusable_Reactor_1.lf
152+
│ │ │ ├── Rusable_Reactor_2.lf
153+
│ │ ├── File_2.lf
154+
│ │ │ ├── Rusable_Reactor_1.lf
155+
│ │ │ ├── Rusable_Reactor_2.lf
156+
...
157+
```
158+
159+
The image below illustrates the **Local Libraries** section. In this depiction, the **"project"** icon represents the LF package folder, while the **"code file"** icon represents the LF program, and the **"bracket"** icon denotes individual reactors within the LF program.
160+
161+
<Image img={local_libraries} style={{maxWidth: 400}} />
162+
163+
The hierarchy categorizes tree items into two types:
164+
165+
1. **file**: Represents the LF file.
166+
2. **reactor**: Represents a reactor within the LF file.
167+
168+
Actions for **Local Libraries** are similar to those in the [**Installed Packages**](#installed-packages) section:
169+
170+
- For **file** items (from right to left):
171+
- **Open in Split View**: Opens the file in a split editor view.
172+
- **Go To File**: Navigates to the file in the editor.
173+
174+
- For **reactor** items (from right to left):
175+
- **Import Selected Reactor**: Imports the selected reactor into the active LF program.
176+
- **Go To File**: Opens the file where the reactor is defined.
177+
- **Open in Split View**: Opens the file in a split editor view (accessible by right-clicking the item).
178+
179+
:::note
180+
The **Import Selected Reactor** option is available only if an LF program is open in the editor.
181+
:::
182+
183+
#### Source Files
184+
185+
The **Source Files** section lists all LF programs in the `./src/` directory. This section provides direct access to the main source files of the package. The hierarchy for this view is straightforward:
186+
187+
```
188+
├── <Package Name>
189+
...
190+
│ ├── Source Files
191+
│ │ ├── File_1.lf
192+
│ │ ├── File_2.lf
193+
│ │ ├── File_3.lf
194+
...
195+
```
196+
197+
Clicking on any of the files will open the corresponding LF program in the editor, providing a way to quickly navigate and edit the source code of a package.
198+
34199
## Notes
35200

36201
### For Python Users

0 commit comments

Comments
 (0)