X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/3c7450bff529a5c4dfef6fef1f379119950e1f74..72ce071e25e2cc2626355a11d3e1088853343bfe:/doc/doxygen/inside.doc diff --git a/doc/doxygen/inside.doc b/doc/doxygen/inside.doc index 19284c0669..a5c25914f8 100644 --- a/doc/doxygen/inside.doc +++ b/doc/doxygen/inside.doc @@ -1,92 +1,148 @@ -/*! @page inside SimGrid Developer Guide - -This page does not exist yet, sorry. We are currently refurbishing the -user documentation -- the internal documentation will follow (FIXME). - -There is two main things you want to know about the internals of -SimGrid. First, you need to understand the component organization, as -SimGrid is heavily layered, with each level being rather highly -specialized and optimized toward a task. For that, please keep reading -this page. If you work actively on the SimGrid project, the second -point you need to understand is about the infrastructure of the -SimGrid project, ie how to extend the framework in any way, how the +/*! @page uhood_tech Coding Standard and Technical Considerations + +This page describes the software infrastructure behind the SimGrid +project. This is not the components' organisation (described in @ref +uhood_arch) but informations on how to extend the framework, how the automatic tests are run, and so on. These informations are split on several pages, as follows: + - @ref uhood_tech_inside - @subpage inside_tests - @subpage inside_doxygen - @subpage inside_extending - @subpage inside_cmake - @subpage inside_release +@section uhood_tech_inside Insiders Considerations + +@subsection uhood_tech_inside_config Extra configuration + +The default build configuration of SimGrid fits the user needs, but +they are not adapted to the ones actually working on SimGrid. See @ref +install_src_config for more information. Note that this is very +different from runtime configuration. + +In particular, the build is configured by default to produce highly +optimized binaries, at the price of high compilation time. The +rationale is that users will compile SimGrid only once, and use it many +times. This is exactly the contrary for the insiders, so you want to +turn off \b enable_compile_optimizations. + +Symmetrically, \b enable_compile_warnings is off for the users because +we don't want to bother them with compiler warnings (that abort the +build in SimGrid), but any insider must turn this option on, or your +code will be refused from the main repository. + +@verbatim + cmake -Denable_compile_optimizations=OFF \ + -Denable_compile_warnings=ON . +@endverbatim + +@subsection uhood_tech_inside_commit Interacting with git + +During the Gran Refactoring to SimGrid4, things are evolving rather +quickly, and some changes impact a large amount of files. You should +thus not have long-standing branches, because they will rot very +quickly and you will suffer to merge them back. Instead, you should +work as much as possible with incremental changes that do not break +things, and get them directly in master. + +Your commit message should follow the git habits, explained in this +blog +post, or in the + +git styleguide of Atom. + + +@subsection uhood_tech_inside_codstand Automatically Enforcing our Coding Standards + +If you plan to commit code to the SimGrid project, you definitely need +to install the relevant tool to ensure that your changes follow our +coding standards: + +@verbatim +# install clang-format +sudo apt-get install clang-format-3.9 # debian + +# tell git to call the script on each commit +ln -s $(realpath tools/git-hooks/clang-format.pre-commit) .git/hooks/pre-commit +@endverbatim + +This will add an extra verification before integrating any commit that +you could prepare. If your code does not respects our formating code, +git will say so, and provide a ready to use patch that you can apply +to improve your commit. Just carefully read the error message you get +to find the exact command with git-apply to fix your formating. + +If you find that for a specific commit, the formatter does a very bad +job, then add --no-verify to your git commit command line. + +@subsection uhood_tech_tricks Random Tricks + +Over the years, we accumulated a few tricks that make it easier to +work with SimGrid. Here is a somewhat unsorted list of such tricks. + +### Easy testing + +Launching all tests can be very time consuming, so you want to build +and run the tests in parallel. Also, you want to save the build output +to disk, for further reference. This is exactly what the +BuildSimGrid.sh script does. It is upper-cased so that the shell +completion works and allow to run it in 4 key press: `./B` + +Note that if you build out of tree (as you should, see below), the +script builds the build/default directory. I usually copy the file in +each build/ subdir to test each of them separately. + +### Easy out of tree builds + +It is easy to break one build configuration or another. That's +perfectly OK and we will not point fingers if it happens. But it is +somewhat forbidden to leave the tree broken for more than one working +day. Monitor the build daemons after you push something, and strive to +fix any breakage ASAP. + +To easily switch between the configs without rebuilding everything, +create a set of out of tree builds (as explained in @ref +install_cmake_outsrc) in addition to your main build tree. +To not mess with git, you want to put your build tree under the build/ +directory, which is ignored by git. For example, I have the following +directories: build/clang build/java build/full +(but YMMV). + +Then, the problem is that when you traverse these directories, you +cannot edit the sources (that are in the srcdir, while you're in +bindir). This makes it difficult to launch the tests and everything. + +To solve that issue, just call `make hardlinks` from your build dir. +This will create hard links allowing to share every source files into +the build dir. They are not copied, but hard linked. It means that +each file is accessible under several names, from the srcdir and from +the bindirs. If you edit a source file found under bindir, the srcdir +version (visible to git) will also be changed (that's the same file, +after all). + +Note that the links sometimes broken by git or others. Relaunching +`make hardlinks` may help if you're getting incoherent build results. + +### Unsorted hints + +* If you want to debug memory allocation problems, here are a few hints: + - disable compiler optimizations, to have better backtraces; + - disable the mallocators, or it will be hard to match malloc's with free's; + - disable model checking, unless your problem lies in the model + checker part of SimGrid (MC brings its own malloc implementation, + which valgrind does not really love). + All this is configured with: + + cmake -Denable_model-checking=OFF + -Denable_mallocators=OFF + -Denable_compile_optimizations=OFF . + +* If you break the logs, you want to define XBT_LOG_MAYDAY at the + beginning of log.h. It deactivates the whole logging mechanism, + switching to printfs instead. SimGrid becomes incredibly verbose + when doing so, but it you let you fixing things. -\htmlonly - -\endhtmlonly -\htmlinclude simgrid_modules.map -\htmlonly -
SimGrid Components (click to jump to API) - -\endhtmlonly - - -\section ug_overview Overview of the toolkit components - - -\subsection ug_overview_envs Programmation environments layer - -SimGrid provides several programmation environments built on top of a unique -simulation kernel. Each environment targets a specific audiance and -constitutes a different paradigm. To choose which of them you want to use, -you have to think about what you want to do and what would be the result of -your work. - - - If you want to study a theoritical problem and compare several - heuristics, you probably want to try \ref MSG_API (yet another - historical name). It was designed exactly to that extend and should allow - you to build easily rather realistic multi-agents simulation. Yet, - realism is not the main goal of this environment and the most annoying - technical issues of real platforms are masked here. Check the \ref - MSG_API section for more information. - - - If you want to study the behaviour of a MPI application using emulation - technics, you should have a look at the \ref SMPI_API (Simulated - MPI) programming environment. Unfortunately, this work is still underway. - Check the \ref SMPI_API section for more information. - -If your favorite programming environment/model is not there (BSP, -components, OpenMP, etc.) is not represented in the SimGrid toolkit yet, you may -consider adding it. You should contact us first on the -SimGrid -developers mailing list, though. - -\subsection ug_overview_kernel Simulation kernel layer - -The core functionnalities to simulate a virtual platform are provided by a -module called \ref SURF_API. It is -very low-level and is not intended to be used as such by end-users. Instead, -it serve as a basis for the higher level layer. - -SURF main features are a fast max-min linear solver and the ability to -change transparently the model used to describe the platform. This greatly -eases the comparison of the several models existing in the litterature. - -See the \ref SURF_API section for more details. - -\subsection ug_overview_fondation Base layer - -The base of the whole toolkit is constituted by the \ref XBT_API -(eXtended Bundle of Tools). - -It is a portable library providing some grounding features such as \ref -XBT_log, \ref XBT_ex and \ref XBT_config. XBT also encompass -the following convenient datastructures: \ref XBT_dynar, \ref XBT_fifo, \ref -XBT_dict, \ref XBT_heap, \ref XBT_set and \ref XBT_swag. - -See the \ref XBT_API section for more details. - - -\subsection ug_lucas_layer Tracing simulation -Finally, a transversal module allows you to trace your simulation. More documentation in the section \ref TRACE_doc */