Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
0ef01a83f1c392279bcf65e00e7d21b16c820a78
[simgrid.git] / 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 rationale 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 # install clang-format
48 sudo apt-get install clang-format-3.8 # debian
49
50 # tell git to call the script on each commit
51 ln -s $(realpath tools/git-hooks/clang-format.pre-commit) .git/hooks/pre-commit
52 @endverbatim
53
54 This will add an extra verification before integrating any commit that
55 you could prepare. If your code does not respects our formating code,
56 git will say so, and provide a ready to use patch that you can apply
57 to improve your commit. Just carefully read the error message you get
58 to find the exact command with git-apply to fix your formating.
59
60 If you find that for a specific commit, the formatter does a very bad
61 job, then add --no-verify to your git commit command line.
62
63 @section uhood_tech_tricks Insider tricks
64
65 Over the years, we accumulated a few tricks that make it easier to
66 work with SimGrid. Here is a somewhat unsorted list of such tricks.
67
68 ### Easy testing
69
70 Launching all tests can be very time consuming, so you want to build
71 and run the tests in parallel. Also, you want to save the build output
72 to disk, for further reference. This is exactly what the
73 BuildSimGrid.sh script does. It is upper-cased so that the shell
74 completion works and allow to run it in 4 key press: `./B<tab>`
75
76 Note that if you build out of tree (as you should, see below), the
77 script builds the build/default directory. I usually copy the file in
78 each build/ subdir to test each of them separately.
79
80 ### Easy out of tree builds
81
82 It is easy to break one build configuration or another. That's
83 perfectly OK and we will not point fingers if it happens. But it is
84 somewhat forbidden to leave the tree broken for a long while. Monitor
85 the build daemons after you push something, and strive to fix any
86 breakage ASAP.
87
88 To easily switch between the configs without rebuilding everything,
89 create a set of out of tree builds (as explained in @ref
90 install_cmake_outsrc) in addition to your main build tree.
91 To not mess with git, you want to put your build tree under the build/
92 directory, which is ignored by git. For example, I have the following
93 directories: build/clang build/java build/full
94 (but YMMV).
95
96 Then, the problem is that when you traverse these directories, you
97 cannot edit the sources (that are in the srcdir, while you're in
98 bindir). This makes it difficult to launch the tests and everything.
99
100 To solve that issue, just call `make hardlinks` from your build dir.
101 This will create hard links allowing to share every source files into
102 the build dir. They are not copied, but hard linked. It means that
103 each file is accessible under several names, from the srcdir and from
104 the bindirs. If you edit a source file found under bindir, the srcdir
105 version (visible to git) will also be changed (that's the same file,
106 after all).
107
108 Note that the links sometimes broken by git or others. Relaunching
109 `make hardlinks` may help if you're getting incoherent build results.
110 */