Installing Gregorio
Before you install Gregorio
If you have never used TeX before, then we strongly recommend that you start to familiarize yourself with gabc by using the Illuminare Score Editor or the Gregorio Chant Engraver. These online tools will only require you to learn about gabc itself, while handling the considerable overhead that comes with using TeX for you. You won't have access to all of the features of GregorioTeX, but you won't have to learn two things at once, making it much easier to ease into the use of Gregorio.
Once you have mastered gabc itself, and find yourself wanting access to more of the capabilities of GregorioTeX, then you need to get yourself a TeX distribution. The most common distribution is TeX Live. This distribution supports many platforms, including all the major ones (Windows, Mac, and all varieties of Linux). For Mac users, there is also a Mac specific variant of TeX Live called MacTeX which does a much better job of integrating it into the Mac environment than the cross-platform installer. Another common distribution is MiKTeX which now supports all three major platforms (Windows, Mac, and Linux in its Ubuntu/Mint varieties).
One more thing...
If you have a full installation of TeX Live (including MacTeX), then Gregorio may already be installed on your system as part of that installation. The table below indicates which versions of Gregorio shipped with which versions of TeX Live:
TeX Live version | Gregorio version |
---|---|
2016 | 4.1 |
2017 | 5.0 |
2018 | 5.1 |
2019 | 5.2 |
2020 | 5.2 |
2021 | 6.0 |
If you have MiKTeX, then Gregorio is also included there. Because of MikTeX's rolling update model, it is impossible for us to tell you exactly what version is there, but you should be able to find and install a fairly recent, if not the most recent, version using the MiKTeX Console.
And now, finally, the installation instructions
If your TeX distribution doesn't have Gregorio, or you want a newer version of Gregorio than is available in your distribution, then refer to the following pages:
Configuration
Executable Access
By default LuaTeX (and all other varieties of TeX is only permitted to access a limited list of third-party programs. This is a security measure which prevents documents from doing things to you system that you might not expect or desire. Of course, in order for Gregorio to work, it has to be able to access its own exectuable. If you've installed TeX Live or MiKTeX, then access to the included executable is already setup for you. However, if you install an updated version, then you will need to enable access to the new executable. This can be accomplished in a number of ways:
Use
--shell-escape
when compiling documents making use of Gregorio. This option enables LuaTeX to call any shell command. Obviously this makes the compilation less secure, but that drop in security applies only to that document compilation, allowing for case-by-case differentiation in compilation behavior. It is our default recommendation because it is the simplest for most people to implement. To see how to automate this process if you are using an editor, see Editor Configuration below.Make the
--shell-escape
mode the default by settingshell_escape=t
in texmf.cnf. This will make all compilations less secure, but means that you don't have to specify the--shell-escape
flag on any given run. You should only do this if you trust all the documents you run through TeX on your system.To find your texmf.cnf file, execute
kpsewhich texmf.cnf
from the command line. Open the file at the given location and search forshell_escape=p
and then change thep
tot
. If you cannot find this line, then you can simply addshell_escape=t
to the bottom of the file.Add the new executable to the list of permitted programs in texmf.cnf. This is the most secure option as it only adds the new executable to the list of allowed programs and nothing else. However, it does need to be done each time you install a new version of Gregorio.
The list that needs editting is called
shell_escape_commands
and the program that needs to be added to it is calledgregorio-x_y_z
wherex_y_z
is the version number of Gregorio that you've installed. If the list is not present in your top-level texmf.cnf, then you'll need to usekpsewhich -a texmf.cnf
to find the lower-level configuration file. Do not edit those lower level files. Instead, copy theshell_escape_commands
list into your top-level texmf.cnf file and edit that copy. Values in the top-level file automatically override those in the lower-level ones.Create a symlink on your system that points
gregorio
togregorio-x_y_z
) (whereis the version number of Gregorio that you've installed). This symlink must be on your
PATH
before the folder containing the TeX executables so that it hides the executable that comes with TeX. This option is as secure as the previous option, and will also need to be updated every time you install a new version of Gregorio. For instructions on how to do this, see the documentation for your system.Resign yourself to using Gregorio in the old school way. This means turning off the autocompile feature and manually running
gregorio-x_y_z
on your gabc files to generate the gtex files. This doesn't work for\gabcsnippet
(only\gregorioscore
) and is damned inconvenient generally, but it is possible, so we list it here to be complete.
For more information about texmf.cnf files (and related issues) we suggest reading this page or asking a question at TeX Stack Exchange.
Editor Configuration
If you plan to use an editor, then you'll need to configure it once Gregorio is installed. For instructions on how to do this, refer to the following pages:
Uninstalling Gregorio
While we hope you'll be satisfied with Gregorio and never want to remove it from your computer, we've also tried to make it as straight forward as possible to do so should the need arise. Follow the instructions below that correspond to your OS and method of installation.
TeX Live or MiKTeX (All OSes)
Make use of the package installation tools for these distributions to remove a version of Gregorio which was installed by them.
Windows Installer
Use the Uninstall feature of Add/Remove Programs. See the Windows documentation for more information.
MacOS Installer
Use the Uninstall-Gregorio-*.*.*.pkg that corresponds to the version which you installed. Download it from the appropriate release page and run it just like you did the original installer.
Command-line installation (MacOS and Linux)
If you've installed a version of Gregorio from the command-line, there is a uninstall-gtex.sh
script which is generated during the installation process which you can use. This file is placed at TEXMFLOCAL/scripts/gregoriotex/uninstall-gtex.sh
(where TEXMFLOCAL
is the place where you installed GregorioTeX, usually the output of kpsewhich --var-value TEXMFLOCAL
. To use the script you first need to set its executable bit and then run it. Given the usual installation path, that looks something like this:
chmod +x $(kpsewhich --var-value TEXMFLOCAL)/scripts/gregoriotex/uninstall-gtex.sh
$(kpsewhich --var-value TEXMFLOCAL)/scripts/gregoriotex/uninstall-gtex.sh
This removes the GregorioTeX components. Once that's done, you simply need to delete the executable, which can be done using make uninstall
in the source code directory. If you did not keep your source code download, then make use of which
and rm
to locate and delete the executable (it should be named gregorio-*_*_*
, where the wild cards correspond to the version number that was installed).
Note: Depending on how and where you installed Gregorio, you may need to execute some of the above commands as root.