mirror of
https://github.com/EiffelSoftware/eiffel-org.git
synced 2026-03-01 04:10:48 +01:00
Upcoming release 24.05
git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@2469 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
eifops
@@ -0,0 +1,10 @@
|
||||
[[Property:title|About the Code Document Object Model (CodeDom)]]
|
||||
[[Property:weight|0]]
|
||||
[[Property:uuid|46136373-34bb-94b7-1f7b-934d584cf637]]
|
||||
CodeDom stands for the '''Code Document Object Model'''. CodeDom allows for representing source code in an abstract data structure. Such a representation is called a '''CodeDom tree''' as the underlying data structure uses a tree paradigm. This abstract representation can then be generated into different programming languages. Each language vendor provides its implementation of the CodeDom interfaces, this implementation is called a '''CodeDom Provider'''. Programmers can then build tools that can work with many different languages without having to know about each one, instead they just delegate code generation to each CodeDom Provider.
|
||||
The CodeDom interfaces also expose types and methods that allow for parsing source code and creating the corresponding CodeDom. The current implementation of the Eiffel CodeDom Provider does not support parsing. Code generation is a much more popular useage of the CodeDom and the current version focuses on this aspect of the technology.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
[[Property:title|Common Scenarios]]
|
||||
[[Property:weight|7]]
|
||||
[[Property:uuid|15334d95-2ef5-6e1b-1754-051342bb7290]]
|
||||
==ASP.NET==
|
||||
Probably the most common use of the CodeDom technology is via Internet Information Services (IIS) and ASP.NET. The installation of the Eiffel for ASP.NET will configure the machine so ASP.NET pages can be written in Eiffel. Consult the [[Eiffel for ASP.NET Installation|Eiffel for ASP.NET documentation]] for details on how to write ASP.NET Eiffel pages.
|
||||
==WSDL==
|
||||
Another use of the CodeDom technology is via the WSDL utility. This utility is part of the .NET Framework SDK and is a common line application that can be used to automatically generate stub source code for any Web Service described by a Web Service Description Language (WSDL) file. It is possible to tell the utility which CodeDom Provider to use via the command line as follows:
|
||||
<code>
|
||||
Wsdl /language:"EiffelSoftware.CodeDom.CodeDomProvider, EiffelSoftware.CodeDom, Version=2.0.1.1402, Culture=neutral, PublicKeyToken=def26f296efef469"<br/>
|
||||
http://api.google.com/GoogleSearch.wsdl</code>
|
||||
|
||||
{{note|The version number used above might differ depending on the version of the Eiffel CodeDom Provider dll installed on your system. }}
|
||||
|
||||
{{note|The example above uses the Google web service, the corresponding URL is correct at the time of writing but there is no guarentee it won't change (or be removed) in the future. }}
|
||||
|
||||
This will generate a file with the extension '''.es''' which contains multiple Eiffel class definitions. Compiling this file will require using the CodeDom compiler (programmatically via the CodeDom <code>ICodeCompiler</code> interface) or using the [[eSplitter|eSplitter]] tool to generate standard Eiffel source files ('''.e''' files) that can then be compiled by the standard Eiffel compiler.
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
[[Property:title|Configuration]]
|
||||
[[Property:weight|3]]
|
||||
[[Property:uuid|2d885f05-adcc-d8da-6515-4568fc76bcf6]]
|
||||
The Eiffel Codedom Provider uses XML configuration files that define additional settings specific to Eiffel. Such settings include whether to fail on error, what events to log, where to log them etc... Each application can define its own configuration to be used when it loads the Eiffel CodeDom Provider. If an application is not associated with a configuration file then a default configuration is used.
|
||||
The association between applications and configurations as well as the actual settings the configuration defines can be set in the [[Eiffel CodeDom Provider Manager|Eiffel CodeDom Provider Manager]] . Run ''ecdpman.exe'' to start the manager.
|
||||
|
||||
{{note|The Eiffel for ASP.NET installation program will add a shortcut in the start menu to the Eiffel CodeDom Provider Manager. }}
|
||||
|
||||
{{seealso|[[Eiffel CodeDom Provider Manager|Eiffel CodeDom Provider Manager]] , [[Logging|Logging]] , [[Required Permissions|Required permissions]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
[[Property:title|Eiffel Implementation]]
|
||||
[[Property:weight|7]]
|
||||
[[Property:uuid|3f945c36-521e-cd71-fc7b-d549a6c05a04]]
|
||||
There are a few topics specific to the implementation of the Eiffel CodeDom Provider that are worth mentioning.
|
||||
==Multiple Classes File==
|
||||
The Eiffel compiler expects that there is only one class per source file (file with extension '''.e'''), however the CodeDom interface specification requires multiple classes to be generated in the same file (actually in the same ''stream''). The Eiffel CodeDom Provider code generator generates files with the extension '''.es''' which may contain multiple class definitions. Each class definition is separated with a special marker that the Eiffel CodeDom Provider compiler will parse to create multiple '''.e''' files - each containing a single class definition - prior to calling the command line Eiffel compiler.
|
||||
|
||||
|
||||
{{note|Only the Eiffel CodeDom Provider compiler knows how to handle '''.es''' files. The standard Eiffel compilers can only parse '''.e''' files. }}
|
||||
|
||||
Eiffel for ASP.NET includes the [[eSplitter|eSplitter]] utility which can 'split' Eiffel multi-class files ('''.es''' files) into single class files ('''.e''' files).
|
||||
==Inheritance Snippet==
|
||||
Any type defined in a CodeDom tree to be consumed by the Eiffel CodeDom Provider may include one (and only one) snippet member that includes an inheritance clause declaration. This ''inheritance snippet'' must start with the keyword '''inherit''' and follows the Eiffel syntax for inheritance clauses. All the feature adaptations available in the Eiffel programming language may be used in such a snippet ('''rename''', '''export''', '''undefine''', '''redefine''', '''select''').
|
||||
|
||||
|
||||
{{note|The CodeDom tree itself might define additional inheritance clauses in which case the Eiffel CodeDom Provider will merge the snippet and the implicit clauses in the generated source file. }}
|
||||
|
||||
==Indexing Snippet and Precompiled Libraries==
|
||||
Another interesting snippet member is the ''indexing clause snippet'' which must start with the '''indexing''' keyword and follows the Eiffel syntax for indexing clauses. This snippet may include the indexing clause '''precompile_definition_file''' which can be used to specify the path to the precompiled library ACE file to be used by the Eiffel CodeDom Compiler. This is specially useful in ASP.NET pages where each page can specify which precompiled ACE file to use when compiling it. This path will be used instead of the path defined in the [[Configuration|configuration file]].
|
||||
|
||||
|
||||
{{note|Only one class per compile unit should define a path to the precompiled library ACE file. If more than one class contain a '''precompile_definition_file''' indexing clause then there is no guarentee on which one the Eiffel CodeDom Compiler will use. }}
|
||||
|
||||
==Eiffel Configuration==
|
||||
There are several Eiffel specific settings that can be set in the Eiffel CodeDom Provider which will affect the generated code as well as the CodeDom compiler behavior. These settings are covered in the [[Configuration|Configuration]] section.
|
||||
|
||||
|
||||
{{seealso|[[eSplitter|eSplitter]], [[Configuration|Configuration]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
[[Property:title|The Eiffel CodeDom Provider]]
|
||||
[[Property:weight|0]]
|
||||
[[Property:uuid|0b45f31f-83ea-6301-9017-7b78c6827772]]
|
||||
The Eiffel CodeDom Provider provides an implementation of the CodeDom Provider generation and compilation interfaces defined in the System.CodeDom namespace of the .NET Framework. This documentation includes the following sections:
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
[[Property:title|Installation]]
|
||||
[[Property:weight|1]]
|
||||
[[Property:uuid|b6197932-4bcb-c79b-afe2-1a8f36dbbd7c]]
|
||||
For certain tools (including ASP.NET) to detect the availability of a CodeDom Provider, the corresponding assembly name must be listed in the .NET machine wide configuration file typically located in:
|
||||
<code>
|
||||
%SYSTEM_DRIVE%\Windows\Microsoft.NET\Framework\vx.x.xxxx\CONFIG\machine.config</code>
|
||||
(where vx.x.xxxx corresponds to the .NET Framework version number). The available CodeDom Providers are listed under the ''<compilers>'' XML node. The Eiffel CodeDom Provider implements a.NET Installer class so that should you need to add the Eiffel CodeDom Provider to the machine configuration file, simply run the .NET SDK command line utility ''InstallUtil'' as follows:
|
||||
<code>
|
||||
InstallUtil EiffelSoftware.Codedom.dll</code>
|
||||
Conversely, should the Eiffel Codedom Provider not be required anymore, running the following command line will remove it from the ''machine.config'' file:
|
||||
<code>
|
||||
InstallUtil /u EiffelSoftware.Codedom.dll</code>
|
||||
|
||||
{{note|The '''Eiffel for ASP.NET''' installation program will take care of registering and unregistering the Eiffel CodeDom Provider properly. }}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,10 @@
|
||||
[[Property:title|Limitations]]
|
||||
[[Property:weight|8]]
|
||||
[[Property:uuid|6d8ab90d-f051-5010-55df-218a020d9cb5]]
|
||||
==Generation Only==
|
||||
The current implementation of the Eiffel CodeDom Provider does not support parsing Eiffel source code to produce a CodeDom tree. Only code generation and compilation are supported in the current release.
|
||||
==Managed Code Only==
|
||||
Only managed code can be generated or compiled by the Eiffel CodeDom Provider. This means that the CodeDom tree being compiled cannot include snippet members which use or define Eiffel external clauses. If the system requires access to external methods, they should be defined in a precompiled library (see [[Configuration|Configuration]] ).
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
[[Property:title|Logging]]
|
||||
[[Property:weight|4]]
|
||||
[[Property:uuid|d425684b-687c-aee6-25fa-650e5885e014]]
|
||||
The Eiffel CodeDom Provider may be configured (via the [[Eiffel CodeDom Provider Manager|Eiffel Codedom Provider Manager]] ) to log information, warnings and/or errors in the Windows Event Log. Logging may be useful for a number of reasons, some of them are:
|
||||
* To detect which CodeDom interface method is called and when it's called. This is particularly useful when the source code for the CodeDom consumer (e.g. ASP.NET) is not available.
|
||||
* To locate the source of a problem when the code generated by the Eiffel CodeDom Provider is incomplete or incorrect. This may happen if the CodeDom tree given to the Eiffel CodeDom Provider uses one of the unsupported constructs as listed in the topic [[Supported Constructs|Supported Constructs]] .
|
||||
* To detect a problem in a CodeDom tree. The logs will help in locating the location of the problem as they include contextual information on the node where the error occurred.
|
||||
|
||||
==Log Details==
|
||||
There are three types of events that can be logged: information events, warnings and errors:
|
||||
* Information events include calls to CodeDom interface methods and other events that will not affect the execution of the Eiffel CodeDom Provider
|
||||
* Warnings include events that will not prevent the CodeDom Provider from running but that may affect the results. For example if a CodeDom tree element references a .NET entity that the Eiffel CodeDom Provider cannot find then it will generate a default Eiffel name by running the default formatting algorithm. This may produce code that does not compile if the Eiffel name of the entity does not correspond to the formatted .NET name (for example if the entity is a type and the type's assembly has a non-empty prefix).
|
||||
* Errors include events that will force the execution of the Eiffel CodeDom Provider to stop. By default the Eiffel CodeDom Provider simply stops and returns an error, it is possible however to configure it so that an exception is raised.
|
||||
|
||||
==Log Location==
|
||||
All the Eiffel CodeDom Provider events are logged into the Windows '''System''' Log. This log can be viewed via the Windows administrative tool ''Event Viewer''. The source for the events raised by the Eiffel CodeDom Provider is ''Eiffel CodeDom Provider''. By default all the events are logged on the machine running the Eiffel CodeDom Provider but it is possible to change its configuration so that the events are logged on a different machine (see [[Required Permissions|Required permissions]] ).
|
||||
{{seealso|[[Eiffel CodeDom Provider Manager|Eiffel CodeDom Provider Manager]] , [[Supported Constructs|Supported constructs]] , [[Required Permissions|Required permissions]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
[[Property:title|Required Permissions]]
|
||||
[[Property:weight|6]]
|
||||
[[Property:uuid|f55af6a0-b896-12b7-fe4a-ebb1787731e5]]
|
||||
The account running the Eiffel CodeDom Provider might have restricted permissions such as when used through ASP.NET. This section aims at defining the security permissions required for the execution of the Eiffel CodeDom Provider.
|
||||
==Eiffel Metadata Cache==
|
||||
Both when generating and compiling source code, the Eiffel CodeDom Provider needs to read and write from and to the Eiffel Metadata Cache. This repository stores the mapping information between .NET and Eiffel names for both types and their members. By default the Eiffel Metadata Cache is located in the ''Assemblies'' subfolder of the Eiffel CodeDom Provider directory.
|
||||
{{note|The Eiffel for ASP.NET installation program will grant read and write access to the Eiffel Metadata Cache folder for the ''ASPNET'' (default ASP.NET worker process account on Windows XP Professional) and the ''IIS_WPG'' (default ASP.NET worker process account on Windows Server 2003) accounts. }}
|
||||
The path to the Eiffel Metadata Cache folder might be changed via the [[Eiffel CodeDom Provider Manager|Eiffel CodeDom Provider Manager]] , make sure the new folder can be read from and written to by the account running the process that uses the Eiffel CodeDom Provider.
|
||||
==Precompile Cache==
|
||||
The same requirements apply to the Precompile Cache folder. By default the Precompile Cache folder is located in the ''Precompile'' subfolder of the Eiffel CodeDom directory.
|
||||
{{note|The Eiffel for ASP.NET installation program will grant read and write access to the Precompile Cache folder for the ''ASPNET'' (default ASP.NET worker process account on Windows XP Professional) and the ''IIS_WPG'' (default ASP.NET worker process account on Windows Server 2003) accounts. }}
|
||||
As with the Eiffel Metadata Cache folder, it is possible to change the location of the Precompile Cache folder but the process running the Eiffel CodeDom Provider must always have read and write access to the folder.
|
||||
==Logging==
|
||||
Logging requires registry read access as well as event log write access. By default, the ASP.NET worker process does not have these permissions. The easiest way to grant the required permissions to the ASP.NET worker process is by using ASP.NET impersonation. This mechanism allows the ASP.NET worker process to run under a different account. This is done by providing a ''web.config'' file in the root folder of the ASP.NET application. The content of the configuration file needs to include the following declaration:
|
||||
<code>
|
||||
<configuration>
|
||||
<system.web>
|
||||
<identity impersonate="true" userName="Username" password="Password"/>
|
||||
</system.web>
|
||||
</configuration></code>
|
||||
where <code>Username</code> is the name of an account which has all the required permissions and <code>Password</code> the corresponding password. Refer to the .NET Framework SDK documentation for additional information on ASP.NET impersonation.
|
||||
The solution described above might not be acceptable on a production web server. However, it is possible to configure the Eiffel CodeDom Provider to log events on a different machine (see [[Eiffel CodeDom Provider Manager|Eiffel CodeDom Provider Manager]] ). The log machine should grant the appropriate permissions to the impersonated account for logging and could only be accessible through the web server. This setting would avoid having to grant additional permissions to the ASP.NET worker process account on the web server while still enabling logging.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
[[Property:title|Supported Constructs]]
|
||||
[[Property:weight|2]]
|
||||
[[Property:uuid|99e15890-75a9-8b76-d0b6-b9be419be5ce]]
|
||||
Since not every language might support all the constructs CodeDom can represent, there needs to be a way for the CodeDom Provider to specify which constructs are supported and which ones are not. This is done through the <code>System.Codedom.Compiler.ICodeGenerator</code> interface using method <code>Supports</code>.<br/>
|
||||
This method takes a flag corresponding to the CodeDom contruct the caller is interested in and returns a boolean value indicating whether or not the construct is supported. In the Eiffel CodeDom Provider implementation there is a third category of constructs which will be reported as supported since the provider will generate valid Eiffel code for them but that should be distinguished from other "truly" supported constructs as the generated code will not correspond to the .NET equivalent of the construct.<br/>
|
||||
Let's take an example: Enum declarations are supported by the Eiffel CodeDom Provider because the generated Eiffel code will correctly make use of the values defined in the enum. However there is no such thing as an enum type in Eiffel so there won't be a corresponding .NET enum type in the generated assembly. Such constructs are said to be "non-roundtripable" because even if the Eiffel CodeDom Provider supported parsing source code, the corresponding CodeDom tree would not include the constructs like the initial CodeDom did.
|
||||
The lists of supported, supported without roundtrip and unsupported constructs for the Eiffel CodeDom Provider are as follows:
|
||||
|
||||
'''Supported constructs''':
|
||||
* Arrays of arrays
|
||||
* Assembly attributes
|
||||
* Complex expressions
|
||||
* Declare value types
|
||||
* Entry point method
|
||||
* Multiple interface members
|
||||
'''Supported constructs (no roundtrip)''':
|
||||
* Declare enums
|
||||
* Declare events
|
||||
* Declare interfaces
|
||||
* Nested types
|
||||
* Public static members
|
||||
* Reference parameters
|
||||
* Try catch statements
|
||||
'''Unsupported constructs''':
|
||||
* Chained constructor arguments
|
||||
* Declare delegates
|
||||
* Goto statements
|
||||
* Multidimensional arrays
|
||||
* Parameter attributes
|
||||
* Return type attributes
|
||||
* Static constructors
|
||||
* Win32 resources
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user