1 files changed, 198 insertions, 0 deletions

diff --git a/docs/using_luarocks.md b/docs/using_luarocks.md
new file mode 100644
index 00000000..c65ef432
--- /dev/null
+++ b/docs/using_luarocks.md
@@ -0,0 +1,198 @@
+# Using LuaRocks
+
+So, you have followed the installation instructions (either on
+[Unix](installation_instructions_for_unix.md) or
+[Windows](installation_instructions_for_windows.md)) and now you have LuaRocks
+installed on your machine. Now you probably want to install some rocks
+(packages containing Lua modules) and use them in your Lua code. 
+
+For LuaRocks to function properly, we have a quick checklist to go through
+first:
+
+# Command-line tools (and the system path) 
+
+LuaRocks installs some command-line tools which are your interface for
+managing your rocks: [luarocks](luarocks.md) and
+[luarocks-admin](luarocks_admin.md). Make sure the directory where they are
+located is in your PATH -- the exact location depends on the flags you gave
+when installing LuaRocks.
+
+Run [luarocks](luarocks.md) to see the available commands:
+
+```
+luarocks 
+```
+
+You can get help on any command by using the [luarocks help](luarocks_help.md) command:
+
+```
+luarocks help install
+```
+
+Installing packages is done by typing commands such as:
+
+```
+luarocks install dkjson
+```
+
+# Rocks trees and the Lua libraries path 
+
+When you install rocks using the `luarocks install`, you get new modules
+available for loading via `require()` from Lua. For example, after we install
+the dkjson rock, type `luarocks show dkjson` to show the module installed by
+the rock:
+
+```
+luarocks show dkjson
+```
+
+This should output something like this:
+
+```
+dkjson 2.5-2 - David Kolf's JSON module for Lua
+  
+dkjson is a module for encoding and decoding JSON data. It supports UTF-8.
+  
+JSON (JavaScript Object Notation) is a format for serializing data based on the
+syntax for JavaScript data structures.
+  
+dkjson is written in Lua without any dependencies, but when LPeg is available
+dkjson uses it to speed up decoding.
+  
+License:        MIT/X11
+Homepage:       http://dkolf.de/src/dkjson-lua.fsl/
+Installed in:   /usr/local
+  
+Modules:
+        dkjson (/usr/local/share/lua/5.3/dkjson.lua)
+```
+
+It presents a short description of the rock, its license, and the list of
+modules it provides (in this case, only one, `dkjson`). Note that "Installed
+in:" shows the directory tree where the rock was installed. This is the "rocks
+tree" in use.
+
+Most LuaRocks installations will feature two rocks trees:
+
+* "system" [rock tree](rocks_repositories.md) (used by default)
+* "user" [rock tree](rocks_repositories.md)
+
+To be able to use the module, we need to make sure that Lua can find that
+dkjson.lua file when we run `require("dkjson")`. You can check your Lua paths
+from the Lua environment, using
+
+```
+print(package.path)
+print(package.cpath)
+```
+
+These variables can be pre-configured from outside Lua, using the LUA_PATH and
+LUA_CPATH environment variables. 
+
+If you installed both Lua and LuaRocks in their default directories
+(/usr/local on Linux and Mac OSX), then the "system" tree is /usr/local and it
+will work by default. However, the "user" tree (for installing rocks without
+admin privileges) is not detected by Lua by default. For that we'll need to
+configure these environment variables.
+
+LuaRocks offers a semi-automated way to do this. If you type the following
+command:
+
+```
+luarocks path --bin
+```
+
+...it will print commands suitable for your platform for setting up your
+environment. On typical Unix terminal environments, you can type this:
+
+```
+eval "$(luarocks path --bin)"
+```
+
+and it apply the changes, temporarily, to your shell. To have these variables
+set permanently, you have to configure the environment variables to your shell
+configuration (for example, by adding the above line to your `.bashrc` file if
+your shell is Bash).
+
+# Multiple versions using the LuaRocks package loader 
+
+If you want to make use of LuaRocks' support for multiple installed versions
+of modules, you need to load a custom package loader: luarocks.loader.
+
+You should be able to launch the Lua interpreter with the LuaRocks-enabled
+loader by typing:
+
+```
+lua -lluarocks.loader
+```
+
+Alternatively, you can load the LuaRocks module loader from Lua by issuing
+this command:
+
+```
+require "luarocks.loader"
+```
+
+If your system is correctly set up so that this command runs with no errors,
+subsequent calls to `require()` are LuaRocks-aware and the exact version of
+each module will be determined based on the dependency tree of previously
+loaded modules. 
+
+# Scripts installed by rocks (and the scripts path) 
+
+Besides modules, rocks can also install command-line scripts. The default
+location of this directory (unless you configured your local repository
+differently) is /usr/local/bin for system-wide installs and ~/.luarocks/bin
+for per-user installs on Unix and %APPDATA%/luarocks/bin on Windows -- make
+sure it is in your PATH as well.
+
+If you use the `--bin` argument in `luarocks path`, it will also print the
+appropriate PATH configuration:
+
+```
+luarocks path --bin
+```
+
+# Using in Unix systems with sudo 
+
+When you use LuaRocks to install a package while you aren't root, the package
+will get installed in $HOME/.luarocks/ instead of the system-wide (by default,
+/usr/local/) and become only available for you. Moreover Lua doesn't know with
+its default setup that packages can be available in the current user's home.
+If you want to install a package available for all users, you should run it as
+superuser, typically using sudo.
+
+For example:
+
+```
+sudo luarocks install stdlib
+```
+
+After that, some files may not have correct permissions. For example, if
+/usr/local/share/lua/5.1/base.lua is only readable by root user, you should at
+least set them to readable for all users (chmod a+r or chmod 644).
+
+For example:
+
+```
+cd /usr/local/share/lua/5.1
+ sudo chmod a+r *
+```
+
+# Using a C compiler 
+
+Because rocks are generally available in the repository as [source
+rocks](types_of_rocks.md) rather than binary rocks, it is best to have a C
+compiler available.
+
+On Windows, MinGW and Microsoft compilers are supported. The compiler should
+be in the system path, or explicitly configured in the LuaRocks config files.
+On Windows systems, one way of getting the compiler in the system path is to
+open the appropriate command prompt as configured by your compiler package
+(for example, the MSVC Command Prompt for Visual Studio).
+
+Note that for compiling binary rocks that have dependencies on other
+libraries, LuaRocks needs to be able to find [external
+dependencies](paths_and_external_dependencies.md).
+
+