-
Notifications
You must be signed in to change notification settings - Fork 15
/
installation.html
167 lines (134 loc) · 13.3 KB
/
installation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
<!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">
<!-- IE patch-->
<div class="text">
<!-- End of header -->
<!-- header -->
<h1>Installing Gregorio</h1>
<h2>Before you install Gregorio</h2>
<p>If you have never used <span class="tex">T<span class="epsilon">e</span>X</span> before, then we strongly recommend that you start to familiarize yourself with gabc by using the <a href="http://apps.illuminarepublications.com/gregorio/">Illuminare Score Editor</a> or the <a href="http://gregorio.gabrielmass.com/cgi/process.pl">Gregorio Chant Engraver</a>. These online tools will only require you to learn about gabc itself, while handling the considerable overhead that comes with using <span class="tex">T<span class="epsilon">e</span>X</span> for you. You won't have access to all of the features of Gregorio<span class="tex">T<span class="epsilon">e</span>X</span>, but you won't have to learn two things at once, making it much easier to ease into the use of Gregorio.</p>
<p>Once you have mastered gabc itself, and find yourself wanting access to more of the capabilities of Gregorio<span class="tex">T<span class="epsilon">e</span>X</span>, then you need to get yourself a <span class="tex">T<span class="epsilon">e</span>X</span> distribution. The most common distribution is <a href="https://www.tug.org/texlive/"><span class="tex">T<span class="epsilon">e</span>X</span> Live</a>. 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 <span class="tex">T<span class="epsilon">e</span>X</span> Live called <a href="http://www.tug.org/mactex/">Mac<span class="tex">T<span class="epsilon">e</span>X</span></a> which does a much better job of integrating it into the Mac environment than the cross-platform installer. Another common distribution is <a href="https://miktex.org">MiK<span class="tex">T<span class="epsilon">e</span>X</span></a> which now supports all three major platforms (Windows, Mac, and Linux in its Ubuntu/Mint varieties).</p>
<h2>One more thing...</h2>
<p>If you have a full installation of <span class="tex">T<span class="epsilon">e</span>X</span> Live (including Mac<span class="tex">T<span class="epsilon">e</span>X</span>), 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 <span class="tex">T<span class="epsilon">e</span>X</span> Live:</p>
<table>
<tr>
<th><span class="tex">T<span class="epsilon">e</span>X</span> Live version</th>
<th>Gregorio version</th>
</tr>
<tr>
<td>2016</td>
<td>4.1</td>
</tr>
<tr>
<td>2017</td>
<td>5.0</td>
</tr>
<tr>
<td>2018</td>
<td>5.1</td>
</tr>
<tr>
<td>2019</td>
<td>5.2</td>
</tr>
<tr>
<td>2020</td>
<td>5.2</td>
</tr>
<tr>
<td>2021</td>
<td>6.0</td>
</tr>
</table>
<p>If you have MiK<span class="tex">T<span class="epsilon">e</span>X</span>, then Gregorio is also included there. Because of Mik<span class="tex">T<span class="epsilon">e</span>X</span>'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 MiK<span class="tex">T<span class="epsilon">e</span>X</span> Console.</p>
<h2>And now, finally, the installation instructions</h2>
<p>If your <span class="tex">T<span class="epsilon">e</span>X</span> 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:</p>
<ul>
<li><a href="installation-windows.html">installation under Windows</a></li>
<li><a href="installation-linux.html">installation under GNU/Linux</a></li>
<li><a href="installation-mac.html">installation under MacOS X</a></li>
</ul>
<h2>Configuration</h2>
<h3>Executable Access</h3>
<p>By default Lua<span class="tex">T<span class="epsilon">e</span>X</span> (and all other varieties of <span class="tex">T<span class="epsilon">e</span>X</span> 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 <span class="tex">T<span class="epsilon">e</span>X</span> Live or MiK<span class="tex">T<span class="epsilon">e</span>X</span>, 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:</p>
<ul>
<li><p>Use <code>--shell-escape</code> when compiling documents making use of Gregorio. This option enables Lua<span class="tex">T<span class="epsilon">e</span>X</span> 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 <a href="#editor">Editor Configuration</a> below.</p></li>
<li><p>Make the <code>--shell-escape</code> mode the default by setting <code>shell_escape=t</code> in texmf.cnf. <b>This will make all compilations less secure</b>, but means that you don't have to specify the <code>--shell-escape</code> flag on any given run. You should only do this if you trust <b>all</b> the documents you run through <span class="tex">T<span class="epsilon">e</span>X</span> on your system.</p>
<p>To find your texmf.cnf file, execute <code>kpsewhich texmf.cnf</code> from the command line. Open the file at the given location and search for <code>shell_escape=p</code> and then change the <code>p</code> to <code>t</code>. If you cannot find this line, then you can simply add <code>shell_escape=t</code> to the bottom of the file.</p></li>
<li><p>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.</p>
<p>The list that needs editting is called <code>shell_escape_commands</code> and the program that needs to be added to it is called <code>gregorio-x_y_z</code> where <code>x_y_z</code> 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 use <code>kpsewhich -a texmf.cnf</code> to find the lower-level configuration file. <b>Do not edit those lower level files.</b> Instead, copy the <code>shell_escape_commands</code> 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.</p></li>
<li><p>Create a symlink on your system that points <code>gregorio</code> to <code>gregorio-x_y_z</code>) (where <code)x_y_z</code> is the version number of Gregorio that you've installed). This symlink must be on your <code>PATH</code> before the folder containing the <span class="tex">T<span class="epsilon">e</span>X</span> executables so that it hides the executable that comes with <span class="tex">T<span class="epsilon">e</span>X</span>. 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.</p></li>
<li><p>Resign yourself to using Gregorio in the old school way. This means turning off the autocompile feature and manually running <code>gregorio-x_y_z</code> on your gabc files to generate the gtex files. This doesn't work for <code>\gabcsnippet</code> (only <code>\gregorioscore</code>) and is damned inconvenient generally, but it is possible, so we list it here to be complete.</p></li>
</ul>
<p>For more information about texmf.cnf files (and related issues) we suggest reading <a href="https://texfaq.org/FAQ-privinst">this page</a> or asking a question at <a href="https://tex.stackexchange.com"><span class="tex">T<span class="epsilon">e</span>X</span> Stack Exchange</a>.
<h3 id="editor">Editor Configuration</h3>
<p>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:</p>
<ul>
<li><a href="configuration-texworks.html"><span class="tex">T<span class="epsilon">e</span>X</span>works</a> (a cross platform editor for Linux, Mac, and Windows)</li>
<li><a href="configuration-texshop.html"><span class="tex">T<span class="epsilon">e</span>X</span>Shop</a> (a Mac only editor)</li>
</ul>
<h3 id="uninstall">Uninstalling Gregorio</h3>
<p>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.</p>
<h4><span class="tex">T<span class="epsilon">e</span>X</span> Live or MiK<span class="tex">T<span class="epsilon">e</span>X</span> (All OSes)</h4>
<p>Make use of the package installation tools for these distributions to remove a version of Gregorio which was installed by them.</p>
<h4>Windows Installer</h4>
<p>Use the Uninstall feature of Add/Remove Programs. See the Windows documentation for more information.</p>
<h4>MacOS Installer</h4>
<p>Use the Uninstall-Gregorio-*.*.*.pkg that corresponds to the version which you installed. Download it from the <a href="https://github.com/gregorio-project/gregorio/releases">appropriate release page</a> and run it just like you did the original installer.</p>
<h4>Command-line installation (MacOS and Linux)</h4>
<p>If you've installed a version of Gregorio from the command-line, there is a <code>uninstall-gtex.sh</code> script which is generated during the installation process which you can use. This file is placed at <code>TEXMFLOCAL/scripts/gregoriotex/uninstall-gtex.sh</code> (where <code>TEXMFLOCAL</code> is the place where you installed Gregorio<span class="tex">T<span class="epsilon">e</span>X</span>, usually the output of <code>kpsewhich --var-value TEXMFLOCAL</code>. 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:</p>
<div class="commandline">
<code>chmod +x $(kpsewhich --var-value TEXMFLOCAL)/scripts/gregoriotex/uninstall-gtex.sh</code><br>
<code>$(kpsewhich --var-value TEXMFLOCAL)/scripts/gregoriotex/uninstall-gtex.sh</code>
</div>
<p>This removes the Gregorio<span class="tex">T<span class="epsilon">e</span>X</span> components. Once that's done, you simply need to delete the executable, which can be done using <code>make uninstall</code> in the source code directory. If you did not keep your source code download, then make use of <code>which</code> and <code>rm</code> to locate and delete the executable (it should be named <code>gregorio-*_*_*</code>, where the wild cards correspond to the version number that was installed).</p>
<p><b>Note:</b> Depending on how and where you installed Gregorio, you may need to execute some of the above commands as root.</p>
<!-- footer -->
</div>
<div class="bottom">
</div>
<script>initialize_menu();</script>
</body>
</html>