EiffelStudio: Using command line options

Compiling and viewing

The Eiffel Compiler line mode command ec has many options, as you can see from the tables below. It may be helpful to think of any one ec command as either a command to compile or a command to view software text.

Getting help

You can get details of the usage and options of the ec command by executing the command with the -help option.

ec -help

The usage and options display gives you information about which options are valid in a particular command context. Use this display along with the table below to choose the options that meet your needs.

Usage and options of the command line compiler vary from version to version in order to accommodate new and changed features. Here is an example of the command line help from the latest version of EiffelStudio:

ISE EiffelStudio version 18.11.10.2549 GPL Edition - win64 Usage: ec [-help | [-compat | -experiment] | -version | -full -batch | -clean | -verbose | -use_settings | -freeze | -finalize [-keep] | -precompile [-finalize [-keep]] | -c_compile | -loop | -debug | -quick_melt | -melt | -clients [-filter filtername] class | -suppliers [-filter filtername] class | -flatshort [-filter filtername] [-all | -all_and_parents | class] | -flat [-filter filtername] [-all | -all_and_parents | class] | -short [-filter filtername] [-all | -all_and_parents | class] | -pretty input_filename [output_filename] | -filter filtername [-all | class] | -descendants [-filter filtername] class | -ancestors [-filter filtername] class | -aversions [-filter filtername] class feature | -dversions [-filter filtername] class feature | -implementers [-filter filtername] class feature | -callers [-filter filtername] [-show_all] [-assigners | -creators] class feature | -callees [-filter filtername] [-show_all] [-assignees | -creators] class feature | [[-config config.ecf] [-target target] [-config_option option]| [class_file.e [-library library_name]] | -stop | -no_library | -project_path Project_directory_path | -file File | -ca_class (-all | class) | -ca_default | -ca_rule rule | -ca_setting file | -gc_stats] Options: default (no option): quick melt the system. -ancestors: show the ancestors of a class. -aversions: show the ancestor versions of a feature. -batch: launch the compilation without user request. -c_compile: launch C compilation if needed. -ca_class: analyze code of a class or of all non-library classes (-all). -ca_default: restore default code analyzer preferences. -ca_rule: activate code analyzer rule(s) (with settings). -ca_setting: load code analyzer preferences from a file. -callees: show the callees of a feature. -callers: show the callers of a feature. -class_file.e: specify a class file for single file compilation. -clean: delete existing project if any and perform a fresh compilation. -clients: show the clients of a class. -compat: enable pre-attached type compatibility. -config: specify the configuration (ECF) file. -config_option: override configuration options of a target. -debug: debug the system as a command loop. -descendants: show the descendants of a class. -dversions: show the descendant versions of a feature. -experiment: enable experimental functionalities. -file: save the output to a file. -filter: show a filtered form (troff, ...) of the class text. -finalize: finalize the system (discard assertions by default). -flat: show the flat form of a class. -flatshort: show the flat-short form of a class. -freeze: freeze the system. -full: with full class checking regardless of ECF settings. -gc_stats: Show GC statistics. -gui: start the graphical environment. -help: show this help message. -implementers: show the classes implementing a feature. -library: specify a library for single file compilation. -loop: run ec as a command loop. -melt: melt the system. -no_library: do not convert clusters into libraries. -overwrite_old_project: overwrite any existing old project. -precompile: precompile the system. -pretty: show the pretty form of a class. -project: specify the project file to load (obsolete). -project_path: specify the compilation directory. -quick_melt: quick melt the system. -short: show the short form of a class. -stop: stop on error. -suppliers: show the suppliers of a class. -target: specify the target. -use_settings: use settings for project location. -version: show compiler version number.

Commands for compiling

The simplest compiling command you can enter is:

ec

The command does not include any of the Compiling options shown below, so the default option "-melt" is used. The "-config" is omitted, so ec will try to find a configuration file named Ace.ecf in the current directory.

The command:

ec -config my_config_file.ecf

melts the system having the configuration file in the current directory my_config_file.ecf .

To freeze or finalize that system, you would just include the appropriate Compiling option:

ec -freeze -config my_config_file.ecf

You can specify the name of a file which contains the root class of a system in the current directory:

ec application.e

This command will compile a system with the class in application.e as its root. If there is no configuration file named application.ecf in the current directory, then ec will create one. It will also use any classes in the current working directory and by default the library EiffelBase.

Tip: This "configuration-less" form of compilation is convenient to use for a quick compile. But you should understand that because it does create a configuration file with default names for the configuration file itself, the project, and the root cluster, using it against a root class file in a folder in which a configuration file with another name already exists could lead to confusion.

You can add additional libraries to the configuration by using the "-library" option and specifying either the short name of one of the EiffelStudio libraries or a path to a library configuration file. To include EiffelTime in the compilation of application.e, you could use this command:

ec application.e -library time

This immediately adds the EiffelTime library to the configuration file application.ecf, so if you compile again, it is not necessary to respecify the library.

Commands for viewing

By selecting certain options on the ec command, you can generate advanced views of your software much like those provided by EiffelStudio. In the table below you will see the set of Viewing options. These options take arguments that are either a class name or a class name and feature name. The following examples will give you an idea of how to use the Viewing options.

To see the "flat" form of class APPLICATION in the example used above:

ec -flat application -config application.ecf

To save the output, add the "-file" option with a file name:

ec -flat application -config application.ecf -file application_flat_form.txt

Feature-oriented options, like "-implementers", take a class name and feature name:

ec -implementers application some_feature -config application.ecf

Commands for generating documentation

You can use variations of the viewing commands to generate documentation for your Eiffel system much like you can from EiffelStudio.

The following command will produce the Chart, Relations, and Text documentation for the "application" system in html-stylesheet format in the "Documentation" subfolder of the project folder.

ec -filter html-stylesheet -all -config application.ecf

To produce documentation for a view other than Text, use its option in the command. The following generates Chart, Relations, and Flat Short documentation:

ec -flatshort -filter html-stylesheet -all -config application.ecf

Commands for the Code Analyzer

The Code Analyzer is invoked when an option to analyze the whole system or a particular class is specified in the command line. Additional command-line options are used to specify some preferences and to enable specific rules:

ec -config project.ecf [-ca_class (-all | <CLASS_NAME(S)>) | -ca_default | -ca_rule <RULE_SPEC(S)> | -ca_setting <FILE_NAME>]

-ca_default

Requests to reset all Code Analyzer preferences to their default values before the analysis is run. For example, this enables all rules that are enabled by default, no matter whether they have been disabled before.

-ca_setting

Requests to use preferences from the specified file. The file is generated by exporting the current preferences from the GUI.

-ca_class

Asks to analyze a given class or a set of classes. Several class names can be specified, separated either by spaces or semicolons. In that case, the argument may need to be enclosed in double quotes (e.g., `"CLASS1; CLASS2"`). A special value `-all` triggers analysis of the whole system.

-ca_rule

Followed by a list of rules, enables those rules for the analysis and disables all the others, overriding the current preferences. Specific rule preferences can also be provided in parentheses. Preferences are separated by commas. The rule names can optionally be separated by semicolons. Example:

-ca_rule "CA001; CA033 (maximum_feature_count=10; maximum_instruction_count=100); CA066 (enforce_prefix=False)"

Command options

The table below lists the available options, the arguments they require, and their effect:

OPTION	ARGUMENTS	EFFECT
Compiling options
-melt		Melt compilation. This is the default option, if no other compiling or viewing option is specified.
-freeze		Freeze system.
-finalize		Finalize system. See note below.
-precompile		Precompile system, treating it as a library.
-full		Full class checking. Rechecks features of the parent classes for validity in heirs. See example in Converting existing software to void-safety. NOTE: Full class checking increases compile times, which may be noticeable in large systems.
-compat		Compile using facilities that are compatible with older versions of Eiffel.
-experiment		Compile using facilities that are compatible with an upcoming version of Eiffel.
Viewing options
-ancestors	class_name	Print the ancestors of the class.
-aversions	class_name, feature_name	Print the ancestor versions of the feature.
-callers	class_name, feature_name	Print all the routines that call the feature.
-clients	class_name	Print the clients of the class
-descendants	class_name	Print the descendants of the class.
-dversions	class_name, feature_name	Print all the versions of the feature in the descendant versions of the class.
-flat	class_name	Print the flat view of the class.
-flatshort	class_name	Print the Flat Contract view (previously called flat-short form) of the class.
-implementers	class_name, feature_name	Print all the classes that declare or redeclare the feature.
-short	class_name	Print the Contract view (previously called short form) of the class.
-suppliers	class_name	Print all the suppliers of the class.
Other options
-batch		Launch the compilation without user request.
-clean		Delete project if already compiled and compile project as if it was the first time.
-config	file_name	Use the file as configuration.
-c_compile		Launch C compilation, if needed, after Eiffel compilation.
-file	file_name	Save the output to the file.
-filter	filter_file_name	Print text as processed by the filter defined in the file named "filter_file_name.fil"
-help		Print the help.
-keep		Keep assertions in final mode. Useful with -finalize only.
-library	library_name	Library is included in the configuration when a file name for the root class is given.
-loop		Enter interactive mode. See: Command line interactive mode.
-metadata_cache_path	directory_name	Specify location of Metadata Cache used for .NET compilation. This overrides any settings from your configuration file.
-no_library		When converting an old configuration file format, do not convert clusters into libraries.
-project_path	directory_name	Use this directory as compilation directory. (Default: current directory.)
-stop		Stop on errors. (Default: no.)
-target	target_name	Act on the system target named target_name.
-use_settings		Use the project global settings to retrieve the project location for the last compilation of this project.
-verbose		Display detail progress report during compile.
-version		Print compiler version number.

Note: In the third column, to print means to produce the requested information on the default output of the ec command.

Note: When using -finalize, assertions will be discarded (unlike in EiffelStudio which asks first). The assertion disposition specified in the project configuration file can be retained in finalization by combining the -keep option with -finalize.

Some options can have modifiers that can affect their results. The modifiers are listed in the table below:

Option	Modifier	Effect
-callers
	-show_all	Include all callers rather than only those in the specified class.
	-assigners	Restrict callers to those that use given feature only as a target of an assignment instruction.
	-creators	Restrict callers to those that use given feature only as a target of a creation instruction.

See Also:
Batch compilation