/*! \mainpage

\image html gnuradio-logo.png

Welcome to GNU Radio!

For details about GNU Radio and using it, please see the <a
href="http://gnuradio.org" target="_blank"><b>main project page</b></a>.

Other information about the project and discussion about GNU Radio,
software radio, and communication theory in general can be found at
the <a href="http://gnuradio.squarespace.com" target="_blank"><b>GNU Radio blog</b></a>.


\section build Building GNU Radio

See the \ref page_build page for details about the project's
dependencies and build process.


\section blocks GNU Radio Blocks

GNU Radio uses discrete signal processing blocks that are connected
together to perform your signal processing application. This manual
contain a list of all GNU Radio <a href="modules.html"><b>C++ Blocks</b></a>.

Please note that at this time, we haven't found an acceptable way to
provide unified documentation for the C++ parts of the system and the
parts written in Python (mostly hierarchical blocks).  Until this gets
worked out, please bear with us, or better yet, solve it for us!


\section toc Manual Contents
More details on packages in GNU Radio:
\li \ref page_audio
\li \ref page_digital
\li \ref page_qtgui
\li \ref page_uhd
\li \ref page_vocoder
\li \ref page_pfb

\section volk_main Using Volk in GNU Radio

The \ref volk_guide page provides an overview of how to incorporate
and use Volk in GNU Radio blocks.

Many blocks have already been converted to use Volk in their calls, so
they can also serve as examples. See the gr_complex_to_xxx.h file for
examples of various blocks that make use of Volk.


\section logging Logging

GNU Radio has a logging interface to enable various levels of logging
information to be printed to the console or a file. The logger derives
from log4cxx (http://logging.apache.org/log4cxx) which is readily
available in most Linux distributions. This is an optional dependency
and GNU Radio will work without it.

When configuring GNU Radio, the -DENABLE_GR_LOG=On|Off option to cmake
will allow the user to toggle use of the logger on and off and will
turn off if log4cxx is not available.

Logging is useful for blocks to print out certain amounts of data at
different levels. These levels are:

    TRACE < DEBUG < INFO < WARN < ERROR < FATAL

The order here determines the level of output. When using the Debug
level, for instance, all Debug and higher messages are logged and
Trace is ignored.

\subsection use_logging Using the Logging Features

In a GNU Radio block, you use the logging features by calling macros
that are defined in gr_log.h, which must be included for use.

The logger must be properly configured, which is easiest by defining a
configuration file. The log4cxx website will provide more information
on how configuration works and looks. Mostly, a default configuration
script provided with GNU Radio can be used. After installation, the
default configuration script is located at:

    $prefix/etc/gnuradio/gr_log_default.xml

However, we use the global GNU Radio configuration file to tell the
system where this file is located. In the [LOG] section of the
configuration file, the location of the logger's XML file can be
specified. The default configuration file is found in:

    $prefix/etc/gnuradio/conf.d/gnuradio-core.conf

A local "~/.gnuradio/config.conf" file can be used to override any
parameter in the global file.

For the following examples, we will assume that our local
"~/.gnuradio/config.conf" looks like this:

\code
[LOG]
log_file = /opt/gr/etc/gnuadio/gr_log_default.xml
log_level = All
\endcode

The startup and configuration process proceeds as follows.

\code
  std::string log_file = gr_prefs::singleton()->get_string("LOG", "log_config", "");
  std::string log_level = gr_prefs::singleton()->get_string("LOG", "log_level", "off");
  GR_CONFIG_LOGGER(log_file);
  GR_LOG_GETLOGGER(LOG, <name>);
  GR_LOG_SET_LEVEL(LOG, log_level);
\endcode

The default config file has two names that can be used (as std::string
types): "gr_log" and "gr_log_debug". The first one will print
all levels of logging informaiton while the second one will only print
Debug and above.

Names of loggers are global, so "gr_log" as a name will be the same
logger no matter where it is picked from.

The "LOG" name for the logger is now a LoggerPtr object and can be
named anything.

For a given block, it is recommended that a new name be specified for
individual control over the logger as loggers are globally held in a
LoggerManager. Since log4cxx is hierarchical, a new name is created by
appending a string to an existing logger. So a general logger used in
the digital_costas_loop_cc.cc class, for instance, could look
something like "gr_log.costas_loop". This will inherit all properties
of the parent logger, "gr_log".

After calling "GR_LOG_GETLOGGER", the LoggerPtr that was specified,
"LOG" in the example above, is used to set the properties. The main
setting we are generally interested in is the level of the
logger. This will determine if this logger gets outputted or not. In
this case, we are actually getting the gr_log level from the GNU Radio
configuration file, stored in log_level. The macro GR_LOG_SET_LEVEL
can take either a string or a log4cxx::LevelPtr object. The log_level
variable in this case holds a string read in from the config file, and
it's case insensitive. I can be "off", "all", "trace", "debug",
"info", "warn", "error", or "fatal" to match with the levels above.

In our example here, all logging information is displayed because the
config file specifies "All". We can then easily turn off all reporting
by setting this value to "Off".

The various logging macros are defined in gr_log.h. Here are some
simple exmaples of using them:

\code
  GR_LOG_TRACE(LOG, "TRACE message");
  GR_LOG_DEBUG(LOG, "DEBUG message");
  GR_LOG_INFO(LOG, "INFO message");
  GR_LOG_WARN(LOG, "WARNING message");
  GR_LOG_ERROR(LOG, "ERROR message");
  GR_FATAL(LOG, "FATAL message");
  GR_ERRORIF(LOG, a>b, "CONDITIONAL ERROR message");
  GR_ASSERT(LOG, a>b, "ASSERT error message");
\endcode

*/