Skip to content

Update Documentation and Installation pages #1877

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Nov 16, 2018
Merged

Update Documentation and Installation pages #1877

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f971262
Simplify introductory copy for Documentation
olivierlacan Nov 15, 2018
4d615d4
Don’t linger on installation in documentation
olivierlacan Nov 15, 2018
f3133b0
Remove redundant listing of Getting Started links
olivierlacan Nov 15, 2018
e01e699
Add listing for the official API documentation
olivierlacan Nov 15, 2018
c06bd27
Clean up and update Installation guide
olivierlacan Nov 15, 2018
1f6e5aa
No one says Weblogs anymore
olivierlacan Nov 15, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion _config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -827,7 +827,7 @@ locales:
description: |
Get in contact with Rubyists in your area.
weblogs:
text: Weblogs
text: Blogs
url: /en/community/weblogs/
description: |
Read about what’s happening right now in the Ruby community.
Expand Down
35 changes: 8 additions & 27 deletions en/documentation/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,32 +4,16 @@ title: "Documentation"
lang: en
---

Here you will find pointers to manuals, tutorials and references that
will come in handy when you feel like coding in Ruby.
Guides, tutorials and reference material to help you learn more about Ruby
{: .summary}

### Installing Ruby

Unless you only want to try Ruby in the browser (see the links below)
you need to have Ruby installed on your computer.
You can check whether Ruby already is available by opening a terminal
and typing

{% highlight sh %}
ruby -v
{% endhighlight %}

This should output some information on the installed Ruby version.
If not, see the [installation page](installation/) for various options
of getting Ruby.
Although you can easily [try Ruby in your browser][1], you can also read
the [installation guide](installation/) for help on installing Ruby.

### Getting Started

[Try Ruby!][1]
: An interactive tutorial that lets you try out Ruby right in your
browser. This 15-minute tutorial is aimed at beginners who want to get
a feeling of the language.

[Official FAQ](/en/documentation/faq/)
: The official frequently asked questions.

Expand All @@ -43,14 +27,6 @@ of getting Ruby.
through stories, wit, and comics. Originally created by *why the lucky
stiff*, this guide remains a classic for Ruby learners.

[Ruby in Twenty Minutes](/en/documentation/quickstart/)
: A nice tutorial covering the basics of Ruby. From start to finish it
shouldn’t take you more than twenty minutes.

[Ruby from Other Languages](/en/documentation/ruby-from-other-languages/)
: Coming to Ruby from another language? Whether it’s C, C++, Java, Perl,
PHP, or Python, this article has you covered!

[Learning Ruby][6]
: A thorough collection of Ruby study notes for those who are new to the
language and in search of a solid introduction to Ruby’s concepts and
Expand Down Expand Up @@ -85,6 +61,10 @@ of getting Ruby.

### Reference Documentation

[Official API Documentation][40]
: The official Ruby API documentation for different versions including
the currently unreleased (trunk) version.

[Ruby Core Reference][13]
: Pulled straight from the source code using [RDoc][14], this reference
work documents all of the core classes and modules (like String,
Expand Down Expand Up @@ -191,4 +171,5 @@ If you have questions about Ruby the
[37]: http://www.sublimetext.com/
[38]: http://ruby.learncodethehardway.org/
[39]: http://kapeli.com/dash
[40]: https://docs.ruby-lang.org/en/
[atom]: https://atom.io/
152 changes: 82 additions & 70 deletions en/documentation/installation/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,35 +4,40 @@ title: "Installing Ruby"
lang: en
---

You can use several tools to install Ruby.
This page describes how to use major package management systems
and third-party tools for managing and installing Ruby
and how to build Ruby from source.
With package managers or third-party tools, you have plenty of options
to install and manage Ruby.
{: .summary}

You may already have Ruby installed on your computer. You can check
inside a [terminal emulator][terminal] by typing:

{% highlight sh %}
ruby -v
{% endhighlight %}

This should output some information on the installed Ruby version.

## Choose Your Installation Method

There are several ways to install Ruby:

* When you are on a UNIX-like operating system, using your system's
**package manager** is the easiest way of getting started.
However, the packaged Ruby version usually is not the newest one.
* On a UNIX-like operating system, using your system's **package
manager** is easiest. However, the packaged Ruby version may not be
the newest one.
* **Installers** can be used to install a specific or multiple
Ruby versions. There is also an installer for Windows.
* **Managers** help you to switch between multiple Ruby installations
* **Managers** help you to switch between multiple Ruby versions
on your system.
* And finally, you can also **build Ruby from source**.
* Finally, you can also **build Ruby from source**.

The following overview lists available installation methods
for different needs and platforms.
Here are available installation methods:

* [Package Management Systems](#package-management-systems)
* [Debian, Ubuntu](#apt)
* [CentOS, Fedora, RHEL](#yum)
* [Gentoo](#portage)
* [Arch Linux](#pacman)
* [OS X](#homebrew)
* [macOS](#homebrew)
* [FreeBSD](#freebsd)
* [Solaris, OpenIndiana](#solaris)
* [Other Distributions](#other-systems)
Expand All @@ -55,20 +60,19 @@ for different needs and platforms.
If you cannot compile your own Ruby, and you do not want to use a
third-party tool, you can use your system's package manager to install Ruby.

Certain members in the Ruby community feel very strongly that you should
never use a package manager to install Ruby and that you should use tools
instead. While the full list of pros and cons is outside of the scope
of this page, the most basic reason is that most package managers have
older versions of Ruby in their official repositories. If you would like to
use the newest Ruby, make sure you use the correct package name,
or use the tools described further below instead.
Some members of the Ruby community feel that you should avoid package
managers to install Ruby and that you should use dedicated tools instead.

It's possible that major package managers will install older Ruby
versions instead of the latest release. To use the latest Ruby release,
check that the package name matches its version number. Or use a
dedicated [installer][installers].

### apt (Debian or Ubuntu)
{: #apt}

Debian GNU/Linux and Ubuntu use the apt package manager.
You can use it like this:
Debian GNU/Linux and Ubuntu use the apt package manager. You can use it
like this:

{% highlight sh %}
$ sudo apt-get install ruby-full
Expand Down Expand Up @@ -101,9 +105,9 @@ Gentoo uses the portage package manager.
$ sudo emerge dev-lang/ruby
{% endhighlight %}

By default, this will try to install versions 1.9 and 2.0,
but more versions are available.
To install a specific version, set `RUBY_TARGETS` in your `make.conf`.
By default, this will try to install versions 1.9 and 2.0, but more
versions are available. To install a specific version, set
`RUBY_TARGETS` in your `make.conf`.
See the [Gentoo Ruby Project website][gentoo-ruby] for details.


Expand All @@ -120,13 +124,14 @@ $ sudo pacman -S ruby
This should install the latest stable Ruby version.


### Homebrew (OS X)
### Homebrew (macOS)
{: #homebrew}

On macOS (High) Sierra and OS X El Capitan, Ruby 2.0 is included.
Ruby versions 2.0 and above are included by default in macOS releases
since at least El Capitan (10.11) all the way through Mojave (10.14).

Many people on OS X use [Homebrew][homebrew] as a package manager.
It is really easy to get a newer version of Ruby using Homebrew:
[Homebrew][homebrew] is a commonly used package manager on macOS.
Installing a Ruby using Homebrew is easy:

{% highlight sh %}
$ brew install ruby
Expand Down Expand Up @@ -178,48 +183,48 @@ latest version of Ruby.
### Other Distributions
{: #other-systems}

On other systems, you can search the package repository of your
Linux distribution's manager for Ruby, or the third-party tools might be the
right choice for you.
On other systems, you can search the package repository of your Linux
distribution's manager for Ruby. Alternatively, you can use a
[third-party installer][installers].


## Installers
{: #installers}

If the version of Ruby provided by your system or package manager is out of
date, a newer one can be installed using a third-party installer.
Some of them also allow you to install multiple versions on the same system;
associated managers can help to switch between the different Rubies.
If you are planning to use [RVM](#rvm) as a version manager you do not need
a separate installer, it comes with its own.
If the version of Ruby provided by your system or package manager is out
of date, a newer one can be installed using a third-party installer.

Some installers allow you to install multiple versions on the same
system; associated managers can help to switch between the different
Rubies.

If you are planning to use [RVM](#rvm) as a version manager you don't
need a separate installer, it comes with its own.


### ruby-build
{: #ruby-build}

[ruby-build][ruby-build] is a plugin for [rbenv](#rbenv) that
allows you to compile and install different versions of Ruby
into arbitrary directories.
ruby-build can also be used as a standalone program without rbenv.
It is available for OS X, Linux, and other UNIX-like operating systems.
[ruby-build][ruby-build] is a plugin for [rbenv](#rbenv) that allows you
to compile and install different versions of Ruby. ruby-build can also
be used as a standalone program without rbenv. It is available for macOS,
Linux, and other UNIX-like operating systems.


### ruby-install
{: #ruby-install}

[ruby-install][ruby-install] allows you to compile and install different
versions of Ruby into arbitrary directories.
There is also a sibling, [chruby](#chruby), which handles switching between
Ruby versions.
It is available for OS X, Linux, and other UNIX-like operating systems.
versions of Ruby into arbitrary directories. [chruby](#chruby) is a
complimentary tool used to switch between Ruby versions. It's available
for macOS, Linux, and other UNIX-like operating systems.


### RubyInstaller
{: #rubyinstaller}

If you are on Windows, there is a great project to help you install Ruby:
[RubyInstaller][rubyinstaller]. It gives you everything you need to set up
a full Ruby development environment on Windows.
On Windows, [RubyInstaller][rubyinstaller] gives you everything you need
to set up a full Ruby development environment.

Just download it, run it, and you are done!

Expand All @@ -230,60 +235,60 @@ Just download it, run it, and you are done!
If you are installing Ruby in order to use Ruby on Rails,
you can use the following installers:

* [RailsInstaller][railsinstaller],
which uses RubyInstaller but gives you
extra tools that help with Rails development.
It supports OS X and Windows.
* [Bitnami Ruby Stack][rubystack],
which provides a complete development environment for Rails.
It supports OS X, Linux, Windows, virtual machines, and cloud images.
* [RailsInstaller][railsinstaller] uses [RubyInstaller][rubyinstaller]
but gives you extra tools that help with Rails development. It
supports macOS and Windows.
* [Bitnami Ruby Stack][rubystack] provides a complete development
environment for Rails. It supports macOS, Linux, Windows, virtual
machines, and cloud images.


## Managers
{: #managers}

Many Rubyists use Ruby managers to manage multiple Rubies.
They confer various advantages but are not officially supported.
Their respective communities are very helpful, however.
Many Rubyists use Ruby managers to manage multiple Rubies. They allow
easy or even automatic switching between Ruby versions depending on the
project and other advantages but are not officially supported. You can
however find support within their respective communities.


### chruby
{: #chruby}

[chruby][chruby] allows you to switch between multiple Rubies.
chruby can manage Rubies installed by [ruby-install](#ruby-install)
or even built from source.
[chruby][chruby] allows you to switch between multiple Rubies. It can
manage Rubies installed by [ruby-install](#ruby-install) or even built
from source.


### rbenv
{: #rbenv}

[rbenv][rbenv] allows you to manage multiple installations of Ruby.
It does not support installing Ruby, but there is a popular plugin
named [ruby-build](#ruby-build) to install Ruby.
Both tools are available for OS X, Linux, or other UNIX-like operating systems.
While it can't install Ruby by default, its [ruby-build](#ruby-build)
plugin can. Both tools are available for macOS, Linux, or other
UNIX-like operating systems.


### RVM ("Ruby Version Manager")
{: #rvm}

[RVM][rvm] allows you to install and manage multiple installations of Ruby
on your system. It can also manage different gemsets.
It is available for OS X, Linux, or other UNIX-like operating systems.
[RVM][rvm] allows you to install and manage multiple installations of
Ruby on your system. It can also manage different gemsets. It is
available for macOS, Linux, or other UNIX-like operating systems.


### uru
{: #uru}

[Uru][uru] is a lightweight, multi-platform command line tool that helps you
to use multiple Rubies on OS X, Linux, or Windows systems.
to use multiple Rubies on macOS, Linux, or Windows systems.


## Building from Source
{: #building-from-source}

Of course, you can install Ruby from source.
[Download](/en/downloads/) and unpack a tarball, then just do this:
[Download][download] and unpack a tarball, then just do this:

{% highlight sh %}
$ ./configure
Expand All @@ -294,6 +299,9 @@ $ sudo make install
By default, this will install Ruby into `/usr/local`.
To change, pass the `--prefix=DIR` option to the `./configure` script.

You can find more information about building from source in the [Ruby
README file][readme].

Using the third-party tools or package managers might be a better idea,
though, because the installed Ruby won't be managed by any tools.

Expand All @@ -314,3 +322,7 @@ though, because the installed Ruby won't be managed by any tools.
[freebsd-ruby]: https://wiki.freebsd.org/Ruby
[freebsd-ports-collection]: https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports-using.html
[homebrew]: http://brew.sh/
[terminal]: https://en.wikipedia.org/wiki/List_of_terminal_emulators
[download]: /en/downloads/
[installers]: /en/documentation/installation/#installers
[readme]: https://github.com/ruby/ruby#how-to-compile-and-install