ESD - Eiffel System Description

Abstract

This document describes an important part of Visual Eiffel - the project/library description facility. Eiffel itself is only a language, but for a practical programming we need a little bit more. Bertrand Meyer offers a special language called LACE (Language for Assembling Components in Eiffel) to support systems development. This language is not a part of Eiffel, so we developed our own language to support the flexibility of Visual Eiffel. We investigated PDL (Project Description Language) of the Eiffel/S compiler and took some features from it, but as we had to support such features as compiler options on a per cluster or even per class basis, different output targets, precompiled libraries and so on we had to extend it. This paper presents the lexical structure and syntax of ESD (the Eiffel System Description) language, and describes the semantics of all its constructions.

Contents

Introduction
Syntax
General Notes
System
Cluster
Class
Examples
default esd file


Introduction

The Eiffel system description (ESD) is a special set of directives, options and commands which describe where to find classes for a current project or library, how to resolve class name clashes and which kind of executable is to be built as a result of compilation. ESD is supported by a special language which is similar to Eiffel/S PDL but has some advanced features and abilities. ESD also supports precompiled libraries by saving a small library description to disk.


Syntax

Keywords

SAL uses the following keywords:

as , assertions
call_back, calls, check, class, cluster, code ,console, constants , creation
debug , dll, dyn_type
end, ensure, exe
fst
heap_size
inline, interface, invariant
leaves, library, link, linker, loop
makepath, native
off, on, once, optimize, option
p_code
rename, require, root , run_time
select, stack_size, strip, subscript, system
target , threshold
variant

If one of these identifiers is used with a different meaning (for example as the name of the root class) it must be enclosed in quotes:

root "target"
creation "native"

ESD supports comments in the Eiffel style, to make your ESD files clearer for you and for others. ESD has an LL-1 grammar, which allows it to be a very simple and rather flexible language. ESD is not case sensitive, so the words MakePath and maKepAth mean the same thing. We suggest that you write everything in lower case, but this is only a suggestion.

Complete Syntax Description

<EiffelSystemDescription> ::= <SystemDescription> | <LibraryDescription>
<SystemDescription> ::=
"system" <ExecutableFileName>
"root" <RootClassName>
"creation" <CreationProcedureName>
"cluster" <ClusterDescription> { <ClusterDescription> }
[ "callback" { <ClassCallBacks> } ]
[ "interface" { <ClassName> } ]
[ "makepath" { <ClusterName> <FileName> } ]
[ "link" { <FileName> } ]
[ "option" { <SystemOption> } ]
"end"
<ClassCallBacks> ::= [ "class" ]
<ClassName> [ ":" ] <RoutineName>
{ [ "," ] <RoutineName> } "end"
<ClusterDescription> ::=
<ClusterNname>
[ "rename" { <ClassName> "as" <ClassName> } ] -- Not supported yet
[ "select" { <ClassName> "as" <ClassName> } ] -- Not supported yet
{ "class" <ClassName> ["option"] { <ClassOption> } "end" }
[ "option" { <ClusterOption> } ]
"end"
<LibraryDescription> ::=
"library" <FileNameWithoutExtension>
[ "cluster" { <ClusterName> "end" } ]
"end"
<SystemOption> ::=
    <ClusterOption>
|   "target" ("EXE"|"DLL") [ "console" ]  
|   <OptimizeOpt>
|   "threshold" <IntegerConstant>
|   "heap_size" <IntegerConstant>
|   "stack_size" <IntegerConstant>
|   <Csubscript>
|   "run_time" "DLL"
|   "debug" <Toggle>
|   "assertions" <Toggle>
|   "require" <Toggle>
|   "ensure" <Toggle>
|   "class" "invariant" <Toggle>
|   "loop" "invariant" <Toggle>
|   "loop" "variant" <Toggle>
|   <StripDebugOpt>
<ClusterOption> ::=
"subscript" <Toggle>
|   "strip" "debug" <Toggle>
|   <CodeOpt>
<ClassOption> ::= <ClusterOption>
<CodeOpt> ::= "code" ("native" | "p_code")
<OptimizeOpt> ::=
"optimize"
    ("FST" | "calls" | "dyn_type" | "leaves" | "constants" | "once" | "inline")
    <Toggle>
<Toggle> ::= "on" | "off"
<ExecutableFileName> ::= <Identifier> | <String>
<RootClassName> ::= <Identifier> | <String>
<CreationProcedureName> ::= <Identifier> | <String>
<FileName> ::= <Identifier> | <String>
<ClassName> ::= <Identifier> | <String>
<FileNameWithoutExtension> ::= <Identifier> | <String>
<RoutineName> ::= <Identifier> | <String>

General notes

A <String> can contain references to environment/registry variables in the following form: $ENV. This means that all occurrences of this form will be replaced with actual value of the variable ENV in the registry or the environment. If you have cluster names beginning with $ then you will have to specify $$ which will be interpreted as $ with no substitution.

Each system or library description should include the current cluster description. This can be done in one of the following ways:

"."
end
-- the actual path
"c:\bla-bla-bla"
end
-- or giving the full path
"..\current"
end
-- or with a path relative to the current cluster

Brief description of the ESD options

Default Settings


System options

These options apply to the entire system, i.e. for all classes included in the system. Cluster options and class options are stronger than system options, and override them if specified.


Cluster options


Class options


Examples

-- The first example shows how to describe an Eiffel system:

system "..\bin\empty" -- name of the executable module (may include a path)
	root
		empty -- name of the root class
	creation
		make -- name of the creation procedure of the root class
	cluster -- list of all clusters of the system
		"."
		end
		"$VE_lib\kernel"
		end
	link -- list of external object files to be passed to the linker
		aaa.obj bbb.obj kljh.lib iuyt.res
		-- Attention! Do not separate files in this list with commas,
		-- semicolons or other separators
	option -- list of system-wide options
		-- Options can be listed in any order. An option may appear more
		-- than once in the list, in which case the last one will apply.
		target			DLL	-- default value EXE
		linker			default
		debug			on	-- default value off
		require			on	-- default value off
		ensure			on	-- default value off
		class invariant		off	-- default value off
		loop  invariant		on	-- default value off
		loop  variant		off	-- default value off
		optimize FST		off	-- default value on
		optimize calls		on	-- default value off
		optimize dyn_type	off	-- default value on
		optimize leaves		on	-- default value off
		strip debug		off	-- default value on
end
-- A further example demonstrates the difference between
-- a system description and a library description:

library "..\LIB\GRAPE" -- library should not have an extension!
	cluster -- list of all libraries which are necessary to build this library
		"."
		end
		"$VE_lib\ES13LIB"
		end
		"$VE_lib\KERNEL"
		end
end

Creating a new esd file

can be done by calling the Visual Eiffel compiler with the /cpt option:

vec /cpt:my_class,my_program

the result is a new .esd file with the following content. If necessary one can change now the name of the creation procedure (it is called make by default). Note that no space is allowed between the comma and "my_program".


system MY_PROGRAM -- name of the executable module (possibly with path)
root MY_CLASS -- name of the root class
creation make -- name of the creation procedure
cluster -- list of all clusters of the system (including libraries)
	"."
	end
	"$VE_LIB\Kernel"
end

...and so on.


Copyright © Object Tools -- info@object-tools.com
Last updated: $Date: 2005/02/02 11:51:33 $