# (🌑) luamb

Lua environment manager built on top of [hererocks](https://github.com/luarocks/hererocks) and inspired by [virtualenvwrapper](https://bitbucket.org/virtualenvwrapper/virtualenvwrapper).


## Supported shells

  * Bash
  * Zsh


## Installation

  1. Install luamb using `pip`:

      ```sh
      pip install [--user] luamb
      ```

      or `pipx`:

      ```sh
      pipx install luamb
      ```

  2. Set up your shell — add the following to `~/.bashrc` or `~/.zshrc`:

      ```sh
      source <(luamb shellsrc)
      ```

  3. Install hererocks:

      ```sh
      luamb update
      ```


## Configuration

luamb is configured via environment variables.

  * `LUAMB_HOME`

    A directory where luamb stores its data (hererocks, environments, etc.). The default value is `$XDG_DATA_HOME/luamb` (usually `~/.local/share/luamb`) on Linux and `~/Library/Application Support/luamb` on macOS.

  * `LUAMB_ENVS_DIR`

    A directory where luamb stores environments. The default value is `$LUAMB_HOME/envs`.

  * `LUAMB_LUA_DEFAULT`

    A default Lua interpreter/version. The format is `interpreter version_specifier`, e.g., `lua 5.3`, `luajit @v2.1`, `moonjit /path/to`, `raptorjit latest`.

  * `LUAMB_LUAROCKS_DEFAULT`

    A default LuaRocks version, e.g, `latest`, `3.11.0`.

  * `LUAMB_DISABLE_COMPLETION`

    Set to `true` to disable shell completions.

  * `LUAMB_PYTHON_BIN`

    If the luamb executable is not in `PATH`, set `LUAMB_PYTHON_BIN` to the Python executable with the `luamb` package installed and change the shell initialization command:

    ```sh
    export LUAMB_PYTHON_BIN=/path/to/bin/python
    source <("$LUAMB_PYTHON_BIN" -m luamb shellsrc)
    ```


## Examples

  * Create an environment 'myproject' with the latest Lua 5.2, the latest LuaRocks and associate it with /home/user/projects/myproject:

    ```sh
    luamb mk myproject -l 5.2 -r latest -a /home/user/projects/myproject
    ```

  * Create an environment 'jittest' with LuaJIT 2.0.4, without LuaRocks and associate it with /home/user/projects/jitproj:

    ```sh
    luamb mk jittest -j 2.0.4 -a /home/user/projects/jitproj
    ```

  * Set the latest LuaJIT 2.0 and the latest LuaRocks as default versions:

    ```sh
    export LUAMB_LUA_DEFAULT='luajit 2.0'
    export LUAMB_LUAROCKS_DEFAULT=latest
    ```

  * Create an environment 'newenv' with the default versions and without associated project directory:

    ```sh
    luamb mk newenv
    ```

  * Create an environment 'norocks' with the default Lua version and without LuaRocks (verbose mode):

    ```sh
    luamb mk norocks --no-luarocks --verbose
    ```

  * Activate the 'newenv' environment:

    ```sh
    luamb on newenv
    ```

  * Deactivate the current environment:

    ```sh
    luamb off
    ```

  * Delete the 'myproject' environment (it will remove the environment directory only, not the project one):

    ```sh
    luamb rm myproject
    ```


## Commands

  * `on` | `enable` | `activate` — activate an environment
  * `off` | `disable` | `deactivate` — deactivate the current environment
  * `mk` | `new` | `create` — create a new environment
  * `rm` | `remove` | `del` | `delete` — remove an environment
  * `info` | `show` — Show the details for a single virtualenv
  * `ls` | `list` — list all of the environments
  * `update` — install/update the `hererocks` script
  * `shellsrc` — print the shell initialization code


## Version history

See [CHANGELOG.md](https://github.com/un-def/luamb/blob/master/CHANGELOG.md).


## License

The [MIT License](https://github.com/un-def/luamb/blob/master/LICENSE).
