What is a good way to manage luarocks rockpec files and why?

Question

I am working on my first lua package, and I am deeply confused about what to call my rockpec and where to put it. Every popular lua package that I look at seems to deal with rockpecs differently. This is very different from, say, Ruby, where each gem has only one gemspec . Here are some examples:

• lua-cliargs : one rock root in the project root (e.g. lua_cliargs-3.0-1.rockspec )
• ldoc : one rockpec instance in the project root named scm instead of version number (e.g. ldoc-scm-2.rockspec )
• lua-MessagePack : several versions with version names stored at the top level of rockspec/ (e.g. lua-messagepack-0.1.0-1.rockspec , ... lua-messagepack-0.3.4-1.rockspec ) and then some with an additional version of lua inserted before the package version (for example, lua-messagepack-lua53-0.3.6-1.rockspec ). Sometimes for the same version of a package there are two carriage options, one of which contains lua53, and the other does not.
• luafilesystem : several versions with version names stored in the top level /rockspec (e.g. luafilesystem-1.3.0-1.rockspec , ... luafilesystem-1.6.1-1.rockspec ), and then some with cvs instead of numbers the version of the package inserted before the version of the package (for example, luafilesystem-cvs-1.rockspec , luafilesystem-cvs-2.rockspec ).
• lpeg : no rockspec at all
• luasocket : one root in the root containing scm instead of the package number (e.g. luasocket-scm-0.rockspec ), and /rockspec containing one instance with the package index (e.g. luasocket-3.0rc2-1.rockspec )

Now, this question explains why someone has a “working” rock file and a separate directory full of versions with the release of the version, but I still have a few questions:

• What are stone revisions? The wiki says that release packages should be tagged in git with a version number, and the example it gives does not include a rockpec revision. If my rockpec is in VCS and I mark a specific commit, does this not effectively eliminate the hints (s) included in that commit and therefore the version? A later revision on rockpec cannot be tagged in a tagged commit.
• How does lpeg point to luarocks but rockspec missing?
• The wiki says scm should be used instead of the package version number if you want your rockpec to reference HEAD. But since HEAD constantly changing, and rockpec should list all the files, it would seem that it would be necessary to constantly increase the revision number of the scm rockpec parameter scm order to keep up with any added or deleted files. You can get around this without using the version number at all for scm overspecs, and yet the ones I see have low revision numbers (like ldoc-scm-2.rockspec ). This is mistake?
• Are any of the above examples best practices?

Answer 1

What are stone revisions?

The rockpec version is the version of the rockpec file itself. Suppose you have released version Foo 1.0; you create rockpec foo-1.0-1.rockspec . You will learn later that to compile Foo 1.0 on FreeBSD, you need to pass the optional -D flag; the source code does not need to be changed at all. You edit rockpec by adding a platform redefinition section and resubmit it to luarocks.org as foo-1.0-2.rockspec .

If my rockpec is in VCS and I mark a specific commit, does this not effectively eliminate the hints (s) included in that commit and therefore the version?

Yes. But this is not a problem, because the rockpec used in the construction is not included in the source distribution. A .src.rock file is an archive containing the presented .rockspec file and tarball of the source code (or the source check in a subdirectory if rockpec uses SCM , for example git:// ).

In fact, this leads to a chicken and egg problem in that the last scalp for Foo 1.0 does not exist when one of the v1.0 tags manually from Github checks, but this is not an expected workflow: when using LuaRocks, the user will usually use luarocks install foo ; and if they want to check the properties of stone objects for the project, they either go to the page for Foo at luarocks.org , or they look at it stored in HEAD, where people generally stop first.

Note that a similar situation with chicken and eggs happens if you want to distribute the original tarball containing the mountain threshold, and then want to set the tarball source.url and its corresponding source.md5 to the rocky. Having MD5 implies that the crest itself cannot be inside the tarball. One way is to simply avoid the source.md5 field or skip the scalpel when packing tarball. This is the same situation as in one case it will include metadata of the Linux distribution package in the top tarball; this is more obvious here because the upstream and the packer tend to be the same person.

How can lpeg be pointed to luarocks, but it has no obstacle?

Perhaps because it is a rare case when the upstream and the packer are not the same person. Roberto Ierasulsamchii released lpeg, but as of December 2016, the races for him are loaded by Gary Vaughan.

[...] the ones I see have low revision numbers (like ldoc-scm-2.rockspec). This is mistake?

There can be many reasons for this, and it may be a mistake or not.

• If rockpec uses the built-in make , then the scm rockspec parameter scm unlikely to change when files are added or deleted;
• Some projects simply do not change their file set so often, so the revision remains low;
• Some developers save their scm parameters to -0 (as in the "unreleased version") and never upload them to luarocks.org (keeping only the released versions). So the one you get when you select a git revision is valid for this snapshot. Incrementing change is an expected practice for the swing releases released by luarocks.org ;
• The rocky threshold can be really obsolete and then a mistake.

Are any of the above examples best practices?

Objectively speaking, since the rockpec file used to execute luarocks install foo is the one contained in the .src.rock file, which is stored separately from the source archives, there are no significant practical consequences as to where in the source tree the developer stores his hints. This is a matter of personal organization.

Keeping the last scm rockpec at the root has a slight advantage in that it is automatically selected by luarocks make if you want to build from a local extracted tree.

But while the downloads are uploaded to the server using luarocks upload foo , the end-user experience will be the same, regardless of where the downloads are in the source tree.