* Programming without compiling::
* Finding functions::
* Code style::
+* Warnings Errors Progress and Debug Output::
* Debugging LilyPond::
* Tracing object relationships::
* Adding or modifying features::
begins.
Each type of music event has an associated iterator. Iterators are defined in
-*-iterator.cc. During iteration, an
+@file{*-iterator.cc}. During iteration, an
event's iterator is called to deliver that music event to the appropriate
context(s).
through its two derived classes: Engraver (for graphical output) and
Performer (for midi output).
-Translators are defined in C++ files named *-engraver.cc and *-performer.cc.
+Translators are defined in C++ files named @file{*-engraver.cc}
+and @file{*-performer.cc}.
Much of the work of translating is handled by Scheme functions,
which is one of the keys to LilyPond's exceptional flexibility.
@node Programming without compiling
@section Programming without compiling
-Much of the development work in LilyPond takes place by changing *.ly or
-*.scm files. These changes can be made without compiling LilyPond. Such
+Much of the development work in LilyPond takes place by changing @file{*.ly} or
+@file{*.scm} files. These changes can be made without compiling LilyPond. Such
changes are described in this section.
Much of LilyPond is written in Scheme or LilyPond input files. These
files are interpreted when the program is run, rather than being compiled
when the program is built, and are present in all LilyPond distributions.
-You will find .ly files in the ly/ directory and the Scheme files in the
-scm/ directory. Both Scheme files and .ly files can be modified and
+You will find @file{.ly} files in the @file{ly/} directory and the Scheme files in the
+@file{scm/} directory. Both Scheme files and @file{.ly} files can be modified and
saved with any text editor. It's probably wise to make a backup copy of
your files before you modify them, although you can reinstall if the
files become corrupted.
This command will search all the contents of the directory subdirectory/
and display every line in any of the files that contains
-functionName. The @code{-i} option makes @command{grep} ignore
+functionName. The @option{-i} option makes @command{grep} ignore
case -- this can be very useful if you are not yet familiar with
our capitalization conventions.
-The most likely directories to grep for function names are scm/ for
-scheme files, ly/ for lilypond input (*.ly) files, and lily/ for C++
+The most likely directories to grep for function names are @file{scm/} for
+scheme files, ly/ for lilypond input (@file{*.ly}) files, and @file{lily/} for C++
files.
@node Indentation
@subsection Indentation
-Standard GNU coding style is used. In emacs:
+Standard GNU coding style is used.
-@verbatim
- (add-hook 'c++-mode-hook
- '(lambda() (c-set-style "gnu")
- ))
-@end verbatim
-
-If you like using font-lock, you can also add this to your
-@q{.emacs}:
-
-@verbatim
- (setq font-lock-maximum-decoration t)
- (setq c++-font-lock-keywords-3
- (append
- c++-font-lock-keywords-3
- '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
- ))
-@end verbatim
+@subsubheading Indenting files with @code{fixcc.py} (recommended)
-Some source files may not currently have proper indenting. If this
-is the case, it is desirable to fix the improper indenting when the
-file is modified, with the hope of continually improving the code.
-
-
-@subheading Indenting files with fixcc.py
-
-LilyPond provides a python script that will correct the indentation
-on a c++ file:
+LilyPond provides a python script that will adjust the indentation
+and spacing on a @code{.cc} or @code{.hh} file to very near the
+GNU standard:
@example
-scripts/auxiliar/fixcc.py lily/my-test-file.cc
+scripts/auxiliar/fixcc.py FILENAME
@end example
-Be sure you replace @code{my-test-file.cc} with the name of the file
-that you edited.
-
-If you are editing a file that contains an ADD_TRANSLATOR or ADD_INTERFACE
-macro, the fixcc.py script will move the final parenthesis up one line
-from where it should be. Please check the end of the file before
-you run fixcc.py, and then put the final parenthesis and semicolon
-back on a line by themselves.
+This can be run on all files at once, but this is not recommended
+for normal contributors or developers.
+@smallexample
+scripts/auxiliar/fixcc.py \
+ $(find flower lily -name '*cc' -o -name '*hh' | grep -v /out)
+@end smallexample
-@subheading Indenting files with emacs in script mode
-@c email to wl@gnu.org when I get here.
+@subsubheading Indenting with emacs
-@warning{this is pending some confirmation on -devel. July 2009 -gp}
-
-Command-line script to format stuff with emacs:
+The following hooks will produce indentation which is similar to
+our official indentation as produced with @code{fixcc.py}.
@example
-#!/bin/sh
-emacs $1 -batch --eval '(indent-region (point-min) (point-max) nil)' -f save-buffer
+(add-hook 'c++-mode-hook
+ '(lambda ()
+ (c-set-style "gnu")
+ (setq indent-tabs-mode nil))
@end example
-(that's all on one line)
+If you like using font-lock, you can also add this to your
+@file{.emacs}:
-Save it as a shell script, then run on the file(s) you modified.
+@example
+(setq font-lock-maximum-decoration t)
+(setq c++-font-lock-keywords-3
+ (append
+ c++-font-lock-keywords-3
+ '(("\\b\\(a-zA-Z_?+_\\)\\b" 1 font-lock-variable-name-face) ("\\b\\(A-Z?+a-z_?+\\)\\b" 1 font-lock-type-face))
+ ))
+@end example
@subheading Indenting with vim
-Although emacs indentation is the LilyPond standard, acceptable
+Although emacs indentation is the GNU standard, acceptable
indentation can usually be accomplished with vim. Some hints for
vim are as follows:
A workable .vimrc:
-@verbatim
+@example
set cindent
set smartindent
set autoindent
set ignorecase smartcase
set hlsearch
set confirm
-set statusline=%F%m%r%h%w\ %{&ff}\ %Y\ [ASCII=\%03.3b]\ [HEX=\%02.2B]\ %04l,%04v\ %p%%\ [LEN=%L]
+set statusline=%F%m%r%h%w\ %@{&ff@}\ %Y\ [ASCII=\%03.3b]\ [HEX=\%02.2B]\ %04l,%04v\ %p%%\ [LEN=%L]
set laststatus=2
set number
" Remove trailing whitespace on write
autocmd BufWritePre * :%s/\s\+$//e
-@end verbatim
+@end example
-With this .vimrc, files can be reindented automatically by highlighting
-the lines to be indented in visual mode (use V to enter visual mode)
-and pressing =.
+With this @file{.vimrc}, files can be reindented automatically by
+highlighting the lines to be indented in visual mode (use V to
+enter visual mode) and pressing @code{=}.
-A scheme.vim file will help improve the indentation. This one
-was suggested by Patrick McCarty. It should be saved in
-~/.vim/after/syntax/scheme.vim.
+A @file{scheme.vim} file will help improve the indentation. This
+one was suggested by Patrick McCarty. It should be saved in
+@file{~/.vim/after/syntax/scheme.vim}.
-@verbatim
+@example
" Additional Guile-specific 'forms'
syn keyword schemeSyntax define-public define*-public
syn keyword schemeSyntax define* lambda* let-keywords*
" Try to highlight all ly: procedures
syn match schemeFunc "ly:[^) ]\+"
-@end verbatim
+@end example
@node Naming conventions
@}
@end example
-See also `flower/getopt-long.cc' and `lily/main.cc'.
+See also @file{flower/getopt-long.cc} and @file{lily/main.cc}.
@item
Do not use leading or trailing whitespace in messages. If you need
@end itemize
+@node Warnings Errors Progress and Debug Output
+@section Warnings, Errors, Progress and Debug Output
+
+@unnumberedsubsec Available log levels
+
+LilyPond has several loglevels, which specify how verbose the output on
+the console should be:
+@itemize
+@item NONE: No output at all, even on failure
+@item ERROR: Only error messages
+@item WARN: Only error messages and warnings
+@item BASIC_PROGRESS: Warnings, errors and basic progress (success, etc.)
+@item PROGRESS: Warnings, errors and full progress messages
+@item INFO: Warnings, errors, progress and more detailed information (default)
+@item DEBUG: All messages, including vull debug messages (very verbose!)
+@end itemize
+
+The loglevel can either be set with the environment variable
+@code{LILYPOND_LOGLEVEL} or on the command line with the @option{--loglevel=...}
+option.
+
+@unnumberedsubsec Functions for debug and log output
+
+LilyPond has two different types of error and log functions:
+@itemize
+
+@item
+If a warning or error is caused by an identified position in the input file,
+e.g. by a grob or by a music expression, the functions of the @code{Input}
+class provide logging functionality that prints the position of the message
+in addition to the message.
+
+@item
+If a message can not be associated with a particular position in an input file,
+e.g. the output file cannot be written, then the functions in the
+@code{flower/include/warn.hh} file will provide logging functionality that
+only prints out the message, but no location.
+
+@end itemize
+
+There are also Scheme functions to access all of these logging functions from
+scheme. In addition, the Grob class contains some convenience wrappers for
+even easier access to these functions.
+
+The message and debug functions in @code{warn.hh} also have an optional
+argument @code{newline}, which specifies whether the message should always
+start on a new line or continue a previous message.
+By default, @code{progress_indication} does NOT start on a new line, but rather
+continue the previous output. They also do not have a particular input
+position associated, so there are no progress functions in the Input class.
+All other functions by default start their output on a new line.
+
+The error functions come in three different flavors: fatal error messages,
+programming error messages and normal error messages. Errors written
+by the @code{error ()} function will cause LilyPond to exit immediately,
+errors by @code{Input::error ()} will continue the compilation, but
+return a non-zero return value of the lilypond call (i.e. indicate an
+unsuccessful program execution). All other errors will be printed on the
+console, but not exit LilyPond or indicate an unsuccessful return code.
+Their only differences to a warnings are the displayed text and that
+they will be shown with loglevel @code{ERROR}.
+
+If the Scheme option @code{warning-as-error} is set, any warning will be
+treated as if @code{Input::error} was called.
+
+
+@unnumberedsubsec All logging functions at a glance
+
+@multitable @columnfractions 0.16 0.42 0.42
+@headitem
+@tab C++, no location
+@tab C++ from input location
+
+@item ERROR
+@tab @code{error ()}, @code{programming_error (msg)}, @code{non_fatal_error (msg)}
+@tab @code{Input::error (msg)}, @code{Input::programming_error (msg)}
+
+@item WARN
+@tab @code{warning (msg)}
+@tab @code{Input::warning (msg)}
+
+@item BASIC
+@tab @code{basic_progress (msg)}
+@tab -
+
+@item PROGRESS
+@tab @code{progress_indication (msg)}
+@tab -
+
+@item INFO
+@tab @code{message (msg)}
+@tab @code{Input::message (msg)}
+
+@item DEBUG
+@tab @code{debug_output (msg)}
+@tab @code{Input::debug_output (msg)}
+
+@item @tab @tab
+
+@headitem
+@tab C++ from a Grob
+@tab Scheme, music expression
+
+@item ERROR
+@tab @code{Grob::programming_error (msg)}
+@tab -
+
+@item WARN
+@tab @code{Grob::warning (msg)}
+@tab @code{(ly:music-warning music msg)}
+
+@item BASIC
+@tab -
+@tab -
+
+@item PROGRESS
+@tab -
+@tab -
+
+@item INFO
+@tab -
+@tab @code{(ly:music-message music msg)}
+
+@item DEBUG
+@tab -
+@tab -
+
+@item @tab @tab
+
+@headitem
+@tab Scheme, no location
+@tab Scheme, input location
+
+@item ERROR
+@tab -
+@tab @code{(ly:error msg args)}, @code{(ly:programming-error msg args)}
+
+@item WARN
+@tab @code{(ly:warning msg args)}
+@tab @code{(ly:input-warning input msg args)}
+
+@item BASIC
+@tab @code{(ly:basic-progress msg args)}
+@tab -
+
+@item PROGRESS
+@tab @code{(ly:progress msg args)}
+@tab -
+
+@item INFO
+@tab @code{(ly:message msg args)}
+@tab @code{(ly:input-message input msg args)}
+
+@item DEBUG
+@tab @code{(ly:debug msg args)}
+@tab -
+
+@end multitable
+
+
+
@node Debugging LilyPond
@section Debugging LilyPond
@end example
@noindent
This loads the LilyPond symbol tables into gdb. Then, to run
-LilyPond on @code{test.ly} under the debugger, enter the following:
+LilyPond on @file{test.ly} under the debugger, enter the following:
@example
run test.ly
has all the LilyPond modules loaded. This requires the following
steps.
-First, define a Scheme symbol for the active module in the .ly file:
+First, define a Scheme symbol for the active module in the @file{.ly} file:
@example
#(module-define! (resolve-module '(guile-user))
'lilypond-module (current-module))
@end example
-Now place a Scheme function in the .ly file that gives an
+Now place a Scheme function in the @file{.ly} file that gives an
interactive Guile prompt:
@example
#(top-repl)
@end example
-When the .ly file is compiled, this causes the compilation to be
+When the @file{.ly} file is compiled, this causes the compilation to be
interrupted and an interactive guile prompt to appear. Once the
guile prompt appears, the LilyPond active module must be set as the
current guile module:
guile> (quit)
@end example
-The compilation of the .ly file will then continue.
+The compilation of the @file{.ly} file will then continue.
@subheading Using the Guile debugger
command at the guile prompt.
Embedding breakpoint commands like this is particularly useful if
-you want to look at how the Scheme procedures in the @var{.scm}
+you want to look at how the Scheme procedures in the @file{.scm}
files supplied with LilyPond work. To do this, edit the file in
the relevant directory to add this line near the top:
Now you can set a breakpoint after the procedure you are interested
in has been declared. For example, if you are working on routines
-called by @var{print-book-with} in @var{lily-library.scm}:
+called by @var{print-book-with} in @file{lily-library.scm}:
@example
(define (print-book-with parser book process-procedure)
In order for the Graphviz tool to work, config.make must be modified.
It is probably a good idea to first save a copy of config.make under
a different name. Then, edit config.make by removing every occurrence
-of @code{-DNDEBUG}.
+of @option{-DNDEBUG}.
@item Rebuilding LilyPond
@item Create a graphviz-compatible @file{.ly} file
In order to use the graphviz utility, the @file{.ly} file must include
-@file{ly/@/graphviz@/-init@/.ly}, and should then specify the
+@file{ly/graphviz-init.ly}, and should then specify the
grobs and symbols that should be tracked. An example of this
is found in @file{input/regression/graphviz.ly}.
output data. Delete everything from the beginning of the file
up to but not including the first occurrence of @code{digraph}.
+Also, delete the final liypond message about successs from the end
+of the file.
+
@item Process the logfile with @code{dot}
The directed graph is created from the log file with the program
The pdf file can then be viewed with any pdf viewer.
-When compiled without @code{-DNDEBUG}, lilypond may run slower
+When compiled without @option{-DNDEBUG}, lilypond may run slower
than normal. The original configuration can be restored by either
renaming the saved copy of @code{config.make} or rerunning
@code{configure}. Then rebuild lilypond with
* Write the code::
* Write regression tests::
* Write convert-ly rule::
-* Automatically update auxiliary information::
-* Manually update auxiliary information::
+* Automatically update documentation::
+* Manually update documentation::
* Edit changes.tely::
* Verify successful build::
* Verify regression tests::
In order to demonstrate that the code works properly, you will
need to write one or more regression tests. These tests are
-typically .ly files that are found in input/regression.
+typically @file{.ly} files that are found in @file{input/regression}.
Regression tests should be as brief as possible to demonstrate the
functionality of the code.
the resulting diff.
-@node Automatically update auxiliary information
-@subsection Automatically update auxiliary information
+@node Automatically update documentation
+@subsection Automatically update documentation
-convert-ly should be used to update the documentation, the snippets,
-and the regression tests. This not only makes the necessary syntax
-changes, it also tests the convert-ly rules.
+@command{convert-ly} should be used to update the documentation,
+the snippets, and the regression tests. This not only makes the
+necessary syntax changes, it also tests the @command{convert-ly}
+rules.
-The automatic updating is a three step process. First, be sure you
-are in the top-level source directory. Then, for the
-documentation, do:
+The automatic updating is performed by moving to the top-level
+source directory, then running:
@example
-find Documentation/ -name '*.itely' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
+scripts/auxiliar/update-with-convert-ly.sh
@end example
-@noindent
-where @var{X.Y.Z} is the version number of the last released development
-version.
-
-Next, for the snippets, do:
+If you did an out-of-tree build, pass in the relative path:
@example
-find Documentation/snippets/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
+BUILD_DIR=../build-lilypond/ scripts/auxiliar/update-with-convert-ly.sh
@end example
-Finally, for the regression tests, do:
-
-@example
-find input/regression/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
-
-@end example
-
-@node Manually update auxiliary information
-@subsection Manually update auxiliary information
+@node Manually update documentation
+@subsection Manually update documentation
Where the convert-ly rule is not able to automatically update the inline
lilypond code in the documentation (i.e. if a NOT_SMART rule is used), the
In order to avoid breaking LilyPond, it is important to verify that
the regression tests succeed, and that no unwanted changes are
introduced into the output. This process is described in
-@ref{Identifying code regressions}.
+@ref{Regtest comparison}.
@subheading Typical developer's edit/compile/test cycle
longer.
Running @command{make@tie{}check} will leave an HTML page
-@file{out/@/test@/-results/@/index@/.html}. This page shows all the
+@file{out/test-results/index.html}. This page shows all the
important differences that your change introduced, whether in the
layout, MIDI, performance or error reporting.
@node Post patch for comments
@subsection Post patch for comments
-For any change other than a minor change, a patch set should be
-posted on @uref{http://codereview.appspot.com/, Rietveld} for comment.
-This requires the use of an external package, git-cl, and an email
-account on Google.
-
-git-cl is installed by:
-
-@example
-git clone git://neugierig.org/git-cl.git
-@end example
-
-Then, add the git-cl directory to your PATH, or create a
-symbolic link to the git-cl and upload.py in one of your
-PATH directories (like usr/bin). git-cl is then
-configured by entering the command
-
-@example
-git cl config
-@end example
-
-@noindent
-in the LilyPond git directory and answering the questions that
-are asked. If you do not understand the question answer with just
-a newline (CR).
-
-The patch set is posted to Rietveld as follows. Ensure your changes
-are committed in a separate branch, which should differ from the
-reference branch to be used by just the changes to be uploaded.
-If the reference branch is to be origin/master, ensure this is
-up-to-date. If necessary, use git rebase to rebase the branch
-containing the changes to the head of origin/master. Finally,
-check out branch with the changes and enter the command:
-
-@example
-git cl upload <reference SHA1 ID>
-@end example
-
-@noindent
-where <reference SHA1 ID> is the SHA1 ID of the commit to be used
-as a reference source for the patch. Generally, this will be the
-SHA1 ID of origin/master, and in that case the command
-
-@example
-git cl upload origin/master
-@end example
-
-@noindent
-can be used.
-
-After prompting for your Google email address and password, the
-patch set will be posted to Rietveld.
-
-You should then announce the patch by sending
-an email to lilypond-devel, with a subject line
-starting with PATCH:, asking for comments on the patch.
-Alternately, you may Publish + Mail a (bogus) comment, in order
-to send an email to lilypond-devel.
-
-As revisions are made in response to comments, successive patch sets
-for the same issue can be uploaded by reissuing the git-cl command
-with the modified branch checked out.
-
-Sometimes in response to comments on revisions, the best way to
-work may require creation of a new branch in git. In order to
-associate the new branch with an existing Rietveld issue,
-the following command can be used:
-
-@example
-git cl issue issue-number
-@end example
-
-@noindent
-where @code{issue-number} is the number of the existing Rietveld
-issue.
-
+See @ref{Uploading a patch for review}.
@node Push patch
most of them are not drawn. See the break-visibility property in
item-interface.
+Here is another e-mail exchange. Janek WarchoĊ asked for a starting point
+to fixing 1301 (change clef colliding with notes). Neil Puttock replied:
+
+The clef is on a loose column (it floats before the head), so the
+first place I'd look would be lily/spacing-loose-columns.cc (and
+possibly lily/spacing-determine-loose-columns.cc).
+I'd guess the problem is the way loose columns are spaced between
+other columns: in this snippet, the columns for the quaver and tuplet
+minim are so close together that the clef's column gets dumped on top
+of the quaver (since it's loose, it doesn't influence the spacing).
@node Info from Han-Wen email
@subsection Info from Han-Wen email
@itemize
@item
-paper-score.cc , Paper_score::process_
+@file{paper-score.cc} , Paper_score::process_
@item
-system.cc , System::get_lines()
+@file{system.cc} , System::get_lines()
@item
The step, where things go from grobs to output, is in
System::get_line(): each grob delivers a Stencil (a Device
independent output description), which is interpreted by our
-outputting backends (scm/output-tex.scm and scm/output-ps.scm)
-to produce TeX and PS.
+outputting backends (@file{scm/output-tex.scm} and
+@file{scm/output-ps.scm}) to produce TeX and PS.
@end itemize
@subheading Where is the functionality associated with KEYWORDs?
-See my-lily-lexer.cc (keywords, there aren't that many) and ly/*.ly
-(most of the other backslashed \words are identifiers)
+See @file{my-lily-lexer.cc} (keywords, there aren't that many)
+and @file{ly/*.ly} (most of the other backslashed @code{/\words} are identifiers)
@subheading What Contexts/Properties/Music/etc. are available when they are processed?
What do you mean exactly with this question?
-See ly/engraver-init.ly for contexts, see scm/define-*.scm for other
-objects.
+See @file{ly/engraver-init.ly} for contexts,
+see @file{scm/define-*.scm} for other objects.
@subheading How do you decide if something is a Music, Context, or Grob property?
Why is part-combine-status a Music property when it seems (IMO)
\autochange is one of these extra strange beasts: it requires
look-ahead to decide when to change staves. This is achieved by
-running the interpreting step twice (see scm/part-combiner.scm , at
-the bottom), and storing the result of the first step (where to switch
+running the interpreting step twice (see
+@file{scm/part-combiner.scm} , at the bottom), and
+storing the result of the first step (where to switch
staves) in a Music property. Since you want to influence that
where-to-switch list, your must affect the code in
-make-autochange-music (scm/part-combiner.scm). That code is called
-directly from the parser and there are no official "parsing
-properties" yet, so there is no generic way to tune \autochange. We
-would have to invent something new for this, or add a separate
-argument,
+make-autochange-music (@file{scm/part-combiner.scm}).
+That code is called directly from the parser and there are no
+official "parsing properties" yet, so there is no generic way
+to tune \autochange. We would have to invent something new
+for this, or add a separate argument,
@example
\autochange #around-central-C ..music..
-> the second c' remains untransposed.
-Take a look at lily/music.cc to see where the transposition takes place.
+Take a look at @file{lily/music.cc} to see where the transposition takes place.
@subheading How do I tell about the execution environment?
@end example
noindent
-inside the .ly file.
+inside the @file{.ly} file.
The breakpoint failing may have to do with the call sequence. See
-parser.yy, run_music_function(). The function is called directly from
+@file{parser.yy}, run_music_function(). The function is called directly from
C++, without going through the GUILE evaluator, so I think that is why
there is no debugger trap.
projects / lilypond.git / blobdiff