INSTALL.TXT

*********************************************************************
*                        INSTALLING MTOOLS                          *
*                                                                   *
* Copyright 2015 Arvind Singh                                       * 
*                                                                   *
* This file is part of the mtools library.                          *
*                                                                   *
* mtools 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 library 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 mtools  If not, see <http://www.gnu.org/licenses/>.    *
*********************************************************************


The library depend on a few external libraries:

    - CImg (http://cimg.eu)
    - fltk (http://www.fltk.org)
    - zlib (http://www.zlib.net)
    - libpng (http://www.libpng.org)
    - libjpeg (http://www.ijg.org/)
	- TinyXML2 (https://github.com/leethomason/tinyxml2)

and optionally
    
    - openCL (https://www.khronos.org/opencl/)
    - openGL (https://www.opengl.org/)
    - cairo (http://cairographics.org/)
    

	
*********************************************************************
*                          CMAKE OPTIONS                            *
*********************************************************************
	
	
The library project files are generated with CMake (https://cmake.org/)
A recent version of CMake is required (>= 3.10). 

Several flag can be set to configure the library: 

	- USE_COTIRE [default 0]
	  If set, use precompiled headers. 

    - CONSOLE_ONLY [default 0] 
      If set to 1, this flag disable mtools::cout console. 
   
    - USE_SSE [default = 0]
      Experimental, if set to 1, use SSE specific code. 
   
    - USE_CAIRO [default = 1 if Cairo found]
      If set to 1, use the Cairo library. 

    - USE_OPENGL [default = 1 if OpenGL found]
      If set to 1, use OpenGL. 
   
    - USE_OPENCL [default = 0]
      If set to 1, use OpenCL for specific GPU accelerated code.
   
    - USE_OPENMP [default = 0]
      If set to 1, use OpenMP. 

    - LOCAL_INSTALL [default  = 1] 
      By default the library in not installed but used directly from 
      the build tree. If LOCAL_INSTALL=0, then the library will be 
      installed inside the directory pointed by CMAKE_INSTALL_PREFIX. 
 
   
The compiler to use to build the library can be specified by setting
the environment variable CMAKE_CXX_COMPILER 


Examples: 

 cmake-mtools                                    [default build]
 cmake-mtools -DCONSOLE_ONLY=1 -DUSE_OPENGL=0    [no graphics and do not use OpenGL]
 cmake-mtools -DLOCAL_INSTALL=0                  [default build, install at default location]
 cmake-mtools -DCMAKE_CXX_COMPILER=/usr/bin/g++-9 [se G++9 to build the library]
 cmake-mtools -DLOCAL_INSTALL=0	-DCMAKE_INSTALL_PREFIX=/usr/local  [custom install dir]
	

	
*********************************************************************
*              Building the library on Linux (and co)               *
*********************************************************************


1) Make sure you use a recent version of gcc. Version 9 or later should do. 
   
2) Make sure that cmake, python, pkg-config and the required libraries are 
   installed (at least Zlib, libPNG, libJPEG, FLTK, Cimg and TinyXML2)   
     - FLTK version should be at least 1.3.5. 
     - CImg is header only: just copy CImg.h somewhere the compiler can find it. 
		
3) Generate the makefiles

         cd mtools
         ./cmake-mtools [-DOPTION1 -DOPTION2 ...]
	   	
4) Build the library
    
         make [-j N]
		 
5) If LOCAL_INSTALL=0, install the library with
	  
         [sudo] make install
	  	  
4) build the examples

         cd examples
         make [-j N]
	
	
*******************************************************************
*                 Building the library on OSX                     *
*******************************************************************

1) All the support libraries can be installed with homebrew 
   (http://brew.sh). For instance:
   
         brew install cmake python pkg-config glib libpng jpeg-turbo freetype cimg pixman cairo fltk tinyxml2
		
2) gcc is recommended over clang (although both compiler should 
   work). It can be installed with

         brew install gcc

3) Generate the makefiles, select the correct compiler with the 
   CMAKE_CXX_COMPILER variable. 

         cd mtools
         ./cmake-mtools [-DCMAKE_CXX_COMPILER=/usr/local/g++-9 -D...]
	   
	-> Make sure to enable OpenGL (i.e. option -DUSE_OPENGL=1 which is on by default)
	   otherwise plotting will be very slow on Mac OS. 
	   
	   
4) Build the library
    
         make [-j N]
	  
5) If LOCAL_INSTALL=0, install the library with
	  
         [sudo] make install
	  	  
4) build the examples

         cd examples
         make [-j N]


		 
*******************************************************************
*              Building on Windows, with VS 2015/17               *
*******************************************************************

1) Install CMake (and optionally Git for updating vcpkg). 

2) Install python 3. In order to use for command line argument 
   to be correctly parsed when a python script is called from the windows shell,
   the registry key [HKEY_CLASSES_ROOT\Applications\python.exe\shell\open\command]
   should have value something like ["C:\Users\Vindar\Anaconda3\python.exe" "%1" %*]
   if %* is missing, add it. 
   

3) Installing the support libraries:

   The easiest way it to use Microsoft's vcpkg package manager. 
   Installation is straightforward: open a powershell where vcpkg 
   should go and type:
   
        git clone https://github.com/Microsoft/vcpkg
        cd vcpkg
        .\bootstrap-vcpkg.bat
        .\vcpkg.exe integrate install
        .\vcpkg.exe integrate powershell
	
   The library should be build for the triplet [x64-windows]. To make 
   it  the default triplet, create a system environment variable: 
	
        VCPKG_DEFAULT_TRIPLET=x64-windows
	
   You MUST also create the system environment variable:
	
        VCPKG_DIR="path\to\vcpkg\root\dir"
		
   the external librairies can now be installed with, for instance, 
	
        .\vcpkg.exe install zlib libpng libjpeg-turbo fltk opengl pixman cairo cimg tinyxml2
		 
   All set !


4) BUG (September 2019). 
   There is a problem with FLTK built by vcpkg. Built it separately and then 
   replace the corresponding libraries and headers files in the vcpkg tree. 

	
2) Generate the Visual studio solution files:

        cd mtools
        ./cmake-mtools [-DOPTION1 -DOPTION2 ...]	   
	
4) Use mtools/build/mtools.sln VS solution file to build the library. 
   If LOCAL_INSTALL=0 was given to cmake, the library is installed by 
   running the project labelled INSTALL inside the solution.
		 
5) Use mtools/build/examples/examples.sln to build the examples. 
	  

  
*******************************************************************
*               Using mtools in a new project                     *
*******************************************************************

The library can be found by CMake using the usual find_package() 
function. However, the simplest way to create a new project that is 
cross-platform is to use the script mtools-project.py located in 
the /tools sub-directory (it is convenient to export mtools/tools/ to 
PATH so that the script can be called from anywhere). Then type:
         
        mtools-project.py [projectname]    create projectname
        cd [projectname]/build             enter the build directory
        cmake ..                           configure the project

On linux/OSX, use
		 
        make

and on windows, use the VS solution file

        /build/[projectname].sln
		 
Then, as the project grows, customize the CMakeLists.txt located in 
the root directory to suit your needs. 
  

  
*******************************************************************
* ABOUT THE MTOOLS_SWAP_THREAD() MACRO                            *
*******************************************************************  
  
The macro 
 
     MTOOLS_SWAP_THREADS(argc, argv)

should be the first line inside the main(int argc, char *argv[]) 
function. it is a dirty dirty hack to deal with the restriction that 
only the main thread can handle graphics on OSX. this macro preempt 
the main thread and use it on the background for drawing graphics 
while an alternate thread is created to run the main() function. 

Remarks: 

     - The macro is disabled on Linux and Windows and it can be 
     removed safely. However, it does no harm to keep it and it 
     make the code cross-plaftorm. 
   
     - Beware that, on OSX, the macro is active hence the global 
     objects are constructed with the main thread which is NOT 
     the one that runs the main() function !