#!/usr/bin/env perl
-# Copyright (c) 2008-2021. The SimGrid Team.
-# All rights reserved.
+# Copyright (c) 2008-2021. The SimGrid Team. All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the terms of the license (GNU LGPL) which comes with this package.
print ".. _logging_categories:\n\n";
print "Existing categories\n";
print "===================\n\n";
+print "This is the list of all categories existing in the SimGrid implementation. "
+ ."Some of them only exist with specific compile-time options, while your implementation may add new ones. "
+ ."Please add \`\`--help-log-categories\`\` to the command-line of a SimGrid simulator to see the exact list of categories usable with it.\n\n";
# Search for calls to macros defining new channels, and prepare the tree representation
my %ancestor;
``iface.log`` file; the logging of the xbt toolbox will be sent to both the ``xbt.log`` file and the ``all.log`` file (because xbt additivity was enabled); and every other loggings
will only be sent to ``all.log``.
+Other options
+.............
+
+``--help-logs`` displays a complete help message about logging in SimGrid.
+
+``--help-log-categories`` displays the actual hierarchy of log categories for this binary.
+
+``--log=no_loc`` hides the source locations (file names and line numbers) from the messages. This is useful to make tests reproducible.
+
+
.. |br| raw:: html
<br />
severity and their topic. There is four main concepts in SimGrid's logging mechanism:
The **category** of a message represents its topic. These categories are organized as a hierarchy, loosely corresponding to SimGrid's modules architecture. `Existing categories
-<xbt_log_cat>`_ are documented online, but some of them may be disabled depending on the compilation options. Use ``--help-logs`` on the command line to see the categories actually
-provided a given simulator.
+<logging_categories>`_ are documented online, but some of them may be disabled depending on the compilation options. Use ``--help-log-categories`` on the command line to see
+the categories actually provided a given simulator.
The message **priority** represents its severity. It can be one of ``trace``, ``debug``, ``verb``, ``info``, ``warn``, ``error`` and ``critical``. Every category has a configured
threshold, and only the messages with a higher severity are displayed (the others are not even evaluated). For example, you may want to see every debugging message of the Host