Lingua Franca ‐ VS Code Extension
The idea involves displaying a Tree View within VS Code, presenting a comprehensive list of Libraries, specifically LF programs comprising multiple reactors, facilitating their seamless integration into our individual LF Programs. These libraries can originate from three sources: those crafted by the programmer within their local workspace (Local Libraries), those downloaded using Lingo Package Manager (Lingo Libraries), and those authored by other developers and accessible as GitHub repositories (Remote Libraries).
The Tree View is organized within a view container named the 'Lingua Franca Package Explorer,' featuring two (or possibly three) distinct sections:
- Local Libraries: This section showcases a catalog of Local Libraries, which are libraries personally defined by the programmer.
- Lingo Libraries: Here, you'll find a catalog of all libraries downloaded in the personal workspace using the Lingo package manager.
- Remote Libraries (to be discussed): This section displays a compilation of GitHub repositories, each linking to a specific repository housing LF Programs. These repositories contain the reactors that the developer intends to incorporate into their program.
The Local Libraries view exclusively presents a listing of LF programs defined by the user and positioned within the designated path. After creating a LF Project, developers can incorporate LF Programs, akin to libraries of reactors, into a folder located at {project_name}/lib/. The Local Libraries view will then enumerate all LF Programs within this directory, typically represented by the pattern /{project_name}/lib/*.lf (though the path specification may vary).
The view's hierarchy is structured as follows:
├── LF Project
│ ├── LF Program 1
│ │ ├── Reactor 1
│ │ └── Reactor 2
│ ├── LF Program 2
│ │ ├── Reactor 1
└── └── └── Reactor 2
The image below illustrates the Local view. In this depiction, the "root folder" icon represents the LF Project folder. The "code file" icon symbolizes the LF Program, and the "bracket" icon denotes individual reactors within the LF Program.
Within the hierarchy, Tree Items can be classified into three types:
-
root: Represents the LF Project folder. -
file: Represents the LF Program. -
reactor: Represents a reactor within the LF Program.
Upon selection, both file and reactor items offer specific actions. From right to left, for the file item, we have the "Open in Split View" and "Go To File" commands. Similarly, for the reactor item, we have the "Open in Split View" and "Import Selected Reactor" options. While the "Open in Split View" and "Go To File" commands are self-explanatory, the "Import Selected Reactor" function inserts an import statement at the beginning of our LF program. However, this action is only available if there's an LF Program open in our active VS Code editor. Otherwise, a popup notification will inform us that there is no LF Program opened.
If the developer instead of defining its own library, already found a ready-to-use LF Program on GitHub that exploit the same functionalities needed by the developer, the it can utilize the Lingo Package Manager to retrieve the remote LF Program and install it into a specified path within the developer's workspace.
Using Lingo Package Manager for GitHub Repo Downloads
To effectively utilize Lingo for downloading a remote LF Project (GitHub repo), proper installation and configuration of Lingo for your LF Project are prerequisites. Detailed guidelines for this setup can be found at the following link and on Lingo GitHub repo. Both the local and remote projects must be initialized with Lingo.
Once Lingo has been properly initialized on the local side, programmers will discover a Lingo.toml file within its folder. An example of this file is the following:
[package]
name = "firstproject"
version = "0.1.0"
[properties]
[lib]
name = "firstproject"
main = "./src/first.lf"
target = "C"
platform = "Native"
[lib.properties]
[dependencies]
library_1 = {version=">=0.1",git="https://github.com/path/to/repo.git"}
library_2 = {version="<=2.3",git="https://github.com/path/to/repo.git"}
The Lingo.toml specifies a set of libs that are executable LF programs, crucial for remote files as it directs where to find the LF program containing the reactors. These apps can be configured with additional build and target properties. Under the [dependencies] section, developers can introduce the remote GitHub repos they deem useful for their project. Once all necessary remote repos are listed, simply execute lingo build, and Lingo will initiate the download of the listed dependencies. Developers can then find the libraries in {project_name}/target/lfc_include/ (the defined path may change), now accessible in the Local view of the VS Code Extension Tree View.
View Structure
After being downloaded into the local workspace, the Lingo Libraries view is responsible for listing all the downloaded libraries, accessible at the following path: {project_name}/target/ lfc_include/*.lf (please note that the defined path may vary). The hierarchy resembles that of the Local Libraries view but introduces an additional level:
├── LF Project
│ ├── library_1
│ │ ├── LF Program 1
│ │ | ├── Reactor 1
│ │ └── └── Reactor 2
│ │ ├── LF Program 2
│ │ | ├── Reactor 1
│ │ └── └── Reactor 2
│ ├── library_2
│ │ ├── LF Program 1
│ │ | ├── Reactor 1
└── └── └── └── Reactor 2
In this structure, the 'LF Project' serves as the root LF Project, while 'LF Libraries' refer to the libraries the developer has inserted in the [dependencies] section of the .toml file. Each library functions as a conventional LF Project containing one or more LF Programs intended as libraries, i.e., they encompass lists of reactors that developers could include.
The image below illustrates the Lingo Libraries view: the 'root folder' icon represents the LF Project folder and downloaded libraries (in the picture, the 'alarm' library). The 'code file' icon symbolizes the LF Program within the downloaded library, while the 'bracket' icon denotes individual reactors within the LF Program.
Within the hierarchy, similar to the Local View, Tree Items can be categorized into three types:
-
root: Represents the LF Root Project folder and the downloaded library. -
file: Represents the LF Program within the downloaded library. -
reactor: Denotes a reactor within the LF Program.
Upon selection, both file and reactor items offer specific actions, consistent with those described in the Local Libraries view, such as "Open in Split View" and "Go To File" commands for the file item, and "Open in Split View" and "Import Selected Reactor" options for the reactor item.
The purpose of the Remote Libraries view is to provide a comprehensive list of all available libraries developed by the Lingua Franca community. The aim is to emulate platforms like Node-RED and others, which offer marketplaces showcasing a plethora of community-developed libraries that are ready-to-use.
Two potential solutions can realize this crucial feature:
- Tree View: Similar to the Local Libraries and Lingo Libraries, the Remote Libraries view presents GitHub repositories containing LF libraries in a hierarchical Tree View. These libraries can be installed using the Lingo Package Manager.
-
Web View: Envision a web page featuring an index of GitHub repositories containing LF libraries (e.g, Node-Red Library). Developers can browse and install these libraries in their projects by adding the repository link to the project's
.tomlfile. This web page could also be seamlessly integrated into the VS Code extension as a web view.
Remote Libraries: Tree View
The Remote Libraries Tree View contains a list of GitHub repositories, each linking to a specific repository housing LF Programs with the reactors the developer intends to incorporate into their program. The developer can browse into this kind of explorer, which has a hierarchical view such as the Local one.
├── GitHub Repo
│ ├── Remote LF Program 1
│ │ ├── Remote Reactor 1
│ │ └── Remote Reactor 2
│ ├── Remote LF Program 2
│ │ ├── Remote Reactor 1
└── └── └── Remote Reactor 2
As for the Local and Lingo Libraries view, also within the hierarchy of the Remote Libraries view, Tree Items can be classified into three types:
-
root: Represents the LF Project folder. -
file: Represents an LF Program file. -
reactor: Represents a reactor within an LF Program.
The primary difference between Local and Remote views lies in the available actions upon selecting each item. For instance, for file and reactor items, users can access actions like “Link To Remote File,” which instantly redirects them to the corresponding file within the GitHub Repo. Additionally, a “Documentation” command proves valuable, guiding developers to the documentation of the remote library. For reactor items specifically, a “Preview” command could be advantageous, offering developers a glimpse into the selected reactor's code.
Furthermore, the “Download” action will utilize the Lingo Package Manager to retrieve the remote LF Program and install it into a specified path within the developer's workspace. Subsequently, the downloaded LF program will be listed in the Local view of the Tree View, as it now physically resides in the developer's workspace.
The figure above illustrates the potential appearance of the Remote view. The "github" logo signifies the remote GitHub repository, while the "code file" icon represents the remote LF Program. Additionally, the "bracket" icon indicates individual remote reactors within the LF Program.
Remote Libraries: Web View
The idea, though still in its nascent stage, envisions a web page linked to the Lingua Franca website, functioning as a library browser. Community developers have the opportunity to create LF libraries and publish them for use by the wider community. Best practice entails providing documentation and examples alongside each library. Developers can browse through various libraries or search for specific ones, subsequently including the links in their project’s .toml file. Once downloaded, the remote libraries are conveniently located in a specific folder within developers’ workspaces, easily accessible through the Lingo Library View. The webpage can still be integrated into the VS Code extension as a Web View, displaying the page directly within the editor. This allows developers to conveniently browse libraries without exiting the editor, thereby enhancing productivity.
The advantages of adopting this approach are manifold, including:
-
Integration of a Search Function for Remote Libraries
Integrating a search function for remote libraries would significantly elevate the user experience. This feature could incorporate filters to sort and categorize libraries based on various criteria, such as download count, user ratings, and last update date. Such functionality empowers developers to effortlessly locate libraries that align with their specific requirements.
-
Tracking Library Updates
Users can navigate through various versions of the same library and select a specific version, enabling them to either update to the latest version or revert to a previous one if needed. This ensures users have control over their library versions, facilitating seamless management of dependencies.
-
Establish a Community for Sharing and Discussing Libraries
Finally, a community could be established where developers can share and discuss libraries. This could take the form of a forum or a chat system integrated into the web page and the web view of the VS Code extension. In this community, developers could share their experiences with different libraries, offer advice on how to use them, and help each other solve problems. This would not only make it easier for developers to find and use libraries, but also foster a sense of community and collaboration among users of the extension.
- How can we efficiently index all remote GitHub repositories containing the necessary libraries?
- Indexing plays a crucial role in enhancing the Remote view with a "Browse" function, allowing developers to seamlessly search for their desired libraries.
- How do we made the registry modular/extensible?
- Clarification of the Import syntax is essential.
- This clarity becomes particularly important when importing reactors from locally installed libraries.
- Clarification on how the "Download" action in the Remote view initiates the download process.
- Suggestion: Upon executing the action, it will append the GitHub repository to the
.tomlfile and trigger thelingo buildcommand.
- Suggestion: Upon executing the action, it will append the GitHub repository to the
- How do we deal with name collisions? (Current issue, not lingo-specific)
- Use well-known package managers (such as
pip,cargo,npm) for Lingo as well.-
When downloading remote libraries using Lingo, there might be instances where they include dependencies in the preamble that cannot be automatically installed on the developer's machine, leading to errors. These issues can be resolved by manually installing such dependencies. Some target languages have their own package managers, which can be leveraged for this purpose. One approach could be to list within the
.tomlfile of LF programs written in a target language with a package manager, the libraries used by the preamble. Upon installing these remote libraries using Lingo, the latter could employ the target's package manager to install the necessary dependencies mentioned in the preamble.// Example of .toml file that exploit this feature ... [lib.preamble] opencv numpy tensorflow ...
-