Using gec |

## Command-line options

The usual way to invoke gec is as follows:

> `gec ecf_filename`

This will read the description of your program in the ECF file `ecf_filename`, compile it and invoke the back-end C compiler on the generated C code as explained below.

For simple programs, one can just provide the Eiffel file containing the root class:

> `gec eiffel_filename`

Here is the list of options that can be used with gec:

`-h`
`--help`
  Print a summary of the command-line options of gec and exit.
`--target=<target_name>`
  Name of target to be used in ECF file. (default: last target in ECF file)
`--finalize`
  Compile with optimizations turned on.
`--gelint`
  Run gelint on the full content of each class being compiled.
`--ise=major[.minor[.revision[.build]]]`
  Version of ISE Eiffel whose semantics should be used during compilation.
`--catcall=<no|error|warning>`
  Should CAT-call errors be considered as fatal errors, as warnings, or just ignored? (default: no)
`--split=<no|yes>`
  Should generated C code be split over several C files instead of being held in a single possibly large C file? (default: yes)
`--split-size=<size>`
  Size (in bytes) of generated C files in bytes when in split mode. (default: 2,500,000)
`--cc=<no|script|gecc>`
  Should the back-end C compiler be invoked on the generated C code, and if yes with what method? Use `gecc` to allow the generated C code to be compiled using multiple threads. (default: gecc)
`--new-instance-types=<filename>`
  File containing the list of types which can have instances created by 'TYPE.new_instance' or 'TYPE.new_special_any_instance'. (default: use all non-deferred, non-NONE, alive types)
`--gc=<no|boehm>`
  Which garbage collector should the application be compiled with? Note that the Boehm GC is included into the Gobo Eiffel package. (default: boehm if available, no otherwise)
`--setting=name=value`
  Override settings defined in ECF file. This option can be used several times to override several settings.
`--capability=name=value`
  Override capability usage defined in ECF file. This option can be used several times to override several capabilities.
`--variable=NAME=VALUE`
  Override variables defined in ECF file. This option can be used several times to override several variables.
`--thread=<thread_count>`
  Number of threads to be used to run gec. Negative numbers -N mean "number of CPUs - N". (default: -3, aka "max (number of CPUs -3, 1)")
`--silent`
  Run gec in silent mode.
`--verbose`
  Run gec in verbose mode.
`--no-benchmark`
  Should no benchmark information be displayed? (default: display non-nested benchmark information)
`--nested-benchmark`
  Should nested benchmark information be displayed?
`--metrics`
  Should metrics information be displayed?
`-V`
`--version`
  Print the version number of gec and exit.

## Environment variables

It is possible to override some of the command-line options above, or the default values for these options, using environment variables.

`$GOBO_CLI_GC`
  Override the command-line option `--gc`.
`$GOBO_DEFAULT_GC`
  Override the default value when the command-line option `--gc` has not been specified and the environment variable `$GOBO_CLI_GC` has not been set.
`$GOBO_CLI_SETTING`
  Override settings as if they were specified with the command-line option `--setting`, or override their values if they are also specified with the command-line option. Several settings can be specified in this environment variable, separated by a comma or a space.
`$GOBO_DEFAULT_SETTING`
  Override the default value for a given setting when the command-line option `--setting` or the environment variable `$GOBO_CLI_SETTING` did not set it. Several settings can be specified in this environment variable, separated by a comma or a space.
`$GOBO_CLI_CAPABILITY`
  Override capabilities as if they were specified with the command-line option `--capability`, or override their values if they are also specified with the command-line option. Several capabilities can be specified in this environment variable, separated by a comma or a space.
`$GOBO_DEFAULT_CAPABILITY`
  Override the default value for a given capability when the command-line option `--capability` or the environment variable `$GOBO_CLI_CAPABILITY` did not set it. Several capabilities can be specified in this environment variable, separated by a comma or a space.

## ECF files

An ECF file contains the description of the Eiffel program to be compiled. gec is able to read the same ECF files as ISE Eiffel. So if you already have your ECF files, you can use them without any modifications with gec.

If you are new to Eiffel and don't know what an ECF file is, please have a look at this description from the documentation of the Gobo Eiffel Tools Library on which gec is based.

Note that for simple programs like a hello_world program, it is not necessary to provide an ECF file. You can just let gec know in which Eiffel file it can find the root class of the Eiffel system:

> `gec hello_world.e`

It will use the first creation procedure declared in the `create` clause of the root class as root creation procedure. This will work fine provided that all classes used in your simple program are part of one of the libraries provided in the Gobo Eiffel Project. You can give it a try using the `HELLO_WORLD` class provided in `$GOBO/library/common/example/hello_world/hello_world.e`. An ECF file will be needed when you want to use classes from other libraries or if you want to override the default settings (e.g. console application, SCOOP mode).

## Back-end C compiler

gec 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 gec uses the Zig toolchain which is included into the Gobo Eiffel package. 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.

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 `$GOBO/tool/gec/backend/c/config/`. Here is an example of such config file, `gcc.cfg` for the gcc compiler:

>     cc: gcc $cflags $includes -c $c
>     link: gcc $lflags -lm -o $exe $objs $libs
>     obj: .o
>     exe:
>     cflags:
>     lflags:
>     cflags_finalize: -O2
>     lflags_finalize:

This config file is used by gec 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 gec. 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 gec is invoked with or without the command-line option `--finalize`. Note that Eiffel-style comments, starting with "--", can be included in these config files.

There are several ways to instruct gec to use a different back-end C compiler. You can either write the name of the chosen C compiler in the file `$GOBO/tool/gec/backend/c/config/default.cfg`. 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 my_cc. gec will then look for the config file `$GOBO/tool/gec/backend/c/config/my_cc.cfg`.