<?xml version="1.0"?> 

<!--
	description:

		"Using gec"

	tool: "Gobo Eiffel Compiler"
	copyright: "Copyright (c) 2006-2016, Eric Bezault and others"
	license: "MIT License"
	date: "$Date$"
	revision: "$Revision$"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="gec/usage">
<chapterinfo>
	<copyright>
		<year>2006-2016</year>
		<holder>Eric Bezault</holder>
	</copyright>
	<author>
		<firstname>Eric</firstname><surname>Bezault</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>27 December 2016</date>
</chapterinfo>

<title>Using gec</title>

<section><title>Command-line options</title>
<para>
The usual way to invoke <projectname>gec</projectname> is as follows:
<blockquote>
	<filename>gec ace_filename</filename>
</blockquote>
This will read the description of your program in the Ace file
<filename>ace_filename</filename>, compile it and invoke the
back-end C compiler on the generated C code as explained
below. Here is the list of options that can be
used with <projectname>gec</projectname>:
<variablelist>
	<varlistentry>
		<term>
			<filename>-h</filename>
		</term>
		<term>
			<filename>--help</filename>
		</term>
		<listitem><para>
			Print a summary of the command-line options of <projectname>gec</projectname> and exit.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--finalize</filename>
		</term>
		<listitem><para>
			Compile with optimizations turned on.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--cat</filename>
		</term>
		<listitem><para>
			CAT-call errors should be considered as fatal errors.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--split=&lt;no|yes&gt;</filename>
		</term>
		<listitem><para>
			Should generated C code be split over several C files instead of being held in a single possibly large C file? (default: yes)
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--split-size=&lt;size&gt;</filename>
		</term>
		<listitem><para>
			Size (in bytes) of generated C files in bytes when in split mode
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--cc=&lt;no|yes&gt;</filename>
		</term>
		<listitem><para>
			Should the back-end C compiler be invoked on the generated C code? (default: yes)
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--gc=&lt;no|boehm&gt;</filename>
		</term>
		<listitem><para>
			Which garbage collector should the application be compiled with? (default: no)
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--silent</filename>
		</term>
		<listitem><para>
			Run <projectname>gec</projectname> in silent mode.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--verbose</filename>
		</term>
		<listitem><para>
			Run <projectname>gec</projectname> in verbose mode.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>-V</filename>
		</term>
		<term>
			<filename>--version</filename>
		</term>
		<listitem><para>
			Print the version number of <projectname>gec</projectname> and exit.
		</para></listitem>
	</varlistentry>
</variablelist>
</para>
</section>

<section><title>Ace files</title>
<para>
An Ace file contains the description of the Eiffel program to be compiled.
<projectname>gec</projectname> is able to read the same Ace files as
ISE Eiffel. So if you already have your Ace files the only thing you have
to do is to instruct <projectname>gec</projectname> to use
<libraryname>FreeELKS</libraryname> kernel classes instead of ISE
<libraryname>EiffelBase</libraryname> kernel classes. To do so you just
have to replace the EiffelBase clusters in your Ace file by:
<informalexample>
	<filename class="directory">all free_elks: "${GOBO}/library/free_elks"</filename>
</informalexample>
If you are new to Eiffel and don't know what an Ace file is, please have
a look at this <link linkend="${library/tools}/ace">description</link> from the
documentation of the <libraryname>Gobo Eiffel Tools Library</libraryname>
on which <projectname>gec</projectname> is based.
</para>
</section>

<section><title>Back-end C compiler</title>
<para>
<projectname>gec</projectname> translates your Eiffel programs into C code.
This C code is then passed to a back-end C compiler to generate an executable.
By default <projectname>gec</projectname> uses Microsoft Visual C
<projectname>cl</projectname> on Windows and GNU <projectname>gcc</projectname>
on other operating systems such as Linux. This section explains how to override
this default if you want to use another back-end C compiler or if you want to
specify different C compilation options.
</para>
<para>
For each C compiler that you want to use as back-end C compiler, you should
provide a config file that should be located in
<filename class="directory">$GOBO/tool/gec/config/c/</filename>. Here is an
example of such config file, <filename>gcc.cfg</filename> for the
<projectname>gcc</projectname> compiler:
<blockquote><programlisting>
cc: gcc $cflags $includes -c $c
link: gcc $lflags -lm -o $exe $objs $libs
obj: .o
exe:
cflags: 
lflags:
cflags_finalize: -O2
lflags_finalize:
</programlisting></blockquote>
This config file is used by <projectname>gec</projectname> to generate a
.bat file on Windows or a shell script on other platforms that will be
executed to compile the generated C code. The variable "cc" represents the
command-line template to turn C files into object files, and "link" to
turn object files into executables. The variables "$cflags", "$includes",
"$c" in the first template, and "$lflags", "$exe", "$objs" and "$libs"
in the second template will be replaced by appropriate values by 
<projectname>gec</projectname>. Next, the variables "obj" and "exe"
represent the file extensions for object files and executables on the
platform on which this C compiler will be invoked. And finally we find
C compilation and linker flags that should be used when
<projectname>gec</projectname> is invoked with or without the
command-line option "--finalize". Note that Eiffel-style comments,
starting with "--", can be included in these config files.
</para>
<para>
There are several ways to instruct <projectname>gec</projectname> to
use a different back-end C compiler. You can either write the name
of the chosen C compiler in the file <filename>$GOBO/tool/gec/config/c/default.cfg</filename>.
You might need to create this file if it does not exist yet. Alternatively
you can specify the name of the chosen C compiler in the environment
variable $GOBO_CC. Let's say that the name of your chosen C compiler
is <projectname>my_cc</projectname>. <projectname>gec</projectname> will
then look for the config file <filename>$GOBO/tool/gec/config/c/my_cc.cfg</filename>.
</para>
</section>

</chapter>
