~xerool/luarocks-build-fennel

Teach LuaRocks how to build your Fennel rock

#1 its broken!

~xerool commented on luarocks-build-fennel todo

10 months ago
10 months ago

#Luarocks Build Fennel

Add some spice to your rocks the easy way! This package has everything you need to tell LuaRocks how to build your Fennel code! Just scroll down, copy, and adapt code from these examples; you'll have a rockspec done in no time! This fork of the builtin LuaRocks builder has you covered.

#How does is work?

Just like the builtin builder, you provide a list of every module your rock has. luarocks-build-fennel will take every file ending in .fnl and convert it to Lua using the fennel binary. Your rock needs to depend on fennel or have a copy of Fennel inside of it. Here's how a rockspec might look:

package = "your-package-here"
version = "scm-1"
source = {
  url = "your-url-here",
}
description = {
  summary = "a dummy project built with luarocks-build-fennel",
  detailed = "long description"
  homepage = "your-url-here",
  license = "MIT/X11"
}
dependencies = {
  "lua >= 5.1",

  -- add these guys :)
  "luarocks-build-fennel >= 0.1",
  "fennel >= 1.3.0",
}
build = {
  type = "fennel",    -- fennel build type! That's me!

  modules = {
    --  list of every single module you have
    ["my-project"]         = "src/my-project/init.fnl",
    ["my-project.util"]    = "src/my-project/util.fnl",
    ["my-project.foo.bar"] = "src/my-project/foo/bar.fnl",

    -- modules also support all the other stuff that build.type = "builtin"
    -- usually provides, such as Lua or C modules
    ["my-project.foo.baz"] = "src/my-project/foo/baz.lua",
    ["my-project.native"] = {
      "src/my-project/native.c",
      "src/my-project/native-extra.c",
    },
  },

  -- It probably isn't smart to share macros through LuaRocks,
  -- but here's how to do it anyway:
  macro_modules = {
    ["my-project.macros"] = "src/my-project/macros.fnl",
  }

  -- If you want to export a binary
  install = { bin = {["myprj"] = "src/my-project/runner.fnl"} }

  -- -- Set this if your rock has a local copy of fennel inside of it.
  -- -- then, the rock doesn't need to depend on "fennel"
  -- provided = true,

  -- -- luarocks-build-fennel will do its best to set the macro-path to something
  -- -- reasonable while building your rock, but if it is missing something,
  -- -- you can prepend extra stuff to the macro path here.
  -- macro_path = "foo/bar/funny/?.fnl"

}

#But my repo needs a very specific version of Fennel and you have to use the right one otherwise everything is going to break!

Hold on, calm down. Take a deep breath. If you don't think LuaRocks has what it takes to get you the right Fennel version, you're still covered. Remove the "fennel >= 1.3.0" dependency, and instead place your version of the fennel binary right in the root of your rock. Then, tell the builder to look for fennel in your rock by adding provided = true. Or, if your fennel is somewhere else in your sources, give me the path: provided = "path/to/fennel".

#Need help?

If something isn't working right, or if you're stuck and need help, ask for help in the issue tracker! You don't even need to make an account; you can send an issue by email. I'll be happy to help!

#Contributing

If there's anything that you want to add, just send me a pull request! What? This site doesn't have pull requests? Well don't worry, I'll take your contributions any way you can get them to me! Upload your version to github, or gitlab, or codeberg, or here on sr.ht, or any other code hosting site of your choice, and then send in an issue over at the issue tracker.

#Rationale

I was frustrated with the state of LuaRocks. I wanted to publish fennel-ls as a rock on LuaRocks, but it is written in Fennel.

One would expect that, since LuaRocks is a build system, it would be easy to ask LuaRocks to run fennel --compile <filename>, or even a fennel --require-as-include --compile <filename> to toss it all into a single Lua file. So, I looked up the docs of LuaRocks. LuaRocks provides this great build mode called build = "command", which looks like what I need! I tossed in a build_command = "fennel --compile --require-as-include src/fennel-ls.fnl > fennel-ls. Well, it turns out that once you commit to using build = "command", you give up on all the goodies from build = "builtin"; most importantly, a cross platform way to install the binary once it has been built. install_command = "cp fennel-ls $(BINDIR)" works great, but it unfortunately leaves Windows compatibility behind, and I don't want to do that. Since there's no way to get what I want out of LuaRocks, I had to step up and do it myself, and that's what you're looking at here: An actual usable way to package up your fennel code into rocks.