-
Notifications
You must be signed in to change notification settings - Fork 18
New blog about how to create and publish packages #295
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
base: main
Are you sure you want to change the base?
Changes from 4 commits
fca1bf0
7bdd2db
ba52b20
e20fe8d
547cef0
13cba12
715a3fd
cfb4d61
1d290d0
b07eab4
f1ac2a0
16fd2ec
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 |
---|---|---|
@@ -0,0 +1,141 @@ | ||
--- | ||
slug: packages | ||
title: Guide to Creating and Publishing a Package | ||
authors: [vinzbarbuto] | ||
tags: [packages, packaging, lingua franca, docs] | ||
--- | ||
|
||
The Lingua Franca (LF) [Package Explorer](/docs/tools/code-extension#package-explorer) is a powerful feature within the Lingua Franca VS Code extension, built to streamline package management for developers. Supporting both local and remote sources, the Package Explorer enables effortless listing and management of packages—whether defined locally by developers or installed through the Lingo Package Manager. This integration aligns with the Lingua Franca community’s vision for a collaborative and reusable ecosystem. Developers can create and publish their own packages, enabling others to easily incorporate these resources into their projects. This collaborative model not only enhances programmability and accelerates product development but also simplifies the design of complex Lingua Franca applications. | ||
|
||
{/* truncate */} | ||
|
||
In this guide, we’ll walk you through the essential steps to create and publish a package to the community repository, covering: | ||
|
||
1. [**Creating a New Package**](#creating-a-package) | ||
Get started by setting up your package with the required files and directory structure to meet Lingua Franca standards. | ||
|
||
2. [**Configuring the `Lingo.toml` File**](#configuring-the-lingotoml-file) | ||
Set up the `Lingo.toml` configuration to ensure compatibility with the Lingo Package Manager, making your package easy to download and install. | ||
|
||
3. [**Publishing to the Community Repository**](#publishing-to-the-community-repository) | ||
Learn how to publish your package to the [Lingua Franca Community Package Repository](https://github.com/lf-pkgs) to share it with the broader community. | ||
|
||
By the end of this guide, you'll have a fully configured, shareable package ready to distribute within the Lingua Franca ecosystem. | ||
|
||
## Creating a New Package | ||
You can create a new [LF package](/docs/glossary/#package) either manually by creating an [LF file](/docs/glossary/#lf-file) or by using the [Lingo Package Manager](https://github.com/lf-lang/lingo). | ||
vinzbarbuto marked this conversation as resolved.
Show resolved
Hide resolved
vinzbarbuto marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
#### 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. | ||
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. remove 2.) VS Code is not needed for this. Make people aware of 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. What should I add about 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. I'm confused about this. |
||
3. Open the terminal in this folder and run the <kbd>lingo init</kbd> command. | ||
|
||
This will set up a new LF package with the following structure: | ||
|
||
``` | ||
├── . | ||
│ ├── src/ | ||
│ │ └── Main.lf | ||
└── └── Lingo.toml # Configuration file for current package | ||
``` | ||
|
||
#### Option 2: Create a New LF File | ||
edwardalee marked this conversation as resolved.
Show resolved
Hide resolved
vinzbarbuto marked this conversation as resolved.
Show resolved
Hide resolved
|
||
1. Go to <kbd>File > New File...</kbd> 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: | ||
|
||
``` | ||
├── . | ||
│ ├── bin/ | ||
│ │ └── Foo | ||
│ ├── src/ | ||
│ │ └── Foo.lf | ||
│ ├── src-gen/ | ||
│ │ └── Foo/ | ||
... | ||
``` | ||
|
||
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. | ||
|
||
### Add `src/lib/` for Local Libraries | ||
|
||
To include local libraries, create a `lib` directory within the `src/` folder and place your LF files there. These files contain reusable reactors that can be used within the same package or, if published, in other packages via the Lingo Package Manager. This setup makes it easy to manage and reuse libraries across Lingua Franca projects. The `lib` directory should be placed alongside the `src` directory, organized as follows: | ||
vinzbarbuto marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
``` | ||
├── . | ||
│ ├── src/ | ||
│ │ ├── lib/ | ||
│ │ │ ├── private/ | ||
│ │ │ │ └── AbstractLibraryFile.lf | ||
│ │ │ ├── LibraryFile_1.lf | ||
│ │ │ └── LibraryFile_2.lf | ||
│ │ └── Foo.lf | ||
... | ||
``` | ||
|
||
In LF, there is no visibility control, meaning you cannot mark a reactor or file as `private` as in other programming languages. The `private` directory serves this purpose by containing files meant solely for internal package use. Files in this directory are hidden in the Package Explorer within the VS Code extension, making them inaccessible to other packages. The `private` directory is useful for implementing design patterns like the Abstract Factory Pattern, which provides an interface for creating families of related objects without specifying concrete classes. For example, a developer might define an `AbstractLibraryFile.lf` containing abstract reactors and implement them in various ways within different files under the `lib` directory. | ||
|
||
### Must-Follow Guidelines | ||
|
||
When creating a new package, ensure that you follow these guidelines: | ||
|
||
- **README.md**: Include a `README.md` file in the root directory. This should provide an overview of the package, its purpose, a description of the LF files in the `lib/` folder, and relevant user information. The `README.md` is essential for publishing your package to the community repository and must be kept up to date. | ||
|
||
vinzbarbuto marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- **File Naming**: Use descriptive names for files in the `lib/` directory that reflect their purpose. For example, name a file containing a reactor for different sensors as `Sensor.lf`. | ||
|
||
- **Example LF Files**: Include example LF files in the `src/` directory to demonstrate how to use the reactors in the `lib/` directory. These examples should be well-documented with comments explaining the purpose and usage of each reactor. | ||
|
||
## Configuring the `Lingo.toml` 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. @tanneberger I think we need to coordinate to provide more info about |
||
|
||
The `Lingo.toml` file is a configuration file that provides essential information about your package, such as its name, version, and dependencies. It ensures that your package is recognized and installed correctly by the Lingo Package Manager. The `Lingo.toml` file should include the following sections: | ||
|
||
- **`[package]`**: Specify the package name, description, and version. | ||
|
||
- **`[lib]`**: Define the package name, the target language used to implement the code, the main reactor (which could be one of the examples from the `src/` directory), and the platform used to build the package. | ||
|
||
Here's an example of a `Lingo.toml` file: | ||
|
||
```toml | ||
[package] | ||
name = "PackageName" | ||
version = "0.3.1" | ||
|
||
[properties] | ||
|
||
[lib] | ||
name = "PackageName" | ||
main = "./src/Main.lf" | ||
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 is not clear to me what 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. In my case, I simply added one of the several 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. @tanneberger tells me that a library should have a location entry rather than main. Unfortunately, I don’t think this is documented anywhere, so I guess this blog will become he primary documentation. Maybe you two need to get together to make this clear? |
||
target = "Python" | ||
platform = "Native" | ||
|
||
[lib.properties] | ||
|
||
[dependencies] | ||
``` | ||
|
||
The `Lingo.toml` can also include additional sections for dependencies and other purpose-specific configurations, however, these are optional and can be added as needed. | ||
|
||
## Publishing to the Community Repository | ||
|
||
Once you've created your package and configured the `Lingo.toml` file, you’re ready to publish it in the [Lingua Franca Packages](https://github.com/lf-pkgs) organization. Publishing your package here allows other developers to easily find, install, and use it in their projects. | ||
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. I think the default workflow should be the folks publish to their own (public) repo. That will already allow for the exchange of reusable libraries. Then, later on in the description we could mention the 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.
I agree with that, it will be easier to show the list of packages, and people in the community won’t need to ask to join the GitHub organization. So, in this blog, I’ll leave out all the comments about the GitHub organization for now 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. On reflection, if we do that route, we don't even need a separate organization. We could just have a |
||
|
||
To publish your package, follow these steps: | ||
|
||
1. **Push your package to your GitHub repository** | ||
Uploading your package to GitHub lets you share it with others right away, even before it becomes part of the organization. | ||
|
||
2. **Name your repository following the `<name>-<target>` scheme** | ||
Use lowercase letters and hyphens in the format `<name>-<target>` (e.g., `package-python`). The `<name>` part should be descriptive and unique, while the `<target>` should be the target language for the package. | ||
|
||
3. **Include the name of the current maintainer in the repository description.** | ||
This helps others know who to contact if they have questions or need assistance. | ||
|
||
3. **Request membership in the Lingua Franca Packages organization** | ||
To join the organization, reach out to the Lingua Franca Packages [owners](https://github.com/orgs/lf-pkgs/people) with a brief overview of your package. This message should include: | ||
- **Motivations**: Describe why you created the package and what problems it solves. | ||
- **Usage**: Outline how others can use the package, highlighting key features or functionalities. | ||
- **Relevant Links**: Include a link to the repository (essential) along with any other resources, such as documentation, demos, or example projects that showcase the package in action. | ||
|
||
This information will help the organization understand the value of your package and how it contributes to the Lingua Franca community. | ||
|
||
4. **Transfer your repository to the Lingua Franca Packages organization** | ||
Once you're a member, transfer your repository to the organization to make it available to the broader community. |
Uh oh!
There was an error while loading. Please reload this page.