installation-linux.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <!--
  Gregorio web site.
  Copyright (C) 2007-2015 The Gregorio project

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  -->
  <title>Gregorio project website</title>
  <meta http-equiv="content-type" content="text/html; charset=utf-8">
  <meta name="description" content="Free software for typesetting Gregorian chant" lang="en">
  <meta name="keywords" content="Gregorian chant, gregorio, gabc, gregoriotex" lang="en">
  <meta name="author" content="The Gregorio project">
  <link rel="shortcut icon" href="./illus/fav.ico">
  <link rel="icon" href="./illus/fav.ico">
  <link rel="stylesheet" href="./style.css" type="text/css" title="default">
  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
  <script type="text/javascript" src="./gregorio-menu.js"></script>
  <script>
    var context = 'gregorio';
    var title = 'Gregorio project website'
  </script>
</head>

<body>
  <div id="ban">
    <img src="./illus/harpedroite.png" title="" class="hd" alt="" />
    <a id="haut" name="haut"></a>
    <div id="banniere">
    </div>
  </div>
  <script>write_gre_menu();</script>
  <div class="flux">
    &nbsp;
    <!-- IE patch-->
    <div class="text">
      <!-- End of header -->
<!-- header -->

<h1>Installing Gregorio under Linux</h1>

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

<h2>Most Recent Release</h2>

<h3>Install dependencies</h3>

<p>As Gregorio uses Lua<span class="tex">T<span class="epsilon">e</span>X</span> to produce the final printed socres, you need to obtain a <span class="tex">T<span class="epsilon">e</span>X</span> distribution which contains this engine.  We recommend <span class="tex">T<span class="epsilon">e</span>X</span>Live.  You can get this either via your package manager (in which case make sure you get the package which contains  the Lua<span class="tex">T<span class="epsilon">e</span>X</span> engine and tools, as package managers often split <span class="tex">T<span class="epsilon">e</span>X</span>Live up into multiple packages to reduce the download size) or from the <a href="https://www.tug.org/texlive/"><span class="tex">T<span class="epsilon">e</span>X</span>Live homepage.</a></p>

<p>While we recommend that you get a complete <span class="tex">T<span class="epsilon">e</span>X</span>Live 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 Lua<span class="tex">T<span class="epsilon">e</span>X</span> engine, but at least xcolor and xstring are known to be in other collections on some platforms.  Additionally, Gregorio 4.1 is included in <span class="tex">T<span class="epsilon">e</span>X</span>Live, 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.  You may also be able to use the package manager to install Gergorio 4.1 in this fashion.</p>

<p>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:</p>

<div class="commandline">
    <code>sudo apt-get install build-essential</code>
</div>


<h3>Obtaining Source</h3>

<p>To obtain the sources of the stable version, you just need to download them from the <a href="https://github.com/gregorio-project/gregorio/releases/latest">download page</a>, and decompress the archive.</p>

<p><b>Nota bene:</b> 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).</p>

<h3>Building & Installing</h3>

<p>While you could follow the usual route of using <code>make</code> 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:</p>

<div class="commandline">
    <code>./build.sh</code><br/>
    <code>sudo ./install.sh</code>
</div>

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

<div class="commandline">
<code>sudo su ./install.sh</code>
</div>

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

<p>Assuming nither of these commands spit out an error message, then you've successfully installed Gregorio and are ready for the <a href="#next">Next Steps</a>.</p>

<h3>Alternate Installation Locations</h3>

<p>By default the automatic installation process will install gregorio in <code>/usr/local/</code> and Gregorio<span class="tex">T<span class="epsilon">e</span>X</span> 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:</p>

<div class="commandline">
    <code>./build.sh --prefix=/path/to/custom/root</code><br/>
    <code>sudo ./install.sh dir:/path/to/custom/texmf</code>
</div>

<h2>Most Recent Development Version</h2>

<h3>Install Dependencies</h3>

<p>In addition to <span class="tex">T<span class="epsilon">e</span>X</span>Live, 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:</p>

<div class="commandline">
    <code>sudo apt-get install git autoconf libltdl7-dev flex bison fontforge python-pygments</code>
</div>

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

<p>If you intend to contribute to development, then you'll also need the following:</p>

<div class="commandline">
    <code>imagemagick</code>
</div>

<p>For building gregorio versions prior to 4.0 this additional dependency is needed:</p>

<div class="commandline">
    <code>libxml2-dev</code>
</div>


<h3>Obtaining Soruces</h3>

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

<div class="commandline">
<code>git clone --depth 1 -b develop https://github.com/gregorio-project/gregorio.git gregorio-git</code><br/>
<code>cd gregorio-git</code>
</div>

<p><b>Nota Bene:</b> 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.</p>

<h3>Building & Installing</h3>

<p>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.</p>

<p>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:</p>

<div class="commandline">
    <code>./build.sh --force=autoreconf</code><br/>
</div>

<p><b>Note:</b> Due to a bug in the current release (v2.7-fix-3) of <code>luaotfload</code> the documentation cannot be built against TeXLive 2016 (see <a href="https://github.com/gregorio-project/gregorio/issues/1188">#1188</a>).  As a result, building from a clone of the repository will fail against that version.  A work around for this bug exists (<a href="https://github.com/henryso/gregorio/commit/9fe9139178dce6adebffbae65016800748450b61">9fe9139</a>), but using it breaks compilation under TeXLive 2015 and the bug has been fixed in the latest master for <code>luaotfload</code>.  The result is that users should do one of the following:</p>

<ul>
<li>Install from the distribution tar ball (recommended for those installing a stable release).</li>
<li>Switch to TeXLive 2015 to build the docs.</li>
<li>Upgrade your <code>luaotfload</code> to a more recent version (v2.8-rc1 or later).</li>
</ul>


<h3>Updating</h3>

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

<h2 id="next">Next steps</h2>

<p>If you've used <span class="tex">T<span class="epsilon">e</span>X</span> 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 href="./introduction.html">a list of the instruction pages here.</a>)</p>

<p> If you're new to <span class="tex">T<span class="epsilon">e</span>X</span>, we suggest that you make use of <span class="tex">T<span class="epsilon">e</span>X</span>works.  It's a basic IDE (integrated development environment) for using <span class="tex">T<span class="epsilon">e</span>X</span> and family and will provide you with a friendly GUI (graphic user interface).  You will need to <a href="./configuration-texworks.html">configure it for Gregorio</a>.  Once that's done, just follow <a href="./introduction-editor.html">the basic inscrutions for how to use Gregorio</a>.  We also strongly recommend going through <a href="./tutorial/tutorial-gabc-01.html">the tutorial</a> as it provides the easiest introduction to the workflow that we have devised.</p>

<!-- footer -->
    </div>
    <div class="bottom">
    </div>
    <script>initialize_menu();</script>
  </body>
</html>