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

2. *.rcdgen_cfg just contains arguments for rcd_autogen script - they could be used directly as well,
   but *.rcdgen_cfg allows using shell comments, line continuation marks, etc - more convenient.

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

   Alternatively, if --scan-target=<file>.rcdgen_target, then the list of dirs and files to scan
   is readed from a file.
   Target file (*.rcdgen_target) syntax:
      - single target file per line, paths 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

   rcd_autogen takes into account only the source files which are referencing
   RCD_AUTOGEN_DEFINE_UNIT macro.

   In general, it should be sufficient to just review the configure.ac and the associated
   config files to get an idea of how all this works - it's really simple in fact.


NOTES:
1. rcd_autogen generates separate source file with functions definitions:
   this allows to have only a single file with functions definitions, and
   multiple files with scope structs.
   This is usefull for big projects where num_of_scopes>RCD_SCOPE_MAX (16383).
   In such case unit id conflict is unavoidable and the caller has to know the
   pointer to scope struct of the callee.
   Libraries don't have to implement RCD functions: only the client app needs
   to have them, so normally --run-mode=basic should be used for libs, *unless*
   the lib functions have to return volatile textual messages along with the rcode (VMSG).
   Normally in the "basic" mode, the library will provide only 2 little accessor functions,
   which returns the pointer to scope struct, and the min. buff. size for printing
   longest rcode message.
   Of course, still each scope structure is prefixed with $base_name, so they are unique.
   If the --run-mode=dummy is used, then scope structs are *not* generated, and
   all the functions are reaplced with stubs (returning NULL/zero -> which is OK for
   app-level rcd functions).
   This is needed to keep the library interface unchanged for linking.

2. configure.ac: AC_RCODE_AUTOGEN_TARGET() creates headers 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.

3. 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/returncode/rcd_autogen src/<prog_path>/<prog_rcdgen_config>.rcdgen_cfg"
   Notice the 'cd' command: this is needed if code::blocks project dir is different
   from the $(top_source_dir).
   It's just more convenient to use "<prog_rcdgen_config>.rcdgen_cfg", instead of
   issuing all the args on cmd line.
   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)_RCD_GET_SCOPE() to get scope
   struct pointer, which should be then passed to ($base_name)_RCD_GET_MSG().

3. List of files to scan: there is no reliable way of creating target files list from makefile.
   Option --scan-target= must be used to define list of files/dirs, optionally the
   <target>.rcdgen_target file can be used.

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 conflicts
	with libs that also can use functions generated by rcd_autogen.
   Additionally, if num_of_files_to_scan>RCD_SCOPE_MAX (16383), the project has to be
   splitted into logical blocks, and the scope structs have to be generated separately
   for each of that blocks.

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.


