eina: documment envvars at eina_init().

following my commit for ecore_init(), do that for eina_init() as well,
sometimes it's hard to find the vars and their meaning without looking
at the code.

1 files changed, 92 insertions, 0 deletions

diff --git a/src/lib/eina/eina_main.h b/src/lib/eina/eina_main.h
index d7a7f0b01f..9905ebfb0a 100644
--- a/src/lib/eina/eina_main.h
+++ b/src/lib/eina/eina_main.h
@@ -80,6 +80,98 @@ EAPI extern Eina_Version *eina_version;
  *
  * When Eina is not used anymore, call eina_shutdown() to shut down
  * the Eina library.
+ *
+ * This function is affected by the following environment variables.
+ *
+ * Logging environment variables:
+ *
+ *  @li @c EINA_LOG_ABORT=1 will cause abort(3) if @c
+ *      EINA_LOG_ABORT_LEVEL, which defaults to 0 (critical), is
+ *      reached.
+ *
+ *  @li @c EINA_LOG_ABORT_LEVEL=LEVEL, where level is an integer such
+ *      as 0 (critical) to 4 (debug). This will cause any messages at
+ *      that level or less (ie: if 4, then messages at level 0 also
+ *      apply) to abort(3) the application if @c EINA_LOG_ABORT=1 was
+ *      defined.
+ *
+ *  @li @c EINA_LOG_BACKTRACE=LEVEL, where level is an integer such as
+ *      0 (critical) to 4 (debug). This will cause any messages at
+ *      that level or less (ie: if 4, then messages at level 0 also
+ *      apply) to dump a backtrace. Note that if systemd-journal is
+ *      used, it's going to the journal as well.
+ *
+ *  @li @c EINA_LOG_COLOR_DISABLE=[0|1] if @c 1 it will disable color
+ *      in log output. If it's @c 0, it will keep colors. By default
+ *      it will use colors if it's a TTY, disabling colors if it's
+ *      printing to a file.
+ *
+ *  @li @c EINA_LOG_FILE_DISABLE=[0|1] if @c 1 it will disable showing
+ *      the source file name and line that generated the message. If
+ *      @c 0, the default, it will show the source file and line.
+ *
+ *  @li @c EINA_LOG_FUNCTION_DISABLE=[0|1] if @c 1 it will disable
+ *      showing the source function name that generated the
+ *      message. If @c 0, the default, it will show the function name.
+ *
+ *  @li @c EINA_LOG_LEVEL=LEVEL, where level is an integer such as 0
+ *      (critical) to 4 (debug), where the number is the the highest
+ *      level to print, that is, using level=4 will lead to messages
+ *      of level 1, 2 and 3 to be displayed as well, but not level
+ *      5. This will control all log domains at once and has lower
+ *      priority than @c EINA_LOG_LEVELS, that defines per-domain.
+ *
+ *  @li @c EINA_LOG_LEVELS=DOMAIN1:LEVEL1,DOMAIN2:LEVEL2 is a comma
+ *      separated list of tuples of DOMAIN and LEVEL values separated
+ *      by a colon. Level is an integer such as 0 (critical) to 4
+ *      (debug), where the number is the the highest level to print,
+ *      that is, using level=4 will lead to messages of level 1, 2 and
+ *      3 to be displayed as well, but not level 5. This offers fine
+ *      grained control, allowing a single domain to be printed at
+ *      debug (4) while keeping others at error (1) only. For instance
+ *      @c EINA_LOG_LEVELS=eina:2,eina_binshare:4 will change eina's
+ *      general purpose logging domain to warning (2) while will make
+ *      the specific eina_binshare debug (4).
+ *
+ *  @li @c EINA_LOG_LEVELS_GLOB=PATTERN1:LEVEL1,PATTERN2:LEVEL2 is a
+ *      comma separated list of tuples of domain PATTERN and LEVEL
+ *      values separated by a colon. PATTERN is a fnmatch(3) pattern
+ *      that will try to match the domain name. Level is an integer
+ *      such as 0 (critical) to 4 (debug), where the number is the the
+ *      highest level to print, that is, using level=4 will lead to
+ *      messages of level 1, 2 and 3 to be displayed as well, but not
+ *      level 5. This offers fine grained control, allowing a single
+ *      domain to be printed at debug (4) while keeping others at
+ *      error (1) only. For instance @c EINA_LOG_LEVELS_GLOB=eina*:4
+ *      will change all domain names starting with "eina", such as
+ *      "eina" (general purpose log domain) and "eina_binshare".
+ *
+ * Memory allocator environment variables:
+ *
+ *  @li @c EINA_MEMPOOL=mempool_allocator will choose another memory
+ *      allocator to use. Commonly this is given @c pass_through as
+ *      the @c mempool_allocator to allow valgrind and other tools to
+ *      debug it more easily.
+ *
+ *  @li @c EINA_MEMPOOL_PASS=1 has the almost the same effect of @c
+ *      EINA_MEMPOOL=pass_through, but if pass_through allocator
+ *      wasn't built, it will use the original allocator.
+ *
+ *  @li @c EINA_MTRACE=1 and @c MALLOC_TRACE=PATH will use mtrace(3)
+ *      and store the memory allocation traces to given @c PATH.
+ *
+ * Module loading environment variables:
+ *
+ *  @li @c EINA_MODULE_LAZY_LOAD=1 will dlopen(3) with RTLD_LAZY, this
+ *      results in faster startup since symbols will be resolved when
+ *      needed, but may omit errors as they will be triggered later
+ *      on.
+ *
+ * Threads environment variables:
+ *
+ *  @li @c EINA_DEBUG_THREADS=1 will print out debug information about
+ *      threads, but requires Eina to be compiled with such feature.
+ *
  */
 EAPI int eina_init(void);