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
-
+@end example
-@subheading Indenting with vim
-Although emacs indentation is the GNU standard, acceptable
-indentation can usually be accomplished with vim. Some hints for
-vim are as follows:
+@subsubheading Indenting with vim
-A workable .vimrc:
+Although emacs indentation is the GNU standard, correct
+indentation for C++ files can be achieved by using the settings
+recommended in the
+@url{https://gcc.gnu.org/wiki/FormattingCodeForGCC, GNU GCC Wiki}.
+Save the following in @file{~/.vim/after/ftplugin/cpp.vim}:
@example
-set cindent
-set smartindent
-set autoindent
-set expandtab
-set softtabstop=2
-set shiftwidth=2
-filetype plugin indent on
-set incsearch
-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 laststatus=2
-set number
-" Remove trailing whitespace on write
+setlocal cindent
+setlocal cinoptions=>4,n-2,@{2,^-2,:2,=2,g0,h2,p5,t0,+2,(0,u0,w1,m1
+setlocal shiftwidth=2
+setlocal softtabstop=2
+setlocal textwidth=79
+setlocal fo-=ro fo+=cql
+" use spaces instead of tabs
+setlocal expandtab
+" remove trailing whitespace on write
autocmd BufWritePre * :%s/\s\+$//e
@end example
-With this @file{.vimrc}, files can be reindented automatically by
+With these settings, files can be reindented automatically by
highlighting the lines to be indented in visual mode (use V to
-enter visual mode) and pressing @code{=}.
+enter visual mode) and pressing @code{=}, or a single line
+correctly indented in normal mode by pressing @code{==}.
-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}.
+A @file{scheme.vim} file will help improve the indentation of
+Scheme code. This one was suggested by Patrick McCarty. It
+should be saved in @file{~/.vim/after/syntax/scheme.vim}.
@example
" Additional Guile-specific 'forms'
syn keyword schemeSyntax def-grace-function
" All of the above should influence indenting too
-set lw+=define-public,define*-public
-set lw+=define*,lambda*,let-keywords*
-set lw+=defmacro,defmacro*,define-macro
-set lw+=defmacro-public,defmacro*-public
-set lw+=use-modules,define-module
-set lw+=define-method,define-class
-set lw+=define-markup-command,define-markup-list-command
-set lw+=define-safe-public,define-music-function
-set lw+=def-grace-function
+setlocal lw+=define-public,define*-public
+setlocal lw+=define*,lambda*,let-keywords*
+setlocal lw+=defmacro,defmacro*,define-macro
+setlocal lw+=defmacro-public,defmacro*-public
+setlocal lw+=use-modules,define-module
+setlocal lw+=define-method,define-class
+setlocal lw+=define-markup-command,define-markup-list-command
+setlocal lw+=define-safe-public,define-music-function
+setlocal lw+=def-grace-function
" These forms should not influence indenting
-set lw-=if
-set lw-=set!
+setlocal lw-=if
+setlocal lw-=set!
" Try to highlight all ly: procedures
syn match schemeFunc "ly:[^) ]\+"
@end example
+For documentation work on texinfo files, identify the file
+extensions used as texinfo files in your @file{.vim/filetype.vim}:
+
+@example
+if exists("did_load_filetypes")
+ finish
+endif
+augroup filetypedetect
+ au! BufRead,BufNewFile *.itely setfiletype texinfo
+ au! BufRead,BufNewFile *.itexi setfiletype texinfo
+ au! BufRead,BufNewFile *.tely setfiletype texinfo
+augroup END
+@end example
+
+and add these settings in @file{.vim/after/ftplugin/texinfo.vim}:
+
+@example
+setlocal expandtab
+setlocal shiftwidth=2
+setlocal textwidth=66
+@end example
@node Naming conventions
@subsection Naming Conventions
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
+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}.
The most commonly used tool for debugging LilyPond is the GNU
debugger gdb. The gdb tool is used for investigating and debugging
-core Lilypond code written in C++. Another tool is available for
+core LilyPond code written in C++. Another tool is available for
debugging Scheme code using the Guile debugger. This section
describes how to use both gdb and the Guile Debugger.
@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
-./configure --disable-optimising
+./configure --disable-optimising
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
@subheading Typical gdb usage
-Once you have compiled the Lilypond image with the necessary
+Once you have compiled the LilyPond image with the necessary
debugging information it will have been written to a location in a
subfolder of your current working directory:
debug> help
@end example
-Alternatively you may code the breakpoints in your Lilypond source
+Alternatively you may code the breakpoints in your LilyPond source
file using a command such as:
@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)))
-(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
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
The executable code of LilyPond must be rebuilt from scratch:
@example
-make -C lily clean && make -C lily
+make clean && make
@end example
@item Create a graphviz-compatible @file{.ly} file
grobs and symbols that should be tracked. An example of this
is found in @file{input/regression/graphviz.ly}.
-@item Run lilypond with output sent to a log file
+@item Run LilyPond with output sent to a log file
-The Graphviz data is sent to stderr by lilypond, so it is
+The Graphviz data is sent to stderr by LilyPond, so it is
necessary to redirect stderr to a logfile:
@example
@item Edit the logfile
-The logfile has standard lilypond output, as well as the Graphviz
+The logfile has standard LilyPond output, as well as the Graphviz
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 lilypond message about success from the end
+Also, delete the final LilyPond message about success from the end
of the file.
@item Process the logfile with @code{dot}
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
+make clean && make
@end 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
@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
+LilyPond code in the documentation (i.e. if a NOT_SMART rule is used), the
documentation must be manually updated. The inline snippets that require
changing must be changed in the English version of the docs and all
translated versions. If the inline code is not changed in the
@code{side-position-interface}:
@example
-@code{DECLARE_ACKNOWLEDGER (note_head)}
-@code{DECLARE_ACKNOWLEDGER (side_position)}
+DECLARE_ACKNOWLEDGER (note_head)
+DECLARE_ACKNOWLEDGER (side_position)
@end example
The @code{DECLARE_END_ACKNOWLEDGER ()} macro sets up a spanner-specific
@code{\consist}-ed (the only exception is if you set
@code{must-be-last} to @code{#t}).
-If useful things are to be done to the acknowledged grobs, this
-should be deferred until all the acknowledging has finished, i.e.,
-store the acknowledged grobs and process the information in a
-@code{process-acknowledged ()} or @code{stop-translation-timestep ()}
-function.
+There will always be a call to @code{process-acknowledged ()} whenever
+grobs have been created, and @emph{reading} stuff from grobs should be
+delayed until then since other acknowledgers might @emph{write} stuff
+into a grob even after your acknowledger has been called. So the basic
+workflow is to use the various acknowledgers to @emph{record} the grobs
+you are interested in and @emph{write} stuff into them (or do read/write
+stuff that more or less is accumulative and/or really unrelated to other
+engravers), and then use the @code{process-acknowledged ()} hook for
+processing (including @emph{reading}) the grobs you had recorded.
+
+You can create new grobs in @code{process-acknowledged ()}. That will lead
+to a new cycle of @code{acknowledger ()} calls followed by a new cycle of
+@code{process-acknowledged ()} calls.
+
+Only when all those cycles are over is @code{stop-translator-timestep ()}
+called, and then creating grobs is no longer an option. You can still
+@q{process} parts of the grob there (if that means just reading out
+properties and possibly setting context properties based on them) but
+@code{stop-translation-timestep ()} is a cleanup hook, and other engravers
+might have already cleaned up stuff you might have wanted to use.
+Creating grobs in there is not possible since engravers and other code may
+no longer be in a state where they could process them, possibly causing
+a crash.
@node Engraver declaration/documentation
@node Purity in LilyPond
@subsection Purity in LilyPond
-Pure properties in LilyPond that do not have any @q{side effects}.
+Pure properties in LilyPond are properties that do not have any
+@q{side effects}.
That is, looking up a pure property should never result in calls to the
following functions:
@itemize
@node How purity is defined and stored
@subsection How purity is defined and stored
Purity is defined in LilyPond with the creation of an unpure-pure container
-(unpure is not a word, but hey, neither was Lilypond until the 90s). For example:
+(unpure is not a word, but hey, neither was LilyPond until the 90s). For example:
@example
#(define (foo grob)
@node LilyPond scoping
@section LilyPond scoping
-The Lilypond language has a concept of scoping, i.e. you can do:
+The LilyPond language has a concept of scoping, i.e. you can do:
@example
foo = 1
This implemented using modules, with each scope being an anonymous
module that imports its enclosing scope's module.
-Lilypond's core, loaded from @file{.scm} files, is usually placed in the
+LilyPond's core, loaded from @file{.scm} files, is usually placed in the
@code{lily} module, outside the @file{.ly} level. In the case of
@example
Return @code{true} if @var{b} is @code{SCM_BOOL_T}, else return @code{false}.
This should be used instead of @code{scm_is_true} and
-@code{scm_is_false} for properties since in Lilypond, unset properties
+@code{scm_is_false} for properties since in LilyPond, unset properties
are read as an empty list, and by convention unset Boolean properties
default to false. Since both @code{scm_is_true} and
@code{scm_is_false} only compare with @code{##f} in line with what
Test whether the type of @var{s} is [type].
[type] is a LilyPond-only set of values (direction, axis...). More
-often than not, the code checks Lilypond specific C++-implemented
+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
@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
-conditionalMark = #(define-music-function (parser location) ()
- #@{ \tag #'instrumental-part @{\mark \default@} #@} )
+conditionalMark =
+#(define-music-function () ()
+ #@{ \tag instrumental-part @{\mark \default@} #@} )
@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
-(define conditionalMark = define-music-function(parser location () ...
+(define conditionalMark = define-music-function () () ...
@end example
@noindent
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}.
+
+Here is the real deal:
-Han-Wen answered as follows:
+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.
-You can see the definition by doing
+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
-#(display conditionalMark)
+#(set-break! (ly:music-function-extract conditionalMark))
@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
projects / lilypond.git / blobdiff