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.

meta.name

Required

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 the name is always the alias that will be used when lit install or lit make. For example when a package with the name creationix/long/pkg is installed, it would be located under deps/pkg. In a similar way, when lit make is used on such a package the executable name would be pkg.

Note: Sadly you cannot install two packages or more with the same alias. That is, you can upload two packages with the names creationix/component/pkg and creationix/another_component/pkg. But you will only be able to install one of them locally.

meta.version

Required

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.

meta.dependencies

Optional

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/luvit@2.0.0, 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/require@0.2.3",
  "luvit/pretty-print@0.1.1",
  "luvit/http-codec@0.1.5",
  "luvit/json@0.1.0",
  "creationix/coro-fs@1.2.3",
  "creationix/coro-tcp@1.0.4",
  "creationix/coro-http@0.1.0",
  "creationix/coro-tls@1.1.1",
  "creationix/coro-wrapper@0.1.0",
  "creationix/hex-bin@1.0.0",
  "creationix/semver@1.0.1",
  "creationix/git@0.1.1",
  "creationix/prompt@1.0.0",
  "creationix/ssh-rsa@0.1.2",
  "creationix/websocket-codec@1.0.0",
}

meta.files

Optional

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.

meta.private

Optional

When set to true, Lit will prevent any lit publish command from actually publishing the package. Useful when testing your package and don't want to accidentally publish it.

meta.obsolete

Optional

When set to true, Lit will hide the package from appearing in any search results. Useful for deprecating packages.

meta.description

Optional

A string used to show description of the package. Useful for describing the package purpose with search results.

meta.keywords

Optional

An array of strings used to get better search results and more accurate ones.

meta.tags

Optional

Table, list of strings. Description of this field to be done.

meta.homepage

Optional

A URL string of where at to find the package. Examples of this can be: the main website of the package, the Git repo of the package, the source-file of the package, etc.

meta.license

Optional

A string value describing the name of this package's license. For example: MIT, Apache License 2.0, etc.

meta.licenses

Optional

An array of strings used to describe a dual licensed package. Each string value representing a possible license of the package. For example: {"MIT", "Apache License 2.0"}, {"LGPL", "GPL"}, etc.

meta.author

Optional

Table. person {name=name, email=email, url=url}. A table structure that better represents the author of this package. Available field are:

• name: string.
• email: string.
• url: string.

An example of this structure:

--[[lit-meta
  name = "username/mylib"
  version = "0.0.1"
  author = {name = "Tim Caswell", email = "your_email@example.com", url = "my-personal-website.example.com"}
]]

meta.contributors

Optional

An array of strings documenting the names of package's contributors.

meta.luvi

Optional

Makes sure Lit uses the specified Luvi version to lit make the package. Available fields are:

• flavor: string (one of "regular", "tiny". Default "regular").
• version: string (e.x. "2.13.0", "2.9.0". Default latest).
• url: string (a template of the URL, where "%s %s %s" would result in version flavor arch. E.x https://github.com/luvit/luvi/releases/download/v%s/luvi-%s-%s).

Metadata Storage

There are three ways to embed metadata in a package. One is in the code itself by having the following comment scheme:

--[[lit-meta
  name = "creationix/happy"
  version = "1.2.3"
]]

Another way is by directly modifying the exports table as follows:

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.