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.