EC Command Line - Revision history

Peter gummer: /* Rational */

2007-07-14T09:52:42Z

‎Rational

Paulb: /* Options */

2007-07-11T18:12:46Z

‎Options

Paulb: /* Backwards Compatibility */

2007-07-11T18:11:11Z

‎Backwards Compatibility

Paulb: Added categories

2007-07-11T18:10:10Z

Added categories

Paulb: /* Usage Groups */

2007-07-11T18:03:56Z

‎Usage Groups

Paulb: /* Options */

2007-07-11T18:03:44Z

‎Options

Paulb: First Editon

2007-07-11T18:02:12Z

First Editon

New page

== Overview ==
This page is used to rationalize a new command line interface for the Eiffel compiler, due for ''possible'' inclusion in 6.1 or some time after. The command line will use the commonly used Eiffel [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/framework/base/application/arg_parser/ argument parser framework library] so all usage options will be built/parsed automatically and respect platform differences.

{{Note|This document is not to be considered to represent a future edition. What is written here is for a ''possible'' future change to the Eiffel compiler}}

== Rational ==
The change has been consider for some time now. The current user interface is partly undocumented and visible options are not greatly documented either. The usage information is complex due aspects of evolution and unreadable, as such mires new users adoption of attempting to getting started. The option names are somewhat incorrect in places and there are no shorthands for advanced users wanting to create terse execution statements. In addition, the command option parser is weak and erroneous in some cases and is very difficult to maintain.

Eiffel Software's [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/framework/base/application/arg_parser/ argument parser library] is more than adequate at dealing with these shortcoming is a elegant, easily maintainable and extensible manner. It builds usage information automatically, permits command statement groups, support long and short name options, validates option values, support ''hidden'' developer options and is an opened ended extensible framework. Compounded with the [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/library/il8n il8n library] it also make for an internationalized version of the command line usage text.

== Backwards Compatibility ==
Backwards compatibility is a given, there is no way we can release a new command line interface without proving support for the myriad of scripts and tool out there already using the existing command line interface. That is to say, all scripts should still function as before, without modification. However the old command line interface will be considered deprecated and undocumented, its existence merely permits backwards compatibility.

=== The Existing Command Line Help ===
As a reference for backwards compatibility here is the command line usage information as of the 6.0 release of EiffelStudio:

Usage:
ec.exe [-help | -version | -batch | -clean | -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] |
-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 |
(obsolete) -ace Ace | (obsolete) -project Project_file_name] |
[class_file.e [-library library_name]] |
-stop | -no_library |
-project_path Project_directory_path | -file File]

== New Command Line ==
It has been discussed that documentation generation is largely unused in the command line interface, as so no new command line options are being defined for documentation generation. Instead the command line will focus on compilation.

=== Usage Groups ===
Compilation:
ec -c [<config file>] [-t <target>] [-o <path>] [-m|-q|-z|-f [-k]] [-l] [-q] [-n <processors>]
[-s <name=value>, [-s <name=value>, ...]]

ec -c [<config file>] [-t <target>] -p [-o <path>] [-f [-k]] [-l] [-q] [-n <processors>]
[-s <name=value>, [-s <name=value>, ...]]

ec -w <class file> [-b <library>, [-b <library>, ...]] [-n <processors>]

Interactive:
ec -i -c [<config file>]
ec -g

Debug:
ec -d

Version:
ec -v

==== Informative Options ====
* -v --version: Version information.
* -h --help (-? on Windows): Display full usage information.
* -nologo: Suppress copyright information.

==== Options ====
* -c --config: Specifies a configuration file.
* -m --melt: Perform a compilation that melts.
* -q --quick: Perform a quick compilation that melts.
* -z --freeze: Perform a compilation that freezes.
* -f --finalize: Perform a quick compilation that finalizes.
* -e --ccompile: Perform a C compilation if required.
* -k --keep: Keep assertions when finalizing (only valid with -f).
* -q --quiet: Emulation of ''batch''/''stop'' mode, prevents any prompts.
* -p --precompile: Performs a precompilation.
* -o --location: Alternative project compilation location.
* -w --class: Compile a single class
* -b --library: Specifies a library name or ECF library location.

==== Advanced Options ====
* -l --clean: Clean (lose) all previous compilation information.
* -s --setting: Overrides a ECF configuration setting, for current compilation only.
* -i --interactive: Enter interactive mode
* -d --debug: Enter debug mode.
* -n --nproc: Maximum number of processors/cores to utilize.

==== Hidden Options ====
* -g --gui: Show graphical environment.

=== Final Notes ===
The descriptions for each switch are by no means final or are to be considered as those being used. They are merely terse reference points for now.

The options will be case-sensitive to future proof against additional options requiring the use of the same short character but utilizing an alternative case.

← Older revision		Revision as of 18:10, 11 July 2007
Line 1:		Line 1:
		+	[[Category:Compiler]]
		+	[[Category:EiffelStudio]]
		+
	== Overview ==		== Overview ==
	This page is used to rationalize a new command line interface for the Eiffel compiler, due for ''possible'' inclusion in 6.1 or some time after. The command line will use the commonly used Eiffel [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/framework/base/application/arg_parser/ argument parser framework library] so all usage options will be built/parsed automatically and respect platform differences.		This page is used to rationalize a new command line interface for the Eiffel compiler, due for ''possible'' inclusion in 6.1 or some time after. The command line will use the commonly used Eiffel [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/framework/base/application/arg_parser/ argument parser framework library] so all usage options will be built/parsed automatically and respect platform differences.

@@ Line 7: / Line 7: @@
 {{Note|This document is not to be considered to represent a future edition. What is written here is for a ''possible'' future change to the Eiffel compiler}}
-== Rational ==
+== Rationale ==
-The change has been consider for some time now. The current user interface is partly undocumented and visible options are not greatly documented either. The usage information is complex due aspects of evolution and unreadable, as such mires new users adoption of attempting to getting started. The option names are somewhat incorrect in places and there are no shorthands for advanced users wanting to create terse execution statements. In addition, the command option parser is weak and erroneous in some cases and is very difficult to maintain.
+The change has been considered for some time now. The current user interface is partly undocumented and visible options are not greatly documented either. The usage information is complex due to aspects of evolution and unreadable, as such mires new users' adoption of attempting to getting started. The option names are somewhat incorrect in places and there are no shorthands for advanced users wanting to create terse execution statements. In addition, the command option parser is weak and erroneous in some cases and is very difficult to maintain.
-Eiffel Software's [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/framework/base/application/arg_parser/ argument parser library] is more than adequate at dealing with these shortcoming is a elegant, easily maintainable and extensible manner. It builds usage information automatically, permits command statement groups, support long and short name options, validates option values, support ''hidden'' developer options and is an opened ended extensible framework. Compounded with the [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/library/il8n il8n library] it also make for an internationalized version of the command line usage text.
+Eiffel Software's [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/framework/base/application/arg_parser/ argument parser library] is more than adequate at dealing with these shortcoming in an elegant, easily maintainable and extensible manner. It builds usage information automatically, permits command statement groups, supports long and short name options, validates option values, supports ''hidden'' developer options and is an open-ended extensible framework. Compounded with the [https://eiffelsoftware.origo.ethz.ch/svn/es/trunk/Src/library/il8n il8n library] it also make for an internationalized version of the command line usage text.
 == Backwards Compatibility ==

@@ Line 72: / Line 72: @@
 * -m --melt: Perform a compilation that melts.
 * -q --quick: Perform a quick compilation that melts.
 * -e --ccompile: Perform a C compilation if required.
 * -k --keep: Keep assertions when finalizing (only valid with -f).
 * -h --halt: Emulation of ''batch''/''stop'' mode, halts on any prompt and ends execution.

@@ Line 13: / Line 13: @@
 == Backwards Compatibility ==
-Backwards compatibility is a given, there is no way we can release a new command line interface without proving support for the myriad of scripts and tool out there already using the existing command line interface. That is to say, all scripts should still function as before, without modification. However the old command line interface will be considered deprecated and undocumented, its existence merely permits backwards compatibility.
+Backwards compatibility is a given, there is no way we can release a new command line interface without proving support for the myriad of scripts and tools out there already using the existing command line interface. That is to say, all scripts should still function as before, without modification. However the old command line interface will be considered deprecated and go undocumented in the future, its existence merely permits backwards compatibility.
 === The Existing Command Line Help ===

@@ Line 42: / Line 42: @@
 === Usage Groups ===
 Compilation:
-  ec -c [<config file>] [-t <target>] [-o <path>] [-m|-q|-z|-f [-k]] [-l] [-q] [-n <processors>]
+  ec -c [<config file>] [-t <target>] [-o <path>] [-m|-q|-z|-f [-k]] [-l] [-h] [-n <processors>]
         [-s <name=value>, [-s <name=value>, ...]]
-  ec -c [<config file>] [-t <target>] -p [-o <path>] [-f [-k]] [-l] [-q] [-n <processors>]
+  ec -c [<config file>] [-t <target>] -p [-o <path>] [-f [-k]] [-l] [-h] [-n <processors>]
         [-s <name=value>, [-s <name=value>, ...]]

@@ Line 73: / Line 73: @@
 * -e --ccompile: Perform a C compilation if required.
 * -k --keep: Keep assertions when finalizing (only valid with -f).
-* -q --quiet: Emulation of ''batch''/''stop'' mode, prevents any prompts.
+* -h --halt: Emulation of ''batch''/''stop'' mode, halts on any prompt and ends execution.
 * -p --precompile: Performs a precompilation.
 * -o --location: Alternative project compilation location.