<?xml version="1.0"?>

<!--
	description:

		"Gec Tasks"

	library: "Gobo Eiffel Ant"
	copyright: "Copyright (c) 2006-2025, Eric Bezault and others"
	license: "MIT License"
-->

<chapter xmlns="https://www.gobosoft.com/eiffel/gobo/documentation" id="gec_task">
<chapterinfo>
	<copyright>
		<year>2006-2023</year>
		<holder>Eric Bezault</holder>
	</copyright>
	<author>
		<firstname>Eric</firstname>
		<surname>Bezault</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>20 December 2023</date>
</chapterinfo>

	<title>gec</title>

	<section id="gec_description">
		<title>Description</title>
		<para>
			Execute gec.
		</para>
	</section>

	<section id="gec_parameters">
		<title>Parameters</title>

		<variablelist>
			<varlistentry>
				<term>ecf</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of ECF file</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid filename pointing to existing file</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>target</term>
				<listitem>
					<para><emphasis>Name of target to be used in ECF file</emphasis></para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>valid target name</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>Last target in ECF file</para>
				</listitem>
			</varlistentry>
			
			<varlistentry>
				<term>finalize</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Should system be compiled in finalized mode?</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>gelint</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Should gelint be run on the full content of each class being compiled?</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>catcall</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Should CAT-call errors be considered as fatal errors, as warnings, or just ignored?</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>(no|error|warning)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>warning</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>split</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Should C code be generated into several files?</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>true</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>split_size</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Size (in bytes) of generated C files in bytes when in split mode</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Positive integer</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>2,500,000 bytes</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>c_compile</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Should the back-end C compiler be invoked on the generated C code, and if yes with what method?</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>(no|script|make|gecc)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>gecc</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>gc</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Which garbage collector should the application be compiled with?</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>(no|boehm)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>no</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>new_instance_types</term>
				<listitem>
					<para><emphasis>Description: </emphasis>File containing
					the list of types which can have instances created by 
					'TYPE.new_instance' or 'TYPE.new_special_any_instance'</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid filename pointing to existing file</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>Use all non-deferred, non-NONE, alive types</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>thread</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Number of threads to be used to run gec. Negative numbers -N mean &quot;number of CPUs - N&quot;</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Integer</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-3, aka &quot;max (number of CPUs -3, 1)&quot;</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>silent</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Run gec in silent mode</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>verbose</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Run gec in verbose mode</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>no_benchmark</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Should no benchmark information be displayed? (default: display non-nested benchmark information)</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>nested_benchmark</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Should nested benchmark information be displayed?</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>metrics</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Should metrics information be displayed?</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>executable</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Filename (optionally with a pathname) of gec executable.
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Valid filename pointing to existing executable</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>Version of 'gec' in the PATH</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>clean</term>
				<listitem>
					<para><emphasis>Description: </emphasis>clean</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>valid system name</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>empty string</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>exit_code_variable</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Name of variable holding the compiler process's return code after it's run
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Integer (usually 0 for OK, and any other number for not OK)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>`Void' (no variable is set if attribute is not specified)</para>
				</listitem>
			</varlistentry>

		</variablelist>
	</section>

	<section id="gec_specification">
		<title>RNG Specification</title>

		<programlisting><![CDATA[
  <define name="gec">
    <element name="gec">
      <ref name="dir_if_unless"/>
      <choice>
        <group>
          <attribute name="ecf"/>
          <optional>
            <attribute name="target"/>
          </optional>
          <optional>
            <attribute name="finalize"/>
          </optional>
          <optional>
            <attribute name="gelint"/>
          </optional>
          <optional>
            <attribute name="catcall"/>
          </optional>
          <optional>
            <attribute name="split"/>
          </optional>
          <optional>
            <attribute name="split_size"/>
          </optional>
          <optional>
            <attribute name="c_compile"/>
          </optional>
          <optional>
            <attribute name="gc"/>
          </optional>
          <optional>
            <attribute name="new_instance_types"/>
          </optional>
          <optional>
            <attribute name="thread"/>
          </optional>
          <optional>
            <attribute name="silent"/>
          </optional>
          <optional>
            <attribute name="verbose"/>
          </optional>
          <optional>
            <attribute name="no_benchmark"/>
          </optional>
          <optional>
            <attribute name="nested_benchmark"/>
          </optional>
          <optional>
            <attribute name="metrics"/>
          </optional>
          <optional>
            <attribute name="executable"/>
          </optional>
        </group>
        <attribute name="clean"/>
      </choice>
      <optional>
        <attribute name="exit_code_variable"/>
      </optional>
    </element>
  </define>
]]>
	</programlisting>

	</section>

	<section id="gec_examples">
		<title>Examples</title>
	<programlisting><![CDATA[
  <gec ecf="system.ecf"/>

  <gec ecf="system.ecf" finalize="true"/>

  <gec clean="${system}"/>
]]>
	</programlisting>
	</section>

</chapter>
