/*!
-@page inside_cmake Modifying the cmake files
+@page inside_cmake Adding source files or examples
-\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.
+SimGrid uses CMake which is a family of tools designed to build, test, and package software.
-\verbatim
-set(SMPI_SRC
- src/smpi/smpi_base.c
- src/smpi/smpi_bench.c
- src/smpi/smpi_c99.c
- src/smpi/smpi_coll.c
- src/smpi/smpi_comm.c
- src/smpi/smpi_global.c
- src/smpi/smpi_group.c
- src/smpi/smpi_mpi.c
- src/smpi/smpi_mpi_dt.c
- src/smpi/smpi_pmpi.c
- src/smpi/smpi_replay.c
- )
-\endverbatim
+@section inside_cmake_addsrc How to add source files?
-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.
-\verbatim
-### If f2c is installed compiled source other-whise source is only copy in the dist
-if(SMPI_F2C)
- set(SMPI_SRC
- ${SMPI_SRC}
- src/smpi/smpi_f77.c
- )
-else()
- set(EXTRA_DIST
- ${EXTRA_DIST}
- src/smpi/smpi_f77.c
- )
-endif()
-\endverbatim
+If you want to rename, add, or delete source file(s) in the SimGrid distribution, you have to edit the
+tools/cmake/DefinePackages.cmake configuration file. Files are organized in sections, then find
+the section you are interested in and modify it.
-\section cmake_dev_guide_ex How to add examples?
+Once you're done, test your changes with ``make distcheck``.
-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.
-set(EXECUTABLE_OUTPUT_PATH "${CMAKE_CURRENT_BINARY_DIR}")
+To ensure that all examples actually work as expected, every example is also used as an 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.
-add_executable(Hello Hello.c)
+The examples/ directory is organized as follows:
+ - examples/s4u/ for examples using the emerging S4U API
+ - examples/smpi/ or examples using the SMPI API
+ - examples/platforms/ only contains platforms descriptions in the XML format (see @ref platform for details)
+ - examples/deprecated/msg/ for examples using the MSG API. Here the naming convention is package-example (e.g., app-masterworker).
+ - examples/deprecated/simdag/ for examples using the SimDag API
+ - examples/deprecated/java/ for examples using the Java bindings to the MSG API. This directory contains packages (app, async,
+ cloud, ...) which in turn contain individual examples. If your new example fits in an existing package, add it here,
+ or create a new package otherwise.
-### Add definitions for compile
-target_link_libraries(Hello simgrid)
+In each of these directories, there is a CMakeLists.txt file that has
+to be edited to include the new examples.
-### You have to put all new files in the apropriated section
-### If they are not there, they can't be on the dist package.
-set(tesh_files
- ${tesh_files}
- PARENT_SCOPE
- )
-set(xml_files
- ${xml_files}
- PARENT_SCOPE
- )
-set(examples_src
- ${examples_src}
- ${CMAKE_CURRENT_SOURCE_DIR}/Hello.c
- PARENT_SCOPE
- )
-set(bin_files
- ${bin_files}
- PARENT_SCOPE
- )
-set(txt_files
- ${txt_files}
- PARENT_SCOPE
- )
-\endverbatim
+Once you're done, test your changes with ``make distcheck``.
-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:
-\verbatim
-set(CMAKE_SOURCE_FILES
- CMakeLists.txt
- ....
- <path_where_is_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
*/
