/*!
@page inside_cmake Modifying the cmake files
-\section cmake_dev_guide_src How to add sources?
+\tableofcontents
-If you want modified, add or delete source files from a library you have to edit <project/directory>/buildtools/Cmake/DefinePackages.cmake.
-Chose the section you are interested in and modifie it.
+\section inside_cmake_intro Generalities on Cmake
+
+\subsection inside_cmake_what What is Cmake?
+
+CMake is a family of tools designed to build, test and package
+software. CMake is used to control the software compilation process
+using simple platform and compiler independent configuration files.
+CMake generates native makefiles and workspaces that can be used in
+the compiler environment of your choice. For more information see
+official web site <a href="http://www.cmake.org/">here</a>.
+
+\subsection inside_cmake_why Why cmake?
+
+CMake permits to developers to compile projects on different
+platforms. Then many tools are embedded like ctest for making test, a
+link to cdash for vizualise results but also test coverage and bug
+reports.
+
+\section inside_cmake_addsrc How to add source files?
+
+If you want modified, add or delete source files from a library you have to edit <project/directory>/tools/cmake/DefinePackages.cmake.
+Chose the section you are interested in and modify it.
\verbatim
set(SMPI_SRC
)
\endverbatim
-If source file are a part of an option library (like fortran smpi source) you have to had it in the compiled sources
-or in the EXTRA_DIST files package which is only copy in the dist.
+If your source is always added to the library, you are set. But if
+it's optional, you must ensure that it gets added to the source
+distribution when not compiled in, or it may well be missing if the
+archive is built without the option activating your source. This is
+done by adding the files to the EXTRA_DIST list, as in the following
+example:
+
\verbatim
-### If f2c is installed compiled source other-whise source is only copy in the dist
-if(SMPI_F2C)
+### If fortran is installed compile source other-whise source is only copied in the dist
+if(SMPI_FORTRAN)
set(SMPI_SRC
${SMPI_SRC}
src/smpi/smpi_f77.c
endif()
\endverbatim
-\section cmake_dev_guide_ex How to add examples?
+Don't forget to run the "make distcheck" target after any modification
+to the cmake files: it checks whether all necessary files are present
+in the distribution.
-If you want make an example you have to create a CMakeList.txt to the src directory.
-You must specified where to create the executable, source list, dependencies and the name of the binary.
+\section inside_cmake_examples How to add an example?
-\verbatim
-cmake_minimum_required(VERSION 2.6)
+The first rule is that the content of examples/ must be interesting to
+the users. It is expected that the users will take one of these
+examples and start editing it to make it fit their needs.
+So, it should be self-contained, informative and should use only the
+public APIs.
+
+To ensure that all examples actually work as expected, every examples
+are also used as integration test (see \ref inside_tests), but you
+should still strive to keep the code under examples/ as informative as
+possible for the users. In particular, torture test cases should be
+placed in teshsuite/, not examples/, so that the users don't stumble
+upon them by error.
+To add a new example, create a CMakeList.txt in the chosen source
+directory. It must specify where to create the executable, the source
+list, dependencies and the name of the binary.
+
+\verbatim
set(EXECUTABLE_OUTPUT_PATH "${CMAKE_CURRENT_BINARY_DIR}")
add_executable(Hello Hello.c)
)
\endverbatim
-Then you have to modified :
-\li<project/directory>/buildtools/Cmake/MakeExeLib.cmake and add line:
-\verbatim
-add_subdirectory(${CMAKE_HOME_DIRECTORY}/<path_where_is_CMakeList.txt>)
-\endverbatim
-
-\li <project/directory>/buildtools/Cmake/DefinePackages.cmake to add your CMakeLists to CMAKE_SOURCE_FILES:
+Then, you have to add your CMakeLists.txt to CMAKEFILES_TXT in <project/directory>/tools/cmake/DefinePackages.cmake:
\verbatim
-set(CMAKE_SOURCE_FILES
- CMakeLists.txt
- ....
- <path_where_is_CMakeList.txt>
+set(CMAKEFILES_TXT
+ <path_to_your_CMakeList.txt>
)
\endverbatim
-\section cmake_dev_guide_test How to add tests?
-To add a test in simgrid you have to modify source <project/directory>/buildtools/Cmake/AddTests.cmake. Create a new test with adding this line:
-\li With tesh
-\verbatim
-# ADD_TEST(test-name ${CMAKE_BINARY_DIR}/bin/tesh <options> <tesh-file>)
-# option --setenv bindir set the directory containing the binary
-# --setenv srcdir set the directory containing the source file
-# --cd set the working directory
-ADD_TEST(my-test-name ${CMAKE_BINARY_DIR}/bin/tesh
- --setenv bindir=${CMAKE_BINARY_DIR}/examples/my-test/
- --setenv srcdir=${CMAKE_HOME_DIRECTORY}/examples/my-test/
- --cd ${CMAKE_HOME_DIRECTORY}/examples/my-test/
- ${CMAKE_HOME_DIRECTORY}/examples/msg/io/io.tesh
-)
-\endverbatim
-
-\li Without tesh
-\verbatim
-# ADD_TEST(NAME <name>]
-# [WORKING_DIRECTORY dir]
-# COMMAND <command> [arg1 [arg2 ...]])
-ADD_TEST(NAME my-test-name
- WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/examples/my-test/
- COMMAND Hello
-)
-\endverbatim
+And finally, add the tesh file and register your example to the
+testing infrastructure. See \ref inside_tests_add_integration for more
+details.
+
+Once you're done, you must run "make distcheck" to ensure that you did
+not forget to add any file to the distributed archives. This ensures
+that everything was commited correctly, so you have to first commit
+before running "make distcheck". If you forgot something, you want to
+"git commit --amend". But never amend a commit that you already pushed
+to public repositories! Do a second commit in that case.
+
*/
