rvm-windows

# rvm-windows [![npm package](https://img.shields.io/npm/v/rvm-windows?color=default&style=plastic&logo=npm&logoColor=red)](https://www.npmjs.com/package/rvm-windows) ![downloads](https://img.shields.io/npm/dt/rvm-windows?color=blue&style=plastic) [![License: MIT](https://img.shields.io/badge/License-MIT-gold.svg?style=plastic&logo=mit)](LICENSE) <img src="doc/img/rvm_cmd_logo_square.png"/> > Reimplementation of most important [rvm.io](https://www.rvm.io) features for MS Windows As there is no rvm.io available for native windows, but only for POSIX by Cygwin, this is a reimplementation of basic [rvm.io](https://rvm.io/) features for native MS Windows on the classic command line. It is based on the packages shipped by [rubyinstaller.org](https://rubyinstaller.org/). RVM 4 Windows allows you to comfortably install and manage several versions of Ruby on your Windows machine. It automatically detects `.ruby-version` files or ruby version definitions in Gemfiles and runs your project on the classic windows command line on the specified ruby version automatically. Beneath you can switch your ruby version instantly. Ruby environment configurations are managed by RVM per user in `C:\Users\%USERNAME%\.rvm` but stored for all users in `C:\ProgramData\rvm` by default. > [!NOTE] > The goal of this project is not to 100% reimplement all features of > rvm.io, but the most important and common ones by preserving most of the > same command line interface. Some special Windows related stuff is added as well. # Table of contents * [Features & Limitations](#features) * [MSYS2_PATH](#msys2_path) * [Commands](#commands) * [Usage](#usage) * [Installation](#installation) * [Troubleshooting](#troubleshooting) * [Does not run the selected ruby](#trouble_selected_ruby) * [Using behind a proxy](#trouble_proxy) * [Contributing](#contributing) <a name="features"></a> ### Features & Limitations * Support automatic installation only for rubies from rubyinstaller starting from 2.4.x and x64 architecture. But you may add older installed rubies manually by using the `rvm add <path>` command. * Windows 10 or later * Classic command line and Powershell * Automatic recognition of `.ruby-version` files with autoswitch * Only one exact ruby version at one time (e.g. you can install and mange 3.3.0 and 3.3.1 separately, but not 3.3.1 two times) * Experimental `rvm kit` command with recipes for several ruby versions to install common used native gems. * When setting a proxy, the HTTP_PROXY and HTTPS_PROXY env will be temporary set, when running any rvm or ruby command <a name="msys2_path"></a> #### MSYS2_PATH When installing a new ruby version, `rvm-windows` by default automatically installs a separate MSYS2 environment delivered by the devkit version. If you want to use a central MSYS2 installation instead, you can set the `MSYS2_PATH` environment variable to the path of your MSYS2 installation. Then `rvm-windows` will instead download the ruby installer without devkit and you can use your central MSYS2 installation for the installed ruby. > [!WARNING] > Be aware, when `MSYS2_PATH` is set, that you have to ensure, that your central MSYS2 installation has all needed packages installed to build native gems for the ruby versions you want to use. > > And there is a risk, that older ruby versions may not work with a newer MSYS2 installation. <a name="commands"></a> ### Commands The following commands are available in rvm-windows: ```ruby add <path> # Add a installed ruby environment to the list (alias: mount) automount # Scan for ruby installations and add them to the RVM configuration (alias: scan) config # Print current RVM config config data # Print RVM data directory config data <path> # Set RVM data directory config default # Print default version config default <version> # Set default version config proxy # Get the configured proxy host. config proxy <host> # Set the proxy server host. E.g. http://proxy:12345 config proxy delete # Remove the proxy server host from the configuration. config proxy enable # Enable using the proxy server host from the configuration. config proxy disable # Disable using the proxy server host from the configuration. current # Print current ruby environment version default # Use default ruby version (alias: rvm use default) delete <version> # Delete given ruby environment (alias: remove) fix # Automatically fix paths and versions in RVM configuration get # Upgrade RVM to its latest release version help # Print this usage guide info # Show the environment information for current ruby init # Initialize RVM by adding it to the PATH environment variable install <version> # Install a specific ruby version kick <version> # Only remove given ruby environment from the RVM list without deleting any ruby environment. kit # Experimental: Install a bunch of widely used x64 dependencies automatically to the current ruby environment, which are needed to build native gems like postgresql, mysql2, ... list # List all installed ruby versions managed by RVM list verbose # List all installed ruby versions managed by RVM with additional info list known # List all installable ruby versions with latest patch version list all # List all installable ruby versions mount <path> # Add a installed ruby environment to the list (alias: add <path>) reinstall <version> # Delete given ruby environment and install it again. remove <version> # Delete given ruby environment (alias: uninstall) scan # Scan for ruby installations and add them to the RVM configuration (alias: automount) system # Use the system ruby (alias: rvm use system) uninstall <version> # Delete given ruby environment (alias: remove) upgrade <version> # Upgrade given version to its latest patch version upgrade <from> <to> # Upgrade given from_version to given to_version upgrades # List installed environments and available upgrades. use <version> # Switch to specified ruby version use --default <version> # Switch to specified ruby version and set it as default version # Display RVM build version ``` <a name="usage"></a> ## Usage ### Usage examples #### List installed rubies ```bash rvm list ``` <div style="background: black; color: white; border-radius: 16px;"> <pre> * <span style="color: green">ruby-3.2.2</span> <span style="color: green">ruby-2.4.10</span> => <span style="color: green">ruby-2.7.8</span> <br/> # => - current # =* - current && default # * - default </pre> </div> #### List installable rubies ```bash rvm list known ``` <div style="background: black; color: white; border-radius: 16px;"> <pre> - ruby-3.3.0 - <span style="color: green">ruby-3.2.2</span> - ruby-3.2.1 ... - ruby-3.0.1 - ruby-3.0.0 - <span style="color: green">ruby-2.7.8</span> ... </pre> </div> #### Switch version You do not need to prefix `ruby-` ```bash rvm use 2.4.10 ``` <div style="background: black; color: white; border-radius: 16px;"> <pre> Using <span style="color: green">ruby-2.4.10</span> ... </pre> </div> You even do not need to specify the exact version, it will automatically use or install the highest one available! ```bash rvm use 2 ``` <div style="background: black; color: white; border-radius: 16px;"> <pre> Using <span style="color: green">ruby-2.7.8</span> ... </pre> </div> #### Additional, undocumented shortcuts There a lots of other shortcuts available, e.g. you can use `rvm lv` instead of `rvm list verbose`. ```js rvm list -> rvm l rvm list -> rvm ls rvm list verbose -> rvm lv rvm list known -> rvm lk rvm list all -> rvm la ... ``` #### Install new version You do not need to prefix `ruby-` or specify the exact version, it will automatically install the highest one available! ```bash rvm install 3.2 # installs latest 3.2.x rvm install 3 # installs latest 3.x.x rvm install 2.7 # installs latest 2.7.x rvm install 2 # installs latest 2.x.x ``` <a name="installation"></a> ## Installation ### Requirements rvm-windows requires * Windows >= 10.x * [NodeJS](https://nodejs.org/) >= 18.x ### Setup You have to use npm and <u>not yarn</u> to install *rvm-windows*, as yarn does not support creating powershell files automatically and differs from its way to handle character encodings. (See https://github.com/magynhard/rvm-windows/issues/5) Ensure that [NodeJS](https://nodejs.org/) >= 18.x is already installed. Then on your command line execute the following command: #### npm ```bash npm install -g rvm-windows ``` After installing the command `rvm` is available on the command line. <a name="troubleshooting"></a> ## Troubleshooting <a name="trouble_selected_ruby"></a> ### Does not run the selected ruby Check if in your system wide PATH setting some ruby environment is listed and remove it from the system PATH variable. Otherwise try ``` rvm init ``` or ``` rvm fix ``` again. <a name="trouble_proxy"></a> ### Using behind a proxy rvm-windows has only basic proxy support with Basic Authentication. For basic authentication, you can use the following format: ```yaml http://<username>:<password>@<proxy-hostname>:<proxy-port> # example http://super:pwn123@myprox.local:1234 ``` #### NTLM & other authentication methods If you need to authenticate with other methods such as NTLM, you will need a intermediate proxy like `px` or `CNTLM`. As CNTLM is only running very stable on *nix, we recommend using [px proxy](https://github.com/genotrance/px). To check if your intermediate proxy is running correctly, try a test request with curl: ```bash curl -x http://127.0.0.1:3128 -X GET https://www.google.de ``` Then you should get the HTML document as response: ``` ... sAttribute("data-ved")?f=a?F(a)||"":"":f=(f=a.closest("[data-ved]"))?F(f)||"":""; f=f||"";if(a.hasAttribute("jsname"))a=a.getAttribute("jsname");else{var E;a=null== (E=a.closest("[jsname]"))?void 0:E.getAttribute("jsname")}google.log("rcm","&ei=" +b+"&tgtved="+f+"&jsname="+(a||""))}}else H=a,G=[b]}window.document.addEventListe ner("DOMContentLoaded",function(){document.body.addEventListener("click",I)});}). call(this);</script></body></html> ``` After installing and configuring and testing px proxy, set your RVM config like this: ```bash rvm config proxy http://127.0.0.1:3128 ``` <a name="contributing"></a> ## Contributing Bug reports and pull requests are welcome on GitHub at https://github.com/magynhard/rvm-windows. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.