LenMus building documentation
==============================

Last updated: 25/Feb/2009


Table of content
-----------------

1. Requirements and supported platforms
    1.1 Dependencies
    1.2 Supported platforms

2. Installing under Linux

3. Installing under Windows



 
====================================================================================
1. Supported platforms and requirements
====================================================================================


1.1 Supported platforms
------------------------

Currently, LenMus has been tested and built in the following platforms:

- Windows XP, using MS VisualStudio .NET 2003

- Linux Ubuntu, using Code::Blocks IDE and GNU GCC compiler

Unfortunately I don't have instructions/makefiles for any other platforms/compilers yet. Please contact me if you would like to help with creating a build for the compiler/platform you use.



1.2 Dependencies
-----------------

LenMus depends on the following software packages (installation instructions for these dependencies are given later):

- wxWidgets (http://www.wxwidgets.org/)
    LenMus is programmed using the wxWidgets framework. Therefore, building LenMus requires to install and build wxWidgets. There is a couple of fixes to add to wxWidgets source code. One of them is critical; without it LenMus will not build. This fixes are listed in file wxwidgets_patches.txt
    
    Currently LenMus can be built with wxMSW (Windows) or wxGTK (Linux). You have to download the wxWidgets sources for the appropriate platform (http://www.wxWidgets.org/downloads/) and build it.


- FreeType (http://www.freetype.org/)
    Renderization of music symbols is done using the FreeType library. Therefore, it is required to have installed:
    
    - For Windows: freetype.dll, freetype.lib
    - For Linux: libfreetype.o
    
    Also, for both systems, the include files (.h) for the Freetype version you are installing are required. 


- Portmidi (http://?)
    LenMus require Portmidi for sound generation. Therefore, it is required to have:
    
    - For Windows: portmidi.lib, porttime.lib and portmidi.dll
    - For Linux: libportmidi.o, libporttime.o
    

- sqlite3 (http://www.sqlite.org)
    LenMus require sqlite3 database for storing user performance data on exercises. Therefore, it is required to sqlite3 libraries (version 3.6.10 or greater):
    
    - For Windows: sqlite3.dll 
    - For Linux: libsqlite3.o
    

- Agg 2.4 (http://www.anti-grain.com/)
    For anti-alised renderization LenMus uses AGG 2.4. It is a collection of source files, that are already included in the LenMus source code. So you don't need to do anything to about this package.




====================================================================================
2. Installing under Linux
====================================================================================

These are instructions on how to build LenMus under Linux. These instructions should work for all Linux distros, as we will be installing from sources.


Install wxWidgets (wxGTK)
-------------------------

1. Download the wxGTK source archive from http://www.wxwidgets.org/downloads/ and expand it. If you intend to use it in place (not install it in system dirs) choose a place where it can stay forever because you won't be able to move it without breaking the build.

2. [Update: You can safely skip this step] Apply the two required patches to the wxWidgtes sources. These patches are detailed in file wxwidgets_patches.txt 

3. Build wxWidgets. For this please refer to wxWidgets documentation. A quick guide is included in file linux_install_wxwidgets.txt for your convenience, and it should be enough in most cases.

    
Install PortMidi libraries
---------------------------------

LenMus require the Portmidi libraries for sound generation. To install these libraries, the following commands should be executed on a terminal window (enter your password as needed):

sudo apt-get install libportmidi-dev

headers are placed at /usr/include/ and libraries at /usr/lib/. To check for it:

ls /usr/lib/libport*                 ;# verify that the libraries are there now
ls /usr/include/port*
    
Install sqlite3 library
---------------------------------

You need libsqlite3.o library. At least version 3.6.10 is required. If it is not already on your system (sqlite3 version included in Ubuntu 8.04 is quite old (3.4.2), and it is not the one expected by the files included in LenMus proyect) do the following:

1. Download the source (sqlite-amalgamation-3.6.11.tar.gz) from http://www.sqlite.org/download.html to a suitable location where you can build it, e.g. ~/install

2. Extract the source:

    cd install
    tar zxvf sqlite-amalgamation-3.6.11.tar.gz

3. Create a build directory:

    mkdir build-sqlite3.6.11

4. Configure it to build for your machine:

    cd build-sqlite3.6.11
    ../sqlite-3.6.11/configure --prefix=/usr/local

5. Build the software:

    make
    sudo make install


    
    
Install FreeType (libraries and include files)
-------------------------------------------------------

LenMus require the FreeType package for renderization of music symbols. Apart of the libraries, the include files (.h) for the FreeType version you are installing are also required to compile LenMus.

The freetype libraries are normally already installed in linux. Verify this:

ls /usr/lib/libfreetype*

If they are not installed, do it:

sudo apt-get install libfreetype6 libfreetype6-dev
ls /usr/lib/libfreetype*                 //verify that the libraries are there

The include files have to be accesible from LenMus makefile.



Compile and build LenMus
------------------------

Once all previous pre-requisites are met, it is just a question of preparing a makefile and using your favourite compiler to compile and build LenMus. Makefiles are included for:

- Linux Ubuntu, with Code::Blocks and GNU GCC

Unfortunately we don't have instructions/makefiles for any other platforms/compilers yet. Please contact us if you would like to help us with creating one for the compiler/platform you use.


a) Using Code::Blocks with GNU GCC

The appropriate project file for Code::Blocks is in folder .../lenmus/build/gtk/lenmus.cbp.
Open this file with Code::Blocks and build LenMus. 

That's all.



Problems with MIDI sound
----------------------------

When installing LenMus in Linux you might find problems with sound as a MIDI synthesizer is not installed by default in some Linux distros. In file 'linux_install_midi.txt' you will find some instructions to install a Midi software synthesis package.





====================================================================================
3. Installing under Windows
====================================================================================

Install wxWidgets (wxMSW)
-------------------------

1. Download the wxMSW source zip archive from http://www.wxwidgets.org/downloads/ and expand it.

2. Apply the two required patches to the wxWidgtes sources. These patches are detailed in file wxwidgets_patches.txt

3. Build wxWidgets. To build LenMus it is enough to generate the 'Unicode Debug' and/or the 'Unicode release' versions of wxWidgets. To build wxWidgets please refer to wxWidgets documentation. A quick guide is included in file windows_install_wxwidgets.txt for your convenience, and it should be enough in most cases.


    
Install PortMidi libraries
---------------------------------

LenMus require the Portmidi libraries for sound generation. The libraries are already included in the LenMus source code package, so you have nothing to do.

Nevertheless, if you prefer to use a later version or to build this library by yourself, you will have to download the portmidi package and follow the instructions in this package.

    
Install FreeType (libraries and include files)
-------------------------------------------------------

LenMus require the FreeType package for renderization of music symbols. appart of the libraries, the include files (.h) for the FreeType version you are installing are also required to compile LenMus. All of them are already included in the LenMus source code package, so you have nothing to do.

Nevertheless, if you prefer to use a later version or to build this library by yourself, you will have to download the FreeType package and follow the instructions in this package to build the library. Once built, copy the following folders and replace those in lenmus/packages/freetype:
    - freetype/include
    - freetype/bin
    - freetype/lib

    
    
Install sqlite3 library
---------------------------------

 The library is already included in the LenMus source code package. You only have to copy file "lenmus\packages\wxSQLite3\sqlite\lib\sqlite3.dll" to the project execution folder (z_bin). Nothing else has to be done.



Compile and build LenMus
------------------------

Once wxWidgets is installed, it is just a question of preparing a makefile and using your favourite compiler to compile and build LenMus. Makefiles and project files are included only for:

- MS VisualStudio V6.0

- MS Visual C++ Express 2008

Unfortunately we don't have instructions/makefiles for any other platforms/compilers yet. Please contact us if you would like to help us with creating one for the compiler/platform you use.


a) Using MS VisualStudio / MS Visual C++

The appropriate project file for MS VisualStudio V6.0 is in folder .../lenmus/build/msw/lenmus.sln, and for MS Visual C++ Express 2008 is in folder .../lenmus/build/msw2008/lenmus.sln.

Before opening the project file, you have to define system environment variable WXWIN. To do it:

    1. From the Start button, select Control Panel. Double click on System.
    2. Click on the 'Advanced options' tab and click on button 'Environment Variables'.
    3  Define a new user variavle, named WXWIN, pointing to the wxWidgets installation root folder.

Now, open the project file with MS VisualStudio and build LenMus. 

Before running the project for the first time, you need to copy some files to certain folders, so that the application can access them from VisualStudio:

    1. Copy file "lenmus\fonts\lmbasic2.ttf" to "lenmus/build/msw" or "lenmus/build/msw2008" folder, depending on your case.

    2. Copy to the to the project execution folder (lenmus/build/z_bin) the following DLLs:
        - lenmus\packages\freetype\bin\freetype6.dll
        - lenmus\packages\freetype\bin\zlib1.dll
        - lenmus\packages\wxSQLite3\sqlite\lib\sqlite3.dll


That should be all.









