1 files changed, 438 insertions, 0 deletions

diff --git a/docs/creating_a_rock.md b/docs/creating_a_rock.md
new file mode 100644
index 00000000..e93505ac
--- /dev/null
+++ b/docs/creating_a_rock.md
@@ -0,0 +1,438 @@
+# Creating a rock
+
+So, you wrote a Lua package (containing one or more modules) and want to make
+it available to users through LuaRocks. The process consists essentially of
+the following steps:
+
+* Writing a rockspec file
+* Publishing your code online
+* Submitting a rockspec for inclusion in the rocks server
+
+## Writing a rockspec
+
+A rockspec file is the metadata file for your package, containing all the
+information LuaRocks needs in order to fetch, build and install your package.
+The [Rockspec format](rockspec_format.md) supports various kinds of build
+systems, but in this tutorial we'll use LuaRocks' own built-in build system --
+that's why we're listing "Writing a rockspec" as the first step. We'll use the
+rockspec in place of a Makefile.
+
+A rockspec is actually a Lua file, but it is loaded in an empty environment,
+so there are no Lua functions available. A skeleton for a basic rockspec looks
+can be written by hand or generated using [luarocks write_rockspec](luarocks_write_rockspec.md).
+It may look like this:
+
+```lua
+package = "LuaFruits"
+version = "1.0-1"
+source = {
+   url = "..." -- We don't have one yet
+}
+description = {
+   summary = "An example for the LuaRocks tutorial.",
+   detailed = [[
+      This is an example for the LuaRocks tutorial.
+      Here we would put a detailed, typically
+      paragraph-long description.
+   ]],
+   homepage = "http://...", -- We don't have one yet
+   license = "MIT/X11" -- or whatever you like
+}
+dependencies = {
+   "lua >= 5.1, < 5.4"
+   -- If you depend on other rocks, add them here
+}
+build = {
+   -- We'll start here.
+}
+```
+
+This should be saved in a file called luafruits-1.0-1.rockspec. The name must
+contain lowercase versions of the "package" and "version" fields, or else
+LuaRocks will complain.
+
+There is some missing stuff in our rockspec which we will fill later, such as
+the source.url and description.homepage fields. We'll add those when we upload
+our sources whatever server you choose to.
+
+Right now our focus will be on the "build" section.
+
+### Building a module
+
+LuaRocks supports a number of "build types": "make" for using Makefiles,
+"cmake" for using CMake, etc. In this tutorial, however, we'll use its
+built-in build system, called the "builtin" type.
+
+```lua
+build = {
+   type = "builtin"
+   -- Now we need to tell it what to build.
+}
+```
+
+In the "builtin" type, we add a subtable called "modules", in which keys are
+module names in Lua notation, and values indicate how to build them. This
+example shows the various possibilities supported:
+
+```lua
+build = {
+   type = "builtin",
+   modules = {
+      -- A simple module written in Lua
+      apricot = "src/apricot.lua",
+
+      -- Note the required Lua syntax when listing submodules as keys
+      ["apricot.seeds"]("apricot.seeds") = "src/apricot/seeds.lua",
+
+      -- A simple module written in C
+      banana = "src/banana.c",
+
+      -- C modules can span multiple files.
+      cherry = {"src/cherry.c", "src/cherry_pie.c"},
+
+      -- C modules also support an extended syntax, supporting
+      -- cross-platform specifications of C defines, libraries and
+      -- paths for external dependencies.
+      date = {
+         sources = {"src/date.c", "src/cali_date.c", "src/arab_date.c"},
+         defines = {"MAX_DATES_PER_MEAL=50"},
+         libraries = {"date"},
+         incdirs = {"$(LIBDATE_INCDIR)"},
+         libdirs = {"$(LIBDATE_LIBDIR)"}
+      }
+   }
+}
+```
+
+Since modules written in Lua do not need to be compiled, LuaRocks only needs
+to know where they are in your source directory tree  in order to copy them to
+the proper place on installation (see the "apricot" and "apricot.seeds" in the
+above example).
+
+Similarly, for C code with no dependencies on external libraries, it suffices
+to say where the sources are and LuaRocks will invoke the appropriate compiler
+and linker for the platform. You can use a simple string value for single-file
+modules, such as the "banana" example above or an array value for multiple
+source files (as in the "cherry" example).
+
+To make writing rocks for projects with a common directory layout even easier,
+the "builtin" build type recursively copies all files and directories it finds
+in a folder called "./lua" (if it exists) to the same place as other Lua
+files.  It's almost as if an entry had been added to `modules` for every file
+in `lua`, except that the files will only be copied - files ending in ".c"
+won't be compiled.
+
+#### Depending on other rocks
+
+You can specify that your code depends on other rocks, so you can use modules
+from other rocks in your code and have them be automatically downloaded and
+installed when a user installs your rock. 
+
+Suppose we need the modules from the "luaknife" rock, in order to cut our
+fruits. But we need version later than 2.3 of luaknife, because we're using
+functions that were introduced in that version. We'll add that to our
+dependencies table:
+
+```lua
+dependencies = {
+   "lua >= 5.1, < 5.4",
+   "luaknife >= 2.3"
+}
+```
+
+Note that the dependency on Lua itself is also given in that table, and that
+it uses two constraints on its version at once: `>= 5.1` and `< 5.4`. When
+several constraints are used like this, they all have to be satisfied.
+Therefore, `lua >= 5.1, < 5.4` means that our rock supports Lua `5.1`, `5.2`,
+and `5.3`, but not yet-to-be-released `5.4`. There are a few other operators
+for specifying version constraints, see
+[Rockspec format](rockspec_format.md#dependency-information).
+
+#### C modules linking to external libraries
+
+*If your code does not use third-party libraries, you may skip this subsection.*
+
+For building C code that links to C libraries, you can use the long syntax
+given in the "date" example above, in which sources are listed in the
+"sources" subtable. You need to specify the libraries to be linked in the
+"libraries" subtable. The library name is specified in a platform-independent
+way: in the above example, `libraries={"date"}` will result in `-ldate` for
+GCC on Unix and `DATE.LIB` for MSVC on Windows. (Note that if this is not
+appropriate, the rockspec format allows [per-platform
+overrides](platform_overrides.md).) If you need to link code that uses
+libraries, you need to tell LuaRocks where to find them. You do this by adding
+a new section to the rockspec:
+
+```lua
+external_dependencies = {
+   LIBDATE = {
+      header = "libdate.h"
+   }
+}
+```
+
+Adding the "external_dependencies" table will make LuaRocks search for the
+external dependencies in its lookup path (on Unix the defaults are
+`/usr/local` and `/usr`; on Windows, which doesn't have a standard for
+development trees, you'll probably have to specify it yourself through the
+[Config file format](config_file_format.md) or the [luarocks](luarocks.md) when
+invoking "luarocks"). We give a hint to LuaRocks, the `libdate.h` header, so
+it can test whether the development package is really there (on many Linux
+distros, one needs to install "-dev" packages in order to have all headers and
+libraries needed for compilation available, so header files are a good hint).
+In this case, for example, it would look for `/usr/local/include/libdate.h`
+and `/usr/include/libdate.h` on Unix. If you (or your users) have LibDate
+installed elsewhere, it's always possible to tell LuaRocks so through the
+command-line, passing for example `LIBDATE_DIR=/opt/libdate` as an argument.
+
+When LuaRocks succeeds finding an external dependency, it creates special
+variables for it which can be used in incdirs and libdirs fields. The example
+above shows two such variables, `LIBDATE_INCDIR` and `LIBDATE_LIBDIR` being
+use. It's important to always pass those variables: if LibDate happened to be
+in the system lookup path of your compiler, compilation would succeed without
+those variables, but they would fail in a user's system where they are
+somewhere else, such as in the `LIBDATE_DIR=/opt/libdate` example given
+earlier.
+
+### Using LuaRocks as a build system
+
+Now that your build section is written, you can use LuaRocks as a build system
+and have it compile and install your code as a rock. Just type:
+
+```
+luarocks make
+```
+
+and it will do its thing. Like "make", it will look for the appropriate rules
+file (in our case, the rockspec) in the current directory and then will
+proceed to build and install the package in your rocks tree, assuming the
+sources are in the current directory as well.
+
+### Including documentation and other files
+
+In the build section you can include arbitrary files through the
+"copy_directories" table. In this table you can list directories in your rock
+that will be copied to the target rocktree during installation. 
+
+```lua
+   copy_directories = { "doc", "test" }
+```
+
+A special case for these is the "doc" directory for locally installed
+documentation. Documentation installed this way will be available on the
+target system through
+
+```
+luarocks doc ROCKNAME
+```
+
+## Publishing your code online
+
+Now, to complete the rockspec for public consumption we need to fill the
+sources.url field. For that, we need the code to be available online. We have
+two approaches for that: if you have your source code in an online repository
+such as [GitHub](GitHub)(https://github.com), you may use that directly.
+Alternatively, you can publish a tarball with the sources on the web.
+
+### Method 1: using a repository such as Github
+
+Make sure your release is tagged in your repository. Failing to use a tag will
+make LuaRocks point at your latest development code, making it a "moving
+target". LuaRocks users should be directed to a specific version of your code.
+(If you want to make a rockspec pointing at your repository's HEAD, use "scm"
+as the version number of your rockspec -- this will identify it as a rockspec
+for the "unstable" version.)
+
+In the `source.url` field, enter the URL for your repository using your SCM tool
+as the protocol. For git repositories, you don't need use the .git extension.
+Then, use the `source.tag` entry to specify your tag. For example, this is how
+our source section would look like if we hosted LuaFruits on Github:
+
+```lua
+source = {
+   url = "git://github.com/me/luafruits",
+   tag = "v1.0",
+}
+```
+
+To tag a release in Git, use the "git tag" command, and remember to pass the
+"--tags" flag to "git push":
+
+```
+git tag v1.0
+git push --tags
+```
+
+Or use GitHub's "Releases" interface.
+
+LuaRocks also supports other source control management systems, such as CVS
+(cvs://), Subversion (svn://) and Mercurial (hg://).
+
+Don't worry about deployment complications when using this method. When you
+submit a rock for inclusion in the LuaRocks repository, a .src.rock file is
+generated which contains a copy of the source code, so LuaRocks users won't
+need to have Git or any other such tool installed to use your rock.
+
+### Method 2: publishing a tarball
+
+When using a zip or tarball, by default LuaRocks expects it to contain a
+top-level directory with your code. This directory should be named the same as
+the tarball itself (but without the .zip or .tar.gz extension) and its
+recommended that this name be the lowercase name of the package with its
+version number (but without the LuaRocks revision number). If your code is
+located in a different directory, please see [Rockspec
+format](rockspec_format.md) for instructions. In our example, we should make a
+tarball with the following contents:
+
+```
+luafruits-1.0/
+luafruits-1.0/src/apricot.lua
+luafruits-1.0/src/apricot/seeds.lua
+luafruits-1.0/src/banana.c
+luafruits-1.0/src/cherry.c
+luafruits-1.0/src/cherry_pie.c
+luafruits-1.0/src/date.c
+luafruits-1.0/src/cali_date.c
+luafruits-1.0/src/arab_date.c
+```
+
+Note that the rockspec itself doesn't need to be stored in the tarball
+(actually, storing the final rockspec inside the package is a chicken-egg
+problem because rockspecs can contain the source.md5 field with a checksum of
+the tarball).
+
+It's important to note that LuaRocks does not enforce the internal structure.
+Our example only has a src/ subdirectory because the build rules listed above
+used it (we could have done without it if we wanted to). The tarball could
+contain other files as well, such as licenses and documentation. The only
+convention used here is the top level directory name, and if desired this can
+be overridden in the rockspec using the sources.dir field. So, now we pack our
+code. On Unix, for example, that would be:
+
+```
+tar czvpf luafruits-1.0.tar.gz luafruits-1.0/
+```
+
+And now we're ready to publish the tarball online. You can upload it to any
+public web server; if you need hosting space, you can use the Pages feature
+from [GitHub](GitHub)(https://github.com). Your source section would then look
+something like this:
+
+```lua
+source = {
+   url = "http://me.github.com/luafruits/luafruits-1.0.tar.gz"
+}
+```
+
+## The completed rockspec
+
+We're ready to complete our rockspec. By now it will look like this:
+
+```lua
+package = "LuaFruits"
+version = "1.0-1"
+source = {
+   url = "git://github.com/me/luafruits",
+   tag = "v1.0",
+}
+description = {
+   summary = "An example for the LuaRocks tutorial.",
+   detailed = [[
+      This is an example for the LuaRocks tutorial.
+      Here we would put a detailed, typically
+      paragraph-long description.
+   ]],
+   homepage = "http://me.github.com/luafruits",
+   license = "MIT/X11"
+}
+dependencies = {
+   "lua >= 5.1, < 5.4",
+   "luaknife >= 2.3"
+}
+external_dependencies = {
+   LIBDATE = {
+      header = "libdate.h"
+   }
+}
+build = {
+   type = "builtin",
+   modules = {
+      apricot = "src/apricot.lua",
+      ["apricot.seeds"]("apricot.seeds") = "src/apricot/seeds.lua",
+      banana = "src/banana.c",
+      cherry = {"src/cherry.c", "src/cherry_pie.c"},
+      date = {
+         sources = {"src/date.c", "src/cali_date.c", "src/arab_date.c"},
+         defines = {"MAX_DATES_PER_MEAL=50"}
+         libraries = {"date"},
+         incdirs = {"$(LIBDATE_INCDIR)"},
+         libdirs = {"$(LIBDATE_LIBDIR)"}
+      }
+   },
+   copy_directories = { "doc", "test" }
+}
+```
+
+## Submitting a rockspec for inclusion in the rocks server
+
+### Web upload
+
+This is the simplest step: just create an account at
+https://luarocks.org/register and upload your rockspec. It will automatically
+be included in the public LuaRocks repository once the mirror propagates the
+change. Users of LuaRocks >= 2.2 will be able to download your package
+immediately. We will usually publish both the .rockspec file and the
+appropriate .rock file in the server.
+
+### Pack command
+
+You can also create .rock files yourself. If you run the [luarocks
+pack](luarocks_pack.md) command on your rockspec, like this:
+
+```
+luarocks pack luafruits-1.0-1.rockspec
+```
+
+you will get a file called luafruits-1.0-1.src.rock, which contains the
+rockspec itself and your sources. Since it contains the source code, users
+won't need to use Git or whatever tool specified in source.url to fetch the
+code; it's all in the rock.
+
+If you have the rock installed in your local tree, you can also pack the
+binaries you just built:
+
+```
+luarocks pack luafruits
+```
+
+(The version is optional, latest is assumed.) This will create a file with a
+name such as luafruits-1.0-1.linux-x86.rock.
+
+### Upload command
+
+When you've verified that creating the rock works, you can upload it to the
+LuaRocks server with the [luarocks upload](luarocks_upload.md) command:
+
+```
+luarocks upload luafruits-1.0-1.rockspec --api-key=<your API key>
+```
+
+You can get an API from the [settings page of your account on the LuaRocks web
+site](https://luarocks.org/settings/api-keys).
+
+## Conclusion
+
+And we're done -- by writing a simple rules file which simply describes which
+sources compose the project and which libraries they use, we actually achieved
+a lot behind the scenes: LuaRocks takes care of using the right compiler for
+your platform (GCC? MSVC?), passing the right flags (-fpic? -shared? -bundle
+-undefined dynamic_lookup?) and checking external dependencies (/usr/lib?
+/usr/local/lib? Is it really there?). Getting all these little portability
+details right is not always easy to do on hand-written Makefiles, so that's
+why we recommend using LuaRocks's own build system whenever possible. There
+are many other features of LuaRocks we haven't covered in this tutorial
+(per-platform overrides, support for command-line scripts, etc.), but this
+should get you started.
+
+
+