Getting Started on LilyPond Development LilyPond is a huge software project, with portions of the package created in C++, Scheme, and python. Extensive makefiles and configuration files exist. The binary is built cross-platform for Linux, Windows, and MacOS. The documentation is automatically generated using a variety of tools. With all this complexity, it can be difficult to know how to get started when trying to contribute to LilyPond development. This document tries to help you get started. These instructions assume that you are working from a command-line environment, such as the cmd environment in Windows or the Terminal program in OS/X. Although GUI equivalents may exist, they are not documented here. Modifying the Distribution Files 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 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. Once you've modified the files, you can test the changes just by running LilyPond on some input file. It's a good idea to create a file that demonstrates the feature you're trying to add. This file will eventually become a regression test and will be part of the LilyPond distribution. There are a few things you need to be careful of when modifying files, especially under Windows. You need to set your editor to save Unix-style line endings, rather than DOS-style line endings. (You'll know you have a problem with this when the patch you create is twice as long as either of the files). Second, you need to make sure that you do not add any tab characters to the file. It's fine to use the tab key for indentation, as long as your editor inserts spaces rather than tab characters. If you don't know how to adjust your editor to avoid having tabs in the file, it's safest to avoid the tab key and just use spaces for indentation. Creating a Patch Once you're satisfied that you've successfully made the change, you should create a patch for the changes. LilyPond accepts new input in the form of patches, rather than revised files. If you're using git, you can create a patch by entering the command git format patch If you're not using git, you can use the diff utility that is generally available on all platforms. You'll want to do something like diff -u oldfile newfile > patchfile where oldfile is the original file, newfile is your modified file, and patchfile is the file that will contain the patch. Finding a LilyPond command One of the real challenges when getting started on extending or patching LilyPond is trying to find where the relevant program lines are found. With nearly 3000 files in the source distribution, a listing of the entire file tree would take more than 50 pages. There is a file ROADMAP that lists the directory structure and the kind of files that are in each folder. However, it's difficult to know exactly where the program lines you want are. The way I generally do this is to use grep, which is a command-line utility that is used to search files for context. Again, grep is usually available in the command line environment. But if grep is not available, any text search utility will do. There are three places I generally start looking for files. All are subdirectories of the main lilypond directory. The ly/ directory contains LilyPond input format files that are used to define commands, contexts, engravers, etc. The scm/ directory contains Scheme files. The lily/ directory contains c++ files. The ly/ and scm/ directories are available in binary distributions of LilyPond, but the lily/ directory is only available in source distributions. Even if you can't or don't want to compile LilyPond, it's probably a good idea to get the source so you can check out how it works. But be warned, the c++ code is pretty hard to figure out initially. Anyway, the technique I usually use to look up the code location for a given function is to grep the scm/ and the ly/ directories for that function. For example, to find out where the addChordShape function is defined, I'd issue the command grep addChordShape scm/* from the main lilypond directory. This command returns nothing, so I'd try the ly/ directory: grep addChordShape ly/* This time I'd find that ly/predefined-fretboards-init.ly has a line addChordShape= and ly/predefined-guitar-fretboards.ly has lots of lines that use /addChordshape. So from this I think that I'll find the definition of the command addChordShape in the file ly/predefined-fretboards-init.ly. And sure enough, when I open that file, I find that it's the right place. In summary, the process of finding where commands are defined consists of searching through the contents of the ly/, scm/, and lily/ directories to find where they are defined. If you have git installed, the process above is greatly simplified. After changing to the lilypond top level directory for the git repository, just type git grep addChordShape and all of the LilyPond source files will be searched for addChordShape. This is a very fast and convenient search command. Just having this command is sufficient reason to install git, in my opinion. You can also use the equivalent of git grep on the Savannah server. 1. Go to http://git.sv.gnu.org/gitweb/?p=lilypond.git 2. In the pulldown box that says commit, select grep. 3. Type addChordShape in the search box, and hit enter/return This will initiate a search of the remote git repository. Using git git is a version tracker that will allow you to get the current source at any time from the git repository at git.savanna.gnu.org. It's a tool that is easy to install on OS/X, Linux, and Windows. You can find instructions about getting started with git in three places: 1. Search the archives of the lilypond-devel@gnu.org mailing list for messages with git in the subject line. 2. Look at the file Documentation/TRANSLATION which is available at http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=tree;f=Documentation. It contains a brief instruction to using git for translation purposes. 3. Look at the file README available at http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=tree;h=refs/heads/web;hb=web. This file contains brief instructions for using git to update the web site. If you're not doing web development, you'll need to modify the commands so they refer to lilypond/master rather than lilypond/web. As a new developer, you won't have push access to the savannah repository. But you do have the right to make your own repository and to create patches using git-format-patch. If you want to get experience using git to track all your modifications, you can create your own remote repository at repo.or.cz. Compiling LilyPond Compiling LilyPond the first time is a very involved process, because you need to make sure you have all of the dependencies involved, and the list is quite large. Once you have everything installed, the compilation itself is quite easy. Simply issue the command "make all" from the main lilypond source directory, and if all is working well, LilyPond will successfully compile. At the present, I know of nobody who has successfully compiled LilyPond on a Windows Vista machine. If I were using Vista, I'd install an alternate bootable Linux operating system, probably Ubuntu, but maybe Fedora Core. Then I'd boot to Ubuntu when I needed to compile LilyPond. On Mac OS/X, Nicolas Sceaux has developed a very nice set of instructions for compiling LilyPond, available at http://nicolas.sceaux.free.fr/. Follow the instructions very carefully, and you should be able to build successfully. Note that if you ever need to rerun lily-configure, you will need to re-patch config.make. On Linux, compiling LilyPond is relatively straightforward, except for the challenge of getting all the proper dependencies installed. Using LilyPond with a debugger This section will be completed later.