mirror of
https://github.com/SSCLI/sscli_20021101
synced 2026-06-08 12:28:57 +00:00
yallie
245 lines
9.7 KiB
HTML
245 lines
9.7 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<TITLE>CIL Assembler (Ilasm.exe)</TITLE>
|
|
<link rel="stylesheet" type="text/css" href="../rotor.css">
|
|
</head>
|
|
<body>
|
|
|
|
<H1>CIL Assembler (Ilasm.exe/ilasm)</H1>
|
|
|
|
<P>The Common Intermediate Language (CIL) Assembler generates a portable executable (PE) file from
|
|
CIL assembly language. You can run the resulting executable, which contains CIL and the required metadata, to determine whether the
|
|
CIL performs as expected.</P>
|
|
|
|
<p>The application file for the CIL assembler is named ilasm.exe in
|
|
the Shared Source CLI (SSCLI) when built on Microsoft Windows®. It is named
|
|
ilasm in the SSCLI when built on UNIX system-based platforms.</p>
|
|
|
|
<h4>Usage</h4>
|
|
|
|
<blockquote>
|
|
|
|
<PRE class="syntax"><B>ilasm </B>[<I>options</I>] <I>filename</I> [[<I>options</I>]<I>filename...</I>]</PRE>
|
|
</blockquote>
|
|
<table border=1>
|
|
|
|
<TR VALIGN="top">
|
|
<TH width=33%>Argument</TH>
|
|
<TH width=67%>Description</TH>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><I>filename</I></TD>
|
|
<TD width=67%>The name of the .il source file. This file consists of metadata declaration directives and symbolic
|
|
CIL instructions. Multiple source file arguments can be supplied to produce a single PE file with
|
|
the CIL Assembler.</TD>
|
|
</TR>
|
|
</table>
|
|
|
|
<h4 align="left">Options</h4>
|
|
|
|
<p align="left">Note: The SSCLI implementation does not support
|
|
Microsoft Win32® resources or cryptographic key containers. The following
|
|
options in the Microsoft .NET Framework implementation of the Microsoft
|
|
Intermediate Language Assembler are
|
|
not be supported by the SSCLI implementation of the CIL assembler.</p>
|
|
|
|
<ul>
|
|
<li>
|
|
|
|
<p align="left"><b>/resources</b>=<res_file> where <i>res_file</i> is a Win32 .res
|
|
resource file.</p>
|
|
|
|
</li>
|
|
<li>
|
|
|
|
<p align="left"><b>/KEY</b>=@<keysource> where <i>keysource</i> is a
|
|
cryptographic key container.</p>
|
|
|
|
</li>
|
|
</ul>
|
|
|
|
<p align="left">The following options are supported in the SSCLI Ilasm
|
|
implementation.</p>
|
|
|
|
<p align="left">Options can be specified using either a dash (-) or a slash
|
|
(/). </p>
|
|
|
|
<table border=1>
|
|
<TR VALIGN="top">
|
|
<TH width=33%>Option</TH>
|
|
<TH width=67%>Description</TH>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/alignment=</B><I>integer</I></TD>
|
|
<TD width=67%>Sets FileAlignment to the value specified by <I>integer</I> in the
|
|
Microsoft Windows NT® Optional header. If the .alignment CIL directive is specified in the file, this option overrides it. </TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/base=</B><I>integer</I></TD>
|
|
<TD width=67%>Sets ImageBase to the value specified by <I>integer</I> in the
|
|
Windows NT Optional header. If the .imagebase
|
|
CIL directive is specified in the file, this option overrides it.<p>The
|
|
resulting portable executable (PE) file modification has significance only on
|
|
the Windows platform.</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/clock</B></TD>
|
|
<TD width=67%>Measures and reports the following compilation times in milliseconds for the specified .il source file:
|
|
<ul>
|
|
<li>Total Run<ul>
|
|
<li>The total time spent performing all the specific operations that follow.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Startup<ul>
|
|
<li>Loading and opening the file.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Parsing<ul>
|
|
<li>Reading the .il file into memory and generating parse-tree data structures.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Emitting MD<ul>
|
|
<li>Emitting metadata.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Ref to Def Resolution<ul>
|
|
<li>Resolving references to definitions in the file.</li>
|
|
</ul>
|
|
</li>
|
|
<li>Fixup and Linking<ul>
|
|
<li>RVA location resolution and name resolution.</li>
|
|
</ul>
|
|
</li>
|
|
<li>CEE File Generation<ul>
|
|
<li>Generating the file image in memory.</li>
|
|
</ul>
|
|
</li>
|
|
<li>PE File Writing<ul>
|
|
<li>Writing the image to a PE file.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/debug</B></TD>
|
|
<TD width=67%>Includes debug information (local variable and argument names, and line numbers).</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/dll</B></TD>
|
|
<TD width=67%>Produces a .dll file as output.</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/exe</B></TD>
|
|
<TD width=67%>Produces an executable file as output. This is the default.</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/flags=</B><I>integer</I></TD>
|
|
<TD width=67%>Sets ImageFlags to the value specified by <I>integer</I> in the
|
|
common language runtime header. If the .corflags CIL directive is specified in the file, this option overrides it. See CorHdr.h , COMIMAGE_FLAGS for a list of valid values for <I>integer</I>.</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/key:</B><I>keyFile</I></TD>
|
|
<TD width=67%>Compiles <I>filename </I>with a strong signature using the private key contained in <I>keyFile</I>.</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/listing</B></TD>
|
|
<TD width=67%>Sends a listing file to the standard output. If you omit this option, no listing file is produced.</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/nologo</B></TD>
|
|
<TD width=67%>Suppresses the Microsoft startup banner display.</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/output:</B><I>file.ext</I></TD>
|
|
<TD width=67%>Specifies the output file name and extension. By default, the output file name is the same as the name of the first source file.
|
|
The default extension is .exe. If you specify the <B>/dll</B> option, the default extension is .dll.
|
|
<P class=indent>Note: Specifying <B>/output:</B>myfile.dll does not set the<B> /dll </B>option. If you do not specify <B>/dll</B>,
|
|
the result will be an executable file named myfile.dll.</P>
|
|
</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/quiet</B></TD>
|
|
<TD width=67%>Specifies quiet mode; does not report assembly progress.</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/subsystem=</B><I>integer</I></TD>
|
|
<TD width=67%>Sets subsystem to the value specified by <I>integer</I> in the
|
|
Windows NT Optional header. If the .subsystem IL directive is specified in the file, this command overrides it. See winnt.h, IMAGE_SUBSYSTEM for a list of valid values for <I>integer</I>.<p>
|
|
The resulting PE file modification has significance only on the Windows
|
|
platform.</TD>
|
|
</TR>
|
|
|
|
<TR VALIGN="top">
|
|
<TD width=33%><B>/?</B></TD>
|
|
<TD width=67%>Displays command syntax and options for the tool.<p>When you use
|
|
this tool on the UNIX system-based platforms <b>/?</b> might expand to a filename. Instead
|
|
use the <b>/help</b> option variation, use <b>-?</b>, or enclose the <b>/?</b> option in quotes: "<b>/?</b>"</TD>
|
|
</TR>
|
|
</table>
|
|
|
|
<P class=indent>Note: All options for the CIL Assembler are case-insensitive and recognized by the first three letters.
|
|
For example, <B>/lis </B>is equivalent to <B>/listing</B> and <B>/res:</B>myresfile.res is equivalent to <B>/resource:</B>myresfile.res.
|
|
Options that specify arguments accept either a colon (:) or an equal sign (=) as the separator between the option and the argument.
|
|
For example, <B>/output:</B><I>file.ext</I> is equivalent to <B>/output=</B><I>file.ext</I>.</P>
|
|
|
|
<h2>Remarks</h2>
|
|
|
|
<P>The CIL Assembler helps tool vendors design and implement CIL generators. Using
|
|
the CIL Assembler, tool and compiler developers can concentrate on
|
|
CIL and metadata generation without being concerned with emitting CIL in the PE file format.</P>
|
|
|
|
<P>Similar to other compilers that target the runtime, such as C#, the CIL
|
|
Assembler does not produce intermediate object files and does not require a linking stage to form a PE file.</P>
|
|
|
|
<P>The CIL Assembler can express all the existing metadata and CIL features of the programming languages that target the runtime. This allows managed code written in any of these programming languages to be adequately expressed in
|
|
CIL Assembler and compiled with the CIL Assembler. </P>
|
|
|
|
<P>You can use the CIL Assembler in conjunction with its companion tool,
|
|
<a href="ildasm.html">CIL Disassembler</a>. The CIL Disassembler takes a PE file that contains
|
|
CIL code and creates a text file suitable as input to the CIL Assembler. This is useful, for example, when compiling code in a programming language that does not support all the runtime metadata attributes. After compiling the code and running the output through Ildasm.exe, the resulting
|
|
CIL text file can be hand-edited to add the missing attributes. You can then run this text file through
|
|
the CIL Assembler to produce a final executable file.</P>
|
|
|
|
<P>You can also use this technique to produce a single PE file from several PE files originally generated by different compilers.</P>
|
|
|
|
<P>To make this combined use of the CIL Disassembler and CIL Assembler as accurate as possible, the assembler does not perform some simple
|
|
optimizations; it does not deduce whether to use short or long forms of instructions. For example, the tool does not try to determine whether it could substitute a short encoding for a long one you might have written in your
|
|
CIL sources (or that might be emitted by another compiler). If you want the short encoding, you must explicitly write that form. However, the assembler does check for out-of-range conditions where this is possible.</P>
|
|
|
|
<h2>Examples</h2>
|
|
|
|
<P>The following command assembles the CIL file <CODE>myTestFile.il</CODE> and produces the executable <CODE>myTestFile.exe.</CODE></P>
|
|
|
|
<P><CODE>ilasm myTestFile</CODE></P>
|
|
|
|
<P>The following command assembles the CIL file <CODE>myTestFile.il</CODE> and produces the .dll file <CODE>myTestFile.dll</CODE>.</P>
|
|
|
|
<PRE>ilasm myTestFile /dll </PRE>
|
|
|
|
<P>The following command assembles the CIL file <CODE>myTestFile.il</CODE> and produces the .dll file <CODE>myNewTestFile.dll</CODE>.</P>
|
|
|
|
<PRE>ilasm myTestFile /dll /output:myNewTestFile.dll</PRE>
|
|
|
|
<h5>See Also</h5>
|
|
|
|
<P><a href="Tools_Index.html">Tools Index</a> | <A HREF="ildasm.html">CIL Disassembler(Ildasm.exe)</A></P>
|
|
<hr>
|
|
<p><i>Copyright (c) 2002 Microsoft Corporation. All rights reserved.</i></p>
|
|
</BODY>
|
|
</HTML> |