New blog about how to create and publish packages #295
Conversation
blog/2024-11-11-package.md
Outdated
|
|
||
| ## 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.
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 lf-pkgs organization and getting people's repos transfered. I'm actually starting to doubt that this is the right approach at all. I think it might be better to have a lf-lang/pkgs repo with a single text file that lists all the repos. That would be super easy to build a little website around where people can search for packages (or a feature in VS Code, for that matter). In the near term, adding a package would just amount to adding the repo URL, and it would not require transferring ownership. Ownership transfer is tedious because anyone who transfers ownership would have to be a member of the lf-lang organization, which has paid seats, so this won't scale. Perhaps this blog should just omit these details? Also tagging @tanneberger for feedback on this.
There was a problem hiding this comment.
I think it might be better to have a lf-lang/pkgs repo with a single text file that lists all the repos.
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.
On reflection, if we do that route, we don't even need a separate organization. We could just have a lf-lang/pkgs repo.
| 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). |
There was a problem hiding this comment.
I would recommend against manually setting up a LF project/package.
And a single LF file does not classify as a package.
There was a problem hiding this comment.
Yes, I can add (recommended) next to Option 1, which involves using Lingo.
And a single LF file does not classify as a package.
That’s correct. In fact, there is already a link to the Glossary explaining what an LF file is. However, it serves as the starting point for creating a package, which should include additional elements (there is a definition for LF package too in the Glossary)
blog/2024-11-11-package.md
Outdated
|
|
||
| #### 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.
remove 2.) VS Code is not needed for this.
Make people aware of --platform and --language
There was a problem hiding this comment.
What should I add about --platform and --language here?
There was a problem hiding this comment.
I'm confused about this. --platform and --language are not documented anywhere that I could find. They are not accepted as command-line options to lingo.
There was a problem hiding this comment.
There is a key piece of information missing here, which is how to use a package. Where would I find that information?
Also, I think the docs can be simplified quite a bit by
- not assuming VS Code. I.e., don't say "Go to File > New File... and select
New Lingua Franca File." Just say "Create a Lingua Franca file". - Give instructions only for using cargo, not manually.
I think these will result in a considerably shorter text.
| 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). |
There was a problem hiding this comment.
| 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). | |
| You can create a new [LF package](/docs/glossary/#package) using the [Lingo Package Manager](https://github.com/lf-lang/lingo) (recommended) or manually by creating the required files. |
| └── └── Lingo.toml # Configuration file for current package | ||
| ``` | ||
|
|
||
| #### Option 2: Create a New LF File |
There was a problem hiding this comment.
| #### Option 2: Create a New LF File | |
| #### Option 2: Manually Create the Required Files |
| 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. | ||
|
|
There was a problem hiding this comment.
| - **LICENSE**: A text file giving the license terms for the package. |
|
|
||
| [lib] | ||
| name = "PackageName" | ||
| main = "./src/Main.lf" |
There was a problem hiding this comment.
It is not clear to me what main should be for a library. Typically, a library will have multiple example programs illustrating the use of the library. What file should this point to?
This PR proposes adding a blog post to the website that explains how to create and publish a package to fully leverage the potential of the Lingua Franca Package Explorer in VS Code extension