Creating Your First Package

Getting started as a lit author is quick and easy!

Authentication

Lit uses a RSA public key system to authenticate authors and verify they created the code they are trying to publish. If you have a GitHub account and your local SSH RSA key is added to GitHub then you're ready to go. Simply run the following with your GitHub username.

lit auth yourUsername

Note

If you are using Lit in CI such as in Github Actions, make sure to provide all three arguments. This should apply to any case where standard input is not a TTY causing readline to hard fail. lit auth username name email. See this for demo.

This will download your public ssh keys from GitHub and compare their fingerprints with the fingerprint of your key at $HOME/.ssh/id_rsa.

Do note that Lit will only accept SSH keys of armor format PEM, ssh-keygen in most cases WILL NOT default to that format anymore; Furthermore you need to explicitly tell keygen which format to use through the flag -m PEM. To check if an existing public key is PEM or not, check the very first line of it where it should start with something similar to BEGIN RSA PRIVATE KEY (instead of -----BEGIN OPENSSH PRIVATE KEY-----).

If you do not already have an SSH RSA key, you can generate one using:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -m PEM

After that you need to link the generated key to your GitHub account.

You can use another private key by manually editing the key path in your local litconfig file, but it currently has to be an RSA key and is linked to your GitHub account.

See the main README for details on claiming a GitHub organization to publish to.

Create the Package

We recommend using Git to manage the source to your new package. Create a new repository on GitHub and check the create a README box and choose a license. Then clone your new empty repository down.

git clone git@github.com:creationix/mylib.git
cd mylib
tree # tree is available in most package managers for osx or linux, use dir on windows

It should look something like:

.
├── LICENSE
└── README.md

Single File Package

If you're creating a simple library that will be contained in a single file, simply create that file now.

touch mylib.lua

This file will contain metadata and library code.

--[[lit-meta
  name = "creationix/mylib"
  version = "0.0.1"
  homepage = "https://github.com/creationix/mylib"
  description = "A cool description of my lib that would show on Lit!"
  license = "MIT"
]]

function greet(name)
  print("Well hello " .. name)
end

return greet

If you're testing this library in the context of a larger project, it can live in the deps or libs folder of that project so that it's available before you publish it.

When you're ready to publish it, that can be done with:

lit publish mylib.lua

Multi-File Library

Or if you're making a larger project and want more files, create a couple files.

touch package.lua
touch init.lua

The package.lua file will contain your metadata like:

return {
  name = "creationix/mylib",
  version = "0.0.1",
  files = {
    "*.lua",
  }
}

The init.lua file will be what's loaded when someone requires your library. It needs to return something useful.

function badadd(a, b)
  return a - b
end

return badadd

Just like above, this library can be symlinked or embedded in the libs or deps folder of a project you're using to test it.

When you're ready to publish, run:

lit publish .

Make sure to point to the folder and not the package.lua file.

Lit init

Instead of having to manually create the initial structure and meta-data, you can make Lit do it for you. All you have to do is running the following:

mkdir mylib
cd mylib
lit init

This will ask you some questions, such as the name of the package, the license to use and the description, and once done it will create either a package.lua or a init.lua (depending on your choice) that contains your project's metadata, ready for your code.

Multi-File Application

Lit also makes it trivial to create single-binary executables with all resources embedded in a zip file at the end of the file.

Create the files like before, but this time, make main.lua and package.lua.

If you want Luvit's require system that knows about libs and deps, make sure to include luvit/require in your dependencies. Also adding luvit/pretty-print will create a global _G.p that pretty-prints any lua value. This is very useful for debugging.

-- package.lua
return {
  name = "creationix/myapp",
  version = "0.0.1",
  private = true, -- This prevents us from accidentally publishing this package.
  dependencies = {
    "luvit/require",
    "luvit/pretty-print",
  }
}

The main.lua file will be what's run when the executable is executed.

-- main.lua
local meta = require('./package')
print("My metadata is:")
p(meta)

To install your dependencies, simply run lit install and it will grab any missing dependencies from package.lua and install them to deps. This will not touch any existing packages in deps. If you want to later update a package, you need to either lit install some/name or delete the local version and run lit install. I will often add deps to my git ignores.

echo deps >> .gitignore

Now to run this app can be done with luvi ..

-- Run the app directly
luvi . -- arg1 arg2

The arguments are passed to main.lua as args. They are also available as ....

The return value from main.lua is the process exit code.

When you're ready to deploy your app, use lit make to compile it into a single binary.

lit make

This will import files according to the files rules in package.lua. It will also install any dependencies there. If they exist in deps those will be used, but if not, it will install from the db.

Once you publish your app (make sure to remove private = true) others can build it directly with the Lit URL.

lit publish .

Then on another machine with nothing more than lit installed, run:

lit make lit://creationix/rye

You can also install from GitHub URLs, HTTP zip URLs, and Git URLs. Note this is not available for lit install, only for lit make.

lit make github://creationix/rye
lit make https://github.com/creationix/rye.git
lit make git://github.com/creationix/rye.git
...