issue 4491: replace BUILD_DIR with LILYPOND_BUILD_DIR

[lilypond.git] / Documentation / contributor / programming-work.itexi

diff --git a/Documentation/contributor/programming-work.itexi b/Documentation/contributor/programming-work.itexi
index 447f553ea4cf2b1f57e5c736f4794aee06392112..99dc79da4a9c6a274aa30ca8e52c68c94ccdc3f2 100644 (file)
--- a/Documentation/contributor/programming-work.itexi
+++ b/Documentation/contributor/programming-work.itexi
@@ -913,17 +913,21 @@ The GNU debugger, gdb, is the principal tool for debugging C++ code.
 @subheading Compiling LilyPond for use with gdb
 
 In order to use gdb with LilyPond, it is necessary to compile
 @subheading Compiling LilyPond for use with gdb
 
 In order to use gdb with LilyPond, it is necessary to compile

-LilyPond with debugging information.  This is accomplished by running
-the following commands in the main LilyPond source directory.
+LilyPond with debugging information.  This is the current default
+mode of compilation.  Often debugging becomes more complicated
+when the compiler has optimised variables and function calls away.
+In that case it may be helpful to run the following command in the
+main LilyPond source directory:

 
 @example
 
 @example

-./configure  --disable-optimising
+./configure --disable-optimising

 make
 @end example
 
 make
 @end example
 

-This will create a version of LilyPond containing debugging
-information that will allow the debugger to tie the source code
-to the compiled code.
+This will create a version of LilyPond with minimal optimization
+which will allow the debugger to access all variables and step
+through the source code in-order.  It may not accurately reproduce
+bugs encountered with the optimized version, however.

 
 You should not do @var{make install} if you want to use a debugger
 with LilyPond.  The @var{make install} command will strip debugging
 
 You should not do @var{make install} if you want to use a debugger
 with LilyPond.  The @var{make install} command will strip debugging


@@ -1130,18 +1134,17 @@ in has been declared.  For example, if you are working on routines
 called by @var{print-book-with} in @file{lily-library.scm}:
 
 @example
 called by @var{print-book-with} in @file{lily-library.scm}:
 
 @example

-(define (print-book-with parser book process-procedure)
-  (let* ((paper (ly:parser-lookup parser '$defaultpaper))
-        (layout (ly:parser-lookup parser '$defaultlayout))
-        (outfile-name (get-outfile-name parser)))
+(define (print-book-with book process-procedure)
+  (let* ((paper (ly:parser-lookup '$defaultpaper))
+         (layout (ly:parser-lookup '$defaultlayout))
+         (outfile-name (get-outfile-name book)))

     (process-procedure book paper layout outfile-name)))
 
     (process-procedure book paper layout outfile-name)))
 

-(define-public (print-book-with-defaults parser book)
-  (print-book-with parser book ly:book-process))
-
-(define-public (print-book-with-defaults-as-systems parser book)
-  (print-book-with parser book ly:book-process-to-systems))
+(define-public (print-book-with-defaults book)
+  (print-book-with book ly:book-process))

 
 

+(define-public (print-book-with-defaults-as-systems book)
+  (print-book-with book ly:book-process-to-systems))

 @end example
 
 At this point in the code you could add this to set a breakpoint at
 @end example
 
 At this point in the code you could add this to set a breakpoint at


@@ -1204,8 +1207,15 @@ number of different platforms:
 
 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
 
 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 @option{-DNDEBUG}.
+a different name.
+
+In order to have the required functionality available, LilyPond
+needs to be compiled with the option @option{-DDEBUG}.  You can
+achieve this by configuring with
+
+@example
+./configure --enable-checking
+@end example

 
 @item Rebuilding LilyPond
 
 
 @item Rebuilding LilyPond
 


@@ -1253,10 +1263,10 @@ dot -Tpdf graphviz.log > graphviz.pdf
 
 The pdf file can then be viewed with any pdf viewer.
 
 
 The pdf file can then be viewed with any pdf viewer.
 

-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
+When compiled with @option{-DDEBUG}, lilypond may run slower
+than normal.  The original configuration can be restored by rerunning
+@code{./configure} with @option{--disable-checking}.  Then
+rebuild lilypond with

 
 @example
 make -C lily clean && make -C lily
 
 @example
 make -C lily clean && make -C lily


@@ -1365,7 +1375,7 @@ scripts/auxiliar/update-with-convert-ly.sh
 If you did an out-of-tree build, pass in the relative path:
 
 @example
 If you did an out-of-tree build, pass in the relative path:
 
 @example

-BUILD_DIR=../build-lilypond/ scripts/auxiliar/update-with-convert-ly.sh
+LILYPOND_BUILD_DIR=../build-lilypond/ scripts/auxiliar/update-with-convert-ly.sh

 @end example
 
 
 @end example
 
 


@@ -2149,7 +2159,7 @@ Test whether the type of @var{s} is [type].
 often than not, the code checks Lilypond specific C++-implemented
 types using
 
 often than not, the code checks Lilypond specific C++-implemented
 types using
 

-@subsubheading [type *] unsmob_[type] (SCM s)
+@subsubheading [Type *] unsmob<Type> (SCM s)

 
 This tries converting a Scheme object to a pointer of the desired
 kind.  If the Scheme object is of the wrong type, a pointer value
 
 This tries converting a Scheme object to a pointer of the desired
 kind.  If the Scheme object is of the wrong type, a pointer value


@@ -2547,22 +2557,24 @@ this will display OBJ through GUILE.
 @subsection Music functions and GUILE debugging
 
 Ian Hulin was trying to do some debugging in music functions, and
 @subsection Music functions and GUILE debugging
 
 Ian Hulin was trying to do some debugging in music functions, and

-came up with the following question
+came up with the following question (edited and adapted to current
+versions):

 
 HI all,
 I'm working on the Guile Debugger Stuff, and would like to try
 debugging a music function definition such as:
 
 @example
 
 HI all,
 I'm working on the Guile Debugger Stuff, and would like to try
 debugging a music function definition such as:
 
 @example

-conditionalMark = #(define-music-function (parser location) ()
-    #@{ \tag #'instrumental-part @{\mark \default@}  #@} )
+conditionalMark =
+#(define-music-function () ()
+  #@{ \tag instrumental-part @{\mark \default@} #@} )

 @end example
 
 @end example
 

-It appears conditionalMark does not get set up as an
+It appears @code{conditionalMark} does not get set up as an

 equivalent of a Scheme
 
 @example
 equivalent of a Scheme
 
 @example

-(define conditionalMark = define-music-function(parser location () ...
+(define conditionalMark = define-music-function () () ...

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -2576,25 +2588,54 @@ although something gets defined because Scheme apparently recognizes
 later on in the file without signalling any Guile errors.
 
 However the breakpoint trap is never encountered as
 later on in the file without signalling any Guile errors.
 
 However the breakpoint trap is never encountered as

-define-music-function passed things on to ly:make-music-function,
-which is really C++ code ly_make_music_function, so Guile never
-finds out about the breakpoint.
+@code{define-music-function} passed things on to
+@code{ly:make-music-function}, which is really C++ code
+@code{ly_make_music_function}, so Guile never finds out about the
+breakpoint.
+
+
+The answer in the mailing list archive at that time was less than
+helpful.  The question already misidentifies the purpose of
+@code{ly:make-music-function} which is only called once at the
+time of @emph{defining} @code{conditionalMark} but is not involved
+in its later @emph{execution}.

 
 

-Han-Wen answered as follows:
+Here is the real deal:

 
 

-You can see the definition by doing
+A music function is not the same as a GUILE function.  It boxes
+both a proper Scheme function (with argument list and body from
+the @code{define-music-function} definition) along with a call
+signature representing the @emph{types} of both function and
+arguments.
+
+Those components can be reextracted using
+@code{ly:music-function-extract} and
+@code{ly:music-function-signature}, respectively.
+
+When LilyPond's parser encounters a music function call in its
+input, it reads, interprets, and verifies the arguments
+individually according to the call signature and @emph{then} calls
+the proper Scheme function.
+
+While it is actually possible these days to call a music function
+@emph{as if} it were a Scheme function itself, this pseudo-call
+uses its own wrapping code matching the argument list @emph{as a
+whole} to the call signature, substituting omitted optional
+arguments with defaults and verifying the result type.
+
+So putting a breakpoint on the music function itself will still
+not help with debugging uses of the function using LilyPond
+syntax.
+
+However, either calling mechanism ultimately calls the proper
+Scheme function stored as part of the music function, and that is
+where the breakpoint belongs:

 
 @example
 
 @example

-#(display conditionalMark)
+#(set-break! (ly:music-function-extract conditionalMark))

 @end example
 
 @end example
 

-noindent
-inside the @file{.ly} file.
-
-The breakpoint failing may have to do with the call sequence.  See
-@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.
+will work for either calling mechanism.

 
 @node Articulations on EventChord
 @subsection Articulations on EventChord
 
 @node Articulations on EventChord
 @subsection Articulations on EventChord