This is pnettools.info, produced by makeinfo version 4.3 from
pnettools.texi.
The Portable.NET development tools assist with building and
manipulating images in the portable executable format. development.
Copyright (C) 2001 Southern Storm Software, Pty Ltd
File: pnettools.info, Node: csdoc invocation, Next: csdoc2html invocation, Prev: Cross-References, Up: Documentation
Invoking csdoc
==============
The general form of the csdoc syntax is as follows:
csdoc [OPTIONS] INPUT.cs ...
Csdoc reads the supplied C# source files, and writes XML data to the
file specified by the `-o' option, or to standard output if `-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. *Note Option Summary::, for more information on cscc
options. In addition, the following options have special significance
to csdoc:
`-o FILE'
Specify the name of the file to write the XML output to. The
default is standard output. Specifying `-o -' will also write the
XML to standard output.
`-fprivate'
By default, csdoc will only write public types and members to the
XML output. Specifying `-fprivate' will force csdoc to also
include private types and members.
`-flibrary-name=NAME'
Specify the library name to use for the types in the XML output
file. By default, no library name is used.
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 `__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.
File: pnettools.info, Node: csdoc2html invocation, Next: csdoc2texi invocation, Prev: csdoc invocation, Up: Documentation
Invoking csdoc2html
===================
The general form of the csdoc2html syntax is as follows:
csdoc2html [OPTIONS] INPUT.xml ...
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.
`-o PATH'
`--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 `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 `-', then the output is written to standard output. If
`PATH' is `-', then the output is written to standard output.
`-fsingle-file'
Write all HTML data to a single output file, rather than splitting
the data across multiple files.
`-fmulti-file'
Split the HTML data across multiple output files. The file
`index.html' in the output directory is the main entry point to
browse the collection. This is the default.
`-fframes'
Use HTML frames when writing the output data in multi-file mode.
This is the default.
`-fno-frames'
Do not use HTML frames when writing the output data in multi-file
mode.
`-fcombine-members'
Combine the documentation for type members into the same output
file as the type itself. This is the default.
`-fseparate-members'
Separate the documentation for type members into distinct output
files.
`-fnamespace-directories'
Write the contents of each namespace into a separate sub-directory.
This is the default.
`-fno-namespace-directories'
Write the contents of all namespaces into the primary output
directory, and do not create any sub-directories.
`-ftitle=TITLE'
Specify the title to use for the collection. The default is the
same as the first input filename.
`-fpage-color=COLOR'
Specify the HTML color value to use for the background of pages.
The default is `#FFFFFF'.
`-fdefn-color=COLOR'
Specify the HTML color value to use for the background of type and
member definitions. The default is `#C0C0C0'.
`-fheader-color=COLOR'
Specify the HTML color value to use for the background of table
headers. The default is `#C0C0C0'.
`--help'
Print a usage message for the csdoc2html program.
`-v'
`--version'
Print the version of the csdoc2html program.
`--'
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 `-'. e.g. `csdoc2html -- -input.xml'. This is not
needed if the input is stdin: `csdoc2html -' is perfectly valid.
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:
csdoc -o program.xml program.cs
mkdir temp
csdoc2html -o temp program.xml
This will write a collection of HTML files to the `temp' directory
that describes all of the types and members in the `program.cs' source
file.
File: pnettools.info, Node: csdoc2texi invocation, Next: csdoc2hier invocation, Prev: csdoc2html invocation, Up: Documentation
Invoking csdoc2texi
===================
The general form of the csdoc2texi syntax is as follows:
csdoc2texi [OPTIONS] INPUT.xml ...
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.
`-o FILE'
`--output FILE'
Specify the name of the file to write the texinfo output to. The
default is `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 `-', then the output is
written to standard output. If `FILE' is `-', then the output is
written to standard output.
`-fstandalone'
Make a stand-alone texinfo document that includes headers, a title
page, and an index. This is the default.
`-fembedded'
Make an embedded texinfo document. Use this if you wish to
incorporate the texinfo output into a larger document.
`-fparent=NAME'
Specify the name of the parent node for an embedded document. The
default value is `Top'. This option is ignored in stand-alone
documents.
`-ffilename=NAME'
Specify the value for `@setfilename'. The default is the same as
the first input file with the extension changed to `.info'. If
the first input file is standard input, then the default value is
`stdout.info'. This option is ignored in embedded documents.
`-ftitle=TITLE'
Specify the title to use for the document. The default is the
same as `-ffilename'. This option is ignored in embedded
documents.
`-fdescription=DESC'
Specify the description to use in the info header of the document.
The default is the same as `-ftitle'. This option is ignored in
embedded documents.
`-fchapternewpage=VALUE'
Specify the value for `@setchapternewpage'. The default value is
`on'. Valid values are `on', `off', or `odd'. This option is
ignored in embedded documents.
`-fcopyright=MSG'
Specify the Copyright message to use for the document. The default
is no Copyright message. This option is ignored in embedded
documents.
`-findex'
Include an index chapter in the output. This is the default in
stand-alone documents.
`-fno-index'
Do not include an index chapter in the output. This is the
default in embedded documents.
`-fnewpage'
Use a new page for each type member description. This is the
default.
`-fno-newpage'
Do not use a new page for each type member description.
`--help'
Print a usage message for the csdoc2texi program.
`-v'
`--version'
Print the version of the csdoc2texi program.
`--'
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 `-'. e.g. `csdoc2texi -- -input.xml'. This is not
needed if the input is stdin: `csdoc2texi -' is perfectly valid.
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 _Global
Namespace_.
This arrangement can be modified by creating an embedded document,
including it into another document, and using `@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:
csdoc -o program.xml program.cs
csdoc2texi program.xml
texi2html -split_node program.texi
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:
csdoc -o program.xml program.cs
csdoc2texi program.xml
texi2dvi --pdf program.texi
This assumes that you have `texi2dvi' and `pdftex' installed on your
system. The resulting file, `program.pdf', can be viewed or printed
with the usual PDF tools.
File: pnettools.info, Node: csdoc2hier invocation, Next: Assembler, Prev: csdoc2texi invocation, Up: Documentation
Invoking csdoc2hier
===================
The general form of the csdoc2hier syntax is as follows:
csdoc2hier [OPTIONS] INPUT.xml ...
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.
`-o FILE'
`--output FILE'
Specify the name of the file to write the output to. The default
is standard output. If `FILE' is `-', then the output is also
written to standard output.
`-fby-library'
Organise the output by library.
`--help'
Print a usage message for the csdoc2hier program.
`-v'
`--version'
Print the version of the csdoc2hier program.
`--'
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 `-'. e.g. `csdoc2hier -- -input.xml'. This is not
needed if the input is stdin: `csdoc2hier -' is perfectly valid.
The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.
File: pnettools.info, Node: Assembler, Next: ilasm invocation, Prev: csdoc2hier invocation, Up: Top
Intermediate language assembler
*******************************
Ilasm converts Intermediate Language (IL) assembly code input into
an IL object file (`.obj'), an IL executable (`.exe'), or an IL dynamic
link library (`.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
File: pnettools.info, Node: ilasm invocation, Next: Assembler Syntax, Prev: Assembler, Up: Assembler
Invoking ilasm
==============
The general form of the ilasm syntax is as follows:
ilasm [OPTIONS] INPUT.il ...
Ilasm reads the supplied input files, assembles them, and writes the
output to the file specified by the `-o' option, or to a default
filename derived from the name of the first input file. If any of the
input filenames are `-', then the standard input stream will be used.
If `-' 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.
`-o FILE'
`--output FILE'
Specify the name of the file to write the assembler output to. The
default is `INPUT.EXT' where `EXT' is one of `obj', `exe', or
`dll', depending on the value of the `--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 `-', then the output is written to standard output. If
`FILE' is `-', then the output is written to standard output.
`-j'
`--format obj'
Write a `.obj' file as output, instead of an executable or dynamic
link library. This is the default value.
`-e'
`--format exe'
Write an executable file as output, instead of a `.obj' file or
dynamic link library.
`-d'
`--format dll'
Write a dynamic link library file as output, instead of a `.obj'
file or executable.
`-g'
`--debug'
Enable the generation of debug symbol information to the output
file.
`-n'
`--no-debug'
Disable the generation of debug symbol information to the output
file. This is the default value.
`-s'
`-fshort-insns'
Always use the shortest version of an instruction when creating the
output. Some instructions have multiple versions. e.g. `br' and
`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.
`-l'
`-fno-short-insns'
Always use the stated version of an instruction when creating the
output. For example, `br' will always generate a 5-byte branch
instruction, and `br.s' will always generate a 2-byte branch
instruction. If the branch is too long, then using `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.
`-L NAME'
`-fstdlib-name=NAME'
Change the name of the standard library to NAME. The default
value is "mscorlib".
`-J'
`-mjvm'
Assemble to JVM bytecode instead of IL.
`-3'
`-m32bit-only'
Tag the output file so that it can only be executed on 32-bit
platforms.
`-c'
`-mcui-subsystem'
Tag the output file so that it can run within the command-line
subsystem under Windows. This is the default.
`-G'
`-mgui-subsystem'
Tag the output file so that it can run within the GUI subsystem
under Windows.
`--help'
Print a usage message for the ilasm program.
`-v'
`--version'
Print the version of the ilasm program.
`--'
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 `-'. e.g. `ilasm -- -input.il'. This is not needed
if the input is stdin: `ilasm -' is perfectly valid.
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 `float' and `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.
File: pnettools.info, Node: Assembler Syntax, Next: Lexical Tokens, Prev: ilasm invocation, Up: Assembler
Assembler Syntax
================
The following sections describe the syntax of the assembly code that
is input to ilasm. The following BNF notations are used:
`A => B'
The non-terminal `A' can be expanded to the sequence `B'.
`*name*'
A lexical terminal keyword called `name'. e.g. `*public*'.
`NAME'
A lexical terminal symbol called `NAME', used to represent
identifiers, numbers, strings, etc.
`{A}'
Zero or more occurrences of `A'.
`(A)+'
One or more occurrences of `A'.
`[A]'
Zero or one occurrences of `A'. i.e. `A' is optional.
`A | B'
Either `A' or `B'.
`<abcd>'
One of the characters `a', `b', `c', or `d'. This is normally
written as `[abcd]' when used for grep(1) regular expressions.
`<^abcd>'
Any character except `a', `b', `c', or `d'.
`<ANY>'
Any character.
`'c''
The character `c'. This can also be expressed as `<c>'.
File: pnettools.info, Node: Lexical Tokens, Next: Helper Non-Terminals, Prev: Assembler Syntax, Up: Assembler
Lexical tokens
==============
The syntax uses lexical terminal symbols called `IDENT', `INT',
`FLOAT', `SQSTRING', `DQSTRING', and `HEXBYTE'. Their structure is
defined as follows:
IDENT => IDALPHA { IDALPHA | DIGIT }
INT => ['-'] (DIGIT)+
| ['-'] '0' <xX> (<0-9a-fA-F>)+
| ['-'] '0' {<0-7>}
FLOAT => [<+->] (DIGIT)+ EXPONENT
| [<+->] {DIGIT} '.' (DIGIT)+ [EXPONENT]
| [<+->] (DIGIT)+ '.' {DIGIT} [EXPONENT]
SQSTRING => <'> { '\' <ANY> | <^'\> } <'>
DQSTRING => '"' { '\' <ANY> | <^"\> } '"'
HEXBYTE => (<0-9a-fA-F>)+
IDALPHA => <a-zA-Z_$?>
DIGIT => <0-9>
EXPONENT => <eE> [<+->] (DIGIT)+
The syntax is very close to that used by C for identifiers, integer
constants, floating point constants, single-quoted strings, and
double-quoted strings. C-like escape sequences can be used for special
characters in strings. Unlike C, single quotes are used for strings
and not character constants. The `HEXBYTE' terminal is used for raw
sequences of bytes in some of the declaration types.
Strings are expected to be in the UTF-8 encoding, ready for
translation into the Unicode strings used by IL binaries. No other
character sets are supported. It is the responsibility of the tool
that generates IL assembly code to perform any necessary character set
conversions.
Comments can be represented in two ways: single-line and multi-line.
Single-line comments begin with `//' and continue to the end of the
current line. Multi-line comments begin with `/*' and continue until
the next occurrence of `*/'. Multi-line comments cannot be nested.
White space in the input is ignored. The allowable white space
characters are Space (0x20), Tab (0x09), Vertical Tab (0x0B), Carriage
Return (0x0D), Line Feed (0x0A), Form Feed (0x0C), and Ctrl-Z (0x1A).
The assembly language has a large number of keywords and instruction
names that begin with lower case letters. If the program uses a keyword
as an identifier for a class, field, method, etc, it must be quoted with
single quotes. For example, a program identifier called `managed'
would need to be written as `'managed'' so that it does not conflict
with the `managed' keyword.
The easiest method to protect identifiers is to quote anything that
begins with a lower case letter. If new keywords are added to ilasm in
the future, there will be no need to modify existing compilers that use
this technique. Compilers can quote only known keywords and
instructions if they wish, but they will not be robust against future
changes.
The following is a list of the assembler keywords:
*abstract algorithm alignment ansi any array as assembly assert
at auto autochar beforefieldinit blob blob_object bool boxed
bstr bytearray byvalstr callmostderived carray catch cdecl
cf char cil class clsid compilercontrolled currency custom
date decimal default demand deny disablejitoptimizer
enablejittracking error explicit extends extern false famandassem
family famorassem fastcall fault field filetime filter final
finally fixed float float32 float64 forwardref fromunmanaged
fullorigin handler hidebysig hresult idispatch il implements
implicitcom implicitres import in inf inheritcheck init initonly
instance int int16 int32 int64 int8 interface internalcall
iunknown java lasterr lateinit lcid linkcheck literal lpstr lpstruct
lptstr lpvoid lpwstr managed marshal method modopt modreq nan
native nested newslot noappdomain noinlining nomachine nomangle
nometadata noncasdemand noncasinheritance noncaslinkdemand
noprocess not_in_gc_heap notserialized null object objectref ole
opt optil out permitonly pinned pinvokeimpl prejitdeny prejitgrant
preservesig private privatescope public publickey readonly record
reqmin reqopt reqrefuse reqsecobj request retval rtspecialname
runtime safearray sealed sequential serializable specialname
static stdcall storage stored_object stream streamed_object string
struct synchronized syschar sysstring tbstr thiscall tls to true
typedref unicode unmanaged unmanagedexp unsigned userdefined value
valuetype vararg variant vector virtual void wchar winapi with*
The following is a list of assembler directives:
*.addon .algorithm .assembly .backing .blob .capability .cctor
.class .comtype .config .corflags .ctor .custom .data .emitbyte
.entrypoint .event .exeloc .export .field .file .fire .get .hash
.imagebase .implicitcom .library .line #line .locale .locals .manifestres
.maxstack .method .mime .module .mresource .namespace .originator .os
.other .override .pack .param .permission .permissionset .processor
.property .publickey .publickeytoken .removeon .set .size .subsystem
.title .try .ver .vtable .vtentry .vtfixup .zeroinit*
The following is a list of the instruction names:
*add add.ovf add.ovf.un and ann.call ann.catch ann.data ann.data.s
ann.dead ann.def ann.hoisted ann.hoisted_call ann.lab ann.live
ann.phi ann.ref ann.ref.s arglist beq beq.s bge bge.s bge.un bge.un.s
bgt bgt.s bgt.un bgt.un.s ble ble.s ble.un ble.un.s blt blt.s blt.un
blt.un.s bne.un bne.un.s box box_old br break brfalse brfalse.s
brinst brinst.s brnull brnull.s br.s brtrue brtrue.s brzero brzero.s
call calli callvirt castclass ceq cgt cgt.un ckfinite clt clt.un
conv.i conv.i1 conv.i2 conv.i4 conv.i8 conv.ovf.i conv.ovf.i1
conv.ovf.i1.un conv.ovf.i2 conv.ovf.i2.un conv.ovf.i4 conv.ovf.i4.un
conv.ovf.i8 conv.ovf.i8.un conv.ovf.i.un conv.ovf.u conv.ovf.u1
conv.ovf.u1.un conv.ovf.u2 conv.ovf.u2.un conv.ovf.u4 conv.ovf.u4.un
conv.ovf.u8 conv.ovf.u8.un conv.ovf.u.un conv.r4 conv.r8 conv.r.un
conv.u conv.u1 conv.u2 conv.u4 conv.u8 cpblk cpobj div div.un dup
endfault endfilter endfinally initblk initobj isinst jmp jmpi ldarg
ldarg.0 ldarg.1 ldarg.2 ldarg.3 ldarga ldarga.s ldarg.s ldc.i4 ldc.i4.0
ldc.i4.1 ldc.i4.2 ldc.i4.3 ldc.i4.4 ldc.i4.5 ldc.i4.6 ldc.i4.7 ldc.i4.8
ldc.i4.m1 ldc.i4.M1 ldc.i4.s ldc.i8 ldc.r4 ldc.r8 ldelema ldelem.i
ldelem.i1 ldelem.i2 ldelem.i4 ldelem.i8 ldelem.r4 ldelem.r8 ldelem.ref
ldelem.u1 ldelem.u2 ldelem.u4 ldelem.u8 ldfld ldflda ldftn ldind.i
ldind.i1 ldind.i2 ldind.i4 ldind.i8 ldind.r4 ldind.r8 ldind.ref
ldind.u1 ldind.u2 ldind.u4 ldind.u8 ldlen ldloc ldloc.0 ldloc.1 ldloc.2
ldloc.3 ldloca ldloca.s ldloc.s ldnull ldobj ldptr ldsfld ldsflda
ldstr ldtoken ldvirtftn leave leave.s localloc mkrefany mul mul.ovf
mul.ovf.un mul.un neg newarr newobj nop not or pop refanytype
refanyval rem rem.un ret rethrow shl shr shr.un sizeof starg starg.s
stelem.i stelem.i1 stelem.i2 stelem.i4 stelem.i8 stelem.r4 stelem.r8
stelem.ref stfld stind.i stind.i1 stind.i2 stind.i4 stind.i8 stind.r4
stind.r8 stind.ref stloc stloc.0 stloc.1 stloc.2 stloc.3 stloc.s
stobj stsfld sub sub.ovf sub.ovf.un switch tail tail. throw unbox
volatile volatile. xor*
File: pnettools.info, Node: Helper Non-Terminals, Next: Top-Level Declarations, Prev: Lexical Tokens, Up: Assembler
Helper Non-Terminals
====================
In this section we define a number of non-terminals that will be used
later in the BNF grammar. They do not necessarily correspond to useful
program constructs on their own.
Identifier => IDENT | SQSTRING
Integer32 => INT /* 32-bit integer */
Integer64 => INT /* 64-bit integer */
Float64 => FLOAT
| *float32* '(' Integer32 ')'
| *float64* '(' Integer64 ')'
| *nan*
| *inf*
| '-' *inf*
ComposedString => DQSTRING
| ComposedString '+' DQSTRING
QualifiedName => Identifier
| QualifiedName '.' Identifier
Bytes => '(' { HEXBYTE } ')'
The second and third forms of the Float64 non-terminal can be used to
convert the raw bit representation of a floating-point number into a
floating-point value. The second form converts the big-endian, 32-bit,
IEEE integer representation of a single-precision value into a 32-bit
float. For example 0x3F800000 represents the value 1.0. The third
form does the same for 64-bit IEEE integer representations of
double-precision values.
The raw bit forms are mainly of use to compilers that wish to output
the exact binary representation of a floating-point constant, rather
than a rounded decimal value.
The ComposedString non-terminal allows long strings to be built up by
appending a sequence of shorter strings.
File: pnettools.info, Node: Top-Level Declarations, Next: Namespace Declarations, Prev: Helper Non-Terminals, Up: Assembler
Top-Level Declarations
======================
The top-most level of the assembly input stream consists of zero or
more declarations:
TopLevel => { Declaration }
Declarations at the top-most level cover program items such as
classes, namespaces, global methods, assembly information, manifest
resources, etc:
Declaration => NamespaceDeclaration
| ClassDeclaration
| FieldDeclaration
| MethodDeclaration
| DebugInformation
| CustomAttributeDeclaration
| AssemblyDeclaration
| AssemblyRefDeclaration
| ModuleDeclaration
| SecurityDeclaration
| ComTypeDeclaration
| FileDeclaration
| ManifestResDeclaration
| DataDeclaration
| VtableDeclaration
| VtfixupDeclaration
The assembler does support some additional kinds of declarations
beyond those described in this document. They are supported for
compatibility with older versions of the assembly syntax, and for
compatibility with tools from other vendors.
The syntax described here is the official Portable.NET syntax, and
deviating from it is not recommended. Support for other syntax may be
removed in a future version of the assembler.
File: pnettools.info, Node: Namespace Declarations, Next: Class Declarations, Prev: Top-Level Declarations, Up: Assembler
Namespace Declarations
======================
Zero or more classes may be grouped together into a namespace, which
prefixes the class name with a particular identifier.
NamespaceDeclaration => *.namespace* QualifiedName
'{' { Declaration } '}'
In the following example, classes with names `C1' and `C2' will be
created within the namespace `N':
.namespace N
{
.class C1 { ... }
.class C2 { ... }
}
Note: the following is not the same as above:
.class N.C1 { ... }
.class N.C2 { ... }
This declares two classes called `N.C1' and `N.C2', within the
global namespace.
File: pnettools.info, Node: Class Declarations, Next: Class Attributes, Prev: Namespace Declarations, Up: Assembler
Class Declarations
==================
Strictly speaking, IL programs do not support classes at all.
Everything is a type. However, for historical reasons, types are
declared by means of a *.class* declaration.
ClassDeclaration => *.class* { ClassAttribute } Identifier
[ *extends* ClassName ]
[ *implements* ClassName { ',' ClassName } ]
'{' { ClassMember } '}'
If the type has custom attributes, they should appear in the assembly
stream just after the class heading and before any other class members.
* Menu:
* Class Attributes:: Attributes that may be used on types.
* Class Members:: Specifying the members of a type.
* Class Layout:: Explicit layout for types.
* Class References:: Referring to local and imported types.
File: pnettools.info, Node: Class Attributes, Next: Class Members, Prev: Class Declarations, Up: Class Declarations
Class Attributes
----------------
ClassAttribute => *public*
| *private*
| *value*
| *unmanaged*
| *interface*
| *sealed*
| *abstract*
| *auto*
| *sequential*
| *explicit*
| *ansi*
| *unicode*
| *autochar*
| *import*
| *serializable*
| *nested public*
| *nested private*
| *nested family*
| *nested assembly*
| *nested famandassem*
| *nested famorassem*
| *beforefieldinit*
| *specialname*
| *rtspecialname*
*public*
Specify that the type is exported from the assembly that declares
it, and is accessible to any other type. This should not be used
on nested types. This corresponds to the C# `public' access level
on non-nested types.
*private*
Specify that the type is private to the assembly that declares it,
and is accessible only to other types in the same assembly. This
should not be used on nested types. This corresponds to the C#
`internal' access level on non-nested types.
*nested public*
Specify that the type is publicly accessible within the scope of
its nesting parent's accessibility. The type is accessible to any
other type that can access the nesting parent. This should only
be used on nested types. This corresponds to the C# `public'
access level on nested types.
*nested private*
Specify that the type is private to its nesting parent and cannot
be accessed by any other type. This should only be used on nested
types. This corresponds to the C# `private' access level on
nested types.
*nested family*
Specify that the type is accessible to its nesting parent and to
any type derived from the nesting parent. This should only be used
on nested types. This corresponds to the C# `protected' access
level on nested types.
*nested assembly*
Specify that the type is accessible to any other type in the
assembly that declares it. This should only be used on nested
types. This corresponds to the C# `internal' access level on
nested types.
*nested famandassem*
Specify that the type is accessible only to types that inherit from
the nesting parent and are also declared in the same assembly as
this type. This should only be used on nested types. There is no
C# equivalent to this access level.
*nested famorassem*
Specify that the type is accessible only to types that inherit from
the nesting parent or that are declared in the same assembly as
this type. This should only be used on nested types. This
corresponds to the C# `protected internal' access level on nested
types.
*value*
Specify that the type is normally used as a value type (C#
`struct') instead of as an object reference.
*unmanaged*
Specify that the type declares an unmanaged value type.
*interface*
Specify that the type is an interface rather than a regular class
or value type. Interfaces should also have the *abstract*
attribute.
*sealed*
Specify that the type cannot be inherited.
*abstract*
Specify that the type cannot be instantiated. This attribute
should be present on interfaces and on any class that has
*abstract* methods.
*auto*
Specify that the fields of the type should be laid out in the most
efficient manner possible, with no user-supplied constraints.
Normally this will be the same as *sequential*, but it does not
have to be the same.
*sequential*
Specify that the fields of the type should be laid out in a manner
which is consistent with the underlying operating system. Most
types will have this attribute set.
*explicit*
Specify that the fields of the type should be laid out using
user-supplied explicit layout rules. These rules are specified
with the *.size* and *.pack* directives, and with explicit offset
information on each of the fields.
*ansi*
Specify that any strings that are marshalled to unmanaged code by
this type should be interpreted using the system's prevailing
locale. If the type does not marshal strings to unmanaged code,
then *ansi* is the default value.
*unicode*
Specify that any strings that are marshalled to unmanaged code by
this type should be interpreted as Unicode. This attribute only
makes sense on Windows machines.
*autochar*
Specify that any strings that are marshalled to unmanaged code by
this type should be interpreted as either Unicode or strings in
the prevailing locale, depending upon the capabilities of the
underlying operating system. This attribute only makes sense on
Windows machines.
*import*
Specify that the type was imported from some other module within
the assembly. This attribute is very rare and can be ignored by
most compilers.
*serializable*
Specify that the fields of the type can be automatically
serialized by the runtime engine's builtin serialization routines.
Any fields that have the *not_serialized* attribute will be
omitted from the builtin serialization.
*beforefieldinit*
Specify that the type does not need to be initialized until the
first time that a static method within the type is called.
*specialname*
Specify that the type may have special significance to tools other
than the runtime engine. This is rarely needed on types.
*rtspecialname*
Specify that the type may have special significance to the runtime
engine. This is rarely needed on types.
File: pnettools.info, Node: Class Members, Next: Class Layout, Prev: Class Attributes, Up: Class Declarations
Class Members
-------------
Types may contain any of the following members:
ClassMember => ClassDeclaration
| ClassLayoutDeclaration
| FieldDeclaration
| MethodDeclaration
| PropertyDeclaration
| EventDeclaration
| DebugInformation
| CustomAttributeDeclaration
| DataDeclaration
| SecurityDeclaration
| ComTypeDeclaration
| ExportDeclaration
| OverrideDeclaration
File: pnettools.info, Node: Class Layout, Next: Class References, Prev: Class Members, Up: Class Declarations
Class Layout
------------
ClassLayoutDeclaration => *.size* Integer32
| *.pack* Integer32
*.size*
Specify the size of the type, in bytes. This should only be used
with *explicit* layout. If this declaration is not present, or
specifies the value zero, then the runtime engine will choose the
size of the type.
*.pack*
Specify the packing size to be used for fields of the type. This
must be one of the values 0, 1, 2, 4, 8, 16, 32, 64, or 128, and
should only be used with *explicit* layout. A packing size of
zero, or a missing packing size, indicates that the default size
for the underlying operating system should be used.
File: pnettools.info, Node: Class References, Next: Type Specifications, Prev: Class Layout, Up: Class Declarations
Class References
----------------
In many places within the assembly source stream, it is necessary to
refer to other classes within the same source, or in other assemblies.
This section describes the syntax of class references.
In IL, there is a distinction defined, primitive, and composed types.
Defined types are used to define the classes and value types that are
used in the program. Primitive types are types such as *int32*,
*bool*, *float64*, etc. Composed types are arrays, pointers, etc, that
are built up from defined and primitive types.
In this section, we will treat a "class name" as a reference to a
defined type, even if the type happens to correspond to a value type.
Primitive and composed types cannot be referred to using class names.
ClassName => [ '[' ImportScope ']' ]
QualifiedName { '/' QualifiedName }
ImportScope => QualifiedName |
| *.module* QualifiedName
| *.library*
Class names begin with an import scope, which specifies where the
defined type is being imported from. If the import scope is not
present, the type is assumed to be declared in the same assembly
stream, or that the type will be resolved by the linker.
If the import scope is a `QualifiedName', then it indicates that the
defined type is being imported from an assembly. The assembler
searches for an assembly reference definition with the same name. If
there is no such assembly reference, then it will search for an
assembly definition with the same name. If an assembly definition is
found, then the interpretation is the same as if the scope was not
supplied at all. An error occurs if there is no assembly reference or
definition for the name.
If the import scope is prefixed with *.module*, then it indicates
that the defined type is being imported from a module. This form of
import is deprecated in favour of assembly imports.
If the import scope is *.library*, then it indicates that the
defined type is being imported from the CLI standard library. This
library is normally in an assembly called `mscorlib', but it is
possible to specify a different name using the `--stdlib-name' option
to `ilasm'.
Following the import scope, the name consists of one of more
components, separated by slashes. A name with no slashes indicates a
type that is declared at the global level of the import scope. A name
with slashes indicates a nested type. For example, the following refers
to the type `HashEntry' which is nested within the standard
`System.Enum' type:
[.library]System.Enum/HashEntry
File: pnettools.info, Node: Type Specifications, Next: Field Declarations, Prev: Class References, Up: Assembler
Type Specifications
===================
Thoughout the assembly source stream, it is necessary to refer to
defined, primitive, and composed types. This is done using type
specifications, which may either be class names or composed types.
TypeSpecification => ClassName | Type
Types may be composed from class names, primitive types, and other
composed types as follows:
Type => *class* ClassName
| *valuetype* ClassName
| Type '[' Bounds { ',' Bounds } ']'
| Type '&' /* reference */
| Type '*' /* pointer */
| Type *pinned*
| Type *modreq* '(' ClassName ')'
| Type *modopt* '(' ClassName ')'
| *method* CallingConventions Type '*'
'(' [ SignatureArguments ] ')'
| PrimitiveType
Every defined type in the program has two forms: class and value
type. The particular form to be used may be specified using the *class*
and *valuetype* prefixes. If the prefix is not present, then the
assembler will guess the correct form from the type definition.
The assembler supports the following primitive type keywords:
PrimitiveType => *void*
| *bool*
| *char*
| *int8*
| *unsigned* *int8*
| *int16*
| *unsigned* *int16*
| *int32*
| *unsigned* *int32*
| *int64*
| *unsigned* *int64*
| *native* *int*
| *native* *unsigned* *int*
| *float32*
| *float64*
| *native* *float*
| *string*
| *object*
| *typedref*
The *string* keyword is replaced with a *class* reference to the
library class `System.String'. The *object* keyword is replaced with a
*class* reference to the library class `System.Object'.
Array bounds are specified as follows:
Bounds => /* empty */
| *...*
| Integer32
| Integer32 *...*
| Integer32 *...* Integer32
The first two forms indicate an array dimension with no lower or
upper bound. The third form indicates an array dimension with lower
bound 0, and the upper bound as one less than the specified value. The
fourth form indicates an array dimension with a specified lower bound,
but no upper bound. The last form indicates an array dimension with
both lower and upper bounds specified.
In certain contexts, types may have marshalling information
associated with them. This marshalling information provides directions
to the runtime engine when it invokes external methods using the PInvoke
mechanism.
MarshalledType => Type [ *marshal* '(' NativeType ')' ]
NativeType => /* empty */
| *custom* '(' ComposedString ',' ComposedString ','
ComposedString ',' ComposedString ')'
| *fixed* *sysstring* '[' Integer32 ']'
| *fixed* *array* '[' Integer32 ']'
| NativeType '*'
| NativeType '[' ']'
| NativeType '[' Integer32 ']'
| NativeType '[' '+' Integer32 ']'
| NativeType '[' Integer32 '+' Integer32 ']'
| *variant*
| *currency*
| *syschar*
| *void*
| *bool*
| *int8*
| *unsigned* *int8*
| *int16*
| *unsigned* *int16*
| *int32*
| *unsigned* *int32*
| *int64*
| *unsigned* *int64*
| *int*
| *unsigned **int*
| *float32*
| *float64*
| *float*
| *error*
| *decimal*
| *date*
| *bstr*
| *lpstr*
| *lpwstr*
| *lptstr*
| *objectref*
| *iunknown*
| *idispatch*
| *struct*
| *interface*
| *nested* *struct*
| *byvalstr*
| *ansi* *bstr*
| *tbstr*
| *variant* *bool*
| *method*
| *lpvoid*
| *as* *any*
| *lpstruct*
Note: native types are highly system-dependent. Many of the types
above only make sense on Windows systems.
File: pnettools.info, Node: Field Declarations, Next: Field Attributes, Prev: Type Specifications, Up: Assembler
Field Declarations
==================
Fields may be defined at the global level of the assembly stream, or
within the body of a class. If the field is global, it must appear
before all class declarations in the assembly stream.
FieldDeclaration => *.field* [ '[' Integer32 ']' ]
{ FieldAttribute } Type Identifier
[ *at* (Integer32 | Identifier) ]
[ '=' FieldInitialization ]
If the field has custom attributes, they should appear in the
assembly stream just after the field declaration.
* Menu:
* Field Attributes:: Attributes that may be used on fields.
* Field Initialization:: Specifying a constant value for a field.
* Field Layout:: Explicit layout for fields.
* Field References:: Referring to local and imported fields.
