1 files changed, 51 insertions, 0 deletions

diff --git a/docs/rock_file_format.md b/docs/rock_file_format.md
new file mode 100644
index 00000000..10748bde
--- /dev/null
+++ b/docs/rock_file_format.md
@@ -0,0 +1,51 @@
+# 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.