X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/8e0e64a25abdae14c8f5c6466e5f957e0ee5521d..93e627932e2b4dfb8b7b4e319a820aeda261ceb9:/doc/doxygen/inside_cmake.doc diff --git a/doc/doxygen/inside_cmake.doc b/doc/doxygen/inside_cmake.doc index 5d47cfb05d..61e85f7acc 100644 --- a/doc/doxygen/inside_cmake.doc +++ b/doc/doxygen/inside_cmake.doc @@ -1,141 +1,42 @@ /*! -@page inside_cmake Modifying the cmake files +@page inside_cmake Adding source files or examples -\tableofcontents +@tableofcontents -\section inside_cmake_intro Generalities on Cmake +SimGrid uses CMake which is a family of tools designed to build, test, and package software. -\subsection inside_cmake_what What is Cmake? +@section inside_cmake_addsrc How to add source files? -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 here. +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. -\subsection inside_cmake_why Why cmake? +Once you're done, test your changes with ``make distcheck``. -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_examples How to add an example? -\section inside_cmake_addsrc How to add source files? +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. -If you want modified, add or delete source files from a library you have to edit /tools/cmake/DefinePackages.cmake. -Chose the section you are interested in and modify it. - -\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 - -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 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 - ) -else() - set(EXTRA_DIST - ${EXTRA_DIST} - src/smpi/smpi_f77.c - ) -endif() -\endverbatim - -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. - -\section inside_cmake_examples How to add an example? - -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 +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. -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) - -### Add definitions for compile -target_link_libraries(Hello simgrid) - -### 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 - -Then, you have to add your CMakeLists.txt to CMAKEFILES_TXT in /tools/cmake/DefinePackages.cmake: -\verbatim -set(CMAKEFILES_TXT - - ) -\endverbatim +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. -And finally, add the tesh file and register your example to the -testing infrastructure. See \ref inside_tests_add_integration for more -details. +In each of these directories, there is a CMakeLists.txt file that has +to be edited to include the new examples. -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. +Once you're done, test your changes with ``make distcheck``. */