-
Notifications
You must be signed in to change notification settings - Fork 0
Package Metadata
All packages managed by lit have metadata in the form of a lua table. This data is free-form and only a few parameters are meaningful to lit.
The first required field is the name field. This will contain something like creationix/git or luvit/luvit, or even crazybob/this/is/long. The only requirement is that the first segment in the path is the owner of the package. It can be an individual github username or a github organization. In the case of an organization you have to claim the org on lit to publish to it.
The last part of this is also uses as the fallback target when creating executibles with lit make.
All packages have a 3-part semver version. Examples are 0.1.2, 2.3.12, or 0.0.100. The numbers do have meaning to lit as it automatically will match to the "best" version when matching dependencies. The basic algorithm is to match the first non-zero number exactly, the next number must be greater or equal, and if there is a third, any will match with preference for the largest.
A project could have history like this:
-
0.0.1- Initial alpha version -
0.0.2- Major refactor -
0.1.0- Starting to get stable -
0.1.1- Tiny bug fix to last release. -
0.2.0- Breaking API change -
1.0.0- Ready for public consumption -
1.0.1- Minor fix again, no new features -
1.1.0- New features added, but nothing breaking -
2.0.0- Breaking changes were introduced...
If these were the versions installed in the database and you asked lit to install version 1.0.1 it would grab 1.1.0. If you asked for 0.0.1 it would only grab 0.0.1. Version 0.1.0 would map to 0.1.1. In this list there are only a few possible versions to use as some strictly replace others.
The active versions are: 0.0.1, 0.0.2, 0.1.1, 0.2.0, 1.1.0, and 2.0.0. When syncing with an upstream, lit will only download the active versions since they will always be preferred over the older versions in each series.
If your app or library depends on other packages, this is where you declare it. Please use the full name including the author. Valid strings include things like luvit/[email protected], luvit/require, and luvit/pretty-print. The version is optional. If it's present it will match the newest in that series as described above, but if no version is specified, the newest overall is used.
The dependencies list is stored as a table of strings.
dependencies = {
"luvit/[email protected]",
"luvit/[email protected]",
"luvit/[email protected]",
"luvit/[email protected]",
"creationix/[email protected]",
"creationix/[email protected]",
"creationix/[email protected]",
"creationix/[email protected]",
"creationix/[email protected]",
"creationix/[email protected]",
"creationix/[email protected]",
"creationix/[email protected]",
"creationix/[email protected]",
"creationix/[email protected]",
"creationix/[email protected]",
}When publishing, you usually don't want to include all the files in your source code tree. This field lets you specify a set of rules to act as a white-list or black-list. (if the first rule is positive, it's a white-list, of negative, a black-list). There are also some special variables $OS and $ARCH useful in publishing platform dependent binaries. See for more details on how to use these.
The filter will walk all trees by default, even if no file in those trees matches, so if you have some large folders you wish to ignore, add them as negative rules like !docs or !tests.
For a lua module, a good positive rule is usually **.lua which will include all lua files in all walked trees.
The rules are evaluated in order so that lower down rules have higher precedence.
The following set of rules:
files = {
"**.lua",
"!docs",
"!tests",
}Will match libs/foo.lua and package.lua and init.lua, but not tests/run.lua. Since the first rule is a positive rule, this is a white-list and any files not matched by any of these rules will also be ignored. So it won't include README.md or LICENSE.
Do note that there is a big difference between ** and *. The former will match anything including path separators while the single asterisk will only match the folder specified. *.lua will match main.lua, but not libs/apple.lua. All rules match to absolute paths relative to the package.lua containing the rules list.
There are two ways to embed metadata in a package. One is in the code itself as modifications to the exports table first thing in the file.
exports.name = "creationix/happy"
exports.version = "1.2.3"
local app = require('super-app')
...The metadata scanner will evaluate the lua code in a sandbox that bails on the first error. Since require isn't defined in this sandbox, this usually means till your first require.
Using this format, you can publish single-file packages to lit. When publishing or adding them, simply point to the lua file directly lit publish happy.lua.
If the package is a folder, then lit will search for package.lua first and then init.lua if that's not found.
Generally init.lua will be your main exports and contain code and have exports embedded at the top just like single-file packages. But since package.lua is used exclusively for lit metadata, it's format is generally:
return {
name = "creationix/happy",
version = "1.2.3",
...
}If your file returns without throwing an error in the sandbox and returns a table value, then this will be used instead of the passed exports table.