~s-cecilio/lenmus/v5.1.x

//-----------------------------------------------------------------------------
//  This file is part of LenMus Phonascus program
//  Copyright (c) 2002-2012 LenMus project
//
//  This program is free software; you can redistribute it and/or modify it under the
//  terms of the GNU General Public License as published by the Free Software Foundation,
//  either version 3 of the License, or (at your option) any later version.
//
//  This program is distributed in the hope that it will be useful, but WITHOUT ANY
//  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
//  PARTICULAR PURPOSE.  See the GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License along with this
//  program. If not, see <http://www.gnu.org/licenses/>.
//
//  For any comment, suggestion or feature request, please contact the manager of
//  the project at cecilios@users.sourceforge.net
//
//-----------------------------------------------------------------------------


             ============================================
              LenMus Phonascus installation instructions  
             ============================================

This document contains instructions for using CMake to build LenMus program 
from sources on all platforms.


Requirements
============
- CMake version 2.8 or higher
- Lomse 0.10 or higher
- SQLite3 3.6 or higher
- wxWidgets 2.8.0 or higher
- Portmidi library


Table Of Content
================
    A. General notes and requirements. ***** PLEASE READ THIS FIRST *****
    B. Quick installation guide
    C. How to generate the makefile or project file for LenMus
        1) Building on Linux
        2) Building on Windows
            2.a) Using CMake GUI program.
            2.b) Using a command window:
    D. "In-source" vs. "Out-of-source" builds



A. General notes and requirements
==================================

1. No makefiles or IDE project files are provided. All makefiles are generated
   with CMake using CMake build system. CMake can generate different kinds of
   native build files for your system (e.g. Unix Makefiles, Eclipse CDT 4.0
   project files, Visual Studio project files). You need CMake 2.8.0 or later
   on your platform. You can download it from
        http://www.CMake.org/CMake/resources/software.html
   Just download and install it (very simple). In Linux, you can install it
   using the package manager:

        sudo apt-get install CMake


2. I have only generated and tested on following platforms:

    - Windows XP, using Visual Studio .NET 2003 (VS7) (generator "Visual Studio 7 .NET")
    - Linux Ubuntu 12.04, Using CodeBlocs with linux makefiles (generator "CodeBlocks - Unix Makefiles")
    - Linux Ubuntu 12.04, Using linux makefiles  (generator "Unix Makefiles")

   No idea if there will be problems for other platforms/configurations. But if
   you try, please let me know for updating the documentation.



B. Quick installation guide
============================

Use a terminal window (Linux) or command window (Windows) and do the following
(fix command names and paths for Windows):

1. Create a directory for the sources:
    cd ~/sources
    mkdir lenmus
    cd lenmus
    
   And download a working copy of the repository: 
    svn co https://lenmus.svn.sourceforge.net/svnroot/lenmus/branches/TRY-5.0 .
    
2. Create a directory to hold your build files:
    cd ..
    mkdir build-lenmus

3. Change directory to the directory you created in the previous step:
    cd build-lenmus

4. Run CMake to generate the makefile:
    cmake -G "Unix Makefiles" ../lenmus
   
   If you would like a 'debug' build add '-DCMAKE_BUILD_TYPE=Debug', For instance:
        cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug ../lenmus  


5. Now you've generated a makefile using CMake. So run 'make' to build the package
and 'sudo make install' for installing it. After installation directories 'build-lenmus'
and 'lenmus' are no longer needed.

    
    


C. How to generate the makefile or project file for LenMus
==========================================================

You need CMake 2.8.0 or later.


1) Building on Linux
--------------------

First, you will also need to install the required packages.

a) package libunittest++-dev 

Installing it should be as simple as typing in the following command in your
terminal (on Debian-like systems):

    sudo apt-get install libunittest++-dev


b) PortMidi libraries and headers. Required for sound generation:

    sudo apt-get install libportmidi-dev

c) Lomse library. It is used to render music scores:


d) SQLite3 library. Install the sqlite3 and libsqlite3-dev packages:

    sudo apt-get install sqlite3, libsqlite3-dev


Now, you can procced to generate LenMus.    

In following instructions it is assumed you want to generate Makefiles. Open a
terminal window, move to the folder in which you have unpackaged the lenmus
sources, and create a folder for building. For instance:

    checkout a working copy:
        mkdir lenmus
        cd lenmus
        svn co https://lenmus.svn.sourceforge.net/svnroot/lenmus/branches/TRY-5.0 .

    create folder to build:
        cd ..
        mkdir build-lenmus
        cd build-lenmus

Using CMake, proceed to create the makefile:

    CMake -G "Unix Makefiles" ../lenmus  

Now, build the lenmus:

    make

Then, either install lenmus or build a Debian installation package:

        sudo make install
    Or
        make package
    
If you build a package, you can install it by running:

    sudo dpkg -i lenmus-0.1.1-Linux.deb


That builds and installs LenMus on Linux. By default, LenMus is installed in
${CMAKE_INSTALL_PREFIX}/bin, with CMAKE_INSTALL_PREFIX defaulting to usr/local.

You can change the install location by running CMake like this:

    CMake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/new/install/prefix  \
        -DCMAKE_BUILD_TYPE=Release ./

Building from source in the repository is recommended, since code in the
repository should always be stable. If it's not, that's a bug to report.


2) Building on Windows
----------------------

In this description it is assumed you want to generate Visual Studio .NET 2003
project files. The procedure for CodeBlocks or any other tool is similar. Just
replace Visual Studio with your favourite tool.

To create the project file / makefile you have two options:

    a) Using the CMake GUI program.
    b) Using a command window.
    

2.a) Using CMake GUI program.

    1. Open CMake GUI program. (C:\Program files\CMake\bin\CMake-gui.exe)
    
    2. Enter requested data in following fields:
        - Where is the sorce code: <path-to-lenmus-root>
            i.e.: D:/projects/lenmus
        - Where to build the binaries: <folder/to/place/makefiles>
            i.e.: D:/projects/lenmus/build

    3. Press the 'Configure' button. A window will open and you will be asked for which tool you would like to generate the makefile. Select, for instance, "Visual Studio 7 .NET".

    4. If there are lines marked in red color. press again the 'Configure' button. Repeat this until no red lines.
    
    5. Press the 'Generate' button.

    Done. Makefiles for the selected platform and generator will be created in the specified folder.
    
    Now open the makefiles/project files and proceed to build the library and the test program. All tests will run automatically when the tests program is built.


2.b) Using a command window:

    The procedure is similar, but using the command window.
    
    1. Open the command window and move to the lenmus root folder:
    
        cd <path-to-lenmus-root>
        
    2. Create a new folder for the makefiles. i.e.  <path-to-lenmus-root>/build/
    
        mkdir build

    3. Now generate the makefiles:

        CMake -G "Visual Studio 7 .NET" ./build

    This should create .sln and .vcproj files for Visual Studio in the 'build' directory.
    
    You can also generate project files for some other VS version. You can get a list of all supported generators by typing in and running CMake.




D. "In-source" vs. "Out-of-source" builds
===========================================

RECOMMENDED WAY OF INSTALLING LENMUS: Out-of-source

When you generates the makefiles, they have to go somewhere. An "in-source"
build puts them in your source tree (i.e. /lenmus/build). In the next example
the makefiles are placed in the same directory as the source code. Therefore,
it is an "in-place" build:

    cd lenmus
    mkdir build
    CMake -G "Unix Makefiles" ./
    make

An out-of-source build puts them in a completely separate directory, so that
your source tree is unchanged. Out-of-source builds are recommended, as you can
build multiple variants in separate directories, i.e.:

        /projects
            /lenmus                  <-- the source tree
            /lenmus-debug
            /lenmus-release

In the following example, an out-of-place build is performed:

    cd lenmus
    mkdir lenmus-debug
    cd lenmus-debug
    CMake -G "Unix Makefiles" ../lenmus
    make

Note: Before performing an out-of-source build, ensure that all CMake generated
in-source build information is removed from the source directory:

    CMakeFiles directory
    Files CMakeCache.txt and cmake_install.CMake