This document contains detailed instructions for building Lomse library and tests program from sources, on Microsoft windows systems. If you find things that need to be fixed in this document and would like to contribute, you are welcome. Please post a message on the Lomse list. Thank you.
For installing the Lomse library you have to use CMake, version 2.8.11 or greater. CMake will generate for you a makefile for doing all necessary steps, as well as additional ones, such as building a test program for checking the library, and an example program.
If you don't have CMake, download and install the latest distribution from http://www.cmake.org/cmake/resources/software.html. Download the installer .exe file and run it.
To build the lomse library, the following software should be installed in your system:
Once you have checked that you have the required packages you can proceed to create the makefile or project file for building Lomse.
Create a folder for Lomse sources. For instance, "C:\MyData\Projects\lomse". Using your Git client software download a working copy of Lomse project. If you are using a command window, the command to issue would be:
LenMus
git clone https://github.com/lenmus/lomse
Now, using CMake, proceed to create the makefile:
Open CMake GUI program. (usually at C:\Program Files\CMake\bin\cmake-gui.exe). It will display this window
Click on the 'Browse Source...' button in the top right hand corner of the window. Use the file browser popup to locate the Lomse source directory (i.e.: C:\MyData\Projects\lomse), and click OK.
Now we create a directory in which to create the Visual Studio project files and hold the build products. This directory should not be the same as, or inside, the the source directory. Here we will create this build directory alongside our source directory.
Click on the 'Browse Build...' button in the top right hand side of the CMake GUI window. Use the file browser popup to browse back to C:\MyData\Projects\, and click on the Make New Folder button. Rename the created folder to lomse-build, and click on the OK button.
The two text entries at the top of the GUI should now contain C:/MyData/Projects/lomse and C:/MyData/Projects/lomse-build respectively (Note: CMake always represents Windows paths with forward slashes).
Click on the 'Configure' button on the left hand side. A window will open and you will be asked for which tool you would like to generate the makefile for. Select, for instance, "Visual Studio 7 .NET". Ensure only the 'Use default native compilers' radio box is checked. Then click on the 'Finish' button.
Once the generator is selected, the configuration process will start. At some point, you will get a listing of all relevant options (CMakeCache entries). All entries at this point will be highlighted in red to signal that you may want to modify some of them. Mouse-hover over entries will generate a brief description, as shown below.
Most of the default settings should be fine, though you may want to change CMAKE_INSTALL_PREFIX. By default, CMake will configure the build to install Lomse under C:\Program Files\lomse. If you do not wish to use this directory, or do not have permission to install there, you can change the installation location. Click on the arrow next to the CMAKE entry in the central options display to expand all CMake specific configuration options. Scroll down to locate the CMAKE_INSTALL_PREFIX entry. Click on the entry and edit the path directly or via the file browser popup. In this example we will modify this install directory to C:/MyData/Projects/lomse-install.
Once you have adjusted any options, click on the Configure button again. After this has finished, all the options listed in the central option display should be white. If you still have entries in red, click Configure to reconfigure until all entries are white.
Building with CMake is an iterative process:
It may happen that CMake won't find some needed libraries, such as FreeType. In this case you will have tree or four variables highlighted in red that you have to fix. Yo have two options for this:
When no more red lines, click on the 'Generate' button. This will create the Visual Studio project files and will be placed in the specified folder. Finally, CMake will report Configuring done, Generating done in the logging window at the bottom of the GUI. You can now close the CMake GUI.
At this point you've generated project files using CMake. Now, just run MS Visual Studio, open the solution file, choose your configuration, and build the ALL_BUILD project.
Once you have built Lomse you can install it by building the INSTALL target in Visual Studio. In the Solution Explorer, right click on the INSTALL solution, and select Build from the popup menu. The solution will now build and install to the directory you chose for CMAKE_INSTALL_PREFIX earlier. If you wish to build a different configuration (Release if you built Debug first, for example), then simply change the solution configuration as described in the previous paragraph, and build the INSTALL solution again.
Please notice that:
While running CMake, all configure options are saved in file CMakeCache.txt, Before repeating all the build procedure (after fixing the errors), you should delete the whole content of the build folder and start again from step 3. Otherwise, values saved in the cache would interfere and cause problems. So move to folder to build and delete all its content before using CMake again.
CMake has knowledge about the standard places to look for third party libraries, but my experience is that few Windows users know about these places and they install software here and there. As a consequence, sometimes it is difficult for my current CMake script to locate installed software, generating too many 'red lines' and forcing users to specify all needed paths. And this is not very user friendly.
Probably my CMake script is a bullshit. But you are a good developer and building Lomse is just compiling the source code, including the headers for the required libraries. Probably you can prepare your own solution and project file for MS Visual Studio. That's what I do for building in Windows (yes, I don't use CMake). Or better, if you are good at MS Windows and CMake, and would like to help me to improve Lomse installation procedures for Windows, you are welcome. Please post a message in the Lomse list. Thank you.
Last updated: 2016/01/31