-/*! @page inside SimGrid Developer Guide
+/*! @page uhood_tech Coding Standard and Technical Considerations
-This page does not exist yet, sorry. We are currently refurbishing the
-user documentation -- the internal documentation will follow (FIXME).
-
-All we can say for now is that once you learn a bit about the SimGrid
-internals, you will probably look a bit like this:
-
-@image html DiscoveringSimgrid.gif Discovering SimGrid's Internals.
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
-automatic tests are run, and so on. These informations are split on
-several pages, as follows:
+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:
- @subpage inside_tests
- @subpage inside_doxygen
- @subpage inside_cmake
- @subpage inside_release
-
-\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 Programmation environments layer
-
-SimGrid provides several programmation environments built on top of a unique
-simulation kernel. Each environment targets a specific audiance 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 theoritical 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 behaviour of a MPI application using emulation
- technics, 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 functionnalities 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 litterature.
-
-See the \ref SURF_API section for more details.
-
-\subsection ug_overview_fondation 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 datastructures: \ref XBT_dynar, \ref XBT_fifo, \ref
-XBT_dict, \ref XBT_heap, \ref XBT_set and \ref XBT_swag.
-
-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
-
+@section uhood_tech_config Insider's 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
+rational 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.
+
+@section uhood_tech_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
+@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.
+
+@section uhood_tech_tricks Insider 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 a long while. 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.
*/
