Installing Gregorio under Linux

This page describes the installation and compilation of Gregorio software under a GNU/Linux system.

Most Recent Release

Install dependencies

As Gregorio uses LuaTeX to produce the final printed socres, you need to obtain a TeX distribution which contains this engine. We recommend TeXLive. You can get this either via your package manager (in which case make sure you get the package which contains the LuaTeX engine and tools, as package managers often split TeXLive up into multiple packages to reduce the download size) or from the TeXLive homepage.

While we recommend that you get a complete TeXLive installation since it will provide you with the most flexibility going forward, we understand that not everyone has the disk space or time to install the roughly 4GB of material that this requires. If you are trying to maintain a slimmer installation, you will need to ensure that you have the following packages installed: xcolor, kvoptions, ifluatex, graphicx, luatexbase, luaotfload, luamplib, and xstring. Most of these packages should come with the LuaTeX engine, but at least xcolor and xstring are known to be in other collections on some platforms. Additionally, Gregorio is included in TeXLive (from 2016 on), so if you install the complete version, you only need to proceed with the following instructions if you want a more recent version of Gregoiro than what shipped with the version of TeXLive that you are using. You may also be able to use the package manager to install Gergorio in this fashion.

You will also need the basic package of build tools for your platform. On Ubuntu/Debian/Mint these can be installed by executing the following in a terminal window:

Obtaining Source

To obtain the sources of the stable version, you just need to download them from the download page, and decompress the archive.

Nota bene: There are two different source code files on the download page: gregorio-x.x.x.tar.bz2 (where x.x.x is the version number) and "Source Code" (in both zip and tar.gz format). "gregorio-x.x.x.tar.bz2" is a special distribution version of the source which has several files, which do not depend on your particular system's architecture, pre-built for you. As a result, it requires fewer tools to build, and should be the default choice for most people. The file named "Source Code" is an image of the repository at the time of the release which is added automatically by GitHub. As a result, the process for building from this file is identical to the process for building from a clone of the repository itself (see below).

Building & Installing

While you could follow the usual route of using make commands to build and install the package, we've provided a couple of convenience scripts that make life easier. To use them, open a terminal window and enter the directory of the sources. Then run:

If you are an Ubuntu User there may occur a problem with the second command due to a special behaviour of the sudo command under Ubuntu. Try the following command:

or specify your texmf-local explicitely (see next section). You can find your system-wide texmf-local via kpsewhich -var-value TEXMFLOCAL. The userspecific texmf-local should be: /home/username/texmf-local

Assuming nither of these commands spit out an error message, then you've successfully installed Gregorio and are ready for the Next Steps.

Alternate Installation Locations

By default the automatic installation process will install gregorio in /usr/local/ and GregorioTeX into they system-wide texmf-local. If you wish to change these destinations, then you can add arguments to the build and install instructions to that effect:

Most Recent Development Version

Install Dependencies

In addition to TeXLive, to build from the repository you will also need to get several build tools with your package manager. On Ubuntu/Debian/Mint execute the following in a terminal window:

Nota bene: You may, should you so choose, use a different pacakge manager, such as aptitude. If you are using a different Linux distribution, then the names of the packages you need may be slightly different.

If you intend to contribute to development, then you'll also need the following:

For building gregorio versions prior to 4.0 this additional dependency is needed:

Obtaining Soruces

To get the development version, create a local copy of the repository of the project, with the command:

Nota Bene: This clone command uses several options to limit your download size to just the most recent development branch. If you're familiar with git, feel free to clone the whole repository. Just remember to switch to the develop branch (or whichever branch you want to install) before going on to the next step.

Building & Installing

To build from the git repository, you will need to configure the build first. This can be done manually, as you would for any other package built from source on Linux, but our build script is capable of detecting the need to do this and executing the necessary commands sos you can simply follow the same build and install instructions as above.

Should you need to force your system to go through the configuration process again for some reason, there is an option for our build script which allows that:

Updating

To update your git version, you just need to go into the directory containing the source files (assuming you kept them), run git pull and recompile with the same commands.

Next steps

If you've used TeX before, then you probably already have a preferred workflow which will need only minor modifications to make Gregorio work within it. Please consult the instruction page appropriate to your work flow. (You can find a list of the instruction pages here.)

If you're new to TeX, we suggest that you make use of TeXworks. It's a basic IDE (integrated development environment) for using TeX and family and will provide you with a friendly GUI (graphic user interface). You will need to configure it for Gregorio. Once that's done, just follow the basic inscrutions for how to use Gregorio. We also strongly recommend going through the tutorials as it provides the easiest introduction to the workflow that we have devised.