# Rock file format

This page describes the .rock file format used by LuaRocks.

Note that there are different [types of rocks](types_of_rocks.md). 

## Filenames

* .rock and .rockspec filenames must be all-lowercase
* Rock names must follow the format "$NAME-$VERSION-$REVISION.$PLATFORM.rock", where:

 * $NAME is an arbitrary name (matchable via `"[a-z0-9_-]+"`)
 * $VERSION is a version number parseable by LuaRocks (e.g. "1.0", "2.1beta1", "scm" for git-HEAD/svn-master rockspecs)
 * $REVISION is the rockspec revision number, a positive integer
 * $PLATFORM must follow the format "$OS-$ARCH", where:

    * $OS is an operating system identifier known by LuaRocks
    * $ARCH is a hardware architecture identifier known by LuaRocks

## Source rocks

A source rock must contain at its root the rockspec file. For a rock called `myrock-1.0-1.src.rock` it would be called:

* `myrock-1.0-1.rockspec` - the [rockspec file](Rockspec format) in the archive root

Additionally, it must contain the sources:

* If the `source.url` field is specified using a file download protocol-type URL (`http://`, `https://`, `file://` and so on) pointing to the source archive (or source file in case of a single-file rock), the rock should contain the product of downloading this URL. 
  * For example, a source rock may contain two files: `myrock-1.0-1.rockspec` and `myrock-1.0.tar.gz`
* If the `source.url` field is specified using a Source Control Manager (SCM) protocol-type URL (`git://`, `hg://`, `svn://` and so on), the rock should contain the corresponding checked-out sources. The SCM metadata (e.g. the `.git` directory) does not need to be present. (Note: This is not specific to "scm" rocks that point to in-development repositories; a stable-version rockspec may use a SCM-based URL and an SCM tag with `source.tag` in the rockspec to point to a release version).
  * For example, a source rock may contain at the root the rockspec `myrock-1.0-1.rockspec` and a directory `myrock` that would be the result of `git clone https://github.com/example/myrock`

## Binary rocks

A binary rock must contain at its root two files. For a rock called `myrock-1.0-1.linux-x86.rock` they would be called:

* `myrock-1.0-1.rockspec` - the [rockspec file](Rockspec-format) in the archive root
* `rock_manifest` - a [rock manifest file](Rock-manifest-file-format)

These standard directories are handled specially:

* `lib/` - a directory containing binary modules (the contents of this directory are files that go into `$PREFIX/lib/lua/5.x/` in a vanilla Lua installation on Unix). The directory structure inside this directory is replicated when installing.
* `lua/` - a directory containing Lua modules (the contents of this directory are files that go into `$PREFIX/share/lua/5.x/` in a vanilla Lua installation on Unix). The directory structure inside this directory is replicated when installing.
* `bin/` - a directory containing executable Lua scripts (the contents of this directory are files that go into `$PREFIX/bin/` in a vanilla Lua installation on Unix) 
* `doc/` or `docs/` - documentation files - if present, their contents are listed when running `luarocks doc`. The directory structure inside this directory is replicated when installing.

Any additional directories in the .rock file are copied verbatim (including subdirectories) to `$ROCK_TREE/lib/luarocks/rocks-5.x/myrock/1.0-1/` (common directories are `tests`, `samples`, `examples`, etc.

### Pure-Lua rocks

Pure-Lua rocks are identical to binary rocks, except that they don't have a `lib/` directory containing binary modules. When a rock contains only `lua/` files and no `lib/` files, it automatically gains the `.all.rock` file extension. If the rock is platform-specific, the packager may rename the file to the proper platform, or specify the list of supported platforms in the `supported_platforms` table of the rockspec.