soundeditor/INSTALL.txt

Table of contents
-----------------

WARNING: Only intended for developers who'll build the software from sources.

I - Pre-requisites

  1 - Building tools
  2 - 3rd party libraries

II - Getting Qatsh sources

  1 - Getting and extracting the official tarball
  2 - Getting the sources from SVN

III - Linux Installation from sources

  1 - Building with GCC 4.x
  2 - Running Qatsh

IV - Windows Installation from sources

  1 - Building with MinGW 4.4
  2 - Building with MS VC++ 2008 (9) / 2010 (10)
  3 - Running Qatsh

V - MacOS X installation from sources

  TODO.

                                ----------------------------------


I - Pre-requisites
------------------

1 - 3rd party libraries

  a. Linux

    * Qt 4.4 (or later) libraries

      Install them through your package manager : the package name should look
      like "libqt-4.x.y...-dev" or "libqt-4.x.y...-devel"
      (don't forget the "-dev(el)" at the end).

      Example:
       * Linux Mint Debian : TODO
       * Ubuntu 12.10 : TODO

    * libSndFile 1.0.17 (or later) library

      Install it through your package manager : the package name should look
      like "libsndfile-1.x.y...-dev" or "libsndfile-1.x.y...-devel"
      (don't forget the "-dev(el)" at the end).

  b. Windows

    * Qt 4.4 (or later) libraries

      Note : You may have them already installed if you installed a complete Qt 4 SDK
             (bundling Qt 4 libs + MinGW + Qt Creator in 1 package)

      Download the latest binary installer of the "Qt libraries"
      for your platform (32 or 64 bits) and chosen compiler (MinGW 4.4 or MSVC 20XX) from :

       http://qt-project.org/downloads#qt-lib

      And then install it in the standard location (recommended).

      And then add the installed "bin" folder in your PATH environment variable
      (to make have CMake detect Qt 4) :
       - Windows "Start Menu"
       - "Settings" / "Configuration panel" / "System"
       - "Advanced" tab / "Environment variables" button,
       - Select the "PATH" user variable and click on "Chnage" button,
       - Add "C:\Qt\4.x.y\bin;" at the beginning of the current value
         (4.x.y being the actual installed version of Qt libraries) , and click on "OK"
       - Click on "OK"
       - Click on "OK"

      Notes for the MinGW version : 
       - Be careful to specify the right folder
         when asked to by the installation wizard about MinGW 4.4 !

    * libSndFile 1.0.17 (or later) library

      Download the latest binary installer for your platform (32 or 64 bits) from :

        http://www.mega-nerd.com/libsndfile/#Download
  
      And then install it in the standard location (recommended).

      Note: The shipped binaries work with both MinGW 4.4 and MSVC 20XX.

  c. Mac OS X

     TODO (should be be close to Linux ; any volunteer ?)


2 - Building tools

  a. Linux

    * GCC 4.1 (or later)

      You generally don't even need to care about this, it's probably installed by default.

      If not, install it through your package manager : the package(s) name(s) should look
      like "gcc" or "g++" or "gnu-c++" or so ...

      Example:
       * Linux Mint Debian : TODO
       * Ubuntu 12.10 : TODO

     * CMake 2.8 (or later)

       Install it through your package manager : the package(s) name(s) should look like "cmake".

  b. Windows

    * CMake 2.8 (or later)

      Download the latest binary installer for your Windows version from :
          http://www.cmake.org/cmake/resources/software.html

      And then install it in the standard location (recommended).

    * Compiler and IDE (option 1) : QtCreator 2.5 (or later) and MinGW 4.4 (no other)

      As of early March 2013, there's no more all-in-one Qt 4 libs + MinGW + Qt Creator
      package available (only for Qt 5). 
      You need to get and install individual components yourself.

      - Download MinGW 4.4 (latest 4.7 is not compatible with Qt 4.8.x libraries)
        from there :
        
         http://nosymbolfound.blogspot.com/2012/12/since-until-now-qt-under-windows-is.html

        And extract its whole contents (it's a ZIP archive) to C:\

        You should now have a C:\MinGW folder with bin, include, lib, ... etc subfolders.

        Then add the installed "bin" folder in your PATH environment variable
        (to make have CMake detect MinGW) :
         - Windows "Start Menu"
         - "Settings" / "Configuration panel" / "System"
         - "Advanced" tab / "Environment variables" button,
         - Select the "PATH" user variable and click on "Chnage" button,
         - Add "C:\MinGW\bin;" at the beginning of the current value, and then click on "OK"
         - Click on "OK"
         - Click on "OK"

        Notes : Digia no more distributes it, and it's a mess, if even possible,
                with the MinGW project install tools at SF.net)

      - Download and install the latest version of QtCreator

         http://qt-project.org/downloads#qt-creator
          (example : qt-creator-windows-opensource-2.6.2.exe)

      - Configure QtCreator (tell it where to find CMake, MinGW 4.4 and Qt libs,
        in cae it didn't auto-detect them : ignore the relevant actions below if so)     
        - start it,
        - Tools / Options opens the Options windows,
        - Select "Compile & Run" in the list of the left,
        - Select the "Compilers" tab,
        - Click on the "Add / MinGW" button on the top right corner,
        - fill in the fields at the bottom :
          . Name : Chose a distinctive one ((ex: MinGW44)
                   (in case you already have other MinGW versions installed)
          . Path to compiler : Browse and select the MinGW c++ compiler executable 
              (C:\MinGW\bin\mingw32-c++.exe if you installed MinGW as explained above)
          . Debugger : Browse and select the MinGW debugger executable 
              (C:\MinGW\bin\gdb.exe if you installed MinGW as explained above)
          . ABI, mkspec : leave as is,
        - Apply (at the bottom right corner),
        - Select the "Kits" tab,
        - Select the "Manual" / "Desktop(default)" kit
        - Update the "Compiler" field below in order to select
          the right compiler name (the "distinctive" one mentionned above),
        - Update the "Debugger" field below through the "Manage ..." button
          in order to select the right debugger (the one for the selected MinGW compiler),
        - Apply (at the bottom right corner),
        - Select the "CMake" tab,
        - Browse and select your CMake executable (ex: C:\Program Files\CMake 2.8\bin\cmake.exe),
        - Apply (at the bottom right corner),
        - Select the "Qt versions" tab,
        - Click on the "Add ..." button on the top right corner,
        - Select the qmake.exe file in the bin subfolder of the Qt 4 libraries installation folder
          (should be something like C:\Qt\4.x.y\bin\qmake.exe)
        - OK (at the bottom right corner).

    * Compiler and IDE (option 2) : MS Visual C++ 2008 (9), 2010 (10) (later should work),

      If you don't have it one already installed, download the latest "Express" (= free)
      version from MS web site and install it (only IDE and C++ compiler needed).

      Note: For the Express versions, check if the "Windows SDK" is actually shipped with it,
            and if not, download the corresponding version from MS web site and install it.

  c. Mac OS X

     TODO (should be be close to Linux ; any volunteer ?)

                                ----------------------------------

II - Getting Qatsh sources
--------------------------

There are 2 ways of building and installing Qatsh from sources :
- from the official source tarball,
- from the subversion repository at SourceForge.net.

1 - Getting and extracting the official tarball

  a. Get the tarball from SF.net download page at

        http://sourceforge.net/projects/speed-dreams/files/qatsh/1.0.0,

      and you should find :

        qatsh-src-1.0.0-r5xxx.tar.xz

  b. Extract the tarball

    * Linux

      Let's say that you downloaded your package in $HOME/qatsh
      and that we'll extract it in the same folder
      (you can do as you like, but we'll use this folder in the explanations below).

      $ cd $HOME/qatsh
      $ tar xvfa qatsh-src-1.0.0-r5xxx.tar.xz
      
    * Windows

      Let's say that you downloaded your package in C:\qatsh
      and that we'll extract it in the same folder
      (you can do as you like, but we'll use this folder in the explanations below).

      You can use "7Zip", an excellent free compressed archive manager
       (download and install it from http://www.7-zip.org/)
      or any other of your choice supporting "tar" lzma-compressed archives.

    * At the end, in the extracted "1.0.0-r5xxx" subfolder, you should now see 
      the "cmake", "qatsh", "mathexpr" and "atsa" folders (among others),
      and a "CMakeLists.txt" file.

  c. Mac OS X

     TODO (any volunteer ?)

2 - Getting the sources from SVN

  Before you start, be aware that the SVN trunk / branches might crash or even not compile
  sometimes. If you want to do it anyway, follow the general instructions at

    http://sourceforge.net/svn/?group_id=239111

  And be aware that Qatsh source tree is at the following URL :

    http://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/subprojects/qatsh

  a. General SVN branching / versionning scheme

    For the moment, 
    - the developments for the next release are located in the trunk subfolder :

       https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/subprojects/qatsh/trunk

    - we make branches under the "branches" subfolder ; as an exemple,
      the "1.0.x" release maintenance branch current state is here :

       https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/subprojects/qatsh/branches/1.0.x

    - we make release tags under the "tags" subfolder ; 
      as an exemple, the "1.0.0" release is here :

       https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/subprojects/qatsh/tags/1.0.0

  b. Linux

    Let's say that you'll work in the $HOME/qatsh folder
      (you can do as you like, but we'll use this folder in the explanations below).

    And let's say that you want to checkout the current _development_ state (trunk).

    Simply run the 2 following commands (in a shell) :

       $ cd $HOME/qatsh
       $ svn co https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/subprojects/qatsh/trunk trunk

    See a. above URLs if you want other SVN "branches".

    At the end, in the extracted "trunk" subfolder, you should now see 
    the "cmake", "qatsh", "mathexpr" and "atsa" folders (among others),
    and a "CMakeLists.txt" file.

  c. Windows

    Let's say that you'll work in the C:\qatsh folder
      (you can do as you like, but we'll use this folder in the explanations below).

    And let's say that you want to checkout the current _development_ state (trunk).

    * Option 1 : Tortoise SVN (GUI integrated in the Windows Explorer)

       . In the Windows, explorer, right-click on the C:\qatsh folder,
         and select "SVN Checkout ..." in the context menu.

       . In the "URL of repository" field, enter the chosen URL
          (https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/subprojects/qatsh/trunk)

       . In the "Checkout directory" field, enter the target folder for the "trunk working copy"
          (C:\qatsh\trunk)

       . Select a "Fully recursive" "Checkout Depth",

       . Don't "Omit externals",

       . Keep the default "HEAD revision" traget revision to checkout
         (you want the last one, called "HEAD")

       . Click on the OK button
       
    * Option 2 : Slik SVN (command line tool)
       
      Simply run the 2 following commands in a Windows console (cmd) :

       $ c:
       $ cd \qatsh
       $ svn co https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/subprojects/qatsh/trunk trunk

    See a. above URLs if you want other SVN "branches".

    At the end, in the extracted "trunk" subfolder, you should now see 
    the "cmake", "qatsh", "mathexpr" and "atsa" folders (among others),
    and a "CMakeLists.txt" file.

  c. Mac OS X

     TODO (any volunteer ?)

                                ----------------------------------

III - Linux installation from sources
-------------------------------------

See above for pre-requisite conventions about where the sources are located.

1 - Building with GCC 4.x

  a. configure

    * create the build dir for CMake

      $ cd $HOME/qatsh
      $ mkdir build
      $ cd build

    * run CMake :

      - for a Release (optimised) build :

        $ cmake ..

      - you may also want to override some default settings :

        for that, you can use the -D option of cmake :

          Example :

            $ cmake -D CMAKE_PREFIX_PATH:STRING=/usr \
                    -D CMAKE_BUILD_TYPE:STRING=Debug ..

        or else you can use ccmake to change the variables interactively :

            $ ccmake ..

             * press (t) for advanced options if needed
             * in order to change a variable :
               * select the associated line using the up/down arrow keys
               * press (enter)
               * edit the value
               * press (enter)
             * press (c) for configure
             * press (g) for generate
             * press (e) to exit


        Usefull CMake variables for Qatsh (note that some might be "advanced" ones) :

        - CMAKE_BUILD_TYPE:STRING :
            Debug, Release, RelWithDebInfo, MinSizeRel (def: Release)

        - CMAKE_PREFIX_PATH:STRING :
            Path prefixes for additional / alterative prerequisite libraries (def:empty)
            (use /usr/local if you compiled some prerequisite libs yourself).

        - CMAKE_INSTALL_PREFIX:PATH :
            Install path for Qatsh (def: /usr/local)

  b. build

      $ make
  
  c. install

      $ sudo make install
  
      Notes:
      * sudo is only useful if your install PREFIX is a read-only folder (like default /usr/local)
      * sudo configuration : you may ask your system administrator to enable you to run
        'sudo make install' ; if he doesn't know how, you can tell him/her
        to add a line like this in /etc/sudoers (or something less permissive ;-) :
           <your login name>    ALL=(ALL) NOPASSWD: ALL

2 - Running Qatsh

  a. Running the installed binaries (the usual way)

     If the default CMake settings were kept, Qatsh is normally installed in /usr/local.

     And as /usr/local/bin is normally already in your PATH variable, simply try :

      $ qatsh
      
     If /usr/local/bin is not already in your PATH variable, you probably want to add it ;
     to do so, simply add the line "export PATH=$PATH:/usr/local/bin" to your  ~/.bashrc file ;
     you can use :

      $ echo "export PATH=$PATH:/usr/local/bin" >> ~/.bashrc" for that

     Then, the above startup command should work now :

      $ qatsh

     Runtime options : type this command to get them explained :

      $ qatsh --help

  b. Running the build binaries (the Qatsh developer way)

     If you plan to make changes to Qatsh, you'll need to build and build again,
     and you probably feel that the install step is too much : you are right !

     You can actually run Qatsh from its build dir (without installing) :

      $ $HOME/qatsh/trunk/build/qatsh/qatsh

                                ----------------------------------

IV - Windows installation from sources
--------------------------------------

Note that these instructions work under Windows XP 32 SP2/SP3 ;
some tweaks might be needed for newer / wider versions.

See above for pre-requisite conventions about where the sources are located.

1 - Building with MinGW

  a. Start QtCreator,

  b. File / Open a file or project ...

  c. Browse and select the master CMakeLists.txt of Qatsh
     (at the top of the source tree, next to the atsa, qatsh, mathexpr and cmake folders)

  d. Then the CMake wizard opens up : 

     * Build location page :
       + Browse and select a build folder (CMake will create and use it for building)
          (ex: <path to CMakeLists.txt/../build)
     * Next
     * Run CMake page :  use :
       + CMake generator : "MinGW generator" (mandatory choice here !)
       + CMake arguments : 
           -DOPTION_OFFICIAL_ONLY:BOOL=On -DCMAKE_BUILD_TYPE:STRING=Release
       + Click on the Run CMake button

       Note: See II.2.c above for more about possible / useful CMake arguments.

       Note: The 'Release' build gives you -O3-optimised binaries.

       Apart from "won't build" or "won't install" message (don't care),
       all should go smoothly, especially the detection of the 3rd party libraries.

     * Done

  e. QtCreator automatically opens your brand new project !

     Note: 
     . Later on, when starting again QtCreator, the project will be automatically
       loaded in the default session.
     . If you need to re-run CMake (sometimes, QtCreator can't detect it, like after adding
       new / removing files in the source tree, or if you need to change the configuration
       settings), simply use the menu : Compile / Run CMake.

  f. Configure the build, deployment and run steps of your project

      * click on the "Projects" button on the left vertical bar
        in order to get the projects configuration panel

      * select your project's tab on the top

      * in the "Compile settings" sub-tab :
        - stay with the default" "all" compile configuration (we need only this)
        - don't change "CMake" section (note that you can re-run CMake from here :
           you'd get into the wizard we used at the beginning)
        - in the "Compilation steps" section, click on the "Details" button of the 1st step,
          and add some arguments to the default "mingw32-make.exe" command :
           . at least the "all" target, at the end of the argument line,
           . and may be some "-j2" of "-j4" boosting option if you own a dual/quad-core CPU :-)
        - leave the other sections as is, they are OK.

      At this point, you can choose 2 options for running Qatsh :
      * run the built binary in-place (in the build/qatsh folder, after building it),
          for this, you need to add the binary folder of libSndFile
          to the PATH variable of the excution environment :
          in the "Run settings" sub-tab, click on the "Details" button
          of the "Run environment" panel, and edit the PATH variable
          (add "C:\Program files\Mega-Nerd\libsndfile\bin;" at its beginning
           if libsndfile was installed in the default location),
      * run the installed binary (after building and installing it) :
          for this, you need to add a deployment step :
          in the "Run settings" sub-tab, in the "Deployment" section,
          . (cosmetic) change the name of the "Method" : 
              "No deployment / Local execution" => "Install"
          . click on the "Add the deployment step" button, and select "Make",
          . add the "install" argument to the default "mingw32-make.exe" command.       
          in the "Run settings" sub-tab, in the "Run" section,
          . click on the "Add ... Custom executable" button,
          . select the target qatsh.exe executable 
            (will be in C:/Program files/bin with default CMake settings).
          . Check the "Run in a terminal" option, to get the run-time traces in a console.

        Note: The deployment" step will be completed when you'll "Run" qatsh
        from QtCreator (no other way, I know, this is not very handy).

  g. Build

      * "Build / Compile all" through the menu (or Shift + Ctrl + B)
      
  h. At this stage, you can already debug or run qatsh from QtCreator

      * For this, now everything is configured,
        you simply have to "Compile / Run" or "Debug / Start debugging / Start debugging"
        from the menu
        (or click on the green arrow buttons on the bottom left corner of QtCreator).

2 - Building MS VC++ 2008 (9) / 2010 (10)

  a.  Startup CMake GUI and set :
      * "Where is the source code" to C:\qatsh\trunk
      * "Where to build the binaries" to C:\qatsh\trunk\build
        (if you follow the folder conventions mentioned above).

  b.  Press the "Configure" button, answer "Yes, create the C:\qatsh\trunk\build folder",
      select the right MSVC compiler version and select the "Use native compilers" option.
      If the "Generate" button is still greyed, press the "Configure" button again.

  c.  Press the "Generate" button. CMake will generate the solution file "qatsh.sln"
      in the ...\build folder, and associated project files (*.vcproj) in the ...\build folder
      and subfolders
      (Note : .sln/.vcproj are OK for MSVC 2005, but you might get other files extensions
              the later MSVC versions).

  d.  Load qatsh.sln in MSVC IDE.

  e.  Select the build configuration (Debug, Release, ...).

  f.  Build the whole Solution (Build / Build Solution)

  g. At this stage, you can already debug or run qatsh from MSVC
     without installing (the built executable in the build/qatsh folder),
     provided you have added "C:\Program files\Mega-Nerd\libsndfile\bin;"
     at the beginning of your PATH environment variable
     (see for how to do this).

  h.  But you can also install it (in C:\Program files\qatsh with default CMake settings) :
      Build the 'INSTALL' project (right click on it and select Build).

3 - Running Qatsh from the explorer (installed binaries)

  Simply double-click on the qatsh.exe executable in C:\Program files\qatsh\bin
  (if default CMake settings were kept).

                                ----------------------------------

V - MacOS X installation from sources

  TODO.