From 0b893299b21b927e5d0d73a094b04b778fb4c3e0 Mon Sep 17 00:00:00 2001 From: vinzbarbuto Date: Mon, 28 Oct 2024 19:24:35 -0700 Subject: [PATCH] Improved documentation; Moved Project Structure to Glossary page --- docs/glossary/glossary.mdx | 42 ++++++++++++++++++++++++++++---- docs/tools/code-extension.mdx | 45 ++++++++++------------------------- 2 files changed, 50 insertions(+), 37 deletions(-) diff --git a/docs/glossary/glossary.mdx b/docs/glossary/glossary.mdx index db1745d8b..694530a69 100644 --- a/docs/glossary/glossary.mdx +++ b/docs/glossary/glossary.mdx @@ -10,17 +10,49 @@ Glossary of terms used in the Lingua Franca (LF) documentation. ### LF File A source file with the `.lf` extension, representing a Lingua Franca (LF) program. +### Library File +An LF file containing one or more reactors intended for reuse, designed to be imported into other LF files. + ### Package 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. +### Package Manager +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. + ### Package Root The **package root** is the top-level directory of a package where both the `Lingo.toml` file and the `src/` directory reside. ### Project 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]. -### Library File -An LF file containing one or more reactors intended for reuse, designed to be imported into other LF files. - -### Package Manager -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. \ No newline at end of file +### Project Structure +The structure of an LF project should follow the directory layout below: + +``` +├── . +│ ├── bin/ # Directory for storing generated code +│ ├── build/ # Directory containing packages installed by the Lingo Package Manager +│ │ ├── lfc_include/ # Directory for storing reusable reactors +│ │ └── / # Directory containing the installed package +│ ├── include/ # Directory for storing header files +│ ├── src/ # Directory containing LF source files +│ │ ├── 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) +│ │ └── Main.lf # Ex: main source file +└── └── Lingo.toml # Configuration file for Lingo Package Manager +``` + +- **Mandatory Directories and Files:** + - `src/`: This folder must contain at least one `.lf` source file. + - `Lingo.toml`: This is the required configuration file. + +- **Automatically Generated Directories:** + - `bin/`: This directory is created during the build process of source files. It is used to store generated code. + - `build/`: This folder is automatically generated when installing packages managed by the Lingo Package Manager. + - `include/`: This directory is autogenerated for header files. + +- **User-Created Directory:** + - `src/lib/`: This folder is for library files and should be created by the user as necessary. + +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. \ No newline at end of file diff --git a/docs/tools/code-extension.mdx b/docs/tools/code-extension.mdx index 5d726f51f..cbb8d7f9a 100644 --- a/docs/tools/code-extension.mdx +++ b/docs/tools/code-extension.mdx @@ -16,7 +16,7 @@ The Lingua Franca extension for Visual Studio Code (VS Code) provides syntax-dir 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). -#### Option 1: Create an Project Using the Lingo Package Manager +#### Option 1: Create a Project Using the Lingo Package Manager 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. 2. Open the folder in VS Code. 3. Open the terminal in this folder and run the lingo init command. @@ -30,7 +30,7 @@ This will set up a new LF package with the following structure: └── └── Lingo.toml # Configuration file for current package ``` -#### Option 2: Create a new [LF File](../glossary/glossary.mdx#lf-file) +#### Option 2: Create a New [LF File](../glossary/glossary.mdx#lf-file) 1. Go to File > New File... and select `New Lingua Franca File`. 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: @@ -47,28 +47,9 @@ This will set up a new LF package with the following structure: 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. -### Opening an Existing LF project +### Opening an Existing LF Project -To open an existing LF project in VS Code, select the [package root](../glossary/glossary.mdx#package-root) as your workspace. - -The correct structure of the LF package should look like this: - -``` -├── . -│ ├── bin/ -│ ├── build/ # directory containing packages installed by Lingo Package Manager -│ │ ├── lfc_include/ # Directory for storing reusable reactors -│ │ └── └── installed_package/ -│ ├── 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) -│ │ └── Main.lf # Ex: main source file -└── └── Lingo.toml # Configuration file for Lingo Package Manager -``` - -To enable the [Package Explorer](#package-explorer), the workspace of your VS Code editor must be the root of a Lingua Franca package. If the workspace is not recognized as a valid Lingua Franca package, an error message will appear when opening the Package Explorer: +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: @@ -119,7 +100,7 @@ Once the packages are installed, they will appear in the `./build/lfc_include/` ``` ├── │ ├── Installed Packages -│ │ ├── installed_package/ +│ │ ├── │ │ │ ├── File_1.lf │ │ │ │ ├── Rusable_Reactor_1.lf │ │ │ │ ├── Rusable_Reactor_2.lf @@ -131,7 +112,7 @@ Once the packages are installed, they will appear in the `./build/lfc_include/` In this structure: - **\**: Represents the root folder of the main package. -- ****: Represents each package listed in `Lingo.toml`, which contains one or more LF projects featuring reusable reactors. +- **\**: Represents each package listed in `Lingo.toml`, which contains one or more LF projects featuring reusable reactors. 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. @@ -139,9 +120,9 @@ The image below shows a visual representation of the **Installed Packages** sect The hierarchy categorizes tree items into the following types: -1. **`package-root`**: Refers to the root folder of each downloaded package. -2. **`file`**: Represents an LF program within the package. -3. **`reactor`**: Refers to individual reactors within the LF program. +1. **package-root**: Refers to the root folder of each downloaded package. +2. **file**: Represents an LF file within the package. +3. **reactor**: Refers to individual reactors within the LF file. 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: @@ -170,8 +151,8 @@ The **Local Libraries** section lists LF programs created by the developer, loca │ │ │ ├── Rusable_Reactor_1.lf │ │ │ ├── Rusable_Reactor_2.lf │ │ ├── File_2.lf -│ │ │ │ ├── Rusable_Reactor_1.lf -│ │ │ │ ├── Rusable_Reactor_2.lf +│ │ │ ├── Rusable_Reactor_1.lf +│ │ │ ├── Rusable_Reactor_2.lf ... ``` @@ -181,8 +162,8 @@ The image below illustrates the **Local Libraries** section. In this depiction, The hierarchy categorizes tree items into two types: -1. **`file`**: Represents the LF program. -2. **`reactor`**: Represents a reactor within the LF program. +1. **file**: Represents the LF file. +2. **reactor**: Represents a reactor within the LF file. Actions for **Local Libraries** are similar to those in the [**Installed Packages**](#installed-packages) section: