/*! @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:
-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 head to
-@ref uhood_arch.
-
-Then, 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 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_config Insider's Configuration
+@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
In particular, the build is configured by default to produce highly
optimized binaries, at the price of high compilation time. The
-rational is that users will compile SimGrid only once, and use it many
+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.
build in SimGrid), but any insider must turn this option on, or your
code will be refused from the main repository.
-@section uhood_tech_codstand Automatically Enforcing our Coding Standards
+@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
+<a href="http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html">blog
+post</a>, or in the
+<a href="https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages">
+git styleguide of Atom</a>.
+
+
+@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
-sudo apt-get install clang-format-3.8
-ln -s $PWD/tools/git-hooks/clang-format.pre-commit .git/hooks/pre-commit
+# 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
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.
-@section uhood_tech_tricks Insider tricks
+@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 out of tree builds
-It is easy to break one build configuration or another. If you're
-serious about code quality, you should not commit your change before
-testing it with gcc and clang, with and without MC; with and without
-Java. To easily switch between the configs without rebuilding
-everything, you want to compile out of tree (as explained in @ref
-install_cmake_outsrc).
+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/default build/clang build/java build/full
+directories: build/clang build/java build/full
(but YMMV).
Then, the problem is that when you traverse these directories, you
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
-these files are accessible both from the srcdir and from the bindir. 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).
+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).
-If you convert from a regular build to an out-of-tree build, you need
-to clean your source tree by removing the following files:
+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.
-@verbatim
-rm -rf Makefile CMakeCache.txt CMakeFiles include/simgrid_config.h src/internal_config.h lib/*.so
-@endverbatim
*/
