Skip to content

Local Development Configuration

Jump to bottom
JJ Allaire edited this page Feb 3, 2015 · 21 revisions

This article covers the steps required to setup a local development configuration of the Rcpp Gallery website. Note that it's not required that you do this in order to contribute an article, however is recommended if you want see a preview of how the article will render within the website.

Requirements

The Rcpp Gallery website is built using the Jekyll static website generator and uses Pygments for syntax highlighting of code. If your version of jekyll is not new enough (i.e., not at least version 2.0.0 or higher), certain features of the Rcpp Gallery website (like figures) will not work for you. Jekyll version 2.4.0 is the recommended version. The first thing you'll want to do is ensure that both of these utilities are installed on your system:

Debian/Ubuntu

sudo apt-get install jekyll python-pygments

If the repository for your Debian--based system only has older Jekyll versions, use

sudo apt-get install ruby-dev
sudo gem install therubyracer
sudo gem install jekyll

Mac OS X

sudo gem install jekyll
sudo easy_install Pygments

C++ Libraries and Tools

Several system-level libraries are required to build all of the articles. On Debian/Ubuntu they can be installed using:

sudo apt-get install libgsl0-dev libboost-all-dev python2.7 python2.7-dev libgmp3-dev

In addition, some articles make use of C++11 features, so a newer version of GCC (4.7+) or Clang (3.2+) should be used to build the gallery.

R Packages

The following R packages are required to build the Rcpp Gallery:

  • Rcpp
  • RcppEigen
  • RcppArmadillo
  • RcppProgress
  • RcppGSL
  • RcppParallel
  • TTR
  • xts
  • BH
  • bigmemory
  • fields
  • bayesm
  • mvtnorm
  • numbers
  • Zelig
  • knitr
  • benchmark
  • rbenchmark
  • microbenchmark
  • sensitivity

Website Preview

After you've cloned a copy of the Rcpp Gallery repository onto your system, you can see a local preview of the website by switching to the repo directory and executing:

$ make preview

This will run a local web server at http://localhost:4000 that will serve a preview of the website. One important note about site preview: the global article search on the home page searches the Rcpp Gallery on the web rather than the local instance so new articles won't show up in the search results until they are published.

Building and Testing

The Rcpp Gallery website is built off of the source files within the src directory of the repository. To add an article to the website you need to:

  • Add an appropriately formatted source file to this directory; and
  • Execute make to compile the source file into web content

Source files can either by plain C++ files (with some special Doxygen comments) or an R Markdown file that includes C++ code blocks. In both cases source files need to be named with their date as a prefix to the filename (e.g. to publish an article with a date of December 15th, 2012 you'd preface the filename with 2012-12-15).

For example, to add a C++ source file that includes an article on Matrix multiplication you might add the following file to the repository:

src/2012-12-15-matrix-manipulation.cpp

You can then compile the file and add it to the website by executing make within either the root or src directory:

$ make

If you have previously executed make preview then after the build completes you can simply refresh the website to see how your article looks.

For additional information on how to author C++ or R Markdown source files for inclusion in the Rcpp Gallery please see Contributing-to-the-Rcpp-Gallery.

Clone this wiki locally