=========================
Building Kst with CMake
=========================

Install CMake from www.cmake.org or your distribution (version >= 2.8).


3rd party libraries
-------------------

	Install Qt 4 and make sure qmake is found.
		Add the folder with qmake to the environment variable PATH.
		If you've compiled Qt by yourself or qmake is not found after
		installing Qt fix PATH,
		Linux/Unix: export PATH=<your path to qt>/bin:$PATH
		Windows   : set PATH=<your path to qt>\bin;%PATH%

	Libraries for plugins:
	Currently only Getdata, Gsl, and Netcdf are supported.
	On pkg systems the libraries should be found automatically,
	on non-pkg systems like Windows you must point to the libraries
	by environment variables NETCDF_DIR, GETDATA_DIR, and GSL_DIR.


Generating build system files
-----------------------------

	CMake is a build system file generator. On all systems it could
	generate files for several build systems, for instance Makefiles
	for make, project files for Visual Studio, Xcode, Eclipse.

	Running cmake without any argument lists all supported build
	systems on your system. Passing one of them as -G"<build system name>" 
	argument when running cmake selects this.


Building out-of-source
----------------------

	The standard way of using CMake is to build in a folder which doesn't resides
	in the source tree. This has the advantage, that a complete fresh build could
	be done by simply deleting all files in the build folder and to re-run cmake 
	again.

	Another benefit of out-of-source builds is that several builds (debug, release,
	command-line builds, IDE project files) could all use the same source tree.

	Therefore when using cmake create a folder outside of the source tree and
	select this folder when using CMake's GUI, cmake-gui, or go into this folder
	when you call cmake from the shell.


Using cmake
-------------

	When calling cmake you must pass the path to the source tree (absolute are relative)
	and optionally the generator (each system has its own default). Additional arguments 
	could be passed with the -D prefix.

	Here some examples, assuming the build folder is in the same folder as the source tree:

	* Makefiles on Linux
		cmake ../kst
	
	* Project files for QtCreator:
		Open the kst/CMakeLists.txt file and select the build folder
		or create the files in the command line using the -G"CodeBlocks *" option, eg
			cmake ../kst -G"CodeBlocks - Unix Makefiles"
	
	* Project files for Xcode
		cmake ../kst -GXcode
		
	* Project files for Visual Studio 10
		cmake ..\kst -G"Visual Studio 10"

	* NMake files for Visual Studio
		cmake ..\kst -G"NMake Makefiles"

	* Makefiles for MinGW
		cmake ..\kst -G"MinGW Makefiles"


	Daily work:

	* Re-running cmake is simple
		cmake .

	* Adding new files 
		The cmake build system scans the directories, so no need to update any file,
		just re-run cmake. Also the mocing rules are generated.

	* Unused source code file
		Because cmake scans the directories for *.cpp and *.h files it will also
		add files to the build system which are not mentioned to build. To exclude
		them change their ending and re-run cmake.

	* Projects
		'make help' lists the available targets.


Options
-------

	Options could be passed by the -D prefix when running cmake.
	Available options will be listed on each cmake run.
	Here the options with their default value:

    -- kst_version_string       = 2.0.x   : Version string. 
    -- kst_release              = OFF   : Build release version: optimize for speed, don't embedded debug symbols. Toggle with '-Dkst_release=1'
    -- kst_deploy               = OFF   : Deploy into install dir. Toggle with '-Dkst_deploy=1'
    -- kst_merge_files          = OFF   : Merge files to speedup build about factor 5. Toggle with '-Dkst_merge_files=1'
    -- kst_merge_rebuild        = OFF   : Rebuild generated files from merged files build. Toggle with '-Dkst_merge_rebuild=1'
    -- kst_verbose              = OFF   : Make verbose CMake run and Makefiles. Toggle with '-Dkst_verbose=1'
    -- kst_install_prefix       = /home/user/kst/INSTALLED   : Install path for Kst, using a default if not set. 
    -- kst_install_libdir       = lib   : Install directory name for libraries. 
    -- kst_3rdparty             = ON    : Build plugins depending on 3rd party libraries. Toggle with '-Dkst_3rdparty=0'
    -- kst_dataobjects          = ON    : Build dataobject plugins. Toggle with '-Dkst_dataobjects=0'
    -- kst_test                 = OFF   : Build unit tests. Toggle with '-Dkst_test=1'
    -- kst_pch                  = ON    : Use precompiled headers. Toggle with '-Dkst_pch=0'
    -- kst_svnversion           = ON    : Use svnversion's output for Kst's version information. Toggle with '-Dkst_svnversion=0'
    -- kst_rpath                = OFF   : Use rpath. Toggle with '-Dkst_rpath=1'
    -- kst_3rdparty_build       = OFF   : Download and build 3rd party libraries. Toggle with '-Dkst_3rdparty_build=1'
    -- kst_3rdparty_download    = OFF   : Download precompiled 3rd party libraries. Toggle with '-Dkst_3rdparty_download=1'
    -- kst_console              = OFF   : Open console on Windows. Toggle with '-Dkst_console=1'
    -- kst_edit_cont            = OFF   : Enable "Edit and Continue" for Visual Studio. Toggle with '-Dkst_edit_cont=1'
    -- kst_python               = OFF   : Install Python support. Toggle with '-Dkst_python=1'
    -- kst_python_build         = OFF   : Download and build NumPy/SciPy then install Python support. Toggle with '-Dkst_python_build=1'


	To enable a option pass the value ON or 1, eg
		cmake ../kst -Dkst_merge_files=1


Using the merged files build
-----------------------------

	When the option 'kst_merge_files' is used then for each library a files 
	is generated(merged_const.cpp) which includes all source files of this 
	library, this speeds up compilation about factor 5.

	When you heavily work on one file you could comment out the relevant 
	define in the 'merged_const.cpp' file, so only the file 'merged_touched.cpp'
	file will be re-compiled again an again.

	The CMake macro 'kst_dont_merge' is only active when the option 'kst_merge_files'
	is used. 'kst_dont_merge' prevents the adding of the listed files to the generated
	file, all listed files will be compiled separately. Sometimes this is needed because
	of too much compiler errors, and it is simpler not to merge the file.

	- Adding new files
	  When you add new files the merging files have to be rebuild:
		cmake -Dkst_merge_rebuild=1 .
	  Or start over by completely  cleaning the build folder.

	- Starting over with same configuration
	  Delete all files but CMakeCache.txt and call
		cmake .


Packaging
----------

	- Source .tar.gz, .tar.bz2, .zip:
		make package_source

	- Binary .tar.gz and install .sh:
		make package

	- Binary .deb:
		create : cpack -G DEB --config CPackConfig.cmake
		list   : dpkg-deb -c Kst-*.deb
		install: dpkg -i Kst-*.deb

	- Binary .rpm:
		create : cpack -G RPM --config CPackConfig.cmake
		list   : rpm -qlp Kst-*.rpm              
		install: rpm -U Kst-*.rpm   

	- Binary .dmg 
		make packages


Status
-------

	Kst builds, starts, and loads all plugins. Tested on Linux,
	Windows, and MacOSX.
	
	Nice to have:
	- add pre-compiled headers for Mac, Xcode



Releasing
----------

	To build a release for Windows install the "Qt SDK for Windows"
	(it ships also MinGW) and call in the folder which contains the 
	kst dir:
	
		kst\misc\mingw-release-download-deps.bat <Kst version name>
		

