Skip to content

Commit 3c69580

Browse files
committed
Added 'Create New Project' section; uniformed the use of 'package' instead of 'project'
1 parent 203e8b3 commit 3c69580

File tree

1 file changed

+53
-26
lines changed

1 file changed

+53
-26
lines changed

docs/tools/code-extension.mdx

Lines changed: 53 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -12,39 +12,66 @@ The Lingua Franca extension for Visual Studio Code (VS Code) provides syntax-dir
1212

1313
## Usage
1414

15-
### Creating a new file
15+
### Creating a New Package
1616

17-
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:
17+
You can create a new LF package either manually by creating an LF file or by using the [Lingo Package Manager](https://github.com/lf-lang/lingo).
18+
19+
#### Option 1: Manually Create an LF File
20+
1. Go to <kbd>File > New File...</kbd> and select `New Lingua Franca File`.
21+
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:
1822

1923
```
20-
bin/Foo
21-
src/
22-
└ Foo.lf
23-
src-gen/Foo
24+
├── LF Package
25+
│ ├── bin/
26+
│ │ └── Foo
27+
│ ├── src/
28+
│ │ └── Foo.lf
29+
│ ├── src-gen/
30+
│ │ ├── Foo/
31+
...
2432
```
2533

26-
:::note
27-
We recommend selecting the root of your Lingua Franca package as your workspace in VS Code. This will enable the package explorer.
28-
:::
34+
Additionally, it's important to manually create the `Lingo.toml` file 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.
35+
36+
#### Option 2: Create an LF Package Using the Lingo Package Manager
37+
1. After installing and configuring the Lingo Package Manager, create an empty folder with the desired name for the LF package.
38+
2. Open the folder in VS Code.
39+
3. Open the terminal in this folder and run the <kbd>lingo init</kbd> command.
40+
41+
This will set up a new LF package with the following structure:
42+
43+
```
44+
├── LF Package
45+
│ ├── src/
46+
│ │ └── Main.lf
47+
└── └── Lingo.toml # Configuration file for current package
48+
```
49+
50+
### Opening an Existing LF package
51+
52+
To open an existing LF package in VS Code, select the root directory of your Lingua Franca package as your workspace.
53+
54+
The correct structure of the LF package should look like this:
2955

3056
```
3157
├── root
3258
│ ├── bin/
3359
│ ├── build/ # directory containing packages installed by Lingo Package Manager
3460
│ │ ├── lfc_include/ # Directory for storing reusable reactors
35-
│ │ │ ├── installed_library/
61+
│ │ └── └── installed_library/
3662
│ ├── include/
3763
│ ├── src/
3864
│ │ ├── lib/ # Directory for storing reusable reactors
3965
│ │ │ ├── Input.lf # Ex: reactor capturing external inputs (e.g., Microphone, Camera)
40-
│ │ └── ComputerVision.lf # Ex: reactor performing computer vision tasks (e.g., object detection, face recognition)
66+
│ │ └── └── ComputerVision.lf # Ex: reactor performing computer vision tasks (e.g., object detection, face recognition)
4167
└── └── Lingo.toml # Configuration file for Lingo Package Manager
4268
```
43-
If the project structure deviates from the expected format, an error message will appear:
69+
70+
To correctly enable the [Package Explorer](#package-explorer), we recommend opening VS Code with the true root of your Lingua Franca package as your workspace. If the package structure deviates from the expected format, an error message will appear when opening the Package Explorer:
4471

4572
<Image img={error_message} style={{maxWidth: 400}} />
4673

47-
### Rendering diagrams
74+
### Rendering Diagrams
4875

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

@@ -62,7 +89,7 @@ Running the code can also be done from the VS Code terminal by executing the gen
6289
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:
6390

6491
```
65-
├── LF Project
92+
├── LF Package
6693
│ ├── Installed Packages
6794
│ ├── Local Libraries
6895
└── └── Source Files
@@ -74,9 +101,9 @@ The **Lingua Franca Package Explorer** can be accessed by clicking on the **LF i
74101

75102
- [**Source Files**](#source-files): Contains the LF source files created by the developer, located in the `src` directory.
76103

77-
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.
104+
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.
78105

79-
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.
106+
Hovering over the **LF Package** 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.
80107

81108
#### Installed Packages
82109

@@ -86,10 +113,10 @@ To install libraries:
86113
1. Configure the `Lingo.toml` file with the desired libraries.
87114
2. Run `lingo build` to download the specified dependencies.
88115

89-
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:
116+
Once the libraries are installed, they will appear in the `{package_name}/build/lfc_include/` directory. The **Installed Packages** section will then be structured as follows:
90117

91118
```
92-
├── LF Project
119+
├── LF Package
93120
│ ├── Installed Packages
94121
│ │ ├── installed_library/
95122
│ │ │ ├── File_1.lf
@@ -102,10 +129,10 @@ Once the libraries are installed, they will appear in the `{project_name}/build/
102129
```
103130

104131
In this structure:
105-
- **LF Project**: Represents the root folder of the main project.
132+
- **LF Package**: Represents the root folder of the main package.
106133
- **installed_library**: Represents each library listed in `Lingo.toml`, which contains one or more LF programs featuring reusable reactors.
107134

108-
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.
135+
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 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.
109136

110137
<Image img={lingo_packages} style={{maxWidth: 400}} />
111138

@@ -132,10 +159,10 @@ The **Import Selected Reactor** option is available only if an LF program is ope
132159

133160
#### Local Libraries
134161

135-
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:
162+
The **Local Libraries** section lists LF programs created by the developer, located in the `{package_name}/src/lib/` directory. These programs serve as local libraries, containing reusable reactors. The directory structure follows this format:
136163

137164
```
138-
├── LF Project
165+
├── LF Package
139166
...
140167
│ ├── Local Libraries
141168
│ │ ├── File_1.lf
@@ -147,7 +174,7 @@ The **Local Libraries** section lists LF programs created by the developer, loca
147174
...
148175
```
149176

150-
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.
177+
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.
151178

152179
<Image img={local_libraries} style={{maxWidth: 400}} />
153180

@@ -173,10 +200,10 @@ The **Import Selected Reactor** option is available only if an LF program is ope
173200

174201
#### Source Files
175202

176-
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:
203+
The **Source Files** section lists all LF programs in the `{package_name}/src/` directory. This section provides direct access to the main source files of the package. The hierarchy for this view is straightforward:
177204

178205
```
179-
├── LF Project
206+
├── LF Package
180207
...
181208
│ ├── Local Libraries
182209
│ │ ├── File_1.lf
@@ -185,7 +212,7 @@ The **Source Files** section lists all LF programs in the `{project_name}/src/`
185212
...
186213
```
187214

188-
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.
215+
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 package.
189216

190217
## Notes
191218

0 commit comments

Comments
 (0)