Setup: Improve Ruby/Jekyll instructions

[gcapes]

http://carpentries.github.io/lesson-example/setup.html#optional-jekyll-setup-for-lesson-development

I have tried to follow the setup instructions and have run into this problem which isn't apparent from the instructions: https://stackoverflow.com/questions/17618113/the-command-rbenv-install-is-missing

Instead, as I previously have done, I have just installed Jekyll using

sudo apt-get install build-essential
sudo apt install ruby2.5-dev
sudo gem2.5 install jekyll

and this seems to work fine (Linux Mint 19). Presumably the above commands would also be required if I'm using rbenv?

I'm writing a PR skill-up workshop, and part of it includes viewing changes locally. I think the jekyll setup instructions will be a stumbling block for many people. I have certainly had a lot of difficulty with this before, and the Jekyll site makes it seem so easy

get up and running in seconds

I'd prefer to point to the documentation in this repo rather than produce my own how-to, but currently it seems like the instructions aren't complete enough (for Linux at least - I've not tested this on Windows yet).

[maxim-belkin]

Hi Gerard,

http://carpentries.github.io/lesson-example/setup.html#optional-jekyll-setup-for-lesson-development

I have tried to follow the setup instructions and have run into this problem which isn't apparent from the instructions: https://stackoverflow.com/questions/17618113/the-command-rbenv-install-is-missing

Thanks for spotting this. Have you tried installing ruby-build as they recommend there? I think we need to add this step after installing rbenv.

Instead, as I previously have done, I have just installed Jekyll using

sudo apt-get install build-essential
sudo apt install ruby2.5-dev
sudo gem2.5 install jekyll

and this seems to work fine (Linux Mint 19). Presumably the above commands would also be required if I'm using rbenv?

No, you wouldn't have to install ruby2.5-dev and jekyll this way (you might have to install build-essentials). Instead, you'll run rbenv install 2.5.3 and gem install jekyll (or gem install jekyll --user-install).

The only reason I suggested using rbenv is because it can install the version of Ruby that GitHub has. You installed 2.5, which could mean 2.5.0, 2.5.1, 2.5.2, 2.5.3, 2.5.4, or 2.5.5.

[gcapes]

Thanks Maxim.

Installing ruby-build does look to be all that is required. I uninstalled ruby2.5-dev first.

However, the rbenv command didn't work.

$ rbenv install 2.5.3
ruby-build: definition not found: 2.5.3

The following versions contain `2.5.3' in the name:
  rbx-2.5.3

See all available versions with `rbenv install --list'.

So then i did

rbenv install rbx-2.5.3

Downloading rubinius-2.5.3.tar.bz2...
-> https://dqw8nmjcqpjn7.cloudfront.net/9af4d6e9d1e78a586579c86b9eb9a082cb863885d4a7cf33989d73280461e5fc
Installing rubinius-2.5.3...

WARNING: rubinius-2.5.3 is past its end of life and is now unsupported.
It no longer receives bug fixes or critical security updates.


BUILD FAILED (LinuxMint 19.1 using ruby-build 20170726)

Inspect or clean up the working tree at /tmp/ruby-build.20190510105150.25481
Results logged to /tmp/ruby-build.20190510105150.25481.log

Last 10 log lines:
/tmp/ruby-build.20190510105150.25481/rubinius-2.5.3/vendor/bundle/ruby/2.5.0/extensions/x86_64-linux/2.5.0/rubinius-melbourne-2.3.1.0/gem_make.out

An error occurred while installing rubinius-melbourne (2.3.1.0), and Bundler
cannot continue.
Make sure that `gem install rubinius-melbourne -v '2.3.1.0' --source
'https://rubygems.org/'` succeeds before bundling.

In Gemfile:
  rubinius-build_tools was resolved to 2.0.0, which depends on
    rubinius-melbourne

So I abandoned that and installed jekyll as before using ruby 2.5.1.

 $ sudo gem install jekyll
Fetching: jekyll-3.8.5.gem (100%)
Successfully installed jekyll-3.8.5
Parsing documentation for jekyll-3.8.5
Installing ri documentation for jekyll-3.8.5
Done installing documentation for jekyll after 1 seconds
1 gem installed

I would suggest checking these installation instructions for the OS covered. If it's important to use the same version of Ruby as GitHub, the instructions should cover how to do this. However I've not yet encountered a problem using a different version of Ruby.

If the instructions are incomplete, or incorrect, contributors will have to be very determined to resolve problems on their own, and simply won't preview their changes.

[maxim-belkin]

However, the rbenv command didn't work.

$ rbenv install 2.5.3
ruby-build: definition not found: 2.5.3

The following versions contain `2.5.3' in the name:
  rbx-2.5.3

See all available versions with `rbenv install --list'.

What does ruby-build --version return for you? I suspect that you somehow installed an old version of ruby-build. Check which 2.x versions of Ruby your ruby-build knows about with:

ruby-build --definitions | grep '^2\.'

I work on a Mac but ruby-build in my Ubuntu Xenial Docker image knows about 2.5.x Ruby versions:

$ docker exec lb bash -c 'ruby-build --definitions | grep "^2\.5"'
2.5.0-dev
2.5.0-preview1
2.5.0-rc1
2.5.0
2.5.1
2.5.2
2.5.3
2.5.4
2.5.5

I know it is not helpful but this discrepancy means that we ought to provide instructions on how to install ruby-build.

So then i did

rbenv install rbx-2.5.3

rbx-2.5.3 is not what we want. The list of all "definitions" that you should see is here.

I would suggest checking these installation instructions for the OS covered.

They have been checked and the challenges that we face here are typical for package managers that attempt to support multiple Linux distributions or operating systems.

If it's important to use the same version of Ruby as GitHub, the instructions should cover how to do this.

I believe using the same version of Ruby is rather desirable than critical. As such, we could modify the instructions to ask to try to install Ruby that GitHub has but, if something fails, install any (newer) version.

If the instructions are incomplete, or incorrect, contributors will have to be very determined to resolve problems on their own, and simply won't preview their changes.

True. I'd only say that instructions are neither incomplete nor incorrect -- at the moment they are not comprehensive enough.

BTW, you could use Docker for your skill-up workshop.

[gcapes]

~ $ ruby-build --version
ruby-build 20170726

~ $ ruby-build --definitions | grep '^2\.'
2.0.0-dev
2.0.0-preview1
2.0.0-preview2
2.0.0-rc1
2.0.0-rc2
2.0.0-p0
2.0.0-p195
2.0.0-p247
2.0.0-p353
2.0.0-p451
2.0.0-p481
2.0.0-p576
2.0.0-p594
2.0.0-p598
2.0.0-p643
2.0.0-p645
2.0.0-p647
2.0.0-p648
2.1.0-dev
2.1.0-preview1
2.1.0-preview2
2.1.0-rc1
2.1.0
2.1.1
2.1.2
2.1.3
2.1.4
2.1.5
2.1.6
2.1.7
2.1.8
2.1.9
2.1.10
2.2.0-dev
2.2.0-preview1
2.2.0-preview2
2.2.0-rc1
2.2.0
2.2.1
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.2.7
2.3.0-dev
2.3.0-preview1
2.3.0-preview2
2.3.0
2.3.1
2.3.2
2.3.3
2.3.4
2.4.0-dev
2.4.0-preview1
2.4.0-preview2
2.4.0-preview3
2.4.0-rc1
2.4.0
2.4.1
2.5.0-dev

I'll look in to Docker - I've no experience with it so this would add quite a lot of effort to the process.

[maxim-belkin]

~ $ ruby-build --version
ruby-build 20170726

Yes, for some reason your ruby-build is outdated. You can install the latest version with:

mkdir -p "$(rbenv root)"/plugins
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

(taken from here)