rcode v4.x

Usage:
1. configure.ac:
   required file: $project_dir/m4/rcd_autoconf.m4
   invocation:
   AC_OPT_RCD_AUTOGEN([src/rcode/rcd_autogen]) #add configure option for rcd_autogen
   AC_RCD_AUTOGEN_TARGET([src/test_c.rcdgen_cfg]) #call autogen for given target config.

   The *.rcdgen_cfg file just contains arguments for rcd_autogen script - they could
   be plased direcly on the command line, but *.rcdgen_cfg allows using shell comments,
   line continuation marks, etc - more convenient.

2. The --scan-target= option must be provided for rcd_autogen.
   The value is a string of comma separated dirs or cource files to be scanned by
   rcd_autogen.

   Alternatively, if --scan-target=<file>.rcdgen_target is given, then the list
   of dirs and files to scan is read from a file.
   Target file (*.rcdgen_target) syntax:
      - single target source file per line, paths are relative to $root_dir argument
      - .SETDIR - sets the base path for the consecutive entries
      - .SCANDIR - scan all files in a given dir
      - #shell comments allowed
      - line continuation marks allowed
      - only files with matching selected language extension are scanned (.c or .cpp).

   rcd_autogen is proocessing only the source files which are referencing
   RCD_AUTOGEN_DEFINE_UNIT macro.

3. --run-mode option value:
   'dummy': almost all generated functions are stubs, implemented for ABI consistency,
   'basic': enables binding of static messages to rcode values,
   'full' : enables support for VMSG (volatile) messages and a rcode call stack.

4. --link-lib=<base_name> option:
   This option generates code which references rcode functions from linked library,
   what reduces code size and improves cache hit ratio. Target library has to be
   compiled in 'full' mode, and --lib-hdr option must be set to target header include
   path.

5. --msg-hdl=<function>
   This option replaces built-in message handler with <function>, what enables
   some special use cases (e.g.):
   - use of dynamically allocated message buffers,
   - accessing message components, like: line/unit number, message string, length
     of the message.
   - process rcode stack entries one by one: the function is invoked by
     <base_name>_rcdGetCallStack() once for each rcode stack entry.

NOTES:
1. configure.ac: AC_RCODE_AUTOGEN_TARGET() generates a header which may be required
   for compiling other programs/libs in the project.
   Therefore, the order of calling AC_RCODE_AUTOGEN_TARGET() is significant, i.e.
   libraries targets have to be preprocessed before programs targets.

2. Running 'rcd_autogen' as pre-build script from an IDE (Code::Blocks example):
   Menu Project->Build_Options->Pre/Post_build_steps:
   "cd <project_root_dir>; ./src/rcode/rcd_autogen src/<prog_path>/<prog_rcdgen_config>.rcdgen_cfg"
   Different IDE's may require additonal steps before running the pre-build scripts.

KNOWN ISSUES:
1. Bash is the only supported shell interpreter for rcd_autogen:
   min version: Bash v4.4.0 (mainly namerefs support)

2. Using of rcode in general-purpose libs leads to unavoidable unit-id conflicts
   at the application level (in case of dedicated libs, which are part of a given
   project, each unit id can be uniqe).
   In all cases, the app has to call ($base_name)_rcdGetScopePtr() to get scope
   struct pointer, which should be then passed to ($base_name)_rcdGetMsg().

5. Functions for handling rcd_scope_t structs have different name prefixes for each
   project/target: $base_name$func_name() . This is required to avoid name space
   conflicts with libs that also can use functions generated by rcd_autogen.
   Additionally, if num_of_files_to_scan>RCD_UNIT_MAX (65535), the project has to be
   splitted into sub-projects, and the scope structs have to be generated separately
   for each of the sub-projects.

6. Function names cannot be resolved by the preprocessor - there's no way generate
   static messages with function names at the preprocessing stage.
   This can be bypased by simply using static names of functions or by using VMSG
   (volatile) messages - but this requires --run-mode=full for rcd_autogen and
   produces bigger code.

7. rcd_autogen requires RCD_UNIT to be defined as plain decimal integer, i.e. hex
   values are not recognized, expression are not evaluated (but macros are expanded).

8. If a function returning rcode is referenced by function pointer, then it can
   be necessary to f.e. store scope struct pointer along with the fn pointer,
   to be able to get rcode messages.


