<chapter id="running">
<title>Running &lilypond;</title>

<sect1 id="pdf_output">
<title>Creating PDF output</title>

<para>
There are currently three different ways you can run &lilypond; on your document.
</para>

<para>
The default one (by pressing the toolbar button or <keycap>Ctrl+M</keycap>) is to output a PDF
preview document. This document contains clickable notes and other objects. If
you click on a note or other object, &frescobaldi; will put the text cursor in the
correct place (and even open the document for you if needed). You can also select fragments
of the &lilypond; input by clicking a note and then shift-clicking another one.
</para>

<para>
In the <guilabel>&lilypond;</guilabel> menu, you can also find the command <guilabel>Run &lilypond; (publish)</guilabel>.
This option also runs &lilypond;, but with clickable notes disabled. The resulting PDF
is much smaller and better suitable for distribution via e-mail or the Web. With
large musical scores, disabling the clickable notes can make the PDF many times
smaller.
</para>

<para>
The third possibility is the command <guilabel>Run &lilypond; (custom)</guilabel>.
This option shows a dialog where you can set some parameters for this run, overriding default settings.
If you have <link linkend="multiple-versions">multiple versions of &lilypond;</link> installed,
you can choose which &lilypond; you want to run.
</para>

<figure>
  <title>The custom Run LilyPond dialog</title>
  <mediaobject>
  <imageobject><imagedata format="PNG" fileref="run-lilypond1.png"/></imageobject>
  <textobject>
  <phrase>The custom Run LilyPond dialog</phrase>  
  </textobject>
  </mediaobject>
</figure>

<para>
While &lilypond; is running, you can follow its progress in the log view. If
&lilypond; encounters errors, you can click on the messages to place the text
cursor in the offending line and column. If there are many errors you want to
correct without waiting for &lilypond; to be finished, you can click the &lilypond;
button again to abort the running &lilypond; process.
</para>

<para>
When you want to run &lilypond; but your document has not been saved yet,
or has been saved to a non-local directory,
&frescobaldi; copies the document contents to a file in a temporary directory
on you local drive, and then runs &lilypond; on it.
</para>

<para>
If your document is on the local drive but has been modified,
&frescobaldi; asks you to save it first. (&frescobaldi; does not use a temporary directory
for files that are already on the local drive.)
If you want &frescobaldi; to always save your last local modifications before running
&lilypond;, check the box &quot;Don't ask this question again.&quot;
(Under
<menuchoice>
  <guimenu>Settings</guimenu>
  <guimenuitem>Configure &frescobaldi;...</guimenuitem>
</menuchoice> you can re-enable this warning if you want.)
</para>

<para>
If &lilypond; created a PDF, you can open it in your default PDF viewer
by clicking the <guibutton>Play/View</guibutton> toolbar button
and selecting the file in the drop-down menu.
You can print the PDF using the <guibutton>Print Music</guibutton> button.
You can email all generated files (including source files) using
<menuchoice>
  <guimenu>File</guimenu>
  <guimenuitem>Email Documents</guimenuitem>
</menuchoice>.
</para>

</sect1>

<sect1 id="midi_output">
<title>Creating MIDI output</title>

<para>
If you want &lilypond; to create a MIDI file, add a <userinput>\midi { }</userinput>
line in your <userinput>\score { }</userinput> section, like this:
</para>

<programlisting>
<![CDATA[\score {
  \relative c'' {
    \time 7/4
    c2 bes4 a2 g a bes4 a( g) f2
  }
  \addlyrics {
    Join us now and share the soft -- ware!
  }
  \layout { }
  \midi { }
}]]>
</programlisting>

<para>
Be sure to also add a <userinput>\layout { }</userinput> line if you add a <userinput>\midi { }</userinput> line, otherwise
&lilypond; will not generate a PDF.
</para>

<para>
To play the generated MIDI file(s) in an external MIDI player,
click the Play/View toolbar button and select the file from the drop-down menu.
You can also use the built-in MIDI player.
</para>

<sect2 id="kmid">
<title>The built-in MIDI player</title>

<para>
The built-in MIDI player can be started by clicking its tab at the bottom of the &frescobaldi; window or
by pressing <keycap>Meta+Alt+M</keycap>.
If a &lilypond; document generated multiple MIDI files, you can select which one to play.
Use the small play and pause buttons to play the MIDI file.
</para>

<para>
The media keys (<keycap>Play/Pause</keycap> and <keycap>Stop</keycap>) and the <keycap>Pause</keycap> key can also be used
to start or stop the music. If you pause the music using the <keycap>Pause</keycap> key, the music will automatically
rewind a few seconds when you start the playing again.
</para>

<para>
The built-in MIDI player uses the embeddable MIDI player component of
<ulink url="http://kmid2.sourceforge.net/">KMid</ulink> version 2.4.0 or higher.
If the MIDI player doesn't work it is recommended to run KMid once from the Applications menu to
configure its sound settings.
</para>

</sect2>

</sect1>

<sect1 id="include">
<title>&lilypond; files that include other files</title>

<para>
When working on large music scores, it might be possible that you divide the
musical score in different files, and include them from a "master" file. Such a
master file, named e.g. <filename>NewSong.ly</filename>, might look like:
</para>

<programlisting>
<![CDATA[\version "2.12.0"

\header {
  title = "New Song"
}

\include "LayoutSettings.ly"

\include "SopranoPart.ly"
\include "PianoPart.ly"

\score {
  <<
    \new Staff = "soprano" \sopranoMusic
    \new Lyrics \lyricsto "soprano" \sopranoText
    \new PianoStaff <<
      \new Staff = "right" \rightHandMusic
      \new Staff = "left" \leftHandMusic
    >>
  >>
}]]>
</programlisting>

<para>
The files <filename>SopranoPart.ly</filename> and <filename>PianoPart.ly</filename> just contain the music definitions and
<filename>LayoutSettings.ly</filename> has some settings for font and page layout etc. Neither one of
them has a <userinput>\score { }</userinput> section in it. So pressing <keycap>Ctrl+M</keycap> and running &lilypond;
while you are working on such an included document might not make much sense, as
it would probably not generate a PDF output file (the document only contains
music expressions that are assigned to variables).
</para>

<para>
In such cases, you can tell &frescobaldi; that another file is the "master" file
for the current document. When you run &lilypond;, &frescobaldi; will run &lilypond;
on the master document rather than the current document. So in <filename>SopranoPart.ly</filename>
and <filename>PianoPart.ly</filename> you add a special line that is just a &lilypond; comment. But
&frescobaldi; will read the line and understand that you want &lilypond; to be run
on the master file. Here is an example how <filename>SopranoPart.ly</filename> would look like:
</para>

<programlisting>
<![CDATA[\version "2.12.0"

% Soprano part

sopranoMusic = \relative c' {
  c d e f g f e d
}

sopranoText = \lyricmode {
  Boer er ligt een kip in't wa -- ter
}

%%master: NewSong.ly
]]></programlisting>

<para>
The last line <userinput>%%master: &lt;filename&gt;</userinput> directs &frescobaldi; to compile <filename>NewSong.ly</filename>
instead of the current document when &lilypond; is started.
</para>

<para>
There are two related special comments: <userinput>%%master-preview:</userinput> and <userinput>%%master-publish:</userinput>.
Those will only compile the named file in either preview or publish mode. That
can be useful if you include several movements or e.g. hymns in a master file,
where every source file has it's own score section. If you e.g. use
<userinput>%%master-publish</userinput>, running in preview mode will just show the current document,
but running in publish mode will compile the master document so you get a view
on the whole score or book. 
</para>

<para>
"Master" and include files only work with documents that are on your local hard drive.
</para>
</sect1>


<sect1 id="multiple-versions">
<title>Using multiple &lilypond; versions</title>

<para>
If you have multiple versions of &lilypond; installed you can add them to &frescobaldi;
under &menu.settings.lilypond;.
One of the &lilypond; instances can be set as the default.
It is also possible to automatically start a &lilypond; instance with a version closest
to the <userinput>\version</userinput> statement in your document.
You can even download and install different binary releases of &lilypond; from within
&frescobaldi;.
See <link linkend="settings-lilypond">Settings Dialog, &lilypond; Preferences</link> for more information.
</para>

</sect1>

</chapter>