doc/doxygen/inside.doc

   1 /*! @page uhood_tech Coding Standard and Technical Considerations
   2
   3 This page describes the software infrastructure behind the SimGrid
   4 project. This is not the components' organisation (described in @ref
   5 uhood_arch) but informations on how to extend the framework, how the
   6 automatic tests are run, and so on. These informations are split on
   7 several pages, as follows:
   8
   9  - @ref uhood_tech_inside
  10  - @subpage inside_tests
  11  - @subpage inside_doxygen
  12  - @subpage inside_extending
  13  - @subpage inside_cmake
  14  - @subpage inside_release
  15
  16 @section uhood_tech_inside Insiders Considerations
  17
  18 @subsection uhood_tech_inside_config Extra configuration
  19
  20 The default build configuration of SimGrid fits the user needs, but
  21 they are not adapted to the ones actually working on SimGrid. See @ref
  22 install_src_config for more information. Note that this is very
  23 different from runtime configuration.
  24
  25 In particular, the build is configured by default to produce highly
  26 optimized binaries, at the price of high compilation time. The
  27 rationale is that users will compile SimGrid only once, and use it many
  28 times. This is exactly the contrary for the insiders, so you want to
  29 turn off \b enable_compile_optimizations.
  30
  31 Symmetrically, \b enable_compile_warnings is off for the users because
  32 we don't want to bother them with compiler warnings (that abort the
  33 build in SimGrid), but any insider must turn this option on, or your
  34 code will be refused from the main repository.
  35
  36 @verbatim
  37     cmake -Denable_compile_optimizations=OFF \
  38           -Denable_compile_warnings=ON .
  39 @endverbatim
  40
  41 @subsection uhood_tech_inside_commit Interacting with git
  42
  43 During the Gran Refactoring to SimGrid4, things are evolving rather
  44 quickly, and some changes impact a large amount of files. You should
  45 thus not have long-standing branches, because they will rot very
  46 quickly and you will suffer to merge them back. Instead, you should
  47 work as much as possible with incremental changes that do not break
  48 things, and get them directly in master.
  49
  50 Your commit message should follow the git habits, explained in this
  51 <a href="http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html">blog
  52 post</a>, or in the
  53 <a href="https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages">
  54 git styleguide of Atom</a>.
  55
  56
  57 @subsection uhood_tech_inside_codstand Automatically Enforcing our Coding Standards
  58
  59 If you plan to commit code to the SimGrid project, you definitely need
  60 to install the relevant tool to ensure that your changes follow our
  61 coding standards:
  62
  63 @verbatim
  64 # install clang-format
  65 sudo apt-get install clang-format-3.9 # debian
  66
  67 # tell git to call the script on each commit
  68 ln -s $(realpath tools/git-hooks/clang-format.pre-commit) .git/hooks/pre-commit
  69 @endverbatim
  70
  71 This will add an extra verification before integrating any commit that
  72 you could prepare. If your code does not respects our formating code,
  73 git will say so, and provide a ready to use patch that you can apply
  74 to improve your commit. Just carefully read the error message you get
  75 to find the exact command with git-apply to fix your formating.
  76
  77 If you find that for a specific commit, the formatter does a very bad
  78 job, then add --no-verify to your git commit command line.
  79
  80 @subsection uhood_tech_tricks Random Tricks
  81
  82 Over the years, we accumulated a few tricks that make it easier to
  83 work with SimGrid. Here is a somewhat unsorted list of such tricks.
  84
  85 ### Easy testing
  86
  87 Launching all tests can be very time consuming, so you want to build
  88 and run the tests in parallel. Also, you want to save the build output
  89 to disk, for further reference. This is exactly what the
  90 BuildSimGrid.sh script does. It is upper-cased so that the shell
  91 completion works and allow to run it in 4 key press: `./B<tab>`
  92
  93 Note that if you build out of tree (as you should, see below), the
  94 script builds the build/default directory. I usually copy the file in
  95 each build/ subdir to test each of them separately.
  96
  97 ### Easy out of tree builds
  98
  99 It is easy to break one build configuration or another. That's
 100 perfectly OK and we will not point fingers if it happens. But it is
 101 somewhat forbidden to leave the tree broken for more than one working
 102 day. Monitor the build daemons after you push something, and strive to
 103 fix any breakage ASAP.
 104
 105 To easily switch between the configs without rebuilding everything,
 106 create a set of out of tree builds (as explained in @ref
 107 install_cmake_outsrc) in addition to your main build tree.
 108 To not mess with git, you want to put your build tree under the build/
 109 directory, which is ignored by git. For example, I have the following
 110 directories: build/clang build/java build/full
 111 (but YMMV).
 112
 113 Then, the problem is that when you traverse these directories, you
 114 cannot edit the sources (that are in the srcdir, while you're in
 115 bindir). This makes it difficult to launch the tests and everything.
 116
 117 To solve that issue, just call `make hardlinks` from your build dir.
 118 This will create hard links allowing to share every source files into
 119 the build dir. They are not copied, but hard linked. It means that
 120 each file is accessible under several names, from the srcdir and from
 121 the bindirs. If you edit a source file found under bindir, the srcdir
 122 version (visible to git) will also be changed (that's the same file,
 123 after all).
 124
 125 Note that the links sometimes broken by git or others. Relaunching
 126 `make hardlinks` may help if you're getting incoherent build results.
 127
 128 ### Unsorted hints
 129
 130 * If you want to debug memory allocation problems, here are a few hints:
 131   - disable compiler optimizations, to have better backtraces;
 132   - disable the mallocators, or it will be hard to match malloc's with free's;
 133   - disable model checking, unless your problem lies in the model
 134     checker part of SimGrid (MC brings its own malloc implementation,
 135     which valgrind does not really love).
 136     All this is configured with:
 137
 138     cmake -Denable_model-checking=OFF
 139           -Denable_mallocators=OFF
 140           -Denable_compile_optimizations=OFF .
 141
 142 * If you break the logs, you want to define XBT_LOG_MAYDAY at the
 143   beginning of log.h. It deactivates the whole logging mechanism,
 144   switching to printfs instead. SimGrid becomes incredibly verbose
 145   when doing so, but it you let you fixing things.
 146
 147
 148 */