dev/cmake/source/intro.rst

   1 Introduction
   2 ============
   3 CMake is a configuration tool generating the build chain (e.g. Makefiles on Linux)
   4 of a software project.
   5 This documentation describes the goals and the good practices to be applied when writing
   6 the CMake files for the configuration of a SALOME module.
   7
   8 This documentation is best browsed with the SALOME KERNEL's sources at hand, in order to be able to
   9 take a look at code snipets. Most references in this document points to KERNEL sources.
  10
  11 The section marked as ADVANCED need not be read by someone only trying to compile SALOME. Those
  12 sections are intented to the core SALOME developers, to help them understand/fix/improve
  13 the process.
  14
  15 Motivations and overview
  16 ========================
  17
  18 CMake must be user-friendly
  19 ---------------------------
  20
  21 Every beginner should be able to build SALOME, without any previous knowledge of SALOME.
  22 With a tool like cmake-gui or ccmake, the user must obtain useful messages to find what is wrong or missing.
  23
  24 The general philosophy is thus to allow a developper to build SALOME with a minimal effort, setting only the
  25 minimal set of variables (via the command line or the environment).
  26
  27 Basic usage
  28 -----------
  29 Once the sources have been retrieved (via a clone of the repository or an extraction of the tarball)
  30 one typically:
  31
  32 * creates a dedicated build directory, e.g. KERNEL_BUILD.
  33 * switches to it, and invoke the ccmake (or cmake-gui) command::
  34
  35     cd KERNEL_BUILD
  36     ccmake ../KERNEL_SRC
  37
  38 * sets all the xyz_ROOT_DIR to point to the root paths of the package <xyz>.
  39 * sets the installation directory in the variable CMAKE_INSTALL_PREFIX.
  40 * generates the build files (hiting 'g' under ccmake).
  41 * invokes the make command in the usual way::
  42
  43     make
  44     make install
  45
  46 * if you see an error complaining that the package was not found, double check that the XYZ_ROOT_DIR variable was correctly set, and delete everything in your build directory before retrying::
  47
  48     cd KERNEL_BUILD
  49     rm -rf *
  50     ccmake ../KERNEL_SRC
  51
  52 If you want to use a specific Python installation to configure and build SALOME, you should ensure that:
  53
  54 * the interpreter is in your path.
  55 * the variables LD_LIBRARY_PATH (PATH under Windows) and PYTHONPATH are properly pointing to the desired Python installation.
  56
  57 Variable reference
  58 ------------------
  59
  60 The following list indicates the expected variables for each module. They can be specified on the CMake command line (with the -D flag) or in the environment.
  61
  62 KERNEL module:
  63
  64 * LIBBATCH_ROOT_DIR: LibBatch package - already uses Python, Swig and PThread
  65 * PYTHON_ROOT_DIR: Python package
  66 * PTHREAD_ROOT_DIR: PThread package - typically not need on Unix systems
  67 * SWIG_ROOT_DIR: SWIG package
  68 * LIBXML2_ROOT_DIR: LibXml2 package
  69 * HDF5_ROOT_DIR: HDF5 package - if HDF5 was compiled with MPI support, the corresponding MPI root directory will be exposed automatically (no need to set MPI_ROOT_DIR)
  70 * BOOST_ROOT_DIR: Boost package
  71 * OMNIORB_ROOT_DIR: OmniORB package
  72 * OMNIORBPY_ROOT_DIR: OmniORB Python backend - if not given, OMNIORB_ROOT_DIR will be tried
  73 * MPI_ROOT_DIR: MPI package (see HDF5_ROOT_DIR above)
  74 * CPPUNIT_ROOT_DIR: CppUnit package
  75 * DOXYGEN_ROOT_DIR: Doxygen package
  76 * GRAPHVIZ_ROOT_DIR: Graphviz package
  77 * SPHINX_ROOT_DIR: Sphinx package - requires setuptools and docutils to work properly.
  78 * SETUPTOOLS_ROOT_DIR: Setuptools package. This package is not detected explicitly in the KERNEL, but the path is used to complete the PYTHON path given to Sphinx.
  79 * DOCUTILS_ROOT_DIR: Docutils package. This package is not detected explicitly in the KERNEL, but the path is used to complete the PYTHON path given to Sphinx.
  80
  81 GUI module - on top of some of the KERNEL prerequisites, the following variables are used:
  82
  83 * VTK_ROOT_DIR: VTK package. If not given, PARAVIEW_ROOT_DIR is used to look for a VTK installation inside the ParaView installation
  84 * (optional) PARAVIEW_ROOT_DIR: see above
  85 * CAS_ROOT_DIR: Cascade package
  86 * SIP_ROOT_DIR: SIP package
  87 * QT4_ROOT_DIR: Qt4 package (only some components are loaded)
  88 * PYQT4_ROOT_DIR: PyQt4 package
  89 * QWT_ROOT_DIR: Qwt package
  90 * OPENGL_ROOT_DIR: OpenGL package
  91
  92 FIELDS module - on top of some of the KERNEL and GUI prerequisites, the following variables are used:
  93
  94 * MEDFILE_ROOT_DIR: MEDFile package
  95 * METIS_ROOT_DIR (optional): Metis package
  96 * PARMETIS_ROOT_DIR (optional): ParMetis package
  97 * SCOTCH_ROOT_DIR (optional): Scotch package
  98
  99 PARAVIS module - on top of some of the KERNEL, GUI and FIELDS prerequisites, the following variables are used:
 100
 101 * PARAVIEW_ROOT_DIR: ParaView package
 102 * at present for a proper build of PARAVIS, the env variables LD_LIBRARY_PATH and PYTHONPATH should be set to contain the HDF5 and ParaView libraries. This is required since the configuration process itself uses a Python script in which the environment is not overriden::
 103
 104     # Paravis compilation needs ParaView (and hence HDF5) in the Python path:
 105     export PYTHONPATH=$PARAVIEW_ROOT_DIR/lib/paraview-3.98/site-packages:$PARAVIEW_ROOT_DIR/lib/paraview-3.98:$PYTHONPATH
 106     export LD_LIBRARY_PATH=$PARAVIEW_ROOT_DIR/lib/paraview-3.98:$HDF5_ROOT_DIR/lib:$LD_LIBRARY_PATH
 107
 108
 109
 110 Overview of the logic (advanced)
 111 --------------------------------
 112
 113 Here are the general principles guiding the implementation:
 114
 115 * Only taking into account the first order prerequisites of a module should be required.
 116   For instance, CASCADE uses Tbb :
 117
 118   * CASCADE is a prerequisite of first order (level 1) of GUI,
 119   * Tbb is a prerequisite of second order (level 2) of GUI,
 120   * GUI CMake files must reference explicitly CASCADE, but never Tbb. The detection logic of CASCADE should make sure Tbb gets included.
 121
 122 * Being able to use different versions/installations of the same product, in the system, or generated by the user.
 123   For instance, using the system python 2.7, or a user-compiled python 2.6.
 124 * The detection of prerequisites is driven by user options.
 125   For example MPI is detected only if option SALOME_USE_MPI is ON.
 126 *       Detection of first order prerequisites is based on a <Product>_ROOT_DIR variable or on what has been detected in another   dependency. For example if both HDF5 and MPI are needed by the current module, we try to detect with which MPI installation HDF5 was compiled, and to offer this one as a default choice for the package itself. Other variables (PATH, LD_LIBRARY_PATH, PYTHONPATH) should never be needed at compile time.
 127 * The only exception to the previous point is Python, which is so central to the process that we assume that LD_LIBRARY_PATH and PYTHONPATH are already correctly pointing to the correct Python installation.
 128 * Trying as much as possible to detect potential conflict, and warn the user:
 129
 130   * if the package was detected at a place different from what was specified in XYZ_ROOT_DIR
 131   * if there is a conflict between what was explicitly set in XYZ_ROOT_DIR, and what was previously used in a dependency
 132
 133
 134