-/*! @page inside Coding Standard and Project Architecture
+/*! @page uhood_tech Coding Standard and Technical Considerations
-TBD: Coding Standard
-
-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
+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
+<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
+# 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<tab>`
+
+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
-<center>
-\endhtmlonly
-\htmlinclude simgrid_modules.map
-\htmlonly
-<br><b>SimGrid Components (click to jump to API)</b>
-</center>
-\endhtmlonly
-
-
-\section ug_overview Overview of the toolkit components
-
-
-\subsection ug_overview_envs Programing environments layer
-
-SimGrid provides several programming environments built on top of a unique
-simulation kernel. Each environment targets a specific audience 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 theoretical problem and compare several
- heuristics, you probably want to try <b>\ref MSG_API</b> (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 behavior of a MPI application using emulation,
- you should have a look at the <b>\ref SMPI_API</b> (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
-<a href=http://lists.gforge.inria.fr/mailman/listinfo/simgrid-devel>SimGrid
-developers mailing list</a>, though.
-
-\subsection ug_overview_kernel Simulation kernel layer
-
-The core functionalities to simulate a virtual platform are provided by a
-module called <b>\ref SURF_API</b>. 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 literature.
-
-See the \ref SURF_API section for more details.
-
-\subsection ug_overview_fundation Base layer
-
-The base of the whole toolkit is constituted by the <b>\ref XBT_API
-(eXtended Bundle of Tools)</b>.
-
-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 C data structures:
-\ref XBT_dynar, \ref XBT_fifo, \ref XBT_dict, \ref XBT_heap, \ref XBT_set and
-\ref XBT_swag. The code is being migrated in C++ so you should probably want
-to use standard C++ containers instead of them if possible.
-
-It contains some C++ polyfills and utilities as well.
-
-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
*/
