doc/doxygen/inside.doc

   1 /*! @page uhood_tech Coding Standard and Technical Considerations
   2
   3
   4 There is two main things you want to know about the internals of
   5 SimGrid. First, you need to understand the component organization, as
   6 SimGrid is heavily layered, with each level being rather highly
   7 specialized and optimized toward a task. For that, please head to
   8 @ref uhood_arch.
   9
  10 Then, if you work actively on the SimGrid project, the second point
  11 you need to understand is about the infrastructure of the SimGrid
  12 project, ie how to extend the framework in any way, how the automatic
  13 tests are run, and so on. These informations are split on several
  14 pages, as follows:
  15
  16  - @subpage inside_tests
  17  - @subpage inside_doxygen
  18  - @subpage inside_extending
  19  - @subpage inside_cmake
  20  - @subpage inside_release
  21
  22 @section uhood_tech_config Insider's Configuration
  23
  24 The default build configuration of SimGrid fits the user needs, but
  25 they are not adapted to the ones actually working on SimGrid. See @ref
  26 install_src_config for more information. Note that this is very
  27 different from runtime configuration.
  28
  29 In particular, the build is configured by default to produce highly
  30 optimized binaries, at the price of high compilation time. The
  31 rational is that users will compile SimGrid only once, and use it many
  32 times. This is exactly the contrary for the insiders, so you want to
  33 turn off \b enable_compile_optimizations.
  34
  35 Symmetrically, \b enable_compile_warnings is off for the users because
  36 we don't want to bother them with compiler warnings (that abort the
  37 build in SimGrid), but any insider must turn this option on, or your
  38 code will be refused from the main repository.
  39
  40 @section uhood_tech_codstand Automatically Enforcing our Coding Standards
  41
  42 If you plan to commit code to the SimGrid project, you definitely need
  43 to install the relevant tool to ensure that your changes follow our
  44 coding standards:
  45
  46 @verbatim
  47 sudo apt-get install clang-format-3.8
  48 ln -s $PWD/tools/git-hooks/clang-format.pre-commit .git/hooks/pre-commit
  49 @endverbatim
  50
  51 This will add an extra verification before integrating any commit that
  52 you could prepare. If your code does not respects our formating code,
  53 git will say so, and provide a ready to use patch that you can apply
  54 to improve your commit. Just carefully read the error message you get
  55 to find the exact command with git-apply to fix your formating.
  56
  57 If you find that for a specific commit, the formatter does a very bad
  58 job, then add --no-verify to your git commit command line.
  59
  60 @section uhood_tech_tricks Insider tricks
  61
  62 Over the years, we accumulated a few tricks that make it easier to
  63 work with SimGrid. Here is a somewhat unsorted list of such tricks.
  64
  65 ### Easy testing
  66
  67 Launching all tests can be very time consuming, so you want to build
  68 and run the tests in parallel. Also, you want to save the build output
  69 to disk, for further reference. This is exactly what the
  70 BuildSimGrid.sh script does. It is upper-cased so that the shell
  71 completion works and allow to run it in 4 key press: `./B<tab>`
  72
  73 Note that if you build out of tree (as you should, see below), the
  74 script builds the build/default directory. I usually copy the file in
  75 each build/ subdir to test each of them separately.
  76
  77 ### Easy out of tree builds
  78
  79 It is easy to break one build configuration or another. If you're
  80 serious about code quality, you should not commit your change before
  81 testing it with gcc and clang, with and without MC; with and without
  82 Java. To easily switch between the configs without rebuilding
  83 everything, you want to compile out of tree (as explained in @ref
  84 install_cmake_outsrc).
  85
  86 To not mess with git, you want to put your build tree under the build/
  87 directory, which is ignored by git. For example, I have the following
  88 directories: build/default build/clang build/java build/full
  89 (but YMMV).
  90
  91 Then, the problem is that when you traverse these directories, you
  92 cannot edit the sources (that are in the srcdir, while you're in
  93 bindir). This makes it difficult to launch the tests and everything.
  94
  95 To solve that issue, just call `make hardlinks` from your build dir.
  96 This will create hard links allowing to share every source files into
  97 the build dir. They are not copied, but hard linked. It means that
  98 these files are accessible both from the srcdir and from the bindir. If
  99 you edit a source file found under bindir, the srcdir version (visible
 100 to git) will also be changed (that's the same file, after all).
 101
 102 If you convert from a regular build to an out-of-tree build, you need
 103 to clean your source tree by removing the following files:
 104
 105 @verbatim
 106 rm -rf Makefile CMakeCache.txt CMakeFiles include/simgrid_config.h src/internal_config.h lib/*.so
 107 @endverbatim
 108
 109 */