# Running &lilypond;

## Creating PDF output

There are currently two different ways you can run &lilypond; on your document.

The default one (by pressing the toolbar button or Ctrl+M) 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.

In the &lilypond; menu, you can also find the option Run &lilypond; (publish). 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.

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.

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.

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;, you can go to Settings Configure &frescobaldi;... and check the option Save document when &lilypond; is run.

After a succesful &lilypond; run, you will see some buttons appear at the bottom of the Log view.

If &lilypond; created a PDF, a button will be shown to open the PDF in the default PDF viewer, and a button to (directly!) print the PDF by sending it to the `lpr` command. (You can configure a different print command in &menu.settings.printcommand;.)

## Creating MIDI output

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 `\midi { }` line in your `\score { }` section, like this:

    \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 { }
    }

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

Also an email button is shown, allowing you to easily send the source and output documents to someone else using your default mail client.

## &lilypond; files that include other files

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. `NewSong.ly`, might look like:

    \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
        >>
      >>
    }

The files `SopranoPart.ly` and `PianoPart.ly` just contain the music definitions and `LayoutSettings.ly` has some settings for font and page layout etc. Neither one of them has a `\score { }` section in it. So pressing Ctrl+M 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).

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 `SopranoPart.ly` and `PianoPart.ly` 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 `SopranoPart.ly` would look like:

    \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

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

There are two related special comments: `%%master-preview:` and `%%master-publish:`. 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 `%%master-publish`, 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.

"Master" and include files only work with documents that are on your local hard drive.