doc/doxygen/inside_cmake.doc

   1 /*!
   2 @page inside_cmake Modifying the cmake files
   3
   4 \tableofcontents
   5
   6 \section inside_cmake_intro Generalities on Cmake
   7
   8 \subsection inside_cmake_what What is Cmake?
   9
  10 CMake is a family of tools designed to build, test and package
  11 software. CMake is used to control the software compilation process
  12 using simple platform and compiler independent configuration files.
  13 CMake generates native makefiles and workspaces that can be used in
  14 the compiler environment of your choice. For more information see
  15 official web site <a href="http://www.cmake.org/">here</a>.
  16
  17 \subsection inside_cmake_why Why cmake?
  18
  19 CMake permits to developers to compile projects on different
  20 platforms. Then many tools are embedded like ctest for making test, a
  21 link to cdash for vizualise results but also test coverage and bug
  22 reports.
  23
  24 \section inside_cmake_addsrc How to add source files?
  25
  26 If you want modified, add or delete source files from a library you have to edit <project/directory>/tools/cmake/DefinePackages.cmake.
  27 Chose the section you are interested in and modify it.
  28
  29 \verbatim
  30 set(SMPI_SRC
  31   src/smpi/smpi_base.c
  32   src/smpi/smpi_bench.c
  33   src/smpi/smpi_c99.c
  34   src/smpi/smpi_coll.c
  35   src/smpi/smpi_comm.c
  36   src/smpi/smpi_global.c
  37   src/smpi/smpi_group.c
  38   src/smpi/smpi_mpi.c
  39   src/smpi/smpi_mpi_dt.c
  40   src/smpi/smpi_pmpi.c
  41   src/smpi/smpi_replay.c
  42   )
  43 \endverbatim
  44
  45 If your source is always added to the library, you are set. But if
  46 it's optional, you must ensure that it gets added to the source
  47 distribution when not compiled in, or it may well be missing if the
  48 archive is built without the option activating your source. This is
  49 done by adding the files to the EXTRA_DIST list, as in the following
  50 example:
  51
  52 \verbatim
  53 ### If fortran is installed compile source other-whise source is only copied in the dist
  54 if(SMPI_FORTRAN)
  55   set(SMPI_SRC
  56     ${SMPI_SRC}
  57     src/smpi/smpi_f77.c
  58     )
  59 else()
  60   set(EXTRA_DIST
  61     ${EXTRA_DIST}
  62     src/smpi/smpi_f77.c
  63   )
  64 endif()
  65 \endverbatim
  66
  67 Don't forget to run the "make distcheck" target after any modification
  68 to the cmake files: it checks whether all necessary files are present
  69 in the distribution.
  70
  71 \section inside_cmake_examples How to add an example?
  72
  73 The first rule is that the content of examples/ must be interesting to
  74 the users. It is expected that the users will take one of these
  75 examples and start editing it to make it fit their needs.
  76 So, it should be self-contained, informative and should use only the
  77 public APIs.
  78
  79 To ensure that all examples actually work as expected, every examples
  80 are also used as integration test (see \ref inside_tests), but you
  81 should still strive to keep the code under examples/ as informative as
  82 possible for the users. In particular, torture test cases should be
  83 placed in teshsuite/, not examples/, so that the users don't stumble
  84 upon them by error.
  85
  86 To add a new example, create a CMakeList.txt in the chosen source
  87 directory. It must specify where to create the executable, the source
  88 list, dependencies and the name of the binary.
  89
  90 \verbatim
  91 set(EXECUTABLE_OUTPUT_PATH "${CMAKE_CURRENT_BINARY_DIR}")
  92
  93 add_executable(Hello Hello.c)
  94
  95 ### Add definitions for compile
  96 target_link_libraries(Hello simgrid)
  97
  98 ### You have to put all new files in the apropriated section
  99 ### If they are not there, they can't be on the dist package.
 100 set(tesh_files
 101   ${tesh_files}
 102   PARENT_SCOPE
 103   )
 104 set(xml_files
 105   ${xml_files}
 106   PARENT_SCOPE
 107   )
 108 set(examples_src
 109   ${examples_src}
 110   ${CMAKE_CURRENT_SOURCE_DIR}/Hello.c
 111   PARENT_SCOPE
 112   )
 113 set(bin_files
 114   ${bin_files}
 115   PARENT_SCOPE
 116   )
 117 set(txt_files
 118   ${txt_files}
 119   PARENT_SCOPE
 120   )
 121 \endverbatim
 122
 123 Then, you have to follow these steps:
 124 \li Add the following line to <project/directory>/tools/cmake/MakeExe.cmake:
 125 \verbatim
 126 add_subdirectory(${CMAKE_HOME_DIRECTORY}/<path_where_is_CMakeList.txt>)
 127 \endverbatim
 128
 129 \li Add your CMakeLists.txt to CMAKE_SOURCE_FILES in <project/directory>/tools/cmake/DefinePackages.cmake:
 130 \verbatim
 131 set(CMAKE_SOURCE_FILES
 132   CMakeLists.txt
 133   ....
 134   <path_to_your_CMakeList.txt>
 135   )
 136 \endverbatim
 137
 138 \li Add the tesh file and register your example to the testing
 139   infrastructure. See \ref inside_tests_add_integration for more
 140   details.
 141
 142 Once you're done, you must run "make distcheck" to ensure that you did
 143 not forget to add any file to the distributed archives.
 144
 145
 146 */