@menu
* Overview of LilyPond architecture::
* LilyPond programming languages::
-* Programming without compiling::
-* Finding functions::
-* Code style::
-* Debugging LilyPond::
+* Programming without compiling::
+* Finding functions::
+* Code style::
+* Debugging LilyPond::
+* Adding or modifying features::
@end menu
@node Overview of LilyPond architecture
programming in Scheme is available in its entirety online.
An introduction to Guile/Scheme as used in LilyPond can be found in the
-Learning Manual, see @rlearning{Scheme tutorial}.
+Learning Manual, see @rlearning{Scheme tutorial}.
@subsection MetaFont
@subsection Compiling with debugging information
In order to use a debugger with LilyPond, it is necessary to compile
-LilyPond with debugging information. This is accomplished by ...
+LilyPond with debugging information. This is accomplished by running
+the following commands in the main LilyPond source directory.
-TODO -- get good description here, or perhaps add debugging compile
-to AU1.1 as it comes to CG and just use a reference here.
+@example
+./configure --disable-optimising
+
+make
+@end example
+
+This will create a version of LilyPond that contains the debugging
+information that will allow the debugger to tie the source code
+to the compiled code.
+
+You should not do @var{make install} if you want to use a debugger
+with LilyPond. @var{make install} will strip the debugging information
+from the LilyPond binary.
+
+To set breakpoints in Scheme functions, put
+
+@example
+\include "guile-debugger.ly"
+@end example
+
+in your input file after any scheme procedures you have defined in
+that file. When your input file is processed, a guile prompt
+will be displayed. At the guile prompt, you can set breakpoints with
+the @code{break!} procedure:
+
+@example
+guile> (break! my-scheme-procedure)
+@end example
-TODO -- Test the following to make sure it is true.
+Once you have set the desired breakpoints, you exit the guile repl frame
+by typing:
-If you want to be able to set breakpoints in Scheme functions, it is
-necessary to compile guile with debugging information. This is done
-by ...
+@example
+guile> (quit)
+@end example
-TODO -- get compiling description for guile here.
+When one of the scheme routines for which you have set breakpoints is
+entered, guile will interrupt execution in a debug frame. At this point,
+you will have access to guile debugging commands. For a listing of these
+commands, type:
+
+@example
+debug> help
+@end example
@subsection Typical gdb usage
The behavior of gdb can be readily customized through the use of
@var{.gdbinit} files. A @var{.gdbinit} file is a file named
@var{.gdbinit} (notice the @qq{.} at the beginning of the file name)
- that is placed in a user's home directory.
+that is placed in a user's home directory.
The @var{.gdbinit} file below is from Han-Wen. It sets breakpoints
for all errors and defines functions for displaying scheme objects
@example
file lily/out/lilypond
-b scm_error
b programming_error
b Grob::programming_error
define ps
print ly_display_scm($arg0)
- end
- define pgrob
- print ly_display_scm($arg0->self_scm_)
- print ly_display_scm($arg0->mutable_property_alist_)
- print ly_display_scm($arg0->immutable_property_alist_)
- print ly_display_scm($arg0->object_alist_)
- end
- define pmusic
- print ly_display_scm($arg0->self_scm_)
- print ly_display_scm($arg0->mutable_property_alist_)
- print ly_display_scm($arg0->immutable_property_alist_)
- end
+end
+define pgrob
+ print ly_display_scm($arg0->self_scm_)
+ print ly_display_scm($arg0->mutable_property_alist_)
+ print ly_display_scm($arg0->immutable_property_alist_)
+ print ly_display_scm($arg0->object_alist_)
+end
+define pmusic
+ print ly_display_scm($arg0->self_scm_)
+ print ly_display_scm($arg0->mutable_property_alist_)
+ print ly_display_scm($arg0->immutable_property_alist_)
+end
@end example
@subsection Using Guile interactively with LilyPond
The compilation of the .ly file will then continue.
+@node Adding or modifying features
+@section Adding or modifying features
+
+When a new feature is to be added to LilyPond, it is necessary to
+ensure that the feature is properly integrated to maintain
+its long-term support. This section describes the steps necessary
+for feature addition.
+
+@subsection Write the code
+
+You should create a new git branch for writing the code, as that
+will separate it from the master branch and allow you to continue
+to work on small projects related to master.
+
+Please be sure to follow the rules for programming style discussed
+earlier in this chapter.
+
+@subsection Write 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.
+
+Regression tests should be as brief as possible to demonstrate the
+functionality of the code.
+
+Regression tests should generally cover one issue per test. Several
+short, single-issue regression tests are preferred to a single, long,
+multiple-issue regression test.
+
+Use existing regression tests as templates to demonstrate the type of
+header information that should be included in a regression test.
+
+@subsection Write documentation
+
+Although it is not required, it is helpful if the developer can
+write relevant material for inclusion in the Notation Reference.
+If the developer does not feel qualified to write the documentation,
+a documentation editor will be able to write it from the regression
+tests.
+
+If the modification changes the input syntax so that inline snippets in
+the documentation need to be changed, you will need to change the
+snippets in both the english version of the documentation and any
+translated versions. If you do not change the snippets in all
+translations, older versions of the snippet may be included
+when the documentation is built.
+
+If lsr snippets need to be changed, the snippet should be copied to
+input/new and modified there. The portions of the snippet that
+are added by makelsr.py should be removed. The changed snippet
+will then be included in all versions of the documentation.
+
+If non-snippet text is changed in the english documentation, no
+corresponding changes should be made in the translated documentation.
+
+@subsection Write convert-ly rule
+
+If the modification changes the input syntax, a convert-ly rule
+should be written to automatically update input files from older
+versions.
+
+convert-ly rules are found in python/convertrules.py
+
+If possible, the convert-ly rule should allow automatic updating
+of the file. In some cases, this will not be possible, so the
+rule will simply point out to the user that the feature needs
+manual correction.
+
+@subsection Write NEWS entry
+
+An entry should be added to the NEWS file to describe the feature
+changes to be implemented. This is especially important for changes
+that change input file syntax.
+
+Hints for NEWS file entries are given at the top of the NEWS file.
+
+New entries in NEWS go at the top of the file.
+
+The NEWS entry should be written to show how the new change
+improves LilyPond, if possible.
+
+@subsection Verify regression test
+
+In order to avoid breaking LilyPond, it is important to verify that
+the regression tests all succeed. This process is described in
+@ref{Regression tests}.
+
+@subsection Post patch for comments
+
+For any change other than a minor change, a patch set should be
+posted on Rietveld for comment.
+
+The patch set is posted by issuing the following command, after
+first committing all changes:
+
+@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).
+
+After prompting for an email and a password, the patch set will be
+posted to Rietveld.
+
+An email should then be sent 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.
+
+@subsection Push patch
+
+Once all the comments have been addressed, the patch can be pushed.
+
+If the author has push privileges, the author will push the patch.
+Otherwise, a developer with push privileges will push the patch.
+
+@subsection Closing the issues
+
+Once the patch has been pushed, all the relevant issues should be
+closed.
+
+On Rietveld, the author should log in an close the issue either by
+using the @q{Edit Issue} link, or by clicking the circled x icon
+to the left of the issue name.
+
+If the changes were in response to a feature request on the Google
+issue tracker for LilyPond, the author should change the status to
+@q{Fixed_x_y_z} where the patch was fixed in version x.y.z. If
+the author does not have privileges to change the status, an email
+should be sent to bug-lilypond requesting the BugMeister to change
+the status.
projects / lilypond.git / blobdiff