Skip to content

Commit

Permalink
Merge pull request #44766 from rails/update-local-dev-guide
Browse files Browse the repository at this point in the history 
Update local development guide
  • Loading branch information
@eileencodes
eileencodes committed Mar 25, 2022
2 parents 52f1f31 + 10314c1 commit 996980e
Showing 1 changed file with 48 additions and 48 deletions.
96 changes: 48 additions & 48 deletions guides/source/development_dependencies_install.md
View file
Expand Up @@ -11,30 +11,23 @@ After reading this guide, you will know:

--------------------------------------------------------------------------------

The Easy Way
------------
Other Ways to Set Up Your Environment
-------------------------------------

The easiest and recommended way to get a development environment ready to hack is to use the [Rails development box](https://github.com/rails/rails-dev-box).
If you don't want to set up Rails for development on your local machine you can use Codespaces, the VS Code Remote Plugin, or rails-dev-box. Learn more about these options [here](https://guides.rubyonrails.org/contributing_to_ruby_on_rails.html#setting-up-a-development-environment).

The Hard Way
------------
Local Development
-----------------

In case you can't use the Rails development box, see the steps below to manually
build a development box for Ruby on Rails core development.
If you want to develop Ruby on Rails locally on your machine see the steps below.

### Install Git

Ruby on Rails uses Git for source code control. The [Git homepage](https://git-scm.com/) has installation instructions. There are a variety of resources on the net that will help you get familiar with Git:

* [Try Git course](https://try.github.io/) is an interactive course that will teach you the basics.
* The [official Documentation](https://git-scm.com/documentation) is pretty comprehensive and also contains some videos with the basics of Git.
* [Everyday Git](https://schacon.github.io/git/everyday.html) will teach you just enough about Git to get by.
* [GitHub](https://help.github.com/) offers links to a variety of Git resources.
* [Pro Git](https://git-scm.com/book) is an entire book about Git with a Creative Commons license.
Ruby on Rails uses Git for source code control. The [Git homepage](https://git-scm.com/) has installation instructions. There are a variety of resources online that will help you get familiar with Git.

### Clone the Ruby on Rails Repository

Navigate to the folder where you want the Ruby on Rails source code (it will create its own `rails` subdirectory) and run:
Navigate to the folder where you want to download the Ruby on Rails source code (it will create its own `rails` subdirectory) and run:

```bash
$ git clone https://github.com/rails/rails.git
Expand All @@ -57,14 +50,15 @@ Here's the list of each gems' additional dependencies:
[Node.js](https://nodejs.org/) installed.

Install all the services you need to properly test the full gem you'll be
making changes to.
making changes to. How to install these services for macOS, Ubuntu, Fedora/CentOS,
and FreeBSD are detailed below.

NOTE: Redis' documentation discourage installations with package managers as those are usually outdated. Installing from source and bringing the server up is straight forward and well documented on [Redis' documentation](https://redis.io/download#installation).
NOTE: Redis' documentation discourages installations with package managers as those are usually outdated. Installing from source and bringing the server up is straight forward and well documented on [Redis' documentation](https://redis.io/download#installation).

NOTE: Active Record tests _must_ pass for at least MySQL, PostgreSQL, and SQLite3. Subtle differences between the various adapters have been behind the rejection of many patches that looked OK when tested only against single adapter.
NOTE: Active Record tests _must_ pass for at least MySQL, PostgreSQL, and SQLite3. Your patch will be rejected if tested against a single adapter, unless the change and tests are adapter specific.

Below you can find instructions on how to install all of the additional
tools for different OSes.
tools for different operating systems.

#### macOS

Expand Down Expand Up @@ -92,6 +86,33 @@ $ brew services start mysql

Replace `mysql` with the name of the service you want to start.

##### Potential Issues

This section details some of the potential issues you may run into with native extensions on macOS, particularly when bundling the mysql2 gem in local development. This documentation is subject to change and may be incorrect as Apple makes changes to the developer environment on Rails.

In order to compile the `mysql2` gem on macOS you will need the following:

1) `openssl@1.1` installed (not `openssl@3`)
2) Ruby compiled with `openssl@1.1`
3) Set compiler flags in the bundle config for `mysql2`.

If both `openssl@1.1` and `openssl@3` are installed you will need to tell Ruby to use `openssl@1.1` in order for Rails to bundle `mysql2`.

In your `.bash_profile` set the `PATH` and `RUBY_CONFIGURE_OPTS` to point to `openssl@1.1`:

```
export PATH="/usr/local/opt/openssl@1.1/bin:$PATH"
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@1.1)"
```

In your `~/.bundle/config` set the following for `mysql2`. Be sure to delete any other entries for `BUNDLE_BUILD__MYSQL2`:

```
BUNDLE_BUILD__MYSQL2: "--with-ldflags=-L/usr/local/opt/openssl@1.1/lib --with-cppflags=-L/usr/local/opt/openssl@1.1/include"
```

By setting these flags before installing Ruby and bundling Rails you should be able to get your local macOS development environment working.

#### Ubuntu

To install all run:
Expand Down Expand Up @@ -146,28 +167,14 @@ $ pkg install sqlite3 mysql80-client mysql80-server postgresql11-client postgres
Or install everything through ports (these packages are located under the
`databases` folder).

NOTE: If you run into troubles during the installation of MySQL, please see
NOTE: If you run into problems during the installation of MySQL, please see
[the MySQL documentation](https://dev.mysql.com/doc/refman/en/freebsd-installation.html).

### Database Configuration

There are couple of additional steps required to configure database engines
required for running Active Record tests.

In order to be able to run the test suite against MySQL you need to create a user named `rails` with privileges on the test databases:

```sql
$ mysql -uroot -p

mysql> CREATE USER 'rails'@'localhost';
mysql> GRANT ALL PRIVILEGES ON activerecord_unittest.*
to 'rails'@'localhost';
mysql> GRANT ALL PRIVILEGES ON activerecord_unittest2.*
to 'rails'@'localhost';
mysql> GRANT ALL PRIVILEGES ON inexistent_activerecord_unittest.*
to 'rails'@'localhost';
```

PostgreSQL's authentication works differently. To set up the development environment
with your development account, on Linux or BSD, you just have to run:

Expand All @@ -181,15 +188,15 @@ and for macOS:
$ createuser --superuser $USER
```

MySQL will create the users when the databases are created. The task assumes your user is `root` with no password.

Then, you need to create the test databases for both MySQL and PostgreSQL with:

```bash
$ cd activerecord
$ bundle exec rake db:create
```

NOTE: You'll see the following warning (or localized warning) during activating HStore extension in PostgreSQL 9.1.x or earlier: "WARNING: => is deprecated as an operator".

You can also create test databases for each database engine separately:

```bash
Expand All @@ -207,7 +214,7 @@ $ bundle exec rake db:drop

NOTE: Using the Rake task to create the test databases ensures they have the correct character set and collation.

If you're using another database, check the file `activerecord/test/config.yml` or `activerecord/test/config.example.yml` for default connection information. You can edit `activerecord/test/config.yml` to provide different credentials on your machine if you must, but obviously you should not push any such changes back to Rails.
If you're using another database, check the file `activerecord/test/config.yml` or `activerecord/test/config.example.yml` for default connection information. You can edit `activerecord/test/config.yml` to provide different credentials on your machine, but you should not push any of those changes back to Rails.

### Install JavaScript dependencies

Expand All @@ -217,29 +224,22 @@ If you installed Yarn, you will need to install the JavaScript dependencies:
$ yarn install
```

### Install Bundler gem

Get a recent version of [Bundler](https://bundler.io/)
### Installing gem dependencies

```bash
$ gem install bundler
$ gem update bundler
```
Gems are installed with [Bundler](https://bundler.io/) which ships by default with Ruby.

and run:
To install the Gemfile for Rails run:

```bash
$ bundle install
```

or:
If you don't need to run Active Record tests you can run:

```bash
$ bundle install --without db
```

if you don't need to run Active Record tests.

### Contribute to Rails

After you've set up everything, read how you can start [contributing](contributing_to_ruby_on_rails.html#running-an-application-against-your-local-branch).

0 comments on commit 996980e

Please sign in to comment.