Rouge is written in Ruby and has a number of development dependencies. To develop new features for Rouge (like a lexer for a new syntax) or to fix bugs, you need to set up a development environment.
Please note that this guide is about how to configure a development environment on your local machine. If you want to isolate your Rouge development environment using Docker, take a gander at our guide.
Ruby and Git
First things first. This guide is not a guide to installing Ruby and Git. There are a number of excellent resources out there explaining how to do these things. For Ruby, we recommend the official documentation and for Git, GitHub's documentation.
This guide assumes you are familiar with the command line. The command line is accessed through a terminal emulator.
In macOS, the default emulator is called "Terminal" and can be found by searching for "Terminal" in Spotlight.
In Windows, you can open a command line by running "Command Prompt". You can start this by typing
cmd.exeat the Start Menu.
In Linux, well, you're probably reading this at the command line.
The official Rouge repository is on GitHub and we use GitHub to coordinate development. While you don't need a GitHub account to hack on Rouge, you're going to need one to contribute your improvements back to the Rouge community. Creating an account is free of charge. And just think how awesome it'll be when you take your collaboration to the "next level".
Forking the Repository
To develop Rouge, we're going to create a "fork" of Rouge where we can make our changes. These will be happily isolated from everyone else and then—through the magic of Git—mergeable back into the main project later.
First, visit the front page of Rouge's repo on GitHub. Unless you're crazy and are trying to develop code on your phone (like perhaps I am doing right now), you'll see a button near the top right of your browser window that will say "Fork". Click this and GitHub will ask where you want to create your fork. Select your account and—boom!—you've just forked Rouge.
Cloning Your Fork
The next thing to do is to get your fork onto your computer. Git makes this easy. In the directory you want to hold your repository, type:
git clone firstname.lastname@example.org:<your_github_account_name>/rouge.git
Git will reach out to GitHub, grab the code and put it in a directory called
By default, the clone of the repository you've made will contain a reference to GitHub. That's great for syncing back to your fork but what if you want to sync your fork back up with the official repository. If you spend a sufficient amount of time developing Rouge, this is something you'll want to do.
Fortunately, it's easy to add additional remote repositories. To add the
official Rouge repository (with the name
upstream), type the following:
git remote add upstream https://github.com/rouge-ruby/rouge.git
Now you'll be able to fetch changes from the official repository and merge them back into your code. For more information, check out the documentation on GitHub.
Installing Development Dependencies
Ruby provides support for using external "packages" of Ruby code. These packages are called gems. While Rouge does not depend on any gems to perform syntax highlighting, it does have a number of dependencies that you need to install to develop Rouge. These are the development dependencies.
The easiest way to install Rouge's development dependencies is using Bundler. Bundler is itself a gem but we'll install it differently to how we install the other dependencies.
If you already develop with Ruby, you no doubt have Bundler installed. You can
check if you do by typing
bundle -v at the command line. If you don't see the
version number then you need to install Bundler. To do this, type:
gem install bundler
gem tool will grab the latest Bundler package and install it. Once
that's complete, you're ready to rock.
Installing the Dependencies
Rouge comes with a list of gems it depends upon called a Gemfile. Make sure you're at the top level of your clone of your repository and type:
bundle config set path 'vendor' bundle install
This first command tells Bundler to register the directory
the project-specific install location for dependencies, and the second command
installs all dependencies. This has one drawback (explained below) but means the
gems we use for Rouge are isolated from the other gems we may have installed on
our system. This will be tremendously helpful in avoiding conflicts that arise
because of the use of incompatible versions of a gem.
The one drawback is that we will need to tell Ruby every time we run our Rouge
code that it needs to look for the gems in
vendor/. Bundler makes this easy by
providing the command
bundle exec. So if we want to run our Rake tests, we
bundle exec rake rather than just
It's best to develop in a branch. You can create a branch by typing:
git checkout -b <name_of_your_branch>
You don't need to do it this way but Rouge maintainers often use the format
feature.<name> for features and
bugfix.<name> for bug fixes.
Using branches will make it easier for others to collaborate with you and make it easier for you to start fresh if you screw things up from your last stable state. You can read more about branches on GitHub.
You're now ready to roll. Here are the things you can do from the top level of your cloned repository:
Run the Visual Test App: Rouge includes a little web app you can run to display highlighted code. You can run this by typing
bundle exec rackup. By default, this will start a web server on port 9292. You can access it by going to http://localhost:9292 with Rack running. If everything is working, you'll see little snippets of code for each lexer in the repository. You can look at the full visual sample for a lexer by clicking on the name of the lexer.
Run the Tests: Rouge comes with a test suite you can run to check for errors in your code. You can run this using Rake. Just type
bundle exec rakeand you'll (hopefully) be greeted by a series of dots that indicate a successful test.
Check Code Quality: Rouge uses the popular library RuboCop for checking code quality. You can run RuboCop by—you guessed it—typing
bundle exec rubocop.
You're all set up! Have fun hacking on Rouge!