Difference between revisions of "EC Command Line"

Latest revision as of 00:52, 14 July 2007

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 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

Rationale

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 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 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 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

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] [-h] [-n <processors>]
      [-s <name=value>, [-s <name=value>, ...]]

ec -c [<config file>] [-t <target>] -p [-o <path>] [-f [-k]] [-l] [-h] [-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.
• -e --ccompile: Perform a C compilation if required.
• -z --freeze: Perform a compilation that freezes, implies -e.
• -f --finalize: Perform a quick compilation that finalizes, implies -e.
• -k --keep: Keep assertions when finalizing (only valid with -f).
• -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.
• -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.