1 files changed, 75 insertions, 0 deletions

diff --git a/docs/luarocks_write_rockspec.md b/docs/luarocks_write_rockspec.md
new file mode 100644
index 00000000..59b3fbe0
--- /dev/null
+++ b/docs/luarocks_write_rockspec.md
@@ -0,0 +1,75 @@
+# luarocks write_rockspec
+
+Write a template for a rockspec file.
+
+## Usage
+
+`[--output=<file>] [...] [<name>] [<version>] [<url>|<path>]`
+
+This commands creates an initial version of a rockspec for a rock
+based on name, version, and location of its sources. The resulting
+rockspec is just a template: several fields, such as `dependencies`,
+have to be filled by hand.
+
+If only two arguments are given, the first one is considered the name and the
+second one is the location.
+If only one argument is given, it must be the location.
+If no arguments are given, current directory is used as location.
+LuaRocks will attempt to infer name and version if not given,
+using "scm" as default version.
+
+If location is a local directory and a Git or Mercurial repository,
+source URL will be inferred from it.
+
+Resulting rockspec is created in current directory, with file name
+based on rock name and version. Output location can be changed using `--output` option.
+
+Several fields of the rockspec can be set explicitly:
+
+* `--license=<license>` sets license name, such as `MIT/X11` (by default inferred
+  from `COPYING`, `LICENSE`, or `MIT-LICENSE.txt` files, if they exist).
+* `--summary=<text>` sets short description (by default inferred from
+  `README.md` or `README` files, if they exist).
+* `--detailed=<text>` sets detailed description (by default inferred
+  from `README.md` or `README` files, if they exist).
+* `--homepage` sets project home page URL (by default may be inferred from source URL).
+* `--lua-version=<versions>` sets supported Lua versions. `<versions>` must be one of
+  "5.1", "5.2", "5.3", "5.1,5.2", "5.2,5.3", or "5.1,5.2,5.3".
+* `--rockspec-format=<version>` sets rockspec format version.
+* `--tag=<tag>` sets tag to use. Will attempt to extract version number from it.
+* `--lib=<lib>[,<lib>]` sets libraries that C files need to link with, filling [external_dependencies](rockspec_format.md#dependency-information) table. The argument should be a comma delimited list of names.
+
+LuaRocks will attempt to fill `build` table of the rockspec using
+[builtin build back-end](rockspec_format.md#builtin), listing files from `src`
+and `lua` directories in project sources.
+
+## Example
+
+Creating an scm rockspec for a project hosted in a Git repository:
+
+```
+mkdir my-rock
+cd my-rock
+git init .
+git remote add origin https://github.com/my-username/my-rock
+luarocks write-rockspec
+```
+
+This creates `my-rock-scm-1.rockspec` file:
+
+```lua
+package = "my-rock"
+version = "scm-1"
+source = {
+   url = "git+https://github.com/my-username/my-rock"
+}
+description = {
+   homepage = "https://github.com/my-username/my-rock",
+   license = "*** please specify a license ***"
+}
+dependencies = {}
+build = {
+   type = "builtin",
+   modules = {}
+}
+```