\input texinfo	@c -*-texinfo-*-
@c %** start of header
@setfilename pnettools.info
@settitle Portable.NET Development Tools
@setchapternewpage off
@c %** end of header

@ifinfo
The Portable.NET development tools assist with building
and manipulating images in the portable executable format.
development.

Copyright @copyright{} 2001 Southern Storm Software, Pty Ltd
@end ifinfo

@titlepage
@sp 10
@center @titlefont{Portable.NET Development Tools}

@vskip 0pt plus 1fill
@center{Copyright @copyright{} 2001 Southern Storm Software, Pty Ltd}
@end titlepage

@c -----------------------------------------------------------------------

@node Top, Overview, , (dir)
@menu
* Overview::                The tools in brief
* C# Compiler::             C# compiler
* Documentation::           XML documentation tools
* Assembler::               Intermediate language assembler
* Disassembler::            Intermediate language disassembler
* Linker::                  Intermediate language assembly linker
* Size::                    Intermediate language size utility
* Native::                  Intermediate language native utility
* Find::                    Intermediate language name find utility
* Dependencies::            Intermediate language dependency utility
* Resources::               Resource generation and conversion
* ECMA Extensions::         ECMA file format extensions
* Load Errors::             Errors while loading IL binaries
* Index::                   Index of concepts and facilities
@end menu

@c -----------------------------------------------------------------------

@node Overview, C# Compiler, Top, Top
@chapter Overview
@cindex Overview

This manual describes a set of tools that can be used to build
and manipulate applications for the Portable.NET platform.

@table @code
@item cscc
The C# compiler.  @xref{C# Compiler}, for more information.
@item csdoc
The C# documentation conversion utility.  @xref{Documentation}, for
more information.
@item csdoc2hier
Used to convert C# XML documentation into a tree hierarhcy diagram.
@xref{csdoc2hier invocation}, for more information.
@item csdoc2html
Used to convert C# XML documentation into HTML.  @xref{csdoc2html invocation},
for more information.
@item csdoc2texi
Used to convert C# XML documentation into texinfo.
@xref{csdoc2texi invocation}, for more information.
@item ilasm
The Intermediate Language (IL) assembler.  @xref{Assembler},
for more information.
@item ildasm
The IL disassembler.  @xref{Disassembler}, for more information.
@item ilalink
The IL assembly linker.  @xref{Linker}, for more information.
@item ilsize
The IL size utility.  @xref{Size}, for more information.
@item ilnative
The IL native utility.  @xref{Native}, for more information.
@item ilfind
The IL find utility.  @xref{Find}, for more information.
@item ildd
The IL dependency utility.  @xref{Dependencies}, for more information.
@item resgen
The resource generation utility.  @xref{Resources}, for more information.
@end table

@c -----------------------------------------------------------------------

@node C# Compiler, cscc invocation, Overview, Top
@chapter C# Compiler
@cindex C# Compiler
@cindex cscc

Cscc compiles input source files, typically in the C# (pronounced C-Sharp)
programming language.

The command-line syntax of cscc has been deliberately designed
to match that of C compilers such as gcc(1), to shorten the learning
curve for new users.

@menu
* cscc invocation::         Invoking cscc
* Option Summary::          Brief list of all options, without explainations
* Overall Options::         Controlling input, output, and overall behaviour
* Language Options::        Controlling the variant of C# that is compiled
* Warning Options::         Controlling how warnings are emitted
* Debugging Options::       Symbol tables and other debugging information
* Optimization Options::    Controlling the level of optimization
* Preprocessor Options::    Controlling conditional compilation and macros
* Assembler Options::       Controlling the behaviour of ilasm
* Directory Options::       Where to find include files
* Linker Options::          Controlling the behaviour of the linker
* Other Options::           Other options supported by cscc
* Language Plugins::        Adding other languages to cscc
* Compiling to the JVM::    Compiling source to JVM bytecode
* Differences::             Differences between cscc and standard C#
@end menu

@c -----------------------------------------------------------------------

@node cscc invocation, Option Summary, C# Compiler, C# Compiler
@section Invoking cscc
@cindex cscc invocation

The general form of the cscc syntax is as follows:

@example
cscc [OPTIONS] input ...
@end example

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.

@c -----------------------------------------------------------------------

@node Option Summary, Overall Options, cscc invocation, C# Compiler
@section Option summary for cscc
@cindex cscc option summary

@table @asis
@item Overall Options
@ref{Overall Options}
@example
-c -S -E -o FILE -pipe -v -vv -x LANGUAGE
@end example

@item Language Options
@ref{Language Options}
@example
-flatin1-charset -foctal-chars -foctal-constants
-fdecimal-constants -fchecked -funchecked -fsyntax-check
-fsemantic-check -funsafe
@end example

@item Warning Options
@ref{Warning Options}
@example
-Wall -Werror -w -W -Woctal-chars -Woctal-constants
-Wunknown-escapes -Winvalid-utf8 -Wlarge-unicode-chars
-Wmulti-char-constant -Wunsafe -Wempty-input
@end example

@item Debugging Options
@ref{Debugging Options}
@example
-g
@end example

@item Optimization Options
@ref{Optimization Options}
@example
-O -O2 -O3 -O0 -fno-peephole
@end example

@item Preprocessor Options
@ref{Preprocessor Options}
@example
-C -P -DSYMBOL -USYMBOL -undef -dM -dN
@end example

@item Assembler Options
@ref{Assembler Options}
@example
-fno-short-insns -filasm-path=PATHNAME -mjvm
-fstdlib-name=NAME
-fsave-asm
@end example

@item Directory Options
@ref{Directory Options}
@example
-IDIR -nostdinc -nostdinc++
@end example

@item Linker Options
@ref{Linker Options}
@example
-e ENTRYPOINT -LDIR -nostdlib -lLIBRARY
-shared -static -m32bit-only -fresources=RESFILE
-mcui-subsystem -mgui-subsystem -gtk -gnome
@end example

@item Other Options
@ref{Other Options}
@example
-dumpversion --help -fplugin-KEY-path=PATHNAME
@end example
@end table

@c -----------------------------------------------------------------------

@node Overall Options, Language Options, Option Summary, C# Compiler
@section Overall options
@cindex Overall options for cscc

@table @code
@cindex -c option (cscc)
@item -c
Compile or assemble the input source files to object files,
but do not link.  The object file corresponding to the input
file @code{FILE.EXT} will be called @code{FILE.obj} unless the
@code{-o} option is supplied.

If the language compiles multiple input source files at a time,
then there will be a single output file.  The name of the output
file will be based on the name of the first input file unless
the @code{-o} option is supplied.

@cindex -S option (cscc)
@item -S
Compile the input source files to produce assembly language in
the Intermediate Language format.  The assembly file corresponding
to the input file @code{FILE.EXT} will be called @code{FILE.il}
unless the @code{-o} option is supplied.

If the language compiles multiple input source files at a time,
then there will be a single output file.  The name of the output
file will be based on the name of the first input file unless
the @code{-o} option is supplied.

@cindex -E option (cscc)
@item -E
Preprocess the input files and write the preprocessed source
to the output file.  If no output file is supplied, then
the preprocessed source is written to standard output.

@cindex -o option (cscc)
@item -o FILE
Specify the name of the file to write the output to.  The default
depends upon how cscc is invoked.  Specifying @code{FILE} as @code{-}
indicates that the output should be set to standard output.
Standard output can only be used for pre-processing.

If none of @code{-c}, @code{-S}, or @code{-E} are supplied,
then the default output file is @code{a.out.exe} or @code{a.out.dll}.
The latter is used when the @code{-shared} option is supplied.

@cindex -pipe option (cscc)
@item -pipe
Not used at present.  Provided for compatibility with gcc(1).

@cindex -v option (cscc)
@item -v
Print verbose debugging information about the files that are
being compiled.

@cindex -vv option (cscc)
@item -vv
Print the names of the command-lines that are executed by
cscc to invoke external programs such as language plug-ins
and the assembler, ilasm.

@cindex -x option (cscc)
@item -x language
Specify the source language to use to compile all input files.
This is typically not needed, because cscc can guess the
language from the input file's extension.

The options @code{-x cs} and @code{-x csharp} specify
that the language is C#.

@xref{Language Plugins}, for more information on this option.
@end table

Default file extensions typically follow the Windows conventions
of @code{.obj}, @code{.exe}, and @code{.dll} rather than the
Unix conventions of @code{.o}, no extension, and @code{.so}
respectively.  This is due to the Windows nature of IL binaries,
and to prevent confusion with native Unix binaries.  The @code{-o}
option can be used to override the defaults.

@c -----------------------------------------------------------------------

@node Language Options, Warning Options, Overall Options, C# Compiler
@section Language options
@cindex Language options for cscc

Every language supported by cscc has its own set of language,
warning, and other options.  The following sections describe
the options for C# only.

@table @code
@cindex -flatin1-charset option (cscc)
@item -flatin1-charset
The input source file's character set is Latin-1, instead of
the UTF-8 default.

If the source is in a character set other than Latin-1 or UTF-8,
the programmer must arrange for it to be converted into UTF-8
prior to invoking the compiler.

@cindex -foctal-chars option (cscc)
@item -foctal-chars
The C# language standard does not support octal characters constants
by default.  This option is enabled by default.

If this option is enabled, sequences such as @code{`\033'} will be
processed as in C, with a warning.  The @code{-Wno-octal-chars}
option can be used to disable the warning.  Use the @code{-fno-octal-chars}
option to disable the use of octal character constants.

@cindex -foctal-constants option (cscc)
@item -foctal-constants
The C# language standard does not support octal integer constants
by default.  Selecting this option will enable them.

If this option is not present, sequences such as @code{\033} will be
parsed as decimal, and a warning will be displayed.  The
@code{-Wno-octal-constants} or @code{-fdecimal-constants} options
will disable the warning.

@cindex -fdecimal-constants option (cscc)
@item -fdecimal-constants
Parse character sequences that look like octal integers as
decimal and suppress the warning.  If both @code{-foctal-constants}
and @code{-fdecimal-constants} are supplied, then the former
takes precedence.

@cindex -fchecked option (cscc)
@cindex -funchecked option (cscc)
@item -fchecked
@itemx -funchecked
Compile arithmetic expressions so that overflow exceptions will
or will not be thrown, respectively.  The default is @code{-funchecked}.
The @code{checked} and @code{unchecked} keywords can be used in
source files to override this setting.

@cindex -fsyntax-check option (cscc)
@item -fsyntax-check
Parse the input source file to check its syntax, but don't
go any further with compilation.

@cindex -fsemantic-check option (cscc)
@item -fsemantic-check
Parse the input source file to check its syntax and perform
semantic analysis, but don't go any further with compilation.

@cindex -funsafe option (cscc)
@item -funsafe
Permit the use of unsafe C# language constructs in the input
source file.  If this option is not supplied, all unsafe
constructs will result in an error.
@end table

@c -----------------------------------------------------------------------

@node Warning Options, Debugging Options, Language Options, C# Compiler
@section Warning options
@cindex Warning options for cscc

@table @code
@cindex -Wall option (cscc)
@cindex -W option (cscc)
@item -Wall
@itemx -W
Enable all warnings that are supported by the compiler.
Individual warnings can be disabled with @code{-Wno-XXX} options.
For example, @code{-Wall -Wno-empty-input} will enable
all warnings except the "empty input file" warning.

@cindex -Werror option (cscc)
@item -Werror
Convert all warnings into errors.

@cindex -w option (cscc)
@item -w
Suppress all warnings.

@cindex -Woctal-chars option (cscc)
@item -Woctal-chars
Warn if the programmer uses the octal form of a character.
The C# language standard only supports @code{\0}, but this
compiler also supports sequences such as @code{\033}.

@cindex -Woctal-constants option (cscc)
@item -Woctal-constants
Warn if the programmer uses a sequence that looks like an
octal integer constant, but which is being parsed as decimal
in accordance with the C# language standard.

@cindex -Wunknown-escapes option (cscc)
@item -Wunknown-escapes
Warn if an unknown escape sequence is used in a string or
character constant.

@cindex -Winvalid-utf8 option (cscc)
@item -Winvalid-utf8
Warn if an invalid UTF-8 sequence is encountered in the
input source file.

@cindex -Wlarge-unicode-chars option (cscc)
@item -Wlarge-unicode-chars
Warn if a character constant uses a Unicode character with
a codepoint value greater than 65535.

@cindex -Wmulti-char-constant option (cscc)
@item -Wmulti-char-constant
Warn if a character constant contains more than one character.

@cindex -Wunsafe option (cscc)
@item -Wunsafe
Warn when an unsafe construct is used in the program.

@cindex -Wempty-input option (cscc)
@item -Wempty-input
Warn if the input source file does not contain any declarations.
@end table

@c -----------------------------------------------------------------------

@node Debugging Options, Optimization Options, Warning Options, C# Compiler
@section Debugging options
@cindex Debugging options for cscc

@table @code
@cindex -g option (cscc)
@item -g
Enable the generation of debug symbol information in the output file.
@end table

@c -----------------------------------------------------------------------

@node Optimization Options, Preprocessor Options, Debugging Options, C# Compiler
@section Optimization options
@cindex Optimization options for cscc

@table @code
@cindex -O option (cscc)
@cindex -O2 option (cscc)
@cindex -O3 option (cscc)
@item -O
@item -O2
@item -O3
Enable various levels of optimization.

@cindex -O0 option (cscc)
@item -O0
Disable all optimizations.

@cindex -fno-peephole option (cscc)
@item -fno-peephole
Disable peephole optimization of the code.
@end table

@c -----------------------------------------------------------------------

@node Preprocessor Options, Assembler Options, Optimization Options, C# Compiler
@section Preprocessor options
@cindex Preprocessor options for cscc

@table @code
@cindex -C option (cscc)
@item -C
Include comments in pre-processor output.  This option is not yet
supported.

@cindex -P option (cscc)
@item -P
Don't use @code{#line} directives in pre-processor output.

@cindex -D option (cscc)
@item -DSYMBOL
Define the macro @code{SYMBOL} prior to pre-processing the input.

C# does not support macros with values.  Supplying a command-line
option of @code{-DSYMBOL=value} will result in a macro called
@code{SYMBOL=value}, which cannot be tested effectively in C#
source code.

@cindex -U option (cscc)
@item -USYMBOL
Undefine the macro @code{SYMBOL} prior to pre-processing the input.

@cindex -undef option (cscc)
@item -undef
Undefine all standard macros prior to pre-processing the input.

@cindex -dM option (cscc)
@item -dM
Dump the macros that were defined in the input source instead of
dumping the pre-processor output.  This can only be used with the
@code{-E} option.

@cindex -dN option (cscc)
@item -dN
Dump both the pre-processor output and the macros that were defined.
This can only be used with the @code{-E} option.
@end table

The standard macro @code{__CSCC__} is defined to indicate that
cscc is being used to compile the source code.

The standard macros @code{DEBUG} or @code{RELEASE} will be defined
to indicate if a debug (@code{-g}) or release version is being built.

The standard macro @code{__JVM__} is defined to indicate that
the output is JVM code instead of IL code.

@c -----------------------------------------------------------------------

@node Assembler Options, Directory Options, Preprocessor Options, C# Compiler
@section Assembler options
@cindex Assembler options for cscc

@table @code
@cindex -fno-short-insns option (cscc)
@item -fno-short-insns
Causes the @code{-no-short-insns} command-line option to be
passed to the ilasm assembler.

This alters how the assembler generates the final object code.
You typically don't need to use this option.

@cindex -filasm-path option (cscc)
@item -filasm-path=PATHNAME
Specifies the full pathname of the ilasm assembler.  By default,
cscc searches for ilasm along the PATH.

@cindex -mjvm option (cscc)
@item -mjvm
Compile to JVM bytecode instead of IL bytecode.

@cindex -fstdlib-name option (cscc)
@item -fstdlib-name=NAME
Change the name of the standard library to NAME.  The default
value is "mscorlib".

@cindex -fsave-asm option (cscc)
@item -fsave-asm
Do not delete intermediate assembly output files.  This is useful
for debugging compiler problems.
@end table

@c -----------------------------------------------------------------------

@node Directory Options, Linker Options, Assembler Options, C# Compiler
@section Directory options
@cindex Directory options for cscc

@table @code
@cindex -I option (cscc)
@item -IDIR
Specify the name of a directory in which the compiler should search
for included files.

@cindex -fnostdinc option (cscc)
@item -fnostdinc
Don't use standard include directories.

@cindex -fnostdinc++ option (cscc)
@item -fnostdinc++
Don't use standard C++ include directories.
@end table

These options are not currently used by the C# compiler.  They are
provided for future language plug-ins that may use include files.

@c -----------------------------------------------------------------------

@node Linker Options, Other Options, Directory Options, C# Compiler
@section Linker options
@cindex Linker options for cscc

@table @code
@cindex -e option (cscc)
@item -e ENTRYPOINT
Specify the name of the entry point for the program.  This may
either be a class name (e.g. @code{MainClass}) or a method
name (e.g. @code{MainClass.Main}).  If this option is not supplied,
the linker will search for any class with a static method called
@code{Main}.

@cindex -L option (cscc)
@item -LDIR
Specify the name of a directory in which the compiler should search
for libraries that the program will be linked against.

@cindex -nostdlib option (cscc)
@item -nostdlib
Don't use standard library directories and libraries.

@cindex -l option (cscc)
@item -lLIBRARY
Link against the specified library.  For example, specifying
@code{-lSystem.XML} will search for the library @code{System.XML.dll}
along the library search path.

Unless @code{-nostdlib} is supplied, the library @code{mscorlib}
is implicitly assumed to always be linked against.

Libraries can also be specified by listing their filenames explicitly
on the command-line.  For example: @code{/usr/local/lib/cscc/System.XML.dll}
would have the same effect as @code{-lSystem.XML}.

@cindex -shared option (cscc)
@item -shared
Create a shared library (@code{.dll}) instead of an executable (@code{.exe}).

@cindex -static option (cscc)
@item -static
Link statically against the supplied libraries.  This will incorporate
the object file data for the libraries into the program being built.

You normally will not need to use this option, unless you are concerned
that a foreign host may not have all of the libraries that are required
to execute the program.

This option will never statically link against a library that has
native, internalcall, or PInvoke methods.  In particular, @code{mscorlib.dll}
will never be linked statically.

@cindex -m32bit-only option (cscc)
@item -m32bit-only
Mark the final output file as only suitable to be executed on 32-bit
platforms.  Use of this option is severely discouraged as it makes
the resultant program less portable.

@cindex -fresources option (cscc)
@item -fresources=RESFILE
Specify the name of a resource file to be linked with the final
library or executable.  Multiple @code{-fresources} options
may be used to specify multiple resource files.

@cindex -mcui-subsystem option (cscc)
@item -mcui-subsystem
Tag the output file so that it can run within the command-line subsystem
under Windows.  This is the default.

@cindex -mgui-subsystem option (cscc)
@item -mgui-subsystem
Tag the output file so that it can run within the GUI subsystem
under Windows.

@cindex -gtk option (cscc)
@item -gtk
Link against all of the libraries that are necessary to use Gtk#.

@cindex -gnome option (cscc)
@item -gnome
Link against all of the libraries that are necessary to use Gnome#.
@end table

@c -----------------------------------------------------------------------

@node Other Options, Language Plugins, Linker Options, C# Compiler
@section Other options
@cindex Other options for cscc

@table @code
@cindex -dumpversion option (cscc)
@item -dumpversion
Dump the version of cscc to standard error and then exit.

@cindex --help option (cscc)
@item --help
Print a usage message about the supported options and then exit.

@cindex -fplugin-KEY-path option (cscc)
@item -fplugin-KEY-path=PATHNAME
Specify the @code{PATHNAME} of a language plug-in to be used to compile
the language identified by @code{KEY}.
@end table

@xref{Language Plugins}, for more information on plug-ins.

@c -----------------------------------------------------------------------

@node Language Plugins, Compiling to the JVM, Other Options, C# Compiler
@section Language plugins
@cindex Language plugins

The compiler can support plug-ins for other programming languages, allowing
the same front-end to be used to service multiple language back-ends.
Using a plug-in allows you to avoid most of the work involved in building
a compiler.  The minimum you must provide is a translator between the
source language and IL assembly code.  The cscc front-end takes care of
assembly and linking for you.

A plug-in must be a regular Unix executable with the name @code{cscc-KEY}
or @code{cscc-KEY-s} where @code{KEY} is either the file extension or a
language name.  e.g. to create a plug-in for a hypothetical @code{superc}
language, that uses @code{.sc} as its primary file extension, create an
executable called @code{cscc-superc}, and a symbolic link called
@code{cscc-sc} that points at the executable.

When cscc searches for an extension, it will first look for an exact case
match.  If that doesn't succeed, it will normalize the extension to lower
case and try again.  Thus, the @code{cscc-sc} plug-in will be passed any file
with an extension of @code{.sc}, @code{.Sc}, @code{.sC}, or @code{.SC}.
If @code{.SC} is a different language, then a separate plug-in must
be supplied.

A language name may be specified using the -x option.  For example:

@example
cscc -x superc -o hello.obj -c hello.c
@end example

Use this when the extension is not the same as the primary extension for
the language type.  Note: @code{-x sc} could also have been used.

The C# compiler is itself implemented as a plug-in called @code{cscc-cs},
with a symbolic link to it called @code{cscc-csharp}.

If the name of the executable ends in @code{-s}, then it indicates a
"single file" language, rather than the default "multiple file" language.

Single file languages are those that must be compiled one file at a time.
C is an example of such a language: each source file is logically
independent.  The plugin is executed once for each source file on
the @code{cscc} command-line.

Multiple file languages are those that must be compiled multiple files
at a time because each file may depend on definitions in the others.
C# is such a language.  All files with a matching extension are passed
to a single execution of the plugin.  The plugin will output a
single assembly stream that contains the compiled versions of all
of the files.

The executable is located as follows:

@itemize @bullet
@item
Look for a @code{-fplugin-KEY-path=XXX} command-line option.  If it is
present, then @code{XXX} is used as the plug-in executable.  For example,
@code{-fplugin-cs-path=../../../pnet/cscc/cscc-cs} is used in the
compilation of the system library to ensure that the current version
of the compiler is used, even if a previous version is already installed.

@item
Look in the directories specified by the @code{CSCC_PLUGINS_PATH}
environment variable for a file called @code{cscc-KEY} or
@code{cscc-KEY-s}.

@item
Look in the installation @code{plugins} directory, which is normally
something like @code{/usr/local/lib/cscc/plugins} or
@code{/usr/lib/cscc/plugins}.

@item
Look in the same directory from which @code{cscc} was loaded, by
inspecting the @code{argv[0]} value.

@item
Search the PATH for the name.
@end itemize

The cscc front-end passes the following options down to the plug-in:

@table @code
@cindex -E option (cscc plug-in)
@item -E
Preprocess instead of compiling.  If the plug-in's language does not support
preprocessing, then it should print a message to standard error
and exit with a status of 1.

@cindex -pipe option (cscc plug-in)
@item -pipe
If the plug-in invokes other tools during compilation, then attempt to
use pipes rather than temporary files.  If it is difficult for the plug-in
to conform with this option, then it can be safely ignored.

@cindex -o option (cscc plug-in)
@item -o NAME
Specify the name of the output file.  The default is standard output.

The plug-in should write preprocessed data to the output file if @code{-E}
is supplied, or IL assembly code otherwise.

@cindex -g option (cscc plug-in)
@item -g
Output debug information.

@cindex -O option (cscc plug-in)
@cindex -O2 option (cscc plug-in)
@cindex -O3 option (cscc plug-in)
@cindex -O0 option (cscc plug-in)
@item -O
@itemx -O2
@itemx -O3
@itemx -O0
Set the optimization level to 1, 2, 3, and 0 respectively.

@cindex -D option (cscc plug-in)
@item -DSYMBOL
@itemx -DSYMBOL=VALUE
Define a symbol within the plug-in language's preprocessor.  The second
form can be used if the language supports values for preprocessor symbols.
C# itself does not support values for preprocessor symbols.

@cindex -U option (cscc plug-in)
@item -USYMBOL
Undefine a symbol within the plug-in language's preprocessor.

@cindex -undef option (cscc plug-in)
@item -undef
Undefine all pre-defined preprocessor symbols that the language may support.

The cscc front-end will always pass down pre-defined
symbols such as @code{__CSCC__} and @code{DEBUG}, unless
@code{-undef} was supplied on its command-line.  Thus, the plug-in
does not need to handle these standard macros itself.

@cindex -I option (cscc plug-in)
@item -IDIR
Specify an include directory that originated on the cscc command-line.

@cindex -J option (cscc plug-in)
@cindex -K option (cscc plug-in)
@item -JDIR
@itemx -KDIR
Specify a system include directory, or a C++ system include directory.
The front-end adds @code{-J} options for each of the system include
directories that it knows about.  The front-end adds @code{-K} options for
each of the C++ system include directories that it knows about.

Plug-ins can use this information, or ignore it and use their own notion
of system include directories.

The @code{-J} options will not appear if the @code{-nostdinc} option
is present.  The @code{-K} options will not appear if the
@code{-nostdincpp} option is present.

@cindex -nostdinc option (cscc plug-in)
@cindex -nostdinc++ option (cscc plug-in)
@item -nostdinc
@itemx -nostdinc++
Don't use any system include directories, or C++ system include directories,
that the plug-in is aware of.

@cindex -L option (cscc plug-in)
@item -LDIR
Specify a library directory that originated on the cscc command-line.

@cindex -M option (cscc plug-in)
@item -MDIR
Specify a system library directory.  The front-end adds @code{-M} options
for each of the system library directories that it knows about.  This
option will not appear if the @code{-nostdlib} option is present.

@cindex -nostdlib option (cscc plug-in)
@item -nostdlib
Don't use any system library directories that the plug-in is aware of.

@cindex -l option (cscc plug-in)
@item -lLIBRARY
Specify the name of a library that is being linked against.

The last four options are provided for informational purposes only.
The plug-in is responsible for compiling and not linking.  However, some
languages (e.g. C#) require information from system libraries to be able to
compile successfully.  These options are supplied to help such compilers.

It is unlikely that @code{-l} options will be seen by the plug-in unless
the program is being compiled and linked in one step.  e.g.

@example
cscc -o testing.exe testing.sc -lSystem
@end example

@cindex -Wall option (cscc plug-in)
@item -Wall
Enable all warnings.

@cindex -w option (cscc plug-in)
@item -w
Suppress the display of all warnings.

@cindex -Werror option (cscc plug-in)
@item -Werror
Treat warning messages as errors.

@cindex -W* option (cscc plug-in)
@cindex -Wno-* option (cscc plug-in)
@item -WNAME, -Wno-NAME
Enable or disable the warning called @code{NAME}.

@cindex -f* option (cscc plug-in)
@item -fNAME
Activate or deactive that compiler extension feature called @code{NAME}.

@cindex -m* option (cscc plug-in)
@item -mNAME
Activate or deactive that machine extension feature called @code{NAME}.

In gcc(1), the @code{-m} options are used to control machine-dependent
features.  Since IL is a platform-independent language, these options
will rarely be required by plug-ins.

Plug-ins can choose to ignore @code{-m} options, or can treat them as a
separate set of compiler extension flags that complement the @code{-f}
options.

The cscc front-end does support some @code{-m} options for controlling
the output of the assembler.  For example, @code{-m32bit-only} is used to
force the generation of IL binaries that can only run on 32-bit systems.

@cindex -dM option (cscc plug-in)
@cindex -dN option (cscc plug-in)
@item -dM
@itemx -dN
Debugging flags used with languages that support preprocessing.

@cindex -P option (cscc plug-in)
@item -P
Don't output @code{#line} directives in preprocessor output.

@cindex -C option (cscc plug-in)
@item -C
Include comments in the preprocessor output.

@cindex -v option (cscc plug-in)
@item -v
Provide verbose messages for debugging purposes.  This can be safely
ignored if the plug-in does not have a verbose mode.

@cindex -mjvm option (cscc plug-in)
@item -mjvm
Compile to JVM assembly code instead of IL assembly code.  If the plug-in
does not know how to compile to JVM assembly code, it should print a message
to standard error and exit with a status of 1.  All plug-ins must support
this option, even if only to report an error.
@end table

The options are followed by the name of the input file, which may be
@code{-} for stdin.  Standard input is only used for preprocessing.
Multiple file languages may have more than one input file supplied
on the command-line.

Any options that are not understood by the plug-in should be ignored.
In particular, @code{-W}, @code{-f}, and @code{-m} options may not always
be understood by the plug-in, because they are intended for a different
language plug-in, cscc itself, ilasm, or the linker.  If the option is
understood, but it has an incorrect value, then the plug-in should
print a message to standard error and exit with a status of 1.

The plug-in is only used for compilation and pre-processing tasks.
It is not used for assembling or linking.  It is expected that the
output is an IL assembly code stream suitable for input to ilasm.
The plug-in does not need to be concerned with generating IL bytecode
directly, or with calling ilasm itself: cscc takes care
of the rest.

The following is an example of invoking cscc for a plug-in language,
and the plug-in command-line that results:

@example
cscc -fno-short-insns -O2 -g -I../include \
    -o hello.obj -c hello.sc

cscc-sc -f no-short-insns -O2 -g -I ../include \
    -J /usr/local/lib/cscc/include \
    -K /usr/local/lib/cscc/cpp-include \
    -D __CSCC__ -D DEBUG -o hello.il hello.sc
@end example

This is followed by a call to ilasm:

@example
ilasm --debug -f no-short-insns \
    --format obj -o hello.obj hello.il
@end example

Note: in this case, the @code{-fno-short-insns} flag is intended for the
assembler, rather than the plug-in.  The plug-in silently ignores any
@code{-f} options that it doesn't understand.  It may also ignore options
like @code{-O2} if it does not support code optimization.

Any non-zero status return from the plug-in will cause cscc to exit
with the same status code.  If the plug-in exits with a signal, then
cscc will exit with a status code of 1 after reporting the signal
to standard error.

@c -----------------------------------------------------------------------

@node Compiling to the JVM, Differences, Language Plugins, C# Compiler
@section Compiling to the JVM
@cindex Compiling to the JVM

The C# compiler supports compiling to either Intermediate Language
(IL) bytecode, or to Java Virtual Machine (JVM) bytecode.  The
@code{-mjvm} command-line option to cscc selects the JVM mode.

C# programs are typically compiled many classes at a time, with all
classes ending up in the same binary image.  The cscc compiler therefore
converts C# source code into Java @code{.jar} files, which can contain
multiple classes.  It can also compile to the @code{.class} format, but
only if the input source contains one class definition.

Compiling to JVM modifies the behaviour of some command-line options.
The file extension @code{.jar} is used instead of @code{.obj}, @code{.dll},
or @code{.exe}.  The file extension @code{.jl} is used instead of
@code{.il} for assembly code streams.  IL-specific options such as
@code{-m32bit-only} and @code{-fno-short-insns} are ignored.

The ilasm assembler supports dual bytecode formats.  A method with
the @code{java} implementation attribute will be assembled using the
Java instruction set instead of the IL instruction set.  For example:

@example
.method public instance int32 foo(int32 x) java
@{
    iload_0
    ireturn
@}
@end example

The rest of the assembly code stream is identical to IL.  The ilasm
program will convert from IL to JVM conventions on the fly.  IL-specific
features, such as module references and assembly definitions, will
be ignored.

This approach makes it relatively easy to support JVM in language
plug-ins that already support IL.  Only the bodies of methods need
to be compiled differently.

Because C# supports some features that aren't present in Java, it is
necessary to perform some "name mangling" on the names of fields and
methods to accomodate the differences.  Mangling is performed on
any field or method that involves a C#-specific type.  The simple
numeric types are mapped as follows:

@multitable {XXXXXXXXXXXXX} {XXXXXXXXXXXXX} {XXXXXXXXXXXXX} {XXXXXXXXXXXXXX}
@item C# Type @tab Java Type @tab Problematic? @tab Mangled Code
@item @code{sbyte} @tab @code{byte} @tab No @tab
@item @code{byte} @tab @code{int} @tab Yes @tab @code{B}
@item @code{short} @tab @code{short} @tab No @tab
@item @code{ushort} @tab @code{int} @tab Yes @tab @code{S}
@item @code{int} @tab @code{int} @tab Sometimes @tab @code{i}
@item @code{uint} @tab @code{uint} @tab Yes @tab @code{I}
@item @code{long} @tab @code{long} @tab Sometimes @tab @code{l}
@item @code{ulong} @tab @code{long} @tab Yes @tab @code{L}
@item @code{char} @tab @code{char} @tab No @tab
@item @code{float} @tab @code{float} @tab No @tab
@item @code{double} @tab @code{double} @tab No @tab
@item @code{bool} @tab @code{boolean} @tab No @tab
@end multitable

Enumerated and value types are always problematic.  Regular class
types are sometimes problematic.

Enumerated types are mapped to their underlying type, and the mangled
code is @code{Ename$}.  Value types are mapped to object references
and the mangled code is @code{V}.  Regular class types are mapped
to object references and the mangled code is @code{C}.

If a field is declared with a problematic type, then its name is
converted into @code{name__code} where @code{code} is the mangled
code.  The field's type will be the corresponding Java type.
If the field's type is only sometimes problematic, then it is not
mapped.

If a method is declared with at least one problematic parameter or
the return type is problematic, then the method signature must
be converted.  All problematic and sometimes problematic types
are converted into mangled codes, in the order of declaration.
Consider the following method definitions:

@example
void m1(int x);
void m2(uint x);
long m3(int x, byte y, uint z);
decimal m4(decimal x, string y);
void m5(System.TypeCode x);
void m6(uint[] x);
@end example

These will be converted into the following Java definitions after
mangling has been applied:

@example
void m1(int x);
void m2__I(int x);
long m3__iIl(int x, byte y, int z);
System.Decimal m4__VCV(System.Decimal x, System.String y);
void m5__ESystem.TypeCode$(int x);
void m6__I(int[] x);
@end example

Note that types that are sometimes problematic must be converted
if any of the other types are problematic.  The mangled code for
an array type is the mangled code for the element type.

Any field or method that is mangled must also have the Java
attribute @code{CLI.NameMangle}, which indicates that mangling
has been applied to the name.  The attribute's value is a non-zero
unsigned 32-bit integer that indicates how many bytes at
the end of the UTF-8 name make up the name mangling information.
This length does not include the "__" separator.

Properties are compiled to get and set methods, as in C#.  Then
the Java attribute @code{CLI.Properties} is added to the class.
The contents of this attribute is a list of property names, plus
the methods that implement each property.

Events are compiled in a similar fashion, with the Java attribute
@code{CLI.Events} indicating which methods correspond to events.

The above mangled codes and attributes can be used to recover the
type information when a @code{.class} file is loaded by a C#-aware
compiler or runtime engine.

@c -----------------------------------------------------------------------

@node Differences, Special Keywords, Compiling to the JVM, C# Compiler
@section Differences between cscc and standard C#
@cindex C# Differences

This section describes the differences between the C# syntax supported
by cscc, and that described in the ECMA specification.

@menu
* Special Keywords::        Special cscc keywords
* Pre-defined Macros::      Macros that are pre-defined by cscc
* Pre-processor Syntax::    Differences in the pre-processor syntax
@end menu

@c -----------------------------------------------------------------------

@node Special Keywords, Pre-defined Macros, Differences, Differences
@section Special cscc keywords
@cindex Special Keywords

The C# standard reserves identifiers that begin with @code{__} for
use by the language implementation.  We provide five such extensions:
@code{__builtin_constant}, @code{__arglist}, @code{__makeref},
@code{__reftype}, and @code{__refvalue}.

@cindex __builtin_constant keyword
The @code{__builtin_constant} keyword can be used to insert special
constants into the input stream that may otherwise be difficult to
represent accurately with regular C# language features.

@table @code
@cindex float_min builtin constant
@item __builtin_constant("float_min")
The minimum value of type @code{float} that can be represented.
This is approximately -3.40282346638528859e38f.

@cindex float_max builtin constant
@item __builtin_constant("float_max")
The maximum value of type @code{float} that can be represented.
This is approximately 3.40282346638528859e38f.

@cindex float_epsilon builtin constant
@item __builtin_constant("float_epsilon")
The smallest positive non-zero value that can be represented by the
@code{float} type.  This is approximately 1.4e-45f.

@cindex double_min builtin constant
@item __builtin_constant("double_min")
The minimum value of type @code{double} that can be represented.
This is approximately -1.7976931348623157e+308.

@cindex double_max builtin constant
@item __builtin_constant("double_max")
The maximum value of type @code{double} that can be represented.
This is approximately 1.7976931348623157e+308.

@cindex double_epsilon builtin constant
@item __builtin_constant("double_epsilon")
The smallest positive non-zero value that can be represented by the
@code{double} type.  This is approximately 4.94065645841247e-324.
@end table

The programmer will not normally use these constructs.  Instead,
they should use the corresponding constants in the @code{System.Single}
and @code{System.Double} classes.  The @code{__builtin_constant} keyword
is intended solely for use in implementing the C# library.

@cindex __arglist keyword
The @code{__arglist} keyword is used to assist interoperation with
C code that uses variable argument lists.  For example:

@example
int AddInts(__arglist)
@{
    int sum = 0;
    ArgIterator iter = new ArgIterator(__arglist);
    while(iter.GetRemainingCount() > 0)
    @{
        sum += __refvalue(iter.GetNextArg(), int);
    @}
    return sum;
@}

void Call()
@{
    int result = AddInts(__arglist(1, 2, 3, 4, 5));
@}
@end example

@noindent
The @code{__arglist} keyword is typically used in three different places:

@itemize @bullet
@item
As the last formal parameter in a method declaration.  This indicates
that the method takes a variable number of arguments.

@item
As the parameter to the @code{System.ArgIterator} constructor.  This
initializes an iterator to traverse the variable arguments.

@item
As the last actual parameter in a method call to specify the variable
arguments to be passed.  The construct @code{__arglist()} is used
when there are no variable arguments to be passed.
@end itemize

@cindex __makeref keyword
The @code{__makeref} keyword is used to convert a variable into
an instance of @code{System.TypedReference}.  The single argument can
be any l-value that can be passed by reference using the @code{ref}
keyword (local variables, object fields, array elements, etc).
For example:

@example
int x;
TypedReference tref;
...
tref = __makeref(x);
@end example

@cindex __reftype keyword
The @code{__reftype} keyword is used to extract the type component
from an instance of @code{System.TypedReference}.  For example:

@example
TypedReference tref;
Type type;
...
type = __reftype(tref);
@end example

@cindex __refvalue keyword
The @code{__refvalue} keyword is used to extract the value component
from an instance of @code{System.TypedReference}, where the second
argument specifies the type to extract.  @code{System.InvalidCastException}
will be thrown if the value component is not of the specified type.
For example:

@example
TypedReference tref;
int x;
...
x = __refvalue(tref, int);
@end example

The @code{__arglist}, @code{__makeref}, @code{__reftype}, and
@code{__refvalue} extensions are present in C# compilers from other
vendors.  The @code{__builtin_constant} extension is unique to cscc.

@c -----------------------------------------------------------------------

@node Pre-defined Macros, Pre-processor Syntax, Special Keywords, Differences
@section Pre-defined pre-procesor macros
@cindex Pre-defined macros

The @code{cscc} compiler defines a number of pre-processor macros prior
to processing source files.

@table @code
@cindex __CSCC__ macro
@item __CSCC__
This macro is defined by the compiler to let the source know that
@code{cscc} is being used to process the source.

@cindex __JVM__ macro
@item __JVM__
This macro is defined by the compiler to let the source know that
the output bytecode format is JVM instead of IL.

@cindex DEBUG macro
@item DEBUG
This macro is defined if the @code{-g} command-line option is
present.

@cindex RELEASE macro
@item RELEASE
This macro is defined if the @code{-g} command-line option is
not present.
@end table

The programmer can disable all pre-defined macros using the @code{-undef}
command-line option.

@c -----------------------------------------------------------------------

@node Pre-processor Syntax, Documentation, Pre-defined Macros, Differences
@section Pre-processor syntax
@cindex Pre-processor syntax

Slight implementation differences between @code{cscc} and other
C# compilers result in the following issues when using pre-processing
features:

@itemize @bullet
@item
Multi-line comments using @code{/*} and @code{*/} do not have to end
on the same line.  The C# standard disallows the following:

@example
#if DEBUG /* multi-line comment on
multiple lines */
    ...
#endif
@end example

Early C# compilers from other vendors did not allow @code{/*} style
comments on pre-processor lines at all, so programmers who are writing
portable code should always use @code{//} style comments on pre-processor
lines.

@item
@code{#define} and @code{#undef} directives can appear anywhere in
the input source.  The C# standard disallows these directives after
the first line of real code.  e.g.

@example
#define A
namespace N
@{
    #define B
    #if B
    class Class1 @{@}
    #endif
@}
@end example

The @code{cscc} compiler will accept this input.

@item
In the C# standard, comments within excluded blocks are not processed.
The following will be parsed correctly if @code{DEBUG} is defined:

@example
#if DEBUG
    CheckConsistency();
#else
    /* Do something else
#endif
@end example

The @code{cscc} compiler will report an error because the @code{#if}
does not have a matching @code{#endif}.

@item
@code{#region} and @code{#endregion} directives are ignored.  Unmatched
region directives will not cause an error.
@end itemize

@c -----------------------------------------------------------------------

@node Documentation, Documentation Sections, Pre-processor Syntax, Top
@chapter Documentation tools
@cindex Documentation

The C# programming language supports embedded documentation in
the form of XML elements.  Such documentation can be added to
types, methods, fields, and other program items using the
@code{///} commenting convention.  For example:

@example
/// <summary>
/// Compute the n'th Fibonacci number.
/// </summary>
///
/// <param name="n">
/// The index of the Fibonacci number to return.
/// </param>
///
/// <returns>
/// The Fibonacci number which corresponds to
/// <paramref name="n"/> in the sequence, where
/// <c>fib(0) = 0</c> and <c>fib(1) = 1</c>.
/// </returns>
public static int fib(int n)
@{
    ...
@}
@end example

To process documentation, the @code{csdoc} program is used to
extract the program structure and documentation comments.  The
output is an XML file.

This XML file is then fed into another program to produce the
desired output format.  One such program, @code{csdoc2html},
converts the XML file into a collection of HTML files which
can be viewed using a standard Web browser.

Another such program, @code{csdoc2texi}, converts the XML file
into texinfo, from which online or printed manuals can be derived.

A third program, @code{csdoc2hier}, converts the XML file into
a tree hierarchy diagram of all types in the input.

@menu
* Documentation Sections::  XML tags used for documentation sections
* Documentation Markup::    XML tags used for marking up text
* Cross-References::        Specifying cross-references in XML tags
* csdoc invocation::        Invoking csdoc
* csdoc2html invocation::   Invoking csdoc2html
* csdoc2texi invocation::   Invoking csdoc2texi
* csdoc2hier invocation::   Invoking csdoc2hier
@end menu

@c -----------------------------------------------------------------------

@node Documentation Sections, Documentation Markup, Documentation, Documentation
@section Documentation sections
@cindex Documentation sections

The following XML element tags are used to describe the major features
of a program item in separate sections:

@table @code
@item <summary> ... </summary>
Specify the summarised description for the current program item.

@item <remarks> ... </remarks>
Specify the detailed description for the current program item.

@item <param name="NAME"> ... </param>
Describe a particular method parameter.

@item <returns> ... </returns>
Describe the value that is returned from a method.

@item <value> ... </value>
Describe the value of a property.

@item <exception cref="CREF"> ... </exception>
The text describes an exception that is thrown during the processing
of the current program item.  The name of the exception is specified
by @code{CREF}.

@item <seealso cref="CREF"/>
@itemx <seealso topic="TOPIC"/>
Specify an item or topic to be added to the "See Also" section of
a program item's documentation.

@item <example> ... </example>
Specify the text of an example for the current program item.

@item <overload> ... </overload>
Provides a description to use when a method is overloaded.
Some documentation systems group all of the variants of a method
in the same section, with specific variant in sub-sections.
The @code{<overload>} element provides the description to use in
the main section, and will normally be identical for all variants.

@item <devdoc> ... </devdoc>
Provides supplemental documentation for developers.

@item <altcompliant cref="CREF"/>
Describes an alternative program item that should be used instead
of the current item in CLS-compliant applications.  @code{CREF}
is a cross-reference string that describes the alternative.

@item <altmember cref="CREF"/>
Specifies an alternative that can be used in place of this member.

@item <internalonly/>
Marks a program item that is intended for internal use by the
assembly that contains the item, and is not normally intended
to be used directly by other developers.

This may be used on methods that override a virtual method from a parent
class to indicate that the parent class method is the primary entry
point for developers.

@item <nodoc/>
Indicate that this program item should be ignored when processed
with conversion programs such as @code{csdoc2texi}.

@item <permission cref="CREF"> ... </permission>
Specifies a security permission that the program item must have to
be executed.

@item <platnote platform="PLATFORM"> ... </platnote>
Specify a note that only applies to a specific platform.

@item <threadsafe> ... </threadsafe>
Specify text that describes the thread-safety (or otherwise) of the
program item.
@end table

@c -----------------------------------------------------------------------

@node Documentation Markup, Cross-References, Documentation Sections, Documentation
@section Documentation markup
@cindex Documentation markup

The following XML element tags are used within the body of the above
elements to mark up the text:

@table @code
@item <b> ... </b>
Format the text between @code{<b>} and @code{</b>} in a bold font.

@item <block subset="SUBSET" type="TYPE"> ... </block>
Normally used inside a @code{<para>} element to indicate a block of
text that is distinguished from the other text as some for of note.
Optionally, an implementation subset may be specified.

Typical values for @code{SUBSET} are @code{none} and @code{ECMAOnly}.
The typical value for @code{TYPE} is @code{note}.

Note blocks are typically formatted as [Note: ...].  If the subset is
something other than @code{none}, then it will also be shown.  For
example, [Note (ECMAOnly): ...].

@item <c> ... </c>
Format the text between @code{<c>} and @code{</c>} in a fixed-width
font that is suitable for displaying code or program output.  The
normal formatting rules apply, in that paragraphs and line breaks
must be explicitly marked.

@item <code lang="LANG"> ... </code>
Format the text between @code{<code>} and @code{</code>} in a fixed-width
font that is suitable for displaying code or program output.  End of
line sequences within the text are treated as hard line breaks.  The
@code{LANG} value indicates that the text is an example in a specific
programming language.  @code{LANG} is usually @code{C#}.

@item <list type="LTYPE"> ... </list>
Format a list of terms and descriptions according to @code{LTYPE}.
Valid types are @code{bullet}, @code{number}, and @code{table}.

@item <item> ... </item>
Describe an item within a @code{<list>} element.

@item <listheader> ... </listheader>
An alternative to @code{<item>} that is used to describe the headers
for a @code{table} list.

@item <term> ... </term>
Mark the text that indicates a term within an @code{<item>} element.
This is only needed for definition lists.

@item <description> ... </description>
Mark the text that is describing a term within an @code{<item>} element.

@item <i> ... </i>
Format the text between @code{<i>} and @code{</i>} in an italicized font.

@item <note type="TYPE"> ... <note>
An alternative way to write @code{<block subset="none" type="TYPE"> ...
</block>}.

@item <para> ... </para>
Mark the start and end of a paragraph within a documentation block.

@item <paramref name="NAME"/>
Refer to a parameter within a documentation block.  The name may
be formatted in an alternative font.

@item <see cref="CREF"/>
Insert a link at the current point in the documentation to the
program item referred to by @code{CREF}.  This is used inline
within a documentation block.

@item <see langword="WORD"/>
Insert a reference to a keyword called @code{WORD} in the C# language.
The keyword will normally be output using the same font as @code{<code>}.

@item <sub> ... </sub>
Format the text between @code{<sub>} and @code{</sub>} in a subscript font.

@item <sup> ... </sup>
Format the text between @code{<sup>} and @code{</sup>} in a superscript font.

@item <subscript term="TERM"/>
An alternative way of specifying @code{<sub>TERM</sub>}.

@item <superscript term="TERM"/>
An alternative way of specifying @code{<sup>TERM</sup>}.
@end table

@c -----------------------------------------------------------------------

@node Cross-References, csdoc invocation, Documentation Markup, Documentation
@section Documentation cross-references
@cindex Documentation cross-references

Cross-reference prefixes:

@table @code
@item E:
The prefix is followed by the fully-qualified name of an event.

@item F:
The prefix is followed by the fully-qualified name of a field.

@item M:
The prefix is followed by the fully-qualified name of a method.

@item P:
The prefix is followed by the fully-qualified name of a property.

@item T:
The prefix is followed by the fully-qualified name of a type.

@item !:
The prefix is followed by an error string, which resulted because
the cross-reference could not be resolved.
@end table

@c -----------------------------------------------------------------------

@node csdoc invocation, csdoc2html invocation, Cross-References, Documentation
@section Invoking csdoc
@cindex csdoc invocation

The general form of the csdoc syntax is as follows:

@example
csdoc [OPTIONS] INPUT.cs ...
@end example

Csdoc reads the supplied C# source files, and writes XML data to the
file specified by the @code{-o} option, or to standard output if
@code{-o} is not supplied.

The supplied source files are parsed and processed using the
first phases of semantic analysis.  Thus, the source should be
valid C#, or a compilation error may occur.  Csdoc will not
generate assembly or object code output.

The csdoc command-line accepts all of the options that may be
supplied to cscc.  @xref{Option Summary}, for more information
on cscc options.  In addition, the following options have special
significance to csdoc:

@table @code
@cindex -o option (csdoc)
@item -o FILE
Specify the name of the file to write the XML output to.  The
default is standard output.  Specifying @code{-o -} will also
write the XML to standard output.

@cindex -fprivate option (csdoc)
@item -fprivate
By default, csdoc will only write public types and members to the
XML output.  Specifying @code{-fprivate} will force csdoc to
also include private types and members.

@cindex -flibrary-name option (csdoc)
@item -flibrary-name=NAME
Specify the library name to use for the types in the XML output
file.  By default, no library name is used.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.

When the input source is compiled, the symbol @code{__DOC__} will
be defined.  The programmer can use this to determine if the program
is being compiled by cscc, or converted into documentation using csdoc.

@c -----------------------------------------------------------------------

@node csdoc2html invocation, csdoc2texi invocation, csdoc invocation, Documentation
@section Invoking csdoc2html
@cindex csdoc2html invocation

The general form of the csdoc2html syntax is as follows:

@example
csdoc2html [OPTIONS] INPUT.xml ...
@end example

Csdoc2html reads the supplied XML input files, and converts them into
a collection of HTML files.  This collection can be viewed
using a standard Web browser.

Specifying multiple input files is exactly the same as specifying
one input file which is the concatenation of all of the files.
Only one output collection is created.  Csdoc2html must be invoked
multiple times to convert multiple input files into multiple output
collections.

@table @code
@cindex -o option (csdoc2html)
@cindex --output option (csdoc2html)
@item -o PATH
@itemx --output PATH
In multi-file mode, this option specifies the name of the directory
to write the HTML output to.  The default is the current directory.

In single-file mode, this option specifies the name of the file to write
the HTML output to.  The default is @code{INPUT.html}.  If there are
multiple input files, then the name of the output file is based on
the name of the first input file.  If the first input file is @code{-},
then the output is written to standard output.  If @code{PATH} is
@code{-}, then the output is written to standard output.

@cindex -fsingle-file option (csdoc2html)
@item -fsingle-file
Write all HTML data to a single output file, rather than splitting
the data across multiple files.

@cindex -fmulti-file option (csdoc2html)
@item -fmulti-file
Split the HTML data across multiple output files.  The file
@code{index.html} in the output directory is the main entry point
to browse the collection.  This is the default.

@cindex -fframes option (csdoc2html)
@item -fframes
Use HTML frames when writing the output data in multi-file mode.
This is the default.

@cindex -fno-frames option (csdoc2html)
@item -fno-frames
Do not use HTML frames when writing the output data in multi-file mode.

@cindex -fcombine-members option (csdoc2html)
@item -fcombine-members
Combine the documentation for type members into the same output
file as the type itself.  This is the default.

@cindex -fseparate-members option (csdoc2html)
@item -fseparate-members
Separate the documentation for type members into distinct output files.

@cindex -fnamespace-directories option (csdoc2html)
@item -fnamespace-directories
Write the contents of each namespace into a separate sub-directory.
This is the default.

@cindex -fno-namespace-directories option (csdoc2html)
@item -fno-namespace-directories
Write the contents of all namespaces into the primary output
directory, and do not create any sub-directories.

@cindex -ftitle option (csdoc2html)
@item -ftitle=TITLE
Specify the title to use for the collection.  The default is
the same as the first input filename.

@cindex -fpage-color option (csdoc2html)
@item -fpage-color=COLOR
Specify the HTML color value to use for the background of pages.
The default is @code{#FFFFFF}.

@cindex -fdefn-color option (csdoc2html)
@item -fdefn-color=COLOR
Specify the HTML color value to use for the background of
type and member definitions.  The default is @code{#C0C0C0}.

@cindex -fheader-color option (csdoc2html)
@item -fheader-color=COLOR
Specify the HTML color value to use for the background of
table headers.  The default is @code{#C0C0C0}.

@cindex --help option (csdoc2html)
@item --help
Print a usage message for the csdoc2html program.

@cindex -v option (csdoc2html)
@cindex --version option (csdoc2html)
@item -v
@itemx --version
Print the version of the csdoc2html program.

@item --
Marks the end of the command-line options, and the beginning of
the input filenames.  You may need to use this if your filename
begins with @code{-}.  e.g. @code{csdoc2html -- -input.xml}.  This is
not needed if the input is stdin: @code{csdoc2html -} is perfectly valid.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.

The simplest way to use this program is as follows:

@example
csdoc -o program.xml program.cs
mkdir temp
csdoc2html -o temp program.xml
@end example

This will write a collection of HTML files to the @code{temp} directory
that describes all of the types and members in the @code{program.cs}
source file.

@c -----------------------------------------------------------------------

@node csdoc2texi invocation, csdoc2hier invocation, csdoc2html invocation, Documentation
@section Invoking csdoc2texi
@cindex csdoc2texi invocation

The general form of the csdoc2texi syntax is as follows:

@example
csdoc2texi [OPTIONS] INPUT.xml ...
@end example

Csdoc2texi reads the supplied XML input files, and converts them into
texinfo.

Specifying multiple input files is exactly the same as specifying
one input file which is the concatenation of all of the files.
Only one output file is created.  Csdoc2texi must be invoked multiple
times to convert multiple input files into multiple output files.

@table @code
@cindex -o option (csdoc2texi)
@cindex --output option (csdoc2texi)
@item -o FILE
@itemx --output FILE
Specify the name of the file to write the texinfo output to.  The
default is @code{INPUT.texi}.  If there are multiple input files, then
the name of the output file is based on the name of the first input file.
If the first input file is @code{-}, then the output is written to
standard output.  If @code{FILE} is @code{-}, then the output is
written to standard output.

@cindex -fstandalone option (csdoc2texi)
@item -fstandalone
Make a stand-alone texinfo document that includes headers,
a title page, and an index.  This is the default.

@cindex -fembedded option (csdoc2texi)
@item -fembedded
Make an embedded texinfo document.  Use this if you wish to
incorporate the texinfo output into a larger document.

@cindex -fparent option (csdoc2texi)
@item -fparent=NAME
Specify the name of the parent node for an embedded document.
The default value is @code{Top}.  This option is ignored
in stand-alone documents.

@cindex -ffilename option (csdoc2texi)
@item -ffilename=NAME
Specify the value for @code{@@setfilename}.  The default is the same
as the first input file with the extension changed to @code{.info}.
If the first input file is standard input, then the default
value is @code{stdout.info}.  This option is ignored in
embedded documents.

@cindex -ftitle option (csdoc2texi)
@item -ftitle=TITLE
Specify the title to use for the document.  The default is
the same as @code{-ffilename}.  This option is ignored in
embedded documents.

@cindex -fdescription option (csdoc2texi)
@item -fdescription=DESC
Specify the description to use in the info header of the document.
The default is the same as @code{-ftitle}.  This option is
ignored in embedded documents.

@cindex -fchapternewpage option (csdoc2texi)
@item -fchapternewpage=VALUE
Specify the value for @code{@@setchapternewpage}.  The default value is
@code{on}.  Valid values are @code{on}, @code{off}, or @code{odd}.
This option is ignored in embedded documents.

@cindex -fcopyright option (csdoc2texi)
@item -fcopyright=MSG
Specify the Copyright message to use for the document.  The default
is no Copyright message.  This option is ignored in embedded documents.

@cindex -findex option (csdoc2texi)
@item -findex
Include an index chapter in the output.  This is the default
in stand-alone documents.

@cindex -fno-index option (csdoc2texi)
@item -fno-index
Do not include an index chapter in the output.  This is the
default in embedded documents.

@cindex -fnewpage option (csdoc2texi)
@item -fnewpage
Use a new page for each type member description.  This is the default.

@cindex -fno-newpage option (csdoc2texi)
@item -fno-newpage
Do not use a new page for each type member description.

@cindex --help option (csdoc2texi)
@item --help
Print a usage message for the csdoc2texi program.

@cindex -v option (csdoc2texi)
@cindex --version option (csdoc2texi)
@item -v
@itemx --version
Print the version of the csdoc2texi program.

@item --
Marks the end of the command-line options, and the beginning of
the input filenames.  You may need to use this if your filename
begins with @code{-}.  e.g. @code{csdoc2texi -- -input.xml}.  This is
not needed if the input is stdin: @code{csdoc2texi -} is perfectly valid.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.

The texinfo output is arranged so that each namespace is placed in
its own chapter, with types in sections, and members in sub-sections.
Types in the global namespace are placed in a chapter entitled
@emph{Global Namespace}.

This arrangement can be modified by creating an embedded document,
including it into another document, and using @code{@@lowersections}
to adjust the section nesting level.

The following is an example of converting C# source code into
online HTML documentation, by way of csdoc2texi:

@example
csdoc -o program.xml program.cs
csdoc2texi program.xml
texi2html -split_node program.texi
@end example

This produces a different output than csdoc2html, which may be useful
in some circumstances.  A better example is converting C# source
code into PDF documentation:

@example
csdoc -o program.xml program.cs
csdoc2texi program.xml
texi2dvi --pdf program.texi
@end example

This assumes that you have @code{texi2dvi} and @code{pdftex}
installed on your system.  The resulting file, @code{program.pdf},
can be viewed or printed with the usual PDF tools.

@c -----------------------------------------------------------------------

@node csdoc2hier invocation, Assembler, csdoc2texi invocation, Documentation
@section Invoking csdoc2hier
@cindex csdoc2hier invocation

The general form of the csdoc2hier syntax is as follows:

@example
csdoc2hier [OPTIONS] INPUT.xml ...
@end example

Csdoc2hier reads the supplied XML input files, and converts them into
a textual diagram of the type hierarchy.

Specifying multiple input files is exactly the same as specifying
one input file which is the concatenation of all of the files.
Only one output file is created.  Csdoc2hier must be invoked multiple
times to convert multiple input files into multiple output files.

@table @code
@cindex -o option (csdoc2hier)
@cindex --output option (csdoc2hier)
@item -o FILE
@itemx --output FILE
Specify the name of the file to write the output to.  The
default is standard output.  If @code{FILE} is @code{-}, then the output
is also written to standard output.

@cindex -fby-library option (csdoc2hier)
@item -fby-library
Organise the output by library.

@cindex --help option (csdoc2hier)
@item --help
Print a usage message for the csdoc2hier program.

@cindex -v option (csdoc2hier)
@cindex --version option (csdoc2hier)
@item -v
@itemx --version
Print the version of the csdoc2hier program.

@item --
Marks the end of the command-line options, and the beginning of
the input filenames.  You may need to use this if your filename
begins with @code{-}.  e.g. @code{csdoc2hier -- -input.xml}.  This is
not needed if the input is stdin: @code{csdoc2hier -} is perfectly valid.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.

@c -----------------------------------------------------------------------

@node Assembler, ilasm invocation, csdoc2hier invocation, Top
@chapter Intermediate language assembler
@cindex Assembler
@cindex ilasm

Ilasm converts Intermediate Language (IL) assembly code input
into an IL object file (@code{.obj}), an IL executable (@code{.exe}),
or an IL dynamic link library (@code{.dll}).

You normally won't need to invoke ilasm directly, because it is
invoked automatically by the cscc compiler.  However, if you
are building your own compiler for the Portable.NET platform,
then you may need to invoke this program.

@menu
* ilasm invocation::        Invoking ilasm
* Assembler Syntax::        Introduction to the assembler syntax
* Lexical Tokens::          Lexical tokens syntax
* Helper Non-Terminals::    Non-terminals that help with syntax definition
* Top-Level Declarations::  Top-level assembler declarations
* Namespace Declarations::  Namespace declarations
* Class Declarations::      Class declarations
* Type Specifications::     Specifying types in field and method signatures
* Field Declarations::      Field declarations
* Method Declarations::     Method declarations
* Property Declarations::   Property declarations
* Event Declarations::      Event declarations
* Debug Information::       Inserting debug information into the output
* Custom Attributes::       Associating custom attributes with program items
* Assembly Declarations::   Assembly declarations
* Module Declarations::     Module declarations
* Other Declarations::      Other declarations
@end menu

@c -----------------------------------------------------------------------

@node ilasm invocation, Assembler Syntax, Assembler, Assembler
@section Invoking ilasm
@cindex ilasm invocation

The general form of the ilasm syntax is as follows:

@example
ilasm [OPTIONS] INPUT.il ...
@end example

Ilasm reads the supplied input files, assembles them, and writes
the output to the file specified by the @code{-o} option, or to a default
filename derived from the name of the first input file.  If any
of the input filenames are @code{-}, then the standard input stream will
be used.  If @code{-} is specified multiple times, then standard input
will be parsed only once.

Specifying multiple input files is exactly the same as specifying
one input file which is the concatenation of all of the files.
Only one output file is created.  Ilasm must be invoked multiple
times to assemble multiple input files into multiple output files.

@table @code
@cindex -o option (ilasm)
@cindex --output option (ilasm)
@item -o FILE
@itemx --output FILE
Specify the name of the file to write the assembler output to.  The
default is @code{INPUT.EXT} where @code{EXT} is one of @code{obj},
@code{exe}, or @code{dll}, depending on the value of the
@code{--format} option.  If there are multiple input files, then
the name of the output file is based on the name of the first input file.
If the first input file is @code{-}, then the output is written to
standard output.  If @code{FILE} is @code{-}, then the output is
written to standard output.

@cindex -j option (ilasm)
@cindex --format obj option (ilasm)
@item -j
@itemx --format obj
Write a @code{.obj} file as output, instead of an executable or dynamic
link library.  This is the default value.

@cindex -e option (ilasm)
@cindex --format exe option (ilasm)
@item -e
@itemx --format exe
Write an executable file as output, instead of a @code{.obj} file or dynamic
link library.

@cindex -d option (ilasm)
@cindex --format dll option (ilasm)
@item -d
@itemx --format dll
Write a dynamic link library file as output, instead of a @code{.obj}
file or executable.

@cindex -g option (ilasm)
@cindex --debug option (ilasm)
@item -g
@itemx --debug
Enable the generation of debug symbol information to the output file.

@cindex -n option (ilasm)
@cindex --no-debug option (ilasm)
@item -n
@itemx --no-debug
Disable the generation of debug symbol information to the output file.
This is the default value.

@cindex -s option (ilasm)
@cindex -fshort-insns option (ilasm)
@item -s
@itemx -fshort-insns
Always use the shortest version of an instruction when creating the
output.  Some instructions have multiple versions.  e.g. @code{br}
and @code{br.s} for long and short versions of the branch instruction.
The assembler will attempt to "squash" the instructions to occupy as
little space as possible.  This is the default value.

When this option is in force, the compiler does not need to concern
itself with choosing the most compact form of an instruction, because
the assembler will do the work.  Long instructions will be converted
into shorter versions whenever possible, and short instructions will
be converted into longer versions if required.  Compiler code generators
can therefore be much simpler.

@cindex -l option (ilasm)
@cindex -fno-short-insns option (ilasm)
@item -l
@itemx -fno-short-insns
Always use the stated version of an instruction when creating the output.
For example, @code{br} will always generate a 5-byte branch instruction,
and @code{br.s} will always generate a 2-byte branch instruction.  If the
branch is too long, then using @code{br.s} will result in an error.

The only reason to use this is to ensure that the form of instruction
that is output by the ildasm disassembler is the same as the
form of instruction that was input to ilasm.  This may be helpful
when attempting to diagnose compiler problems.

@cindex -L option (ilasm)
@cindex -fstdlib-name option (ilasm)
@item -L NAME
@itemx -fstdlib-name=NAME
Change the name of the standard library to NAME.  The default
value is "mscorlib".

@cindex -J option (ilasm)
@cindex -mjvm option (ilasm)
@item -J
@itemx -mjvm
Assemble to JVM bytecode instead of IL.

@cindex -3 option (ilasm)
@cindex -m32bit-only option (ilasm)
@item -3
@itemx -m32bit-only
Tag the output file so that it can only be executed on 32-bit platforms.

@cindex -c option (ilasm)
@cindex -mcui-subsystem option (ilasm)
@item -c
@itemx -mcui-subsystem
Tag the output file so that it can run within the command-line subsystem
under Windows.  This is the default.

@cindex -G option (ilasm)
@cindex -mgui-subsystem option (ilasm)
@item -G
@itemx -mgui-subsystem
Tag the output file so that it can run within the GUI subsystem
under Windows.

@cindex --help option (ilasm)
@item --help
Print a usage message for the ilasm program.

@cindex -v option (ilasm)
@cindex --version option (ilasm)
@item -v
@itemx --version
Print the version of the ilasm program.

@item --
Marks the end of the command-line options, and the beginning of
the input filenames.  You may need to use this if your filename
begins with @code{-}.  e.g. @code{ilasm -- -input.il}.  This is not needed
if the input is stdin: @code{ilasm -} is perfectly valid.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.

The parser is fairly unforgiving of errors and will bail out at the
first sign of trouble.  This is not expected to be a problem because
ilasm will normally be processing the output of a compiler
such as cscc.  Compilers are presumed to be aware of how to
generate correct IL assembly code.

Ilasm uses the host's native C types @code{float} and @code{double} to
handle floating point numbers.  If the host does not have a strict
IEEE floating point implementation, then the values of floating point
constants may not be exactly what was expected.  The problem can be
avoided by using the raw bit forms, which are guaranteed to produce exact
IEEE-compliant values.

@c -----------------------------------------------------------------------

@include pnetasm.texi

@c -----------------------------------------------------------------------

@node Disassembler, ildasm invocation, Other Declarations, Top
@chapter Intermediate language disassembler
@cindex Disassembler
@cindex ildasm

Ildasm converts IL object files (@code{.obj}), IL executables (@code{.exe}),
and IL dynamic link libraries (@code{.dll}) into Intermediate Language (IL)
assembly code.  The output is suitable for input to ilasm.

Ildasm is useful for diagnosing problems with compilers and other
development tools.  It is rarely useful to regular users or programmers.

@menu
* ildasm invocation::       Invoking ildasm
@end menu

@c -----------------------------------------------------------------------

@node ildasm invocation, Linker, Disassembler, Disassembler
@section Invoking ildasm
@cindex ildasm invocation

The general form of the ildasm syntax is as follows:

@example
ildasm [OPTIONS] INPUT ...
@end example

@table @code
@cindex -o option (ildasm)
@cindex --output option (ildasm)
@item -o FILE
@itemx --output FILE
Specify the name of the file to write the assembler output to.  The
default is standard output.  Specifying @code{FILE} as @code{-} also
indicates that the output should be set to standard output.

@cindex -d option (ildasm)
@cindex --dump-sections option (ildasm)
@item -d
@itemx --dump-sections
Dump the contents of the IL program sections in hexadecimal instead
of as IL assembly code.  This may be useful for diagnosing problems
with badly formatted IL binaries.

@cindex -r option (ildasm)
@cindex --real-offsets option (ildasm)
@item -r
@itemx --real-offsets
By default, ildasm prints "relative virtual addresses", or RVA's,
when dumping IL program sections in hexadecimal, and when dumping the
names of labels within methods.  The @code{-r} option informs ildasm
to use real file offsets instead.  This may assist in locating data within
the file with separate tools.

@cindex -t option (ildasm)
@cindex --show-tokens option (ildasm)
@item -t
@itemx --show-tokens
Show the token codes of program elements within the disassembly output.

@cindex -q option (ildasm)
@cindex --quote-names option (ildasm)
@item -q
@itemx --quote-names
Quote all identifiers within the disassembly output so that they are not
confused with reserved words.  This is necessary if the output will be fed
into ilasm.

@cindex -w option (ildasm)
@cindex --whole-file option (ildasm)
@item -w
@itemx --whole-file
Dump the contents of the whole input file in hexadecimal.  If the
file is not otherwise recognized by ildasm as an IL binary,
this may be the only way to inspect the contents to determine what
the problem is.

@cindex -b option (ildasm)
@cindex --dump-bytes option (ildasm)
@item -b
@itemx --dump-bytes
Dump the IL instructions in hexadecimal.

@cindex -n option (ildasm)
@cindex --no-il option (ildasm)
@item -n
@itemx --no-il
Do not dump the IL instructions within the methods.

@cindex --help option (ildasm)
@item --help
Print a usage message for the ildasm program.

@cindex -v option (ildasm)
@cindex --version option (ildasm)
@item -v
@itemx --version
Print the version of the ildasm program.

@item --
Marks the end of the command-line options, and the beginning of
the input filenames.  You may need to use this if your filename
begins with @code{-}.  e.g. @code{ildasm -- -input.obj}.  This is
not needed if the input is stdin: @code{ildasm -} is perfectly valid.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.  @xref{Load Errors}, for a
complete list of errors that may occur when loading an IL image file.

@c -----------------------------------------------------------------------

@node Linker, ilalink invocation, ildasm invocation, Top
@chapter Intermediate language assembly linker
@cindex Linker
@cindex ilalink

Ilalink links a number of IL object files (@code{.obj}) together,
resolves external references to IL libraries, and creates a final
IL executable (@code{.exe}) or IL dynamic link library (@code{.dll}).

@menu
* ilalink invocation::      Invoking ilalink
@end menu

@c -----------------------------------------------------------------------

@node ilalink invocation, Size, Linker, Linker
@section Invoking ilalink
@cindex ilalink invocation

The general form of the ilalink syntax is as follows:

@example
ilalink [OPTIONS] INPUT ...
@end example

@table @code
@cindex -o option (ilalink)
@cindex --output option (ilalink)
@item -o FILE
@itemx --output FILE
Specify the name of the file to write the linker output to.  The
default is @code{a.out.exe}, @code{a.out.dll}, or @code{a.out.obj},
depending on the value of the @code{--format} option.

@cindex -j option (ilalink)
@cindex --format obj option (ilalink)
@item -j
@itemx --format obj
Write a @code{.obj} file as output, instead of an executable or dynamic
link library.  This is normally not very useful.

@cindex -e option (ilalink)
@cindex --format exe option (ilalink)
@item -e
@itemx --format exe
Write an executable file as output, instead of a @code{.obj} file or dynamic
link library.  This is the default value.

@cindex -d option (ilalink)
@cindex --format dll option (ilalink)
@item -d
@itemx --format dll
Write a dynamic link library file as output, instead of a @code{.obj} file or
executable.

@cindex -l option (ilalink)
@cindex --library option (ilalink)
@item -l NAME
@itemx --library NAME
Link against the library called @code{NAME}.  The linker will search all of
the library directories for a file called @code{NAME.dll}.  If
@code{--no-stdlib} is not specified, then the standard library
@code{mscorlib} will be automatically added to the list of libraries.
The name of the standard library can be changed using the
@code{-fstdlib-name} option.

@cindex -L option (ilalink)
@cindex --library-dir option (ilalink)
@item -L PATH
@itemx --library-dir PATH
Specify a directory to be searched for libraries.  The option @code{-L .}
must be explicitly supplied to search the current directory.  If
@code{--no-stdlib} is not specified, then a standard set of builtin paths
will be added to the end of the list specified by the @code{-L} options.
The set of builtin paths can be overridden by setting the
@code{CSCC_LIB_PATH} environment variable to an appropriate value.

@cindex -n option (ilalink)
@cindex --no-stdlib option (ilalink)
@item -n
@itemx --no-stdlib
Do not include the standard library or any of the builtin library directories.

@cindex -S option (ilalink)
@cindex -fstdlib-name option (ilalink)
@item -S NAME
@itemx -fstdlib-name=NAME
Set the name of the standard library to @code{NAME}.
The default is @code{mscorlib}.

@cindex --shared option (ilalink)
@item --shared
Link the output as a shared image.  This is the default.

@cindex --static option (ilalink)
@item --static
Link the output statically.  This option is not yet implemented.  It is
provided for compatibility with other tools.

@cindex -a option (ilalink)
@cindex -fassembly-name option (ilalink)
@item -a NAME
@itemx -fassembly-name=NAME
Set the name of the final assembly to @code{NAME}.  The default is
the name of the output file without its directory path or extension.

@cindex -A option (ilalink)
@cindex -fassembly-version option (ilalink)
@item -A NN:NN:NN:NN
@itemx -fassembly-version NN:NN:NN:NN
Set the final assembly version to @code{NN:NN:NN:NN}.  The default is
@code{0:0:0:0}, unless a non-zero version is supplied by one of the
input files.

@cindex -M option (ilalink)
@cindex -fmodule-name option (ilalink)
@item -M NAME
@itemx -fmodule-name=NAME
Set the name of the final module to @code{NAME}.  The default is the name of
the output file without its directory path.

@cindex -E option (ilalink)
@cindex --entry-point option (ilalink)
@item -E NAME
@itemx --entry-point NAME
Specify the name of the program's entry point.  This should only be used
if the output is an executable (@code{.exe}).  If this option is not present,
the linker will attempt to deduce which method is the entry point by
inspecting the names and signatures of methods within the input files.
The name is either a class name, or a class name plus method name.
The sequence @code{::} is used to separate the class and method names.
Examples are @code{MyClass}, @code{MyNamespace.MyClass}, and
@code{MyNamespace.MyClass::Main}.

@cindex -r option (ilalink)
@cindex -fresources option (ilalink)
@item -r FILE
@itemx -fresources=FILE
Specify the name of a resource file to be linked with the output assembly.

@cindex -R option (ilalink)
@cindex --resources-only option (ilalink)
@item -R
@itemx --resources-only
Create an output assembly that only contains resources.  This is useful
for building satellite resource assemblies for foreign languages.

@cindex -p option (ilalink)
@cindex -fprivate-resources option (ilalink)
@item -p
@itemx -fprivate-resources
Mark the resources as private to the output assembly.

@cindex -H option (ilalink)
@cindex -fhash-algorithm option (ilalink)
@item -H ALG
@itemx -fhash-algorithm=ALG
Set the assembly hash algorithm to @code{ALG}, which must be either
@code{SHA1} or @code{MD5}.  The default is @code{SHA1}.

@cindex -3 option (ilalink)
@cindex -m32bit-only option (ilalink)
@item -3
@itemx -m32bit-only
Mark the final output assembly so that it can only be used on 32-bit
systems.  Use of this option is severely discouraged.

@cindex -c option (ilalink)
@cindex -mcui-subsystem option (ilalink)
@item -c
@itemx -mcui-subsystem
Link the final output assembly for the command-line subsystem
on Windows.  This is the default.

@cindex -G option (ilalink)
@cindex -mgui-subsystem option (ilalink)
Link the final output assembly for the GUI subsystem on Windows.

@cindex --help option (ilalink)
@item --help
Print a usage message for the ilalink program.

@cindex -v option (ilalink)
@cindex --version option (ilalink)
@item -v
@itemx --version
Print the version of the ilalink program.

@item --
Marks the end of the command-line options, and the beginning of
the input filenames.  You may need to use this if your filename
begins with @code{-}.  e.g. @code{ilalink -- -input.obj}.  This is
not needed if the input is stdin: @code{ilalink -} is perfectly valid.
@end table

The @code{-f} and @code{-m} options can be specified on the cscc
command-line, and will be passed to the linker automatically by the compiler.

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.

@c -----------------------------------------------------------------------

@node Size, ilsize invocation, ilalink invocation, Top
@chapter Intermediate language size utility
@cindex Size
@cindex ilsize

Ilsize lists size information for each of the sections within an IL object
file (@code{.obj}), an IL executable (@code{.exe}), or an IL dynamic link
library (@code{.dll}).  The output is similar to that produced by size(1).

@menu
* ilsize invocation::       Invoking ilsize
@end menu

@c -----------------------------------------------------------------------

@node ilsize invocation, Native, Size, Size
@section Invoking ilsize
@cindex ilsize invocation

The general form of the ilsize syntax is as follows:

@example
ilsize [OPTIONS] input ...
@end example

@table @code
@cindex --radix option (ilsize)
@item --radix NUM
Set the radix for displaying size values within the output.  The default
value is 10.  Legal values are 8, 10, and 16.

@cindex -d option (ilsize)
@item -d
Set the radix to 10.  Same as @code{--radix 10}.

@cindex -o option (ilsize)
@item -o
Set the radix to 8.   Same as @code{--radix 8}.

@cindex -x option (ilsize)
@item -x
Set the radix to 16.  Same as @code{--radix 16}.

@cindex -D option (ilsize)
@cindex --detailed option (ilsize)
@item -D
@itemx --detailed
Use a more detailed output that also includes the number of classes,
fields, methods, etc.

@cindex --help option (ilsize)
@item --help
Print a usage message for the ilsize program.

@cindex -v option (ilsize)
@cindex -V option (ilsize)
@cindex --version option (ilsize)
@item -v
@itemx -V
@itemx --version
Print the version of the ilsize program.

@item --
Marks the end of the command-line options, and the beginning of
the input filenames.  You may need to use this if your filename
begins with @code{-}.  e.g. @code{ilsize -- -input.obj}.  This is
not needed if the input is stdin: @code{ilsize -} is perfectly valid.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.  @xref{Load Errors}, for a
complete list of errors that may occur when loading an IL image file.

Ilsize does not currently understand the format of @code{.a} or
@code{.lib} archive libraries, so it cannot display information about
archive contents like size(1) can.

@c -----------------------------------------------------------------------

@node Native, ilnative invocation, ilsize invocation, Top
@chapter Intermediate language native utility
@cindex Native
@cindex ilnative

Ilnative lists the native methods that are used within an IL object file
(@code{.obj}), an IL executable (@code{.exe}), or an IL dynamic link
library (@code{.dll}).  This can aid developers who are building programs
that use native methods, or developers who are attempting to discover which
native methods a third party program requires.

@menu
* ilnative invocation::     Invoking ilnative
@end menu

@c -----------------------------------------------------------------------

@node ilnative invocation, Find, Native, Native
@section Invoking ilnative
@cindex ilnative invocation

The general form of the ilnative syntax is as follows:

@example
ilnative [OPTIONS] INPUT ...
@end example

@table @code
@cindex -n option (ilnative)
@cindex --names-only option (ilnative)
@item -n
@itemx --names-only
Only print the names of the methods, and not the type information.

@cindex --help option (ilnative)
@item --help
Print a usage message for the ilnative program.

@cindex -v option (ilnative)
@cindex --version option (ilnative)
@item -v
@itemx --version
Print the version of the ilnative program.

@item --
Marks the end of the command-line options, and the beginning of
the input filenames.  You may need to use this if your filename
begins with @code{-}.  e.g. @code{ilnative -- -input.obj}.
This is not needed if the input is stdin: @code{ilnative -}
is perfectly valid.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.  @xref{Load Errors}, for a
complete list of errors that may occur when loading an IL image file.

@c -----------------------------------------------------------------------

@node Find, ilfind invocation, ilnative invocation, Top
@chapter Intermediate language name find utility
@cindex Find
@cindex ilfind

Ilfind searches for a pattern within the supplied input files.  Each input
file must be an IL object file (@code{.obj}), an IL executable (@code{.exe}),
or an IL dynamic link library (@code{.dll}).

For each assembly, namespace, class, field, method, event, or property
whose name matches the pattern, a line is written to standard output
describing the match.

@menu
* ilfind invocation::       Invoking ilfind
@end menu

@c -----------------------------------------------------------------------

@node ilfind invocation, Dependencies, Find, Find
@section Invoking ilfind
@cindex ilfind invocation

The general form of the ilfind syntax is as follows:

@example
ilfind [OPTIONS] PATTERN INPUT ...
@end example

@table @code
@cindex -w option (ilfind)
@cindex --whole-string option (ilfind)
@item -w
@itemx --whole-string
Match the whole pattern string against names in the input files.
This is the default.  For example, the pattern @code{ABC} will match
classes, fields, and methods called @code{ABC}, but will not match
items called @code{ABCD}.

@cindex -s option (ilfind)
@cindex --sub-string option (ilfind)
@item -s
@itemx --sub-string
Match the pattern against sub-strings of names in the input files.
For example, the pattern @code{ABC} will match any item that contains
@code{ABC} within its name.

@cindex -f option (ilfind)
@cindex --file-regex option (ilfind)
@item -f
@itemx --file-regex
Use a file-like regular expression matching scheme.  This is the
default.  Patterns can use `?' and `*' to match a single character
or multiple characters.  Patterns can use the characters `[' and `]'
to group a set of alternative characters.  This pattern syntax
is similar to that used to match filenames in shells such as
sh(1) and csh(1).

@cindex -g option (ilfind)
@cindex --grep-regex option (ilfind)
@item -g
@item --grep-regex
Use a regular expression matching scheme similar to grep(1).
Note: the `^' and `$' characters will be implicitly prepended and
appended to the pattern if whole string matching is enabled
(@code{-w}).

@cindex -n option (ilfind)
@cindex --no-regex option (ilfind)
@item -n
@itemx --no-regex
Do not use regular expression matching.  This will perform a simple
identity check against names (@code{-w}) or a simple sub-string check
(@code{-s}).

@cindex -i option (ilfind)
@cindex --ignore-case option (ilfind)
@item -i
@itemx --ignore-case
Ignore case when matching names against the pattern.

@cindex -p option (ilfind)
@cindex --public-only option (ilfind)
@item -p
@itemx --public-only
Search only the classes that are publicly accessible.

@cindex --help option (ilfind)
@item --help
Print a usage message for the ilfind program.

@cindex -v option (ilfind)
@cindex --version option (ilfind)
@item -v
@itemx --version
Print the version of the ilfind program.

@item --
Marks the end of the command-line options.  The next argument is
the pattern.  You may need to use this if your pattern
begins with @code{-}.  e.g. @code{ilfind -- -name input.obj}.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.  @xref{Load Errors}, for a
complete list of errors that may occur when loading an IL image file.

@c -----------------------------------------------------------------------

@node Dependencies, ildd invocation, ilfind invocation, Top
@chapter Intermediate language dependency utility
@cindex Dependencies
@cindex ildd

Ildd lists the assemblies and PInvoke modules that are referenced by
an IL object file (@code{.obj}), an IL executable (@code{.exe}),
or an IL dynamic link library (@code{.dll}).

@menu
* ildd invocation::         Invoking ildd
@end menu

@c -----------------------------------------------------------------------

@node ildd invocation, Resources, Dependencies, Dependencies
@section Invoking ildd
@cindex ildd invocation

The general form of the ildd syntax is as follows:

@example
ildd [OPTIONS] PATTERN INPUT ...
@end example

@table @code
@cindex --help option (ildd)
@item --help
Print a usage message for the ildd program.

@cindex -v option (ildd)
@cindex --version option (ildd)
@item -v
@itemx --version
Print the version of the ildd program.

@item --
Marks the end of the command-line options.  The next argument is
the pattern.  You may need to use this if your filename
begins with @code{-}.  e.g. @code{ildd -- -input.exe}.  This is
not needed if the input is stdin: @code{ildd -} is perfectly valid.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.  @xref{Load Errors}, for a
complete list of errors that may occur when loading an IL image file.

@c -----------------------------------------------------------------------

@node Resources, resgen invocation, ildd invocation, Top
@chapter Resource generation and conversion
@cindex Resources
@cindex resgen

Resgen converts strings between a number of resource formats that are used
within the Portable.NET platform.  It is typically used to convert
text resources (@code{.txt}), XML resources (@code{.resx}), or GNU gettext
resources (.po) into binary resources (@code{.resources}) that can be
attached to an IL executable or dynamic link library.

@menu
* resgen invocation::       Invoking resgen
* Resource Format::         Text resource file format
* Resource Examples::       Resource conversion examples
@end menu

@c -----------------------------------------------------------------------

@node resgen invocation, Resource Format, Resources, Resources
@section Invoking resgen
@cindex resgen invocation

The general form of the resgen syntax is as follows:

@example
resgen [OPTIONS] INPUT ... OUTPUT
@end example

Resgen can convert multiple input files into a single output file.
A number of options are available to specify the format of the
input files and the output file.  Alternatively, resgen can
guess the format of a file from its extension:

@table @code
@item .txt
@itemx .text
Text resources.

@item .resources
Binary resources.

@item .resx
@itemx .xml
XML resources.

@item .po
GNU gettext resources.

@item .exe
@itemx .dll
@itemx .obj
@itemx .o
Binary resources within an IL image (input only).
@end table

The input filename @code{-} may be used to specify standard input.  If an
input format is not specified, standard input is assumed to contain
text resources.

The output filename @code{-} may be used to specify standard output.  If an
output format is not specified, the format of standard output is
assumed to be text.

@table @code
@cindex -t option (resgen)
@cindex --text-input option (resgen)
@item -t
@itemx --text-input
The input files are all assumed to be in text resource format.

@cindex -r option (resgen)
@cindex --res-input option (resgen)
@item -r
@itemx --res-input
The input files are all assumed to be in binary resource format.

@cindex -i option (resgen)
@cindex --il-input option (resgen)
@item -i
@itemx --il-input
The input files are all assumed to be IL image files (i.e. executables,
dynamic link libraries, or object files).

@cindex -x option (resgen)
@cindex --xml-input option (resgen)
@item -x
@itemx --xml-input
The input files are all assumed to be in XML resource format.

@cindex -p option (resgen)
@cindex --po-input option (resgen)
@item -p
@itemx --po-input
The input files are all assumed to be in GNU gettext .po resource format.

@cindex -T option (resgen)
@cindex --text-output option (resgen)
@item -T
@itemx --text-output
The output format is set to text resources.

@cindex -R option (resgen)
@cindex --res-output option (resgen)
@item -R
@itemx --res-output
The output format is set to binary resources.

@cindex -X option (resgen)
@cindex --xml-output option (resgen)
@item -X
@itemx --xml-output
The output format is set to XML resources.

@cindex -P option (resgen)
@cindex --po-output option (resgen)
@item -P
@itemx --po-output
The output format is set to GNU gettext .po resources.

@cindex -s option (resgen)
@cindex --sort-names option (resgen)
@item -s
@itemx --sort-names
When writing text resources as output, sort the resources by name.
This typically makes it easier for humans to read the output.

This option is ignored if the output format is not text.

@cindex --help option (resgen)
@item --help
Print a usage message for the resgen program.

@cindex -v option (resgen)
@cindex --version option (resgen)
@item -v
@itemx --version
Print the version of the \fBresgen\fR program.

@item --
Marks the end of the command-line options, and the beginning of
the input filenames.  You may need to use this if your filename
begins with @code{-}.  e.g. @code{ilresgen -- -input.txt output.resources}.
This is not needed if the input is stdin: @code{ilresgen - output.resources}
is perfectly valid.
@end table

The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.

@c -----------------------------------------------------------------------

@node Resource Format, Resource Examples, resgen invocation, Resources
@section Text resource file format
@cindex Resource Format

Text resource files contain one line for each resource.  Each line
has the form @code{name=value}, where @code{name} is the
tag name associated with the resource, and @code{value} is the
resource's string value.  For example:

@example
Arg_InvalidBase=Base must be 2, 8, 10, or 16
Overflow_Byte=Valid Byte values are between 0 and 255, inclusive
@end example

Comments are lines that begin with a @code{#} character.  Blank lines
are also considered comments.

Resource string values are assumed to be in the UTF-8 text encoding.
No other character sets are currently supported.  Values can contain
one of the following escape sequences, which indicate special
characters:

@table @code
@item \n
Newline character, @code{\u000A}.

@item \r
Carriage return character, @code{\u000D}.

@item \t
TAB character, @code{\u0009}.

@item \f
Form feed character, @code{\u000C}.

@item \v
Vertical TAB character, @code{\u000B}.

@item \0
NUL character, @code{\u0000}.

@item \NNN
8-bit octal Unicode character.

@item \xHH
8-bit hexadecimal Unicode character.

@item \uHHHH
16-bit hexadecimal Unicode character.

@item \UHHHHHHHH
32-bit hexadecimal Unicode character.
@end table

@c -----------------------------------------------------------------------

@node Resource Examples, ECMA Extensions, Resource Format, Resources
@section Resource conversion examples
@cindex Resource Examples

The following command-line converts three text resource input files
into a binary resource output file:

@example
resgen file1.txt file2.txt file3.txt output.resources
@end example

If the files did not have extensions whose format can be guessed,
then command-line options can be used specify the formats:

@example
resgen --text-input --res-output file1 file2 file3 output
@end example

The default resources within an executable can be extracted to text
format on standard output as follows:

@example
resgen -s program.exe -
@end example

The @code{-s} option was used here to sort the output so that it is more
easily digested by the user.

@c -----------------------------------------------------------------------

@node ECMA Extensions, Object Files, Resource Examples, Top
@chapter ECMA file format extensions
@cindex ECMA Extensions

The ECMA Partition II specification for IL binaries is missing some
capabilities that a full development toolchain requires.  This chapter
describes extensions to the ECMA file formats that our development
tools use.  This information is provided to assist interoperation
between free software projects that manipulate IL binaries.

@menu
* Object Files::            Object file format extensions
* Debug Symbols::           Debug symbol extensions
@end menu

@c -----------------------------------------------------------------------

@node Object Files, Debug Symbols, ECMA Extensions, ECMA Extensions
@section Object file format extensions
@cindex Object Files
@cindex .text$il section

The ECMA specifications on IL binaries do not define an object
file format for incremental compilations.  Tools from other vendors
typically take an entire set of source files and compile them to either
a @code{.exe} or @code{.dll} in one hit.

Because we wish to support incremental compilation of programs and libraries
through the cscc compiler, we have defined an object file format
for IL binaries, which is similar to the PE/COFF .obj format on Windows
systems.

IL object files are PE/COFF images with the following properties:

@itemize @bullet
@item
There is no MS-DOS stub program or PE signature.

@item
The machine type in the PE/COFF header is always 0x014C (386), which
also acts as the "magic number" to detect whether a file is an object
or an executable/DLL.

@item
There is no optional header after the main PE/COFF header, and the
"characteristics" field is set to zero.

@item
The IL runtime header, code, resources, metadata, etc are placed in
a read-only section called @code{.text$il} instead of @code{.text}.
The IL runtime header begins at the start of the section.

@item
Other PE/COFF sections such as @code{.text}, @code{.rsrc}, and @code{.reloc},
can be omitted.  If present, they provide information about native code which
is outside the scope of this specification.
@end itemize

The IL data in the @code{.text$il} section is formatted in accordance with
the normal ECMA conventions for DLL's.  At link time, the metadata can be used
to combine multiple object files into a single DLL or executable.

This format was designed to be as compatible as possible with regular
PE/COFF object files.  The main distinguishing characteristic is the
use of @code{.text$il} to tag the file as containing IL data.

@c -----------------------------------------------------------------------

@node Debug Symbols, Load Errors, Object Files, ECMA Extensions
@section Debug symbol extensions
@cindex Debug Symbols
@cindex .ildebug section

The assembler syntax defined in the ECMA specification allows for line
number and local variable name information to be inserted into the
assembly code stream.  This information is typically used by source-level
debuggers.

However, ECMA does not specify a standard way to represent this
debug information in the final IL binary.  It leaves it instead
to the specific implementations.

The following sections describe the format used by our development tools
for representing debug information within the IL binary.

@subsection Requirements

The following requirements were identified for the debug format:

@itemize @bullet
@item
It must be easy to strip from an image file.

@item
It should not impact runtime engines and tools that are
unaware of how to handle the debug information.

@item
It must be extensible to new debug data in the future,
while retaining forwards and backwards compatibility.

@item
It should be efficient to locate all debug information
that is relevant to a metadata token.
@end itemize

@subsection The @code{.ildebug} section

All debug information for an IL image is placed into a read-only,
discardable, data section called @code{.ildebug}.

The contents of @code{.ildebug} should be the last section within
the PE/COFF image file.  This allows the debug information to be easily
stripped by truncating the image, removing the @code{.ildebug}
entry from the PE/COFF section table, and reducing the total image size
in the PE/COFF headers.

The section begins with a header consisting of the following fields:

@table @asis
@item Magic
4-byte magic number string @code{ILDB}.

@item Version
32-bit value indicating the version.  This must be 1.

@item IndexOffset
32-bit offset from the start of this header to the beginning
of the token index.

@item NumIndexEntries
32-bit value that indicates the number of entries in the
token index.

@item StringOffset
32-bit offset from the start of this header to the beginning
of the string table.

@item StringLength
32-bit value that indicates the length of the string table.
@end table

Unless otherwise stated, all numeric quantities will be assumed to be
in little-endian order.

@subsection Token index

The token index consists of 8-byte entries of the following form:

@table @asis
@item Token
32-bit token value.

@item Offset
32-bit offset from the start of the debug section to
a block of debug information that is associated with
the token.
@end table

The token index must be sorted into ascending order of "Token",
and should be aligned on a 4-byte boundary.  There may be multiple
entries in the index for the same token.  Use the following algorithm
to locate all debug information for a token:

@itemize @bullet
@item
Perform a binary search within the index for the token.

@item
Scan backwards in the index until the first entry for the token is found.

@item
Scan forwards in the index until the last entry for the token is found.
@end itemize

Because the token index is sorted, multiple debug information blocks
for the same token could be in any order.  Tools should not rely upon
the blocks being in any particular order, and are free to change the
order when modifying the debug section.

All of the debug information in this document refers to a specific
metadata token.  However, in the future it may be possible for
debug information to pertain to the entire image, or to objects
other than metadata tokens.  To store debug information for non-tokens,
it is first necessary to construct a pseudo-token using the following
algorithm:

@itemize @bullet
@item
Pick a unique 4-character string for the item.
e.g. @code{ABCD}.  The last character must be 7-bit ASCII.

@item
Convert the string into a little-endian value, where the
first character is assumed to be the least significant
byte.  e.g. @code{0x44434241}.

@item
Set the high bit of the value to 1.  e.g. @code{0xC4434241}.
@end itemize

The result is the pseudo-token value.  Because regular metadata
tokens cannot have their high bit set, this will result in a value
that won't conflict with regular tokens.

As an additional requirement, standard pseudo-tokens will use
upper case characters in their names.  e.g. @code{ABCD}.
Private pseudo-tokens will use lower case characters.
e.g. @code{abcd}.  There are no standard pseudo-tokens
at present.

@subsection String table

The string table stores NUL-terminated strings that are referenced
by the debug information.  In the current version of this document,
the strings will typically be filenames and local variable names.

Strings are referenced by their index, which is an offset from the
beginning of the string table.  The string value begins at that offset
and continues until the next zero byte is encountered.  The last byte
in the string table must be zero, which means that the string table
can never be empty.

This document does not specify any particular character set for
the strings.

@subsection Debug information blocks

Each entry in the token index contains an offset of the debug
information that is associated with that entry.  This debug
information begins with the following header:

@table @asis
@item Type
The type of debug information.

@item Length
The number of bytes of debug information that follow this header.
@end table

The "Type" and "Length" values are encoded with the same multi-byte
"compressed" format used in metadata to encode unsigned 32-bit values:

@table @asis
@item 0-127
Encode as the value itself in a single byte.

@item 128-16383
Encode as @code{(0x80 | (value >> 8))}, @code{(value & 0xFF)}.
Note: 16383 is (2^14 - 1).

@item 16384-536870911
Encode as @code{(0xC0 | (value >> 24))}, @code{((value >> 16) & 0xFF)},
@code{((value >> 8) & 0xFF)}, @code{(value & 0xFF)}.
Note: 536870911 is (2^29 - 1).

@item 536870912-4294967295
Encode as @code{0xE0}, @code{((value >> 24) & 0xFF)},
@code{((value >> 16) & 0xFF)}, @code{((value >> 8) & 0xFF)},
@code{(value & 0xFF)}.
@end table

The following debug types are supported, which are further
described in the following sections:

@table @asis
@item 1
Line number and column block.

@item 2
Line number and offsets block.

@item 3
Line number, column, and offsets block.

@item 4
Local variables block.

@item 5
Local variables and offsets block.
@end table

If a debug block type is not understood, it should be silently ignored.
This allows future versions of this specification to extend the set
of debug block types without affecting existing implementations

All of the values described below are encoded using the above multi-byte
compressed format.

@subsection Line number and column block

This block begins with an index into the string table that indicates
the name of the file.  The rest of the block consists of pairs of
line number and column values.  A value of zero indicates an
unspecified line or column.

This block type is typically used for metadata tokens, other than methods,
to indicate the line in the source file where the token was declared.

@subsection Line number and offsets block

This block begins with an index into the string table that indicates
the name of the file.  The rest of the block consists of pairs
of line number and offset values.

This block type is typically used for method tokens, to indicate which
source file line corresponds to which offset within the method's code.

@subsection Line number, column, and offsets block

This block begins with an index into the string table that indicates
the name of the file.  The rest of the block consists of triples
of line number, column, and offset values.  A value of zero for the
line or column indicates that it is unspecified.

This block type is typically used for method tokens, to indicate which
source file line corresponds to which offset within the method's code.

The previous type is more compact if column numbers are not available.

@subsection Local variables block

This block consists of pairs of name and index values.  The name value
is an offset into the string table and indicates the name of the local
variable.  The index is the number assigned to the local variable within
the method's code.

This block type is typically used for method tokens whose local variables
extend for the entire scope of the method's body.

@subsection Local variables and offsets block

This block begins with two offset values, indicating the start and end
of a region of code.  The rest of the block consists of pairs of name
and index values for the local variables.

This block is typically used for method tokens where some of the local
variables have a scope that does not extend for the entire length of the
method's body.  Thus, it is possible for the same local variable name
to refer to different indices at different points within the code.

Multiple local variable blocks for a method do not need to be ordered in
any particular way.  Debug tools may need to sort the blocks so that names
in inner scopes override those in outer scopes.

@c -----------------------------------------------------------------------

@node Load Errors, Index, Debug Symbols, Top
@appendix Errors while loading IL binaries
@cindex Load Errors

@table @samp
@item filename: truncated image
The input file is truncated in some way that prevents it from being
read as an IL image.

@item filename: not a valid PE/COFF image
The input file is not a PE/COFF file.  That is, it is not formatted
as a Windows executable or dynamic link library, and is also not
formatted as an object file.  @xref{Object Files}, for details
on the object file format.

@item filename: image does not contain IL data (may be an ordinary Windows executable)
The input file is a valid PE/COFF file, but it does not contain
an IL binary within it.  It is probably an ordinary native Windows
executable that cannot be processed by the development tools.

@item filename: incorrect IL version
The input file is a valid PE/COFF file that contains a valid IL binary,
but the IL data is for an unsupported version.

@item filename: required sections in reverse order
There was something wrong with the order of sections within the file
that caused the loader to need to seek backwards.  This will normally
only happen for IL binaries that have been incorrectly generated or
corrupted in some way.

@item filename: not enough memory to load image
The IL binary was so large that it could not be loaded into memory
prior to processing.

@item filename: bad addresses in image
The PE/COFF file or IL binary within the file contained a "relative
virtual address", or RVA, that was invalid.  This will normally only
happen for IL binaries that have been incorrectly generated or
corrupted in some way.

@item filename: invalid metadata in image
The metadata section was invalid in some way.  Usually this indicates
a corrupted IL binary.

@item filename: uses undocumented metadata feature
The metadata section was mostly valid, but it used features for which
we do not have sufficient documentation to parse successfully.

@item filename: unresolved external references
The metadata section was valid, but it referred to types in another
file that could not be fully resolved.

@item metadata error: ...
Depending on how the development tools were built, errors of this kind
may appear in addition to the other errors listed above.  They provide
additional diagnostics that mainly of interest to the authors.  If you
come across a file that produces such an error, then contact the authors.
@end table

In addition, any of the usual filesystem-related errors may be
produced.  For example, @samp{filename: No such file or directory}.

@c -----------------------------------------------------------------------

@page

@node Index, , Load Errors, Top
@unnumbered Index

@printindex cp

@contents
@bye