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

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

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 repo on github and check the create a README box and choose a license. Then clone your new empty repo down.

git clone [email protected]: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.

exports.name = "creationix/mylib"
exports.version = "0.0.1"

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

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 export something useful.

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

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.

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.

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