<?xml version="1.0" ?>
<notes>
<p>
When processing a project for the first time,
<em>Cscout</em> may terminate its processing with a syntax error.
The errors are typically occurring because of incompatibilities
between <em>CScout</em> and C compiler extensions or features of a
particular version of the C Standard used in the project.
Here is advice for troubleshooting such errors.
</p>

<ul>
  <li>Examine the offending source code.</li>
  <li>If the issue is obvious consider the following alternatives.</li>
  <ul>
    <li>Add a workaround macro in the appropriate file in the source code
      <code>include/template</code> directory, and reinstall <em>CScout</em>.
      Look within the existing header files for examples of how diverse
      compiler extensions are handled.
      If the fix is general and widely applicable, please consider
      contributing it back via a GitHub pull request.
    </li>
    <li>Skip the offending code, by adding a
      <code>#if !defined(__CSCOUT__)</code> conditional compilation directive.
    </li>
    <li>Skip the offending file, by commeting out the corresponding
      <code>#pragma process</code> directive of the employed <em>CScout</em>
      processing script.
    </li>
    <li>Extend <em>CScout</em> to handle the offending construct.
      In this case, please consider contributing back your fix
      via a GitHub pull request.
    </li>
  </ul>
  <li>If the issue is non-obvious it is likely that it is hidden underneath
    code generated by the preprocessor.
    In this case proceed as follows.
  </li>
  <ul>
    <li>Run <em>CScout</em> to proprocess the offending C file, with a
      command such as <code>cscout -E /path/to/file.c main.cs >file.i</code>.
    </li>
    <li>If the <em>CScout</em> script part associated with the offending
      part, contains <code>#pragma process</code> directives for header
      files, as in the example below, then the above method will not work.
      <pre>
#include "/usr/local/include/cscout/csmake-post-defs.h"
#pragma process "[...]/include/linux/kconfig.h"
#pragma process "[...]/init/do_mounts_rd.c"
      </pre>
      In this case, employ the <em>cscut</em> command to extract from the
      processing script the part associated with the offending file
      (e.g. into a file named <code>file.cs</code>),
	and then run <em>CScout</em> in preprocessing mode on that file:
	<code>cscout -E . file.cs >file.i</code>
    </li>
    <li>Create a <em>CScout</em> processing script for the preprocessed
      file, such as the following.
      <pre>
#pragma block_enter
#pragma block_enter
#pragma process "file.i"
#pragma block_exit
#pragma block_exit
      </pre>
    </li>
    <li>Process the new script with <em>CScout</em>to see the line in which
      the error occurs in the preprocessed code and handle it as in the
      first case.
    </li>
    <li>To identify the correspondence between the preprocessed code and
      the original source code, try to match identifiers that are likely
      to be specific to the offending code part, such as the name of
      a function being defined.</li>
  </ul>
  <li>In all cases, optimize your work process as follows.
  <ul>
    <li>Use a <code>cscout -P</code> command to process only the parts
      of the processing script associated with the offending file.
      This will allow you to iterate through possible fixes and test them,
      without waiting for <em>CScout</em> to process all other files.
      As described above, if the processing
      script contains <code>#pragma process</code> directives for header
      files use <em>cscut</em> to extract the script part for the offending
      file, and only process this.
    </li>
    <li>As you advance through the <em>CScout</em> processing script,
      generate a subset of unprocessed parts with a <code>cscut -e</code>
      command or by deleting the processed parts with your editor.
      When modifying the processing script by hand,
      be careful not to violate the project and file block nestings.
      You can remove the processing of entire projects (an outward
      <code>#pragma block_enter / block_exit</code> block) or entire
      files (an inward <code>#pragma block_enter / block_exit</code>),
      but you should never leave incomplete blocks.
    </li>
  </ul>
  </li>
</ul>
</notes>
