From 57f2b60f0b2f666a8ea1e9835d28bee94db3fde7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Michonneau?= Date: Fri, 26 Jun 2020 19:07:11 +0200 Subject: [PATCH] add bundler installation and comprehensive setup instructions (#276) Co-authored-by: Erin Becker --- setup.md | 239 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 201 insertions(+), 38 deletions(-) diff --git a/setup.md b/setup.md index 84ea2805..af97b015 100644 --- a/setup.md +++ b/setup.md @@ -3,7 +3,7 @@ title: Setup --- Our lesson template is kept in the [`carpentries/styles` repository][styles]. The `styles` -repository is carefully curated so that changes made to it are easily mergable by downstream +repository is carefully curated so that changes made to it are easily mergeable by downstream lessons. The `styles` repository contains various bits that take Markdown files and render them as a lesson web page. For more information on how to develop lessons and maintain them, see our [lesson-example][lesson-example]. It will walk you through the basics of lesson design and how to @@ -174,73 +174,236 @@ before pushing them to GitHub. In order to preview changes locally, you must install the software described below. -1. **[Ruby](https://www.ruby-lang.org/en/downloads/)**. +### Windows + +For Windows, there are two main ways to setup your system to be able to render the lessons. + +- Option 1 relies on the Windows Subsystem for Linux (WSL). WSL allows you to run a Linux + environment directly from Windows. +- Option 2 relies on using Windows built-in applications. + +> ## Option 1 - Using the Windows Subsystem for Linux (WSL) +> +> If your version of Windows supports it, using the WSL will make the installation of the tools +> needed easier. Instructions to install Linux distributions from Windows 10/Windows Server are +> available from the [Microsoft website](https://docs.microsoft.com/en-us/windows/wsl/about). +> +> Once you have installed a Linux distribution, you can follow the installation instructions for +> [Linux](#linux-ubuntu) listed below. If you install a distribution other than Ubuntu, you will +> need to adjust the commands that install the packages. +{: .solution} + +> ## Option 2 - Using Windows built-in applications +> +> With the instructions below, you'll be able to preview websites for non-R based lessons. You'll be +> able to do so from the Git Bash terminal or from the "Command Prompt with Ruby" that comes with +> the Ruby installation. You won't be able to use the `make` commands as Make isn't available from +> the Git Bash terminal (see the optional section below for more info). +> +> 1. **Ruby**, go to choose Ruby+DevKit for your +> system (typically x64), and the most recent version available. During the +> installation process, choose to install the MSYS2 toolchain. On the last step +> of the installation screen, make sure that "Run 'ridk install'" is checked. +> This will bring a terminal window with 3 options, press "Enter" (for the +> default installation). After this step completes, you'll be prompted again, +> and press "Enter" again (for the default option). Once the installation is +> complete, restart your system. +> +>2. Navigate to the folder that contains the lesson, and you can now use `bundle +> exec jekyll serve` from your Git Bash terminal to preview the lessons. +> +> ### Optional (but recommended) +> +> With these instructions, you'll be able to use the `make` commands and render all lessons +> including those that use R. However, you won't be able to do so from the Git Bash terminal, but +> from the other terminals (Windows Powershell, cmd.exe, or the Command Prompt with Ruby). +> +>1. In the File Explorer, right-click on "This PC" icon, and click on +> "Properties". Click on "Advanced System Settings", and click on the button +> "Environment Variables". Click on the variable "Path", and then the "Edit" +> button. Click on the "New" button and add `C:\Ruby26-x64\msys64\usr\bin` (use +> the File Explorer to make sure this is the correct path for your Ruby and +> MSYS2 installation). If you're working on R-based lessons and R isn't already +> listed there, you need to add it by adding `C:\Program Files\R\R-3.x.x\bin` +> (using the correct path and R version number for your installation). +> +>2. Open the "Command Prompt with Ruby" (if it was open before you edited the +> Path, close it and re-open it). +{: .solution} + +Regardless of the option you chose, go to the section [For Everyone](#for-everyone). + +### macOS + +1. First make sure you have Homebrew installed by doing + +To install Homebrew, open the [Homebrew website](https://brew.sh/) and copy/paste the first command +on that page into your Terminal. It will look something like: + + ~~~ + /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + ~~~ + {: .language-bash} + + If you're not sure whether you have brew installed, type + + ~~~ + brew help + ~~~ + {: .language-bash} + + If you have Homebrew installed, you should see something like: + + ~~~ + Example usage: + brew search [TEXT|/REGEX/] + brew info [FORMULA...] + brew install FORMULA... + brew update + brew upgrade [FORMULA...] + brew uninstall FORMULA... + brew list [FORMULA...] + +Troubleshooting: + brew config + brew doctor + brew install --verbose --debug FORMULA + +Contributing: + brew create [URL [--no-fetch]] + brew edit [FORMULA...] + +Further help: + brew commands + brew help [COMMAND] + man brew + https://docs.brew.sh + ~~~ + {: .output} + + +2. **Ruby** -- `brew install ruby` + +3. **bundler** -- `gem install bundler --user-install` + +4. Go to the section [For Everyone](#for-everyone) + +### Linux (Ubuntu) + +1. **[Ruby](https://www.ruby-lang.org/en/downloads/)** and other dependencies. + + You will need to have the following packages installed (some might already + be on your system): - **Linux/macOS**: Ruby is usually included with Linux and macOS --- - this is usually sufficient to preview your changes locally. + ~~~ + sudo apt-get install ruby ruby-dev build-essential libxml2-dev + ~~~ + {: .language-bash} - If you aren't able to preview reliably with your default Ruby installation, - you can use the same version of Ruby as GitHub. Currently, - GitHub uses Ruby 2.5.3. In order to install Ruby 2.5.3 on Linux and macOS, we recommend using - [rbenv](https://github.com/rbenv/rbenv): +2. **[bundler](https://bundler.io/)** ~~~ - rbenv install 2.5.3 + gem install bundler --user-install ~~~ {: .language-bash} - And then instructing `rbenv` to use it in your lesson development process by executing the - following command from your lesson directory: + `gem` is the package management framework for Ruby. It was installed as part + of Ruby in the step above. `bundler` is also a package manager but at the + scale of a project instead of being system-wide. It makes it easier to + manage dependencies. + + +### For Everyone + +1. **The GitHub Pages Ruby Gem** + + Make sure there is a `Gemfile` at the root of your lesson repository. This + file should only contain: ~~~ - rbenv local 2.5.3 + source 'https://rubygems.org' + gem 'github-pages', group: :jekyll_plugins + ~~~ + + If you don't have it, create it and the two lines above to it. + + At the root of your repository type + + ~~~ + bundle update ~~~ {: .language-bash} - To install `rbenv`, please use [rbenv-installer](https://github.com/rbenv/rbenv-installer). + If you haven't used `bundler` yet for your project, this command will + install all the needed dependencies. Otherwise, it will update them to match + the current versions used by GitHub Pages. - **Windows**: Please use [RubyInstaller][ruby-installer] to install Ruby on Windows. +4. **Generate the lesson** - Upon installing Ruby, check its version by executing + Now you are ready to run jekyll to build your website and run a local server. To do this run: ~~~ - ruby --version + make serve ~~~ {: .language-bash} - Windows users should select the start menu option `Start command prompt with Ruby` - to execute the above command. + There will be several lines of output after this. If there were errors or warnings you can use + them to fix your lesson and run again if ti it failed. If it was successful the last few lines + will include `Server address: http://217.0.0.1:4000` and `Server running... press ctrl-c to + stop`. You can see your rendered site by pointing your browser to the address shown. - For more information, see [the Ruby installation guidelines][ruby-install-guide]. +### For R-based lessons -2. **[RubyGems][rubygems]** - is a tool which manages Ruby packages. It should have been installed along with Ruby and you can - test your installation by running +You will need a recent version of R (>= 3.5.0). Installation instructions are available from the [CRAN website](https://cran.r-project.org). + +We use the [knitr][cran-knitr], and [remotes](https://cran.r-project.org/package=remotes) to format +lessons written in R Markdown and figure out needed packages to execute the code in the lesson. You +will need to install the `remotes` package to build R lessons (and this example lesson), the other +packages will be installed automatically during the rendering of the lesson. You can install this +package by opening an R terminal and typing: + +~~~ +install.packages('remotes', repos = 'https://cran.rstudio.com') +~~~ +{: .language-r} + +### Troubleshooting + +1. Check your version of Ruby: + + ~~~ + ruby -v + ~~~ + {: .language-bash} + + You need Ruby 2.1.0 or later (currently GitHub pages uses Ruby 2.5.3). If you + have an older version of Ruby, if possible upgrade your operating system to a + more recent version. If it's not possible, consider using [rbenv](https://github.com/rbenv/rbenv). ~~~ - gem --version + rbenv install 2.5.3 ~~~ {: .language-bash} -3. **[Jekyll][jekyll]**. - You can install this by running `gem install jekyll`. - On macOS, a user does not have a permission to write to `/Library/Ruby/Gems/`. - Run `gem install jekyll --user-install` instead. + And then instructing `rbenv` to use it in your lesson development process by + executing the following command from your lesson directory: + + ~~~ + rbenv local 2.5.3 + ~~~ + {: .language-bash} -4. **R Packages**. - We use [knitr][cran-knitr], [stringr][cran-stringr], and [checkpoint][cran-checkpoint] - to format lessons written in R Markdown, - so you will need to install these to build R lessons - (and this example lesson). The best way to install these packages is to open an R terminal and type: +2. **[RubyGems][rubygems]** + is a tool which manages Ruby packages. It should have been installed along with Ruby and you can + test your installation by running ~~~ - install.packages(c('knitr', 'stringr', 'checkpoint', 'ggplot2'), - repos = 'https://cran.rstudio.com', dependencies = TRUE) + gem --version ~~~ - {: .language-r} + {: .language-bash} + +3. If you want to run `bin/lesson_check.py` (which is invoked by `make lesson-check`) +you will need the [PyYAML][pyyaml] module for Python 3. -If you want to run `bin/lesson_check.py` (which is invoked by `make lesson-check`) -you will need Jekyll (so that you have its Markdown parser, which is called Kramdown) -and the [PyYAML][pyyaml] module for Python 3. {% include links.md %}