diff options
| -rw-r--r-- | docs/luarocks.md | 135 |
1 files changed, 50 insertions, 85 deletions
diff --git a/docs/luarocks.md b/docs/luarocks.md index 6338743b..99dff011 100644 --- a/docs/luarocks.md +++ b/docs/luarocks.md | |||
| @@ -2,101 +2,66 @@ | |||
| 2 | 2 | ||
| 3 | **luarocks** is the command-line interface for LuaRocks, the Lua package manager. | 3 | **luarocks** is the command-line interface for LuaRocks, the Lua package manager. |
| 4 | 4 | ||
| 5 | # Usage | 5 | ## Usage |
| 6 | 6 | ||
| 7 | ``` | 7 | ``` |
| 8 | luarocks [--server=<server> | --only-server=<server>] [--tree=<tree>] [--only-sources=<url>] [--deps-mode=<mode>] [<VAR>=<VALUE>]... <command> [<argument>] | 8 | luarocks [--server=<server> | --only-server=<server>] [--tree=<tree>] [--only-sources=<url>] [--deps-mode=<mode>] [<VAR>=<VALUE>]... <command> [<argument>] |
| 9 | ``` | 9 | ``` |
| 10 | 10 | ||
| 11 | Variables from the "variables" table of the [configuration file](config_file_format.md) can be overriden with VAR=VALUE assignments. | 11 | Variables from the "variables" table of the [configuration file](config_file_format.md) can be overridden with `VAR=VALUE` assignments. |
| 12 | 12 | ||
| 13 | {| | 13 | ### Options |
| 14 | | --server=_server_ || Fetch rocks/rockspecs from this server (takes priority over config file) | ||
| 15 | |- | ||
| 16 | | --only-server=_server_ || Fetch rocks/rockspecs from this server only (overrides any entries in the config file) | ||
| 17 | |- | ||
| 18 | | --only-sources=_url_ || Restrict downloads of sources to URLs starting with the given URL. For example, --only-sources=https://luarocks.org will allow LuaRocks to download sources only if the URL given in the rockspec starts with https://luarocks.org . | ||
| 19 | |- | ||
| 20 | | --tree=_tree_ || Which tree to operate on. | ||
| 21 | |- | ||
| 22 | | --local || Use the tree in the user's home directory. To enable it, see `[luarocks path](luarocks_path.md)` | ||
| 23 | |- | ||
| 24 | | --deps-mode=_mode_ || Select dependencies mode: | ||
| 25 | 14 | ||
| 26 | How to handle the list of rocks servers given in the rocks_servers array in the [config file](config_file_format.md). | 15 | - `--server=<server>`: Fetch rocks/rockspecs from this server (takes priority over config file). |
| 16 | - `--only-server=<server>`: Fetch rocks/rockspecs from this server only (overrides any entries in the config file). | ||
| 17 | - `--only-sources=<url>`: Restrict downloads of sources to URLs starting with the given URL. For example, `--only-sources=https://luarocks.org` will allow LuaRocks to download sources only if the URL given in the rockspec starts with `https://luarocks.org`. | ||
| 18 | - `--tree=<tree>`: Which tree to operate on. | ||
| 19 | - `--local`: Use the tree in the user's home directory. To enable it, see [`luarocks path`](luarocks_path.md). | ||
| 20 | - `--deps-mode=<mode>`: Select dependencies mode: | ||
| 21 | - **one**: Consider only the tree at the top of the list (possibly, the one given by the `--tree` flag, overriding all entries from `rocks_trees`). | ||
| 22 | - **all**: Consider all trees: if a dependency is installed in any tree of the `rocks_trees` list, we have a positive match. | ||
| 23 | - **order**: Consider only trees starting from the "current" one in the order, where the "current" is either: | ||
| 24 | - the one at the bottom of the `rocks_trees` list, | ||
| 25 | - or one explicitly given with `--tree`, | ||
| 26 | - or the "home" tree if `--local` was given or `local_by_default=true` is configured (usually at the top of the list). | ||
| 27 | - `--verbose`: Display verbose output of commands executed. | ||
| 28 | - `--timeout`: Timeout on network operations, in seconds. `0` means no timeout (wait forever). Default is `30`. | ||
| 27 | 29 | ||
| 28 | * **one** - Consider only the tree at the top of the list (possibly, the one given by the --tree flag, overriding all entries from rocks_trees), ignore all others | 30 | --- |
| 29 | * **all** - Consider all trees: if a dependency is installed in any tree of the rocks_trees list, we have a positive match. | ||
| 30 | * **order** - Consider only trees starting from the "current" one in the order, where the "current" is either: | ||
| 31 | * the one at the bottom of the rocks_trees list, | ||
| 32 | * or one explicitly given with --tree | ||
| 33 | * or the "home" tree if --local was given or local_by_default=true is configured (usually at the top of the list) | ||
| 34 | |- | ||
| 35 | | --verbose || Display verbose output of commands executed. | ||
| 36 | |- | ||
| 37 | | --timeout || Timeout on network operations, in seconds. 0 means no timeout (wait forever). Default is 30. | ||
| 38 | |} | ||
| 39 | 31 | ||
| 40 | # Supported commands | 32 | ## Supported Commands |
| 41 | 33 | ||
| 42 | {| | 34 | - **[build](luarocks_build.md)**: Build/compile and install a rock. |
| 43 | | [build](luarocks_build.md) || Build/compile and install a rock. | 35 | - **[doc](luarocks_doc.md)**: Shows documentation for an installed rock. |
| 44 | |- | 36 | - **[download](luarocks_download.md)**: Download a specific rock or rockspec file from a rocks server. |
| 45 | | [doc](luarocks_doc.md) || Shows documentation for an installed rock. | 37 | - **[help](luarocks_help.md)**: Help on commands. |
| 46 | |- | 38 | - **[install](luarocks_install.md)**: Install a rock. |
| 47 | | [download](luarocks_download.md)|| Download a specific rock or rockspec file from a rocks server. | 39 | - **[lint](luarocks_lint.md)**: Check syntax of a rockspec. |
| 48 | |- | 40 | - **[list](luarocks_list.md)**: Lists currently installed rocks. |
| 49 | | [help](luarocks_help.md) || Help on commands. | 41 | - **[config](luarocks_config.md)**: Query and set the LuaRocks configuration. |
| 50 | |- | 42 | - **[make](luarocks_make.md)**: Compile package in the current directory using a rockspec and install it. |
| 51 | | [install](luarocks_install.md) || Install a rock. | 43 | - **[new_version](luarocks_new_version.md)**: Auto-write a rockspec for a new version of a rock. |
| 52 | |- | 44 | - **[pack](luarocks_pack.md)**: Create a rock, packing sources or binaries. |
| 53 | | [lint](luarocks_lint.md) || Check syntax of a rockspec. | 45 | - **[path](luarocks_path.md)**: Return the currently configured package path. |
| 54 | |- | 46 | - **[purge](luarocks_purge.md)**: Remove all installed rocks from a tree. |
| 55 | | [list](luarocks_list.md) || Lists currently installed rocks. | 47 | - **[remove](luarocks_remove.md)**: Uninstall a rock. |
| 56 | |- | 48 | - **[search](luarocks_search.md)**: Query the LuaRocks repositories. |
| 57 | | [config](luarocks_config.md) || Query and set the LuaRocks configuration. | 49 | - **[test](luarocks_test.md)**: Run the test suite in the current directory. |
| 58 | |- | 50 | - **[show](luarocks_show.md)**: Shows information about an installed rock. |
| 59 | | [make](luarocks_make.md) || Compile package in current directory using a rockspec and install it. | 51 | - **[unpack](luarocks_unpack.md)**: Unpack the contents of a rock. |
| 60 | |- | 52 | - **[upload](luarocks_upload.md)**: Upload a rockspec to the public rocks repository. |
| 61 | | [new_version](luarocks_new_version.md) || Auto-write a rockspec for a new version of a rock. | 53 | - **[write_rockspec](luarocks_write_rockspec.md)**: Write a template for a rockspec file. |
| 62 | |- | ||
| 63 | | [pack](luarocks_pack.md) || Create a rock, packing sources or binaries. | ||
| 64 | |- | ||
| 65 | | [path](luarocks_path.md) || Return the currently configured package path. | ||
| 66 | |- | ||
| 67 | | [purge](luarocks_purge.md) || Remove all installed rocks from a tree. | ||
| 68 | |- | ||
| 69 | | [remove](luarocks_remove.md) || Uninstall a rock. | ||
| 70 | |- | ||
| 71 | | [search](luarocks_search.md) || Query the LuaRocks repositories. | ||
| 72 | |- | ||
| 73 | | [test](luarocks_test.md) || Run the test suite in the current directory. | ||
| 74 | |- | ||
| 75 | | [show](luarocks_show.md) || Shows information about an installed rock. | ||
| 76 | |- | ||
| 77 | | [unpack](luarocks_unpack.md) || Unpack the contents of a rock. | ||
| 78 | |- | ||
| 79 | | [upload](luarocks_upload.md) || Upload a rockspec to the public rocks repository. | ||
| 80 | |- | ||
| 81 | | [write_rockspec](luarocks_write_rockspec.md) || Write a template for a rockspec file. | ||
| 82 | |} | ||
| 83 | 54 | ||
| 84 | # Overview of the difference between "make", "build", "install" and "pack" | 55 | --- |
| 85 | |||
| 86 | {| | ||
| 87 | | luarocks install modulename || downloads a binary .rock file and installs it to the local tree (falls back to "luarocks build modulename" behavior if a binary rock is not found) | ||
| 88 | |- | ||
| 89 | | luarocks build modulename || downloads a .src.rock or a rockspec and builds+installs it to the local tree. | ||
| 90 | |- | ||
| 91 | | luarocks build modulename-1.0-1.linux-x86.rock || extracts the rockspec from the rock and builds it as if the rockspec was passed in the command-line (i.e., redownloading sources and recompiling C modules if any). | ||
| 92 | |- | ||
| 93 | | luarocks build modulename-1.0-1.rockspec || builds+installs the rock using the given rockspec downloading the sources | ||
| 94 | |- | ||
| 95 | | luarocks make modulename-1.0-1.rockspec || builds+installs the rock using the rockspec using the contents of your current directory (kind of like the way make uses a Makefile) instead of downloading sources | ||
| 96 | |- | ||
| 97 | | luarocks pack modulename || grabs the rock from your local tree and packs it into a binary .rock file | ||
| 98 | |- | ||
| 99 | | luarocks pack modulename-1.0-1.rockspec || downloads the sources from the url and packs it into a .src.rock file | ||
| 100 | |} | ||
| 101 | 56 | ||
| 57 | ## Overview of the Difference Between `make`, `build`, `install`, and `pack` | ||
| 102 | 58 | ||
| 59 | | Command | Description | | ||
| 60 | |-------------------------------------------|-------------------------------------------------------------------------------------------------| | ||
| 61 | | `luarocks install modulename` | Downloads a binary `.rock` file and installs it to the local tree (falls back to `luarocks build modulename` behavior if a binary rock is not found). | | ||
| 62 | | `luarocks build modulename` | Downloads a `.src.rock` or a rockspec and builds+installs it to the local tree. | | ||
| 63 | | `luarocks build modulename-1.0-1.linux-x86.rock` | Extracts the rockspec from the rock and builds it as if the rockspec was passed in the command-line (i.e., redownloading sources and recompiling C modules if any). | | ||
| 64 | | `luarocks build modulename-1.0-1.rockspec` | Builds+installs the rock using the given rockspec, downloading the sources. | | ||
| 65 | | `luarocks make modulename-1.0-1.rockspec` | Builds+installs the rock using the rockspec and the contents of your current directory (kind of like the way `make` uses a Makefile) instead of downloading sources. | | ||
| 66 | | `luarocks pack modulename` | Grabs the rock from your local tree and packs it into a binary `.rock` file. | | ||
| 67 | | `luarocks pack modulename-1.0-1.rockspec` | Downloads the sources from the URL and packs it into a `.src.rock` file. | | ||