Left: | ||
Right: |
OLD | NEW |
---|---|
1 @c -*- coding: utf-8; mode: texinfo; -*- | 1 @c -*- coding: utf-8; mode: texinfo; -*- |
2 @node Programming work | 2 @node Programming work |
3 @chapter Programming work | 3 @chapter Programming work |
4 | 4 |
5 @menu | 5 @menu |
6 * Overview of LilyPond architecture:: | 6 * Overview of LilyPond architecture:: |
7 * LilyPond programming languages:: | 7 * LilyPond programming languages:: |
8 * Programming without compiling:: | 8 * Programming without compiling:: |
9 * Finding functions:: | 9 * Finding functions:: |
10 * Code style:: | 10 * Code style:: |
11 * Warnings Errors Progress and Debug Output:: | 11 * Warnings Errors Progress and Debug Output:: |
12 * Debugging LilyPond:: | 12 * Debugging LilyPond:: |
13 * Tracing object relationships:: | 13 * Tracing object relationships:: |
14 * Adding or modifying features:: | 14 * Adding or modifying features:: |
15 * Iterator tutorial:: | 15 * Iterator tutorial:: |
16 * Engraver tutorial:: | 16 * Engraver tutorial:: |
17 * Callback tutorial:: | 17 * Callback tutorial:: |
18 * LilyPond scoping:: | 18 * LilyPond scoping:: |
19 * Scheme->C interface:: | |
19 * LilyPond miscellany:: | 20 * LilyPond miscellany:: |
20 @end menu | 21 @end menu |
21 | 22 |
22 @node Overview of LilyPond architecture | 23 @node Overview of LilyPond architecture |
23 @section Overview of LilyPond architecture | 24 @section Overview of LilyPond architecture |
24 | 25 |
25 LilyPond processes the input file into graphical and musical output in a | 26 LilyPond processes the input file into graphical and musical output in a |
26 number of stages. This process, along with the types of routines that | 27 number of stages. This process, along with the types of routines that |
27 accomplish the various stages of the process, is described in this section. A | 28 accomplish the various stages of the process, is described in this section. A |
28 more complete description of the LilyPond architecture and internal program | 29 more complete description of the LilyPond architecture and internal program |
(...skipping 1507 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
1536 If the author has push privileges, the author will push the patch. | 1537 If the author has push privileges, the author will push the patch. |
1537 Otherwise, a developer with push privileges will push the patch. | 1538 Otherwise, a developer with push privileges will push the patch. |
1538 | 1539 |
1539 | 1540 |
1540 @node Closing the issues | 1541 @node Closing the issues |
1541 @subsection Closing the issues | 1542 @subsection Closing the issues |
1542 | 1543 |
1543 Once the patch has been pushed, all the relevant issues should be | 1544 Once the patch has been pushed, all the relevant issues should be |
1544 closed. | 1545 closed. |
1545 | 1546 |
1546 On Rietveld, the author should log in an close the issue either by | 1547 On Rietveld, the author should log in and close the issue either by |
1547 using the @q{Edit Issue} link, or by clicking the circled x icon | 1548 using the @q{Edit Issue} link, or by clicking the circled x icon |
1548 to the left of the issue name. | 1549 to the left of the issue name. |
1549 | 1550 |
1550 If the changes were in response to a feature request on the Google | 1551 If the changes were in response to a feature request on the Google |
1551 issue tracker for LilyPond, the author should change the status to | 1552 issue tracker for LilyPond, the author should change the status to |
1552 Fixed and a tag @q{fixed_x_y_z} should be added, where the patch was | 1553 Fixed and a tag @q{fixed_x_y_z} should be added, where the patch was |
1553 fixed in version x.y.z. If | 1554 fixed in version x.y.z. If |
1554 the author does not have privileges to change the status, an email | 1555 the author does not have privileges to change the status, an email |
1555 should be sent to bug-lilypond requesting the BugMeister to change | 1556 should be sent to bug-lilypond requesting the BugMeister to change |
1556 the status. | 1557 the status. |
(...skipping 247 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
1804 we want to reuse the built-in definitions, without changes effected in | 1805 we want to reuse the built-in definitions, without changes effected in |
1805 user-level @file{a.ly} leaking into the processing of @file{b.ly}. | 1806 user-level @file{a.ly} leaking into the processing of @file{b.ly}. |
1806 | 1807 |
1807 The user-accessible definition commands have to take care to avoid | 1808 The user-accessible definition commands have to take care to avoid |
1808 memory leaks that could occur when running multiple files. All | 1809 memory leaks that could occur when running multiple files. All |
1809 information belonging to user-defined commands and markups is stored in | 1810 information belonging to user-defined commands and markups is stored in |
1810 a manner that allows it to be garbage-collected when the module is | 1811 a manner that allows it to be garbage-collected when the module is |
1811 dispersed, either by being stored module-locally, or in weak hash | 1812 dispersed, either by being stored module-locally, or in weak hash |
1812 tables. | 1813 tables. |
1813 | 1814 |
1815 | |
1816 @node Scheme->C interface | |
1817 @section Scheme->C interface | |
1818 | |
1819 Most of the C functions interfacing with Guile/Scheme used in LilyPond | |
1820 are described in the API Reference of the | |
1821 @uref{http://www.gnu.org/software/guile/manual/html_node/index.html, | |
1822 GUILE Reference Manual}. | |
1823 | |
1824 The remaining functions are defined in @file{lily/lily-guile.cc}, | |
1825 @file{lily/include/lily-guile.hh} and | |
1826 @file{lily/include/lily-guile-macros.hh}. | |
1827 Although their names are meaningful there's a few things you should know | |
1828 about them. | |
1829 | |
1830 @menu | |
1831 * Comparison:: | |
1832 * Conversion:: | |
1833 @end menu | |
1834 | |
1835 @node Comparison | |
1836 @subsection Comparison | |
1837 | |
1838 This is the trickiest part of the interface. | |
1839 | |
1840 Mixing Scheme values with C comparison operators won't produce any crash | |
1841 or warning when compiling but must be avoided: | |
1842 | |
1843 @example | |
1844 scm_string_p (scm_value) == SCM_BOOL_T | |
1845 @end example | |
1846 | |
1847 As we can read in the reference, @code{scm_string_p} returns a Scheme | |
1848 value: either @code{#t} or @code{#f} which are written @code{SCM_BOOL_T} | |
1849 and @code{SCM_BOOL_F} in C. This will work, but it is not following | |
1850 to the API guidelines. For further information, read this discussion: | |
1851 | |
1852 @smallexample | |
1853 @uref{http://lists.gnu.org/archive/html/lilypond-devel/2011-08/msg00646.html} | |
1854 @end smallexample | |
1855 | |
1856 There are functions in the Guile reference that returns C values | |
1857 instead of Scheme values. In our example, a function called | |
1858 @code{scm_is_string} (described after @code{string?} and @code{scm_string_p}) | |
1859 returns the C value 0 or 1. | |
1860 | |
1861 So the best solution was simply: | |
1862 | |
1863 @example | |
1864 scm_is_string (scm_value) | |
1865 @end example | |
1866 | |
1867 There a simple solution for almost every common comparison. Another example: | |
1868 we want to know if a Scheme value is a non-empty list. Instead of: | |
1869 | |
1870 @example | |
1871 (scm_list_p (scm_value) && scm_value != SCM_EOL) | |
dak
2011/10/23 21:23:11
scm_list_p is _always_ true according to C since i
| |
1872 @end example | |
1873 | |
1874 one should use: | |
1875 | |
1876 @example | |
1877 scm_is_pair (scm_value) | |
1878 @end example | |
1879 | |
1880 since a list of at least one member is considered as a pair. | |
dak
2011/10/23 21:23:11
But not every pair is a proper list. scm_list_[ r
| |
1881 | |
1882 Unfortunately, there is not a @code{scm_is_[something]} function for | |
1883 everything. That's one of the reasons why LilyPond has its own Scheme | |
1884 interface. | |
dak
2011/10/23 21:23:11
As a rule of thumb, you get an scm_is_[something]
| |
1885 | |
1886 @subheading General definitions | |
1887 | |
1888 @subsubheading bool to_boolean (SCM b) | |
1889 | |
1890 Return @code{true} if @var{b} is @code{SCM_BOOL_T}, else return @code{false}. | |
1891 | |
1892 This should be used instead of @code{scm_is_true} and @code{scm_is_false} | |
dak
2011/10/23 21:23:11
Both scm_is_true and scm_is_false compare only for
| |
1893 for properties since empty lists are sometimes used to unset them. | |
dak
2011/10/23 21:23:11
since reading any unset property returns an empty
| |
1894 | |
1895 @subsubheading bool ly_is_[something] (args) | |
1896 | |
1897 Behave the same as scm_is_[something] would do if it existed. | |
1898 | |
1899 @subsubheading bool is_[type] (SCM s) | |
1900 | |
1901 Test whether the type of @var{s} is [type]. | |
1902 [type] is a LilyPond-only type of value (direction, axis...). | |
1903 | |
1904 @node Conversion | |
dak
2011/10/23 21:23:11
The whole node is duplication.
| |
1905 @subsection Conversion | |
1906 | |
1907 @subheading General definitions | |
1908 | |
1909 @subsubheading bool to_boolean (SCM b) | |
1910 | |
1911 Return @code{true} if @var{b} is @code{SCM_BOOL_T}, else return @code{false}. | |
1912 | |
1913 This should be used instead of @code{scm_is_true} and @code{scm_is_false} | |
1914 for properties since empty lists are sometimes used to unset them. | |
1915 | |
1916 @subsubheading [C type] ly_scm2[C type] (SCM s) | |
1917 | |
1918 Behave the same as scm_to_[C type] would do if it existed. | |
1919 | |
1920 @subsubheading [C type] robust_scm2[C type] (SCM s, [C type] d) | |
1921 | |
1922 Behave the same as scm_to_[C type] would do if it existed. | |
1923 Return @var{d} if type verification fails. | |
1924 | |
1925 | |
1814 @node LilyPond miscellany | 1926 @node LilyPond miscellany |
1815 @section LilyPond miscellany | 1927 @section LilyPond miscellany |
1816 | 1928 |
1817 This is a place to dump information that may be of use to developers | 1929 This is a place to dump information that may be of use to developers |
1818 but doesn't yet have a proper home. Ideally, the length of this section | 1930 but doesn't yet have a proper home. Ideally, the length of this section |
1819 would become zero as items are moved to other homes. | 1931 would become zero as items are moved to other homes. |
1820 | 1932 |
1821 | 1933 |
1822 @menu | 1934 @menu |
1823 * Spacing algorithms:: | 1935 * Spacing algorithms:: |
(...skipping 397 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
2221 #(display conditionalMark) | 2333 #(display conditionalMark) |
2222 @end example | 2334 @end example |
2223 | 2335 |
2224 noindent | 2336 noindent |
2225 inside the @file{.ly} file. | 2337 inside the @file{.ly} file. |
2226 | 2338 |
2227 The breakpoint failing may have to do with the call sequence. See | 2339 The breakpoint failing may have to do with the call sequence. See |
2228 @file{parser.yy}, run_music_function(). The function is called directly from | 2340 @file{parser.yy}, run_music_function(). The function is called directly from |
2229 C++, without going through the GUILE evaluator, so I think that is why | 2341 C++, without going through the GUILE evaluator, so I think that is why |
2230 there is no debugger trap. | 2342 there is no debugger trap. |
OLD | NEW |