Configuring Build Options

(Difference between revisions)
Jump to: navigation, search
m
(Make targets)
(19 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Introduction==
+
On all platforms, Stellarium uses a two-step building process:
 +
* <tt>[http://www.cmake.org/ CMake]</tt> processes a set of project files (<tt>CMakeLists.txt</tt>) to generate a set of scripts for <tt>make</tt> (if you are using Qt Creator, it runs CMake when you open the project);
 +
* <tt>[http://en.wikipedia.org/wiki/Make_%28software%29 make]</tt> performs the steps detailed in the scripts, calling the compiler, the linker and other utility programs to build Stellarium's executables, libraries and data files.
  
==Configuring Build Options==
+
This page explains the various command-line options that can be passed to <tt>CMake</tt> and <tt>make</tt> to produce different build configurations.
===CMAKE_BUILD_TYPE===
+
Possible values: None, Debug, GProf, Valgrind, Release, RelWithDebInfo, MinSizeRel.
+
  
''Default value'': '''Debug'''
+
== CMake options ==
====Debug====
+
This option is enable the debug mode - binary package includes debug chars; this mode is default for developers.
+
  
====GProf====
+
CMake caches the current project configuration in <tt>CMakeCache.txt</tt>, including the options passed to it at the command line. This is useful, as it saves typing the next time you invoke CMake for the project, but it can also be annoying if you are not careful.
This option is enable support for GNU gprof profiler - binary package includes debug chars for profiler; this mode is for developers.
+
  
====Valgrind====
+
The proper way to change the options is to pass them to CMake on the command line, instead of editing directly the CMakeCache file. This way, the make files will be updated in case there is some hidden dependency on the value of the option you are passing.
This option is enable support for Valgring tool - binary package includes debug chars for memory debugging, memory leak detection, and profiling; this mode is for developers.
+
  
====Release====
+
For example, the next command is a first invocation of CMake for Stellarium that configures the build of a development version for Windows in Release mode which based on revision 5520:
This option is enable the release mode - binary package not include debug chars; this mode is default for users.
+
  cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=C:/stellarium -DCMAKE_BUILD_TYPE=Release -DRELEASE_BUILD=0 -DBZR_REVISION=5520 ../..
 
+
===CMAKE_INSTALL_PREFIX===
+
This option enable prefix for install of binary package. On Linux default location for software, building from source code, is ''/usr/local'' but if you want install software into ''/opt'' you need use ''CMAKE_INSTALL_PREFIX=/opt''
+
 
+
===CMAKE_C_COMPILER===
+
This option set custom path to C compiler. As example you have installed GCC and Clang; For using Clang compiler you need use ''CMAKE_C_COMPILER=/usr/bin/clang''
+
 
+
===CMAKE_CXX_COMPILER===
+
This option set custom path to C++ compiler. As example you have installed GCC and Clang; For using Clang compiler you need use ''CMAKE_CXX_COMPILER=/usr/bin/clang''
+
 
+
===OPTIMIZE_INTEL_ATOM===
+
''Default value'': '''0'''.
+
  
This option enable optimization for Atom processors.
+
Qt Creator provides a wrapper around CMake - the CMake Wizard. It is automatically launched when Stellarium's CMakeLists.txt is opened for the first time, and it can be launched at any time from the "Build" -> "Run CMake" menu.  
  
 
===BUILD_FOR_MAEMO===
 
===BUILD_FOR_MAEMO===
 
''Default value'': '''0'''.
 
''Default value'': '''0'''.
  
This option enable building Stellarium for Maemo devices and enable optimization for ARM processors.
+
This option enables building Stellarium for Maemo devices and also enables optimization for ARM processors.
  
===ENABLE_NLS===
+
===BUILD_STATIC_PLUGINS===
 
''Default value'': '''1'''.
 
''Default value'': '''1'''.
  
This option activate translation with gettext.
+
This option defines that plugins should be compiled statically and linked to the main program. ''If this option has value '''1''' then for BUILD_DYNAMIC_PLUGINS should be value '''0'''.''
  
===ENABLE_SOUND===
+
===BUILD_DYNAMIC_PLUGINS===
 
''Default value'': '''0'''.
 
''Default value'': '''0'''.
  
This option activate sound support.
+
This option defines that plugins should be compiled dynamically. ''If this option has value '''1''' then for BUILD_STATIC_PLUGINS should be value '''0'''.''
  
===ENABLE_SCRIPTING===
+
===BZR_REVISION===
''Default value'': '''1'''.
+
This option is used together with [[#RELEASE_BUILD|RELEASE_BUILD]] option and sets Bazaar's revision for package.
  
This option activate scripting feature.
+
===CMAKE_BUILD_TYPE===
 +
Possible values: None, Debug, GProf, Valgrind, Release, RelWithDebInfo, MinSizeRel.
  
===ENABLE_SCRIPT_CONSOLE===
+
''Default value'': '''Debug'''
''Default value'': '''1'''.
+
  
This option activate the script edit console.
+
Possible values:
 +
;Release:Release mode - the binary package does not include debug characters and some of the source code is ignored; this mode is the default for users.
 +
;Debug:Debug mode - the binary package includes debug characters and debug macros in the source code are not ignored; this mode is the default for developers.
 +
;RelWithDebInfo:Release mode, but the binary package includes debug characters; this mode is for developers and users.
 +
;GProf:Support for GNU gprof profiler - binary package includes debug characters for profiler; this mode is for developers
 +
;Valgrind:Support for Valgrind - binary package includes debug characters for memory debugging, memory leak detection, and profiling; this mode is for developers.
 +
;MinSizeRel:Release mode - binary package optimized for minimal size.
  
===ENABLE_STRATOSCRIPT_COMPAT===
+
===CMAKE_INSTALL_PREFIX===
''Default value'': '''0'''.
+
This option sets a prefix for the installation of the binary package location. Used on Linux to set the location for the software installation, building from source code, the default location is ''/usr/local'' but if you want to install software elsewhere such as into ''/opt'' you need use ''CMAKE_INSTALL_PREFIX=/opt''
  
This option enable the StratoScript compatibility mode.
+
===CMAKE_C_COMPILER===
 +
This option sets a custom path to C compiler. For example if you have installed GCC and Clang; and wish to use the  Clang compiler you need use ''CMAKE_C_COMPILER=/usr/bin/clang''
  
 +
===CMAKE_CXX_COMPILER===
 +
This option sets a custom path to the C++ compiler. For example; if you have installed GCC and Clang; to use the Clang compiler you need use ''CMAKE_CXX_COMPILER=/usr/bin/clang''
  
===RELEASE_BUILD===
+
===ENABLE_NLS===
 
''Default value'': '''1'''.
 
''Default value'': '''1'''.
  
This option flag this build as an official release.
+
This option activates translation with gettext.
  
===BZR_REVISION===
+
===ENABLE_SOUND===
This option used together with RELEASE_BUILD option and set Bazaar's revision for package.
+
 
+
===BUILD_STATIC_PLUGINS===
+
''Default value'': '''1'''.
+
 
+
This option define that plugins should be compiled statically and linked to the main program. ''If this option has value '''1''' then for BUILD_DYNAMIC_PLUGINS should be value '''0'''.''
+
 
+
===BUILD_DYNAMIC_PLUGINS===
+
 
''Default value'': '''0'''.
 
''Default value'': '''0'''.
  
This option define that plugins should be compiled dynamically. ''If this option has value '''1''' then for BUILD_STATIC_PLUGINS should be value '''0'''.''
+
This option activates sound support.The default value is 0 because sound is not available on all platforms and may require 3rd party software.
  
===USE_PLUGIN_HELLOSTELMODULE===
+
===ENABLE_SCRIPTING===
''Default value'': '''0'''.
+
 
+
This option define that the HelloStelModule plugin should be built.
+
 
+
===USE_PLUGIN_ANGLEMEASURE===
+
 
''Default value'': '''1'''.
 
''Default value'': '''1'''.
  
This option define that the Angle Measure plugin should be built.
+
This option activates the scripting feature.
  
===USE_PLUGIN_COMPASSMARKS===
+
===ENABLE_SCRIPT_CONSOLE===
 
''Default value'': '''1'''.
 
''Default value'': '''1'''.
  
This option define that the Compass Marks plugin should be built.
+
This option activates the script edit console.
  
===USE_PLUGIN_SATELLITES===
+
===ENABLE_STRATOSCRIPT_COMPAT===
''Default value'': '''1'''.
+
 
+
This option define that the Satellites plugin should be built.
+
 
+
===USE_PLUGIN_TELESCOPECONTROL===
+
''Default value'': '''1'''.
+
 
+
This option define that the Telescope Control plugin should be built.
+
 
+
===USE_PLUGIN_LOGBOOK===
+
 
''Default value'': '''0'''.
 
''Default value'': '''0'''.
  
This option define that the LogBook plugin should be built.
+
This option enable the StratoScript compatibility mode. If set to 1 many of the old *.sts scripts can be used.
  
===USE_PLUGIN_OCULARS===
+
===GUI_MODE===
''Default value'': '''1'''.
+
Possible values: Standard, None, External
  
This option define that the Oculars plugin should be built.
+
''Default value'': '''Standard'''.
  
===USE_PLUGIN_SVMT===
+
This option set a type of GUI for using in Stellarium.
''Default value'': '''0'''.
+
  
This option define that the SVMT plugin should be built.
+
===OPENGL_MODE===
 +
Possible values: Desktop, ES2
  
===USE_PLUGIN_TEXTUSERINTERFACE===
+
''Default value'': '''Desktop'''.
''Default value'': '''1'''.
+
  
This option define that the Text User Interface plugin should be built.
+
This option defines mode to supporting OpenGL version - OpenGL for desktops or OpenGL ES
  
===USE_PLUGIN_TIMEZONECONFIGURATION===
+
===OPTIMIZE_INTEL_ATOM===
''Default value'': '''1'''.
+
 
+
This option define that the Time Zone Configuration plugin should be built.
+
 
+
===USE_PLUGIN_VIRGO===
+
 
''Default value'': '''0'''.
 
''Default value'': '''0'''.
  
This option define that the VirGO plugin should be built.
+
This option enables optimization for Atom processors.
  
===USE_PLUGIN_SOLARSYSTEMEDITOR===
+
===RELEASE_BUILD===
 
''Default value'': '''1'''.
 
''Default value'': '''1'''.
  
This option define that the Solar System Editor plugin should be built.
+
This option flags the build as an official release.
  
===USE_PLUGIN_SUPERNOVAE===
+
===STELLARIUM_SPLASH===
''Default value'': '''1'''.
+
Possible values: Development, ReleaseCandidate, Release
  
This option define that the Historical Supernovae plugin should be built.
+
''Default value'': '''Development'''.
  
===USE_PLUGIN_QUASARS===
+
This option set the splash screen for Stellarium.
''Default value'': '''1'''.
+
  
This option define that the Quasars plugin should be built.
+
===USE_PLUGIN_*===
 +
These options control whether the given plugin is built. For example to build the Historical Supernovae plugin you need use ''USE_PLUGIN_SUPERNOVAE=1''.
  
===USE_PLUGIN_PULSARS===
+
;USE_PLUGIN_HELLOSTELMODULE: (Default value: '''0''') The Hello StelModule example plugin.
''Default value'': '''1'''.
+
;USE_PLUGIN_ANGLEMEASURE: (Default value: '''1''') The Angle Measure plugin.
 +
;USE_PLUGIN_COMPASSMARKS: (Default value: '''1''') The Compass Marks plugin.
 +
;USE_PLUGIN_SATELLITES: (Default value: '''1''') The Satellites plugin.
 +
;USE_PLUGIN_TELESCOPECONTROL: (Default value: '''1''') The Telescope Control plugin.
 +
;USE_PLUGIN_LOGBOOK: (Default value: '''0''') The Logbook plugin - unfinished, development suspended indefinitely.
 +
;USE_PLUGIN_OCULARS: (Default value: '''1''') The Oculars plugin.
 +
;USE_PLUGIN_SVMT: (Default value: '''0''') The [https://launchpad.net/svmt Survey Monitoring and Visualization Tool], a plug-in for professional astronomers developed separately from Stellarium. (I.e. its code is not in the main repository.)
 +
;USE_PLUGIN_TEXTUSERINTERFACE: (Default value: '''1''') The Text User Interface plugin.
 +
;USE_PLUGIN_TIMEZONECONFIGURATION: (Default value: '''1''') The Time Zone plugin.
 +
;USE_PLUGIN_VIRGO: (Default value: '''0''') [https://launchpad.net/virgo VirGO], a plug-in for professional astronomers developed separately from Stellarium. (I.e. its code is not in the main repository.)
 +
;USE_PLUGIN_SOLARSYSTEMEDITOR: (Default value: '''1''') The Solar System Editor plugin.
 +
;USE_PLUGIN_SUPERNOVAE: (Default value: '''1''') The Historical Supernovae plugin.
 +
;USE_PLUGIN_QUASARS: (Default value: '''1''') The Quasars plugin.
 +
;USE_PLUGIN_PULSARS: (Default value: '''1''') The Pulsars plugin.
 +
;USE_PLUGIN_EXOPLANETS: (Default value: '''1''') The Exoplanets plugin.
  
This option define that the Pulsars plugin should be built.
+
==Make targets==
  
===USE_PLUGIN_EXOPLANETS===
+
Make groups various tasks as "targets". Starting <code>make</code> without any arguments causes make to build the default target - in our case, building Stellarium, its tests, the localization files, etc.
''Default value'': '''1'''.
+
  
This option define that the Exoplanets plugin should be built.
+
To list all possible targets, use the "help" target:
 
+
make help
===OPENGL_MODE===
+
Possible values: Desktop, ES2
+
 
+
''Default value'': '''Desktop'''.
+
  
This option define mode to supporting OpenGL version - OpenGL for desktops or OpenGL ES
+
Other useful targets:
  
==Build Options==
+
make install
 +
Installation of all binaries and related files to the directory determined by [[#CMAKE_INSTALL_PREFIX|CMAKE_INSTALL_PREFIX]]. Straight installation on Linux, first step of creating an installer package on Windows.
 +
 +
make test
 +
Launch the suite of test executables.
 +
 +
make macosx_bundle
 +
Package a bundle for Mac OS X.
  
 +
make package
 +
This option make package for Linux.
  
 
[[Category: Development]]
 
[[Category: Development]]
 
[[Category: Customization]]
 
[[Category: Customization]]

Revision as of 15:54, 28 October 2012

On all platforms, Stellarium uses a two-step building process:

  • CMake processes a set of project files (CMakeLists.txt) to generate a set of scripts for make (if you are using Qt Creator, it runs CMake when you open the project);
  • make performs the steps detailed in the scripts, calling the compiler, the linker and other utility programs to build Stellarium's executables, libraries and data files.

This page explains the various command-line options that can be passed to CMake and make to produce different build configurations.

Contents

CMake options

CMake caches the current project configuration in CMakeCache.txt, including the options passed to it at the command line. This is useful, as it saves typing the next time you invoke CMake for the project, but it can also be annoying if you are not careful.

The proper way to change the options is to pass them to CMake on the command line, instead of editing directly the CMakeCache file. This way, the make files will be updated in case there is some hidden dependency on the value of the option you are passing.

For example, the next command is a first invocation of CMake for Stellarium that configures the build of a development version for Windows in Release mode which based on revision 5520:

 cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=C:/stellarium -DCMAKE_BUILD_TYPE=Release -DRELEASE_BUILD=0 -DBZR_REVISION=5520 ../..

Qt Creator provides a wrapper around CMake - the CMake Wizard. It is automatically launched when Stellarium's CMakeLists.txt is opened for the first time, and it can be launched at any time from the "Build" -> "Run CMake" menu.

BUILD_FOR_MAEMO

Default value: 0.

This option enables building Stellarium for Maemo devices and also enables optimization for ARM processors.

BUILD_STATIC_PLUGINS

Default value: 1.

This option defines that plugins should be compiled statically and linked to the main program. If this option has value 1 then for BUILD_DYNAMIC_PLUGINS should be value 0.

BUILD_DYNAMIC_PLUGINS

Default value: 0.

This option defines that plugins should be compiled dynamically. If this option has value 1 then for BUILD_STATIC_PLUGINS should be value 0.

BZR_REVISION

This option is used together with RELEASE_BUILD option and sets Bazaar's revision for package.

CMAKE_BUILD_TYPE

Possible values: None, Debug, GProf, Valgrind, Release, RelWithDebInfo, MinSizeRel.

Default value: Debug

Possible values:

Release
Release mode - the binary package does not include debug characters and some of the source code is ignored; this mode is the default for users.
Debug
Debug mode - the binary package includes debug characters and debug macros in the source code are not ignored; this mode is the default for developers.
RelWithDebInfo
Release mode, but the binary package includes debug characters; this mode is for developers and users.
GProf
Support for GNU gprof profiler - binary package includes debug characters for profiler; this mode is for developers
Valgrind
Support for Valgrind - binary package includes debug characters for memory debugging, memory leak detection, and profiling; this mode is for developers.
MinSizeRel
Release mode - binary package optimized for minimal size.

CMAKE_INSTALL_PREFIX

This option sets a prefix for the installation of the binary package location. Used on Linux to set the location for the software installation, building from source code, the default location is /usr/local but if you want to install software elsewhere such as into /opt you need use CMAKE_INSTALL_PREFIX=/opt

CMAKE_C_COMPILER

This option sets a custom path to C compiler. For example if you have installed GCC and Clang; and wish to use the Clang compiler you need use CMAKE_C_COMPILER=/usr/bin/clang

CMAKE_CXX_COMPILER

This option sets a custom path to the C++ compiler. For example; if you have installed GCC and Clang; to use the Clang compiler you need use CMAKE_CXX_COMPILER=/usr/bin/clang

ENABLE_NLS

Default value: 1.

This option activates translation with gettext.

ENABLE_SOUND

Default value: 0.

This option activates sound support.The default value is 0 because sound is not available on all platforms and may require 3rd party software.

ENABLE_SCRIPTING

Default value: 1.

This option activates the scripting feature.

ENABLE_SCRIPT_CONSOLE

Default value: 1.

This option activates the script edit console.

ENABLE_STRATOSCRIPT_COMPAT

Default value: 0.

This option enable the StratoScript compatibility mode. If set to 1 many of the old *.sts scripts can be used.

GUI_MODE

Possible values: Standard, None, External

Default value: Standard.

This option set a type of GUI for using in Stellarium.

OPENGL_MODE

Possible values: Desktop, ES2

Default value: Desktop.

This option defines mode to supporting OpenGL version - OpenGL for desktops or OpenGL ES

OPTIMIZE_INTEL_ATOM

Default value: 0.

This option enables optimization for Atom processors.

RELEASE_BUILD

Default value: 1.

This option flags the build as an official release.

STELLARIUM_SPLASH

Possible values: Development, ReleaseCandidate, Release

Default value: Development.

This option set the splash screen for Stellarium.

USE_PLUGIN_*

These options control whether the given plugin is built. For example to build the Historical Supernovae plugin you need use USE_PLUGIN_SUPERNOVAE=1.

USE_PLUGIN_HELLOSTELMODULE
(Default value: 0) The Hello StelModule example plugin.
USE_PLUGIN_ANGLEMEASURE
(Default value: 1) The Angle Measure plugin.
USE_PLUGIN_COMPASSMARKS
(Default value: 1) The Compass Marks plugin.
USE_PLUGIN_SATELLITES
(Default value: 1) The Satellites plugin.
USE_PLUGIN_TELESCOPECONTROL
(Default value: 1) The Telescope Control plugin.
USE_PLUGIN_LOGBOOK
(Default value: 0) The Logbook plugin - unfinished, development suspended indefinitely.
USE_PLUGIN_OCULARS
(Default value: 1) The Oculars plugin.
USE_PLUGIN_SVMT
(Default value: 0) The Survey Monitoring and Visualization Tool, a plug-in for professional astronomers developed separately from Stellarium. (I.e. its code is not in the main repository.)
USE_PLUGIN_TEXTUSERINTERFACE
(Default value: 1) The Text User Interface plugin.
USE_PLUGIN_TIMEZONECONFIGURATION
(Default value: 1) The Time Zone plugin.
USE_PLUGIN_VIRGO
(Default value: 0) VirGO, a plug-in for professional astronomers developed separately from Stellarium. (I.e. its code is not in the main repository.)
USE_PLUGIN_SOLARSYSTEMEDITOR
(Default value: 1) The Solar System Editor plugin.
USE_PLUGIN_SUPERNOVAE
(Default value: 1) The Historical Supernovae plugin.
USE_PLUGIN_QUASARS
(Default value: 1) The Quasars plugin.
USE_PLUGIN_PULSARS
(Default value: 1) The Pulsars plugin.
USE_PLUGIN_EXOPLANETS
(Default value: 1) The Exoplanets plugin.

Make targets

Make groups various tasks as "targets". Starting make without any arguments causes make to build the default target - in our case, building Stellarium, its tests, the localization files, etc.

To list all possible targets, use the "help" target:

make help

Other useful targets:

make install

Installation of all binaries and related files to the directory determined by CMAKE_INSTALL_PREFIX. Straight installation on Linux, first step of creating an installer package on Windows.

make test

Launch the suite of test executables.

make macosx_bundle

Package a bundle for Mac OS X.

make package

This option make package for Linux.

Personal tools
Namespaces
Variants
Actions
in this wiki
other languages
Toolbox