Setting up VS Code for Lilypond

[Ankush Laxman]

SETTING UP VS CODE FOR LILYPOND
------------------------------

INTRODUCTION
------------

VS Code can be used as an editor for Lilypond files. In this post, I am going to show you how to set up VS Code as an editor for Lilypond files. First, you need to ensure that Lilypond is setup properly (including the command line *Important*). The installations instructions described here are for a Windows 10 machine (64-bit) using the most recent version of Windows 10 (20H2). I am assuming you have Adobe Acrobat and the latest version of Python installed correctly on the system. Python is needed for required files for formatting the Lilypond file (with proper indentation) in VS Code and Adobe Acrobat is needed for generating and viewing the PDF files. If not, install Adobe Acrobat and Python (including setting up Python for the command line - Google search) from the following links:

Adobe Acrobat:

https://get.adobe.com/reader/

Python:

https://www.python.org/

At the time of writing this post:

• The latest version of Lilypond is 2.22.0
• The latest version of VS Code is 1.53.2
• The latest version of Python is 3.9.2
• The latest version of Adobe Acrobat Reader DC is 2021.001.20140

"Easy editor" applies to third-party Lilypond file editors indicated on Lilypond's website

INSTALL AND/OR UPDATE LILYPOND
------------------------------

1. If installing Lilypond for the first time

• Install Lilypond (as administrator) from the Lilypond website.
  
  https://lilypond.org/

• For the command line to work, the environment variables must be set up correctly (very important). To access the environment variables, click on the search icon found on the taskbar and type "environment variables". Open the Control Panel settings for the environment variables from the search results. Click on the button "Environment Variables". Double click the variable titled "Path". You can use the "New" button on the menu to add an entry to the "Path" environment variable.
  
  Add the entry for the PATH environment variable, like so:
  
  For 64-bit Windows machine: C:\Program Files (x86)\LilyPond\usr\bin
  For 32-bit Windows machine: C:\Program Files\LilyPond\usr\bin

• Restart the system

2. If updating Lilypond

• Ensure that the previous version of Lilypond is first uninstalled. Before installing the updated version, remove the entry for Lilypond from the "Path" environment variable. To access the environment variables, click on the search icon found on the taskbar and type "environment variables". Open the Control Panel settings for the environment variables from the search results. Click on the button "Environment Variables". Double click the variable titled "Path". You can use the buttons on the menu to add, modify and delete environment variables. If updating from a previous version of Lilypond delete the Lilypond entry from the "Path" environment variable. Additionally, restart the system after complete uninstallation of the old version of Lilypond. This is to ensure a fresh installation of Lilypond as far as possible.

• Then, install the latest version of Lilypond.

• For the command line to work, the environment variables must be set up correctly (very important). After reinstalling Lilypond (and before installing the easy editor of your choice), add the entry for the PATH environment variable, like so:
  
  For 64-bit Windows machine: C:\Program Files (x86)\LilyPond\usr\bin
  For 32-bit Windows machine: C:\Program Files\LilyPond\usr\bin

• Restart the system.
  

3. Checking if Lilypond is working from the command line

• Once the environment variables are set up, one needs to check if Lilypond can be invoked from the command line. Open the command prompt app on the machine. Use the search icon on the taskbar and type "cmd". Open the Command Prompt app from the search results. Run the following command (without the quotes):
  
  "lilypond --v"

• The first line of the command result should be "GNU LilyPond 2.22.0". As of writing this post, the latest stable version is 2.22.0. If you get an error (such as an older version number or any other error), then Lilypond and/or the environment variables were not set up correctly. If so, you will have to start from the beginning with Lilypond's installation

• Ensure you create a Lilypond file first.

• You can create the file in "Lilypad" or "Notepad", and save it as, say, "test.ly" stored in a folder of your choosing (let's say "MusicEngraving" on the "C" drive). I use the following snippet for testing purposes:
  
  \version "2.22.0"
  {
     c' e' g' e'
  }

• In the command prompt, navigate to your directory using the "cd" command. For information using the "cd" command (and navigating between drives) in Windows command prompt, check on Google search. You will find umpteen sources on the "cd" command.

• Now, in the command prompt, enter the following line (without the quotes):
  
  "lilypond test.ly"
  
  You should get the following output:
  
  GNU LilyPond 2.22.0
  Processing `test.ly'
  Parsing...
  Interpreting music...
  Preprocessing graphical objects...
  Finding the ideal number of pages...
  Fitting music on 1 page...
  Drawing systems...
  Converting to `test.pdf'...
  Success: compilation successfully completed
  
  If you did not get this output, then you need to check your environment variables and if you are using the latest version of Lilypond. Please note that if there were prior installations of any of the easy editors, uninstall them and start afresh with Lilypond's installation. If needed, you can always install the easy editor later.
  

INSTALL VSCODE AND LILYPOND EXTENSION FOR VSCODE
------------------------------------------------

1) Installing VS Code

• Setup VS Code from the following link (I used the "system" installation file with the file being run as an administrator):
  
  https://code.visualstudio.com/docs/setup/windows#_user-versus-system-setup

• Restart the system
  

2) Installing the Lilypond extension for VSCode

To get Lilypond to work with VS Code, you need two main extensions (vscode-pdf and VSLilyPond). First, install the vscode-pdf extension (by tomoki1207, https://marketplace.visualstudio.com/items?itemName=tomoki1207.pdf)

• Open VS Code

• In VS Code Navigate to File -> Preferences -> Extensions

• Search for the extension "VSLilyPond" (by lhl2617, https://marketplace.visualstudio.com/items?itemName=lhl2617.VSLilyPond). As of writing this post, the latest version of this extension is 1.4.2 and has been tested successfully for Lilypond 2.22.0.

• After installing the extensions, restart VS Code.

• In VSCode, Click on File -> Open File and navigate to the directory where you stored your "test.ly" file.

• You will need "python-ly" installed as well for formatting the Lilypond file. More information can be found here:
  
  https://github.com/lhl2617/VSLilyPond/blob/master/docs/INSTALL.md
  
  For installing python-ly:
  
  https://pypi.org/project/python-ly/

• If you have Python (latest version 3.9.2, as of writing this post), run the following command in command prompt (without the quotes):
  
  "python -m pip install python-ly"

• Restart VS Code

• Open your "test.ly" file again, right click and select "Format Document". If you do not get an error and the document formats properly with correct indentation, all is good. 

• To check if everything is installed properly, make some changes to your "test.ly" file. I added the following snippet (after the first snippet):
  
  {
    c e g c
  }

• Press "Ctrl+S" on your keyboard to save the file. In VS Code's terminal, you should get the following output:
  
  Compiling: c:\MusicEngraving\test.ly
  Compilation successful
  
  If you get an error, then you will get an output that says "Compilation failed". In that case, something probably went wrong with the way the extensions were installed (including the python-ly extension). You may need to check the installation document found at the following link:
  
  https://github.com/lhl2617/VSLilyPond/blob/master/docs/INSTALL.md
  
  If no error is shown in the terminal output, navigate to the folder of your "test.ly" file and you should see an updated PDF of your "test.ly" file.
  

CONCLUSION
----------

Here is the full snippet used in my "test.ly" file:

\version "2.22.0"
{
  c' e' g' e'
}

{
  c e g c
}

Aaaaand, I have finished writing this post. Lilypond is a great music engraving tool and I've only just begun using it. I hope someone finds this post useful for installing and using Lilypond with VS Code. Cheers!