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.
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.
scripts/auxiliar/fixcc.py lily/my-test-file.cc
@end example
-Be sure you replace @code{my-test-file.cc} with the name of the file
+Be sure you replace @file{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
@}
@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 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)
@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
* 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.
rule will simply point out to the user that the feature needs
manual correction.
+@subsubheading Updating version numbers
-@node Automatically update auxiliary information
-@subsection Automatically update auxiliary information
-
-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.
-
-The automatic updating is a three step process. First, be sure you
-are in the top-level source directory. Then, for the
-documentation, do:
+If a development release occurs between you writing your patch and
+having it approved+pushed, you will need to update the version
+numbers in your tree. This can be done with:
@example
-find Documentation/ -name '*.itely' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
+scripts/auxiliar/update-patch-version old.version.number new.version.number
@end example
-@noindent
-where @var{X.Y.Z} is the version number of the last released development
-version.
+It will change all files in git, so use with caution and examine
+the resulting diff.
+
-Next, for the snippets, do:
+@node Automatically update documentation
+@subsection Automatically update documentation
+
+@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 performed by moving to the top-level
+source directory, then running:
@example
-find Documentation/snippets/ -name '*.ly' | xargs convert-ly -e --from @qq{@var{X.Y.Z}}
+scripts/auxiliar/update-with-convert-ly.sh
@end example
-Finally, for the regression tests, do:
+If you did an out-of-tree build, pass in the relative path:
@example
-find input/regression/ -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
-@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.
-
-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
@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