<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>
After a succesful &lilypond; run, you will see some buttons appear at the bottom
of the Log view.
</para>

<para>
If &lilypond; created a PDF, buttons will be shown to open the PDF in the default
PDF viewer, and to print the PDF document.
</para>

</sect1>

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

<para>
If &lilypond; created a MIDI file, a button will be shown to play the MIDI in the
default MIDI player. 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>
Also an email button is shown, allowing you to easily send the source and output
documents to someone else using your default mail client.
</para>

</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.
See <link linkend="settings-lilypond">Settings Dialog, &lilypond; Preferences</link> for more information.
</para>

</sect1>


</chapter>