Installing Gregorio under Mac OSX

The TeX distribution

The first step to make Gregorio work is to have a TeX distribution: MacTeX (or TeXLive for Mac). See the official site for instructions.

While we recommend that you get a complete TeXLive (MacTeX itself, not BasicTeX) 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 4.5GB of material that this requires. If you are trying to maintain a slimmer installation (BasicTeX), 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 not. Additionally, Gregorio is included in MacTeX (from 2016 on), so if you install it, you only need to proceed with the following instructions if you want a more recent version of Gregoiro than which shipped with MacTeX

New Users

If you are new to using Gregorio and TeX, then installing the current version of MacTeX is all you need to do. The remaining instructions are meant for more advanced users who are looking to install an intermediate update (i.e. one which occurs between the annual releases of TeXLive) or the development version of the Gregorio.

The installer

An installer has been created for some Mac systems. It is available from the download page, and is meant for systems running OS X versions 10.5 or later.

The installer will automatically place the command-line tool in your path and will add the GregorioTeX files to your texmf tree. It will also create a directory at /Users/Shared/Gregorio containing the documentation, examples, and contributed add-ons.

Compiling from sources

Development environment installation

To be able to compile Gregorio, you must first install an installation environment. Here are the main guidelines:

download XCode (free) from the Apple Mac App Store
lauch it, it will ask you to agree to the terms of use, agree to them
open TERMINAL and do xcode-select --install to install the command line tools
download and install MacPorts (free)
once installed, in the TERMINAL, do sudo port selfupdate to get the latest sources packages
do sudo port install libtool autoconf automake flex bison py-pygments.
For gregorio versions prior to 4.0, if you are using --enable-xml-read then this additional dependency is needed: sudo port install libxml2.
Because the versions of git and bash which ship with OSX are not the most recent, you may also want to consider adding the following two packages: sudo port install bash git If you are planning on helping with development, then the bash upgrade is required.

Once all this is done, you should be able to compile Gregorio.

If you want to compile fonts (to modify them, or when building directly from git), do sudo port install fontforge.

If you intend to aid in development, then there are a couple of more packages which will come in handy: sudo port install python27 ImageMagick coreutils

Source downloading

You have a choice between versions of Gregorio. To obtain the sources of the stable version, you just need to download the sources from the download page, and decompress the archive. Previous versions and current beta or release candidates are also available on this page.

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).

To get the git version, that is, the version in development (more functionalities, but might contain more bugs), you will have to create a local copy of the git repository of the project, with the command:

$ git clone --depth 1 -b develop https://github.com/gregorio-project/gregorio.git gregorio-git

The above command minimizes the size of the download by not grabing the complete history of the repository. If you plan on helping with development, however, that complete history is essential and you should use the following command instead:

$ git clone https://github.com/gregorio-project/gregorio.git gregorio-git

Once cloned, you'll be on the master branch of the repository (latest stable release) and can use the normal git commands to navigate and explore the repository (for instance, you might want to checkout the develop branch before compilation).

Compilation

Once the sources are downloaded, open a TERMINAL window and navigate to the directory containing the source files. Once there, carry out the following commands:

$ ./build.sh --arch=x86_64
$ sudo ./install.sh

Nota bene: For versions of Gregorio prior to 4.0, you may want to add the following flags to build.sh: --enable-all-static --disable-shared --enable-static-ltdl. They will reduce the number of files installed on your machine by making the command line tool self contained, rather than using linked libraries.

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:

./build.sh --arch=x86_64 --prefix=/path/to/custom/root
sudo ./install.sh dir:/path/to/custom/texmf

Note: Due to a bug in the current release (v2.7-fix-3) of luaotfload the documentation cannot be built against TeXLive 2016 (see #1188). As a result, building from a clone of the repository will fail against that version. A work around for this bug exists (9fe9139), but using it breaks compilation under TeXLive 2015 and the bug has been fixed in the latest master for luaotfload. The result is that users should do one of the following:

Install using the Mac installer (recommended for those installing a stable release).
Switch to TeXLive 2015 to build the docs.
Upgrade your luaotfload to a more recent version (v2.8-rc1 or later).

Update

To update your git version, you just need to go into the directory containing the source files (assuming you kept it), run git pull and recompile with the same instructions as the previous Compilation section. If you deleted that directory after install, then just repeat the steps above starting at the git clone command.

Next steps

It can be very helpful to configure TeXShop for Gregorio. Once you have done so, refer to the introduction page to start using Gregorio !