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: Top, Next: Overview, Up: (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
File: pnettools.info, Node: Overview, Next: C# Compiler, Prev: Top, Up: Top
Overview
********
This manual describes a set of tools that can be used to build and
manipulate applications for the Portable.NET platform.
`cscc'
The C# compiler. *Note C# Compiler::, for more information.
`csdoc'
The C# documentation conversion utility. *Note Documentation::,
for more information.
`csdoc2hier'
Used to convert C# XML documentation into a tree hierarhcy diagram.
*Note csdoc2hier invocation::, for more information.
`csdoc2html'
Used to convert C# XML documentation into HTML. *Note csdoc2html
invocation::, for more information.
`csdoc2texi'
Used to convert C# XML documentation into texinfo. *Note
csdoc2texi invocation::, for more information.
`ilasm'
The Intermediate Language (IL) assembler. *Note Assembler::, for
more information.
`ildasm'
The IL disassembler. *Note Disassembler::, for more information.
`ilalink'
The IL assembly linker. *Note Linker::, for more information.
`ilsize'
The IL size utility. *Note Size::, for more information.
`ilnative'
The IL native utility. *Note Native::, for more information.
`ilfind'
The IL find utility. *Note Find::, for more information.
`ildd'
The IL dependency utility. *Note Dependencies::, for more
information.
`resgen'
The resource generation utility. *Note Resources::, for more
information.
File: pnettools.info, Node: C# Compiler, Next: cscc invocation, Prev: Overview, Up: Top
C# Compiler
***********
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#
File: pnettools.info, Node: cscc invocation, Next: Option Summary, Prev: C# Compiler, Up: C# Compiler
Invoking cscc
=============
The general form of the cscc syntax is as follows:
cscc [OPTIONS] input ...
The exit status is 1 if an error occurred while processing the input.
Otherwise the exit status is 0.
File: pnettools.info, Node: Option Summary, Next: Overall Options, Prev: cscc invocation, Up: C# Compiler
Option summary for cscc
=======================
Overall Options
*Note Overall Options::
-c -S -E -o FILE -pipe -v -vv -x LANGUAGE
Language Options
*Note Language Options::
-flatin1-charset -foctal-chars -foctal-constants
-fdecimal-constants -fchecked -funchecked -fsyntax-check
-fsemantic-check -funsafe
Warning Options
*Note Warning Options::
-Wall -Werror -w -W -Woctal-chars -Woctal-constants
-Wunknown-escapes -Winvalid-utf8 -Wlarge-unicode-chars
-Wmulti-char-constant -Wunsafe -Wempty-input
Debugging Options
*Note Debugging Options::
-g
Optimization Options
*Note Optimization Options::
-O -O2 -O3 -O0 -fno-peephole
Preprocessor Options
*Note Preprocessor Options::
-C -P -DSYMBOL -USYMBOL -undef -dM -dN
Assembler Options
*Note Assembler Options::
-fno-short-insns -filasm-path=PATHNAME -mjvm
-fstdlib-name=NAME
-fsave-asm
Directory Options
*Note Directory Options::
-IDIR -nostdinc -nostdinc++
Linker Options
*Note Linker Options::
-e ENTRYPOINT -LDIR -nostdlib -lLIBRARY
-shared -static -m32bit-only -fresources=RESFILE
-mcui-subsystem -mgui-subsystem -gtk -gnome
Other Options
*Note Other Options::
-dumpversion --help -fplugin-KEY-path=PATHNAME
File: pnettools.info, Node: Overall Options, Next: Language Options, Prev: Option Summary, Up: C# Compiler
Overall options
===============
`-c'
Compile or assemble the input source files to object files, but do
not link. The object file corresponding to the input file
`FILE.EXT' will be called `FILE.obj' unless the `-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
`-o' option is supplied.
`-S'
Compile the input source files to produce assembly language in the
Intermediate Language format. The assembly file corresponding to
the input file `FILE.EXT' will be called `FILE.il' unless the `-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
`-o' option is supplied.
`-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.
`-o FILE'
Specify the name of the file to write the output to. The default
depends upon how cscc is invoked. Specifying `FILE' as `-'
indicates that the output should be set to standard output.
Standard output can only be used for pre-processing.
If none of `-c', `-S', or `-E' are supplied, then the default
output file is `a.out.exe' or `a.out.dll'. The latter is used
when the `-shared' option is supplied.
`-pipe'
Not used at present. Provided for compatibility with gcc(1).
`-v'
Print verbose debugging information about the files that are being
compiled.
`-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.
`-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 `-x cs' and `-x csharp' specify that the language is
C#.
*Note Language Plugins::, for more information on this option.
Default file extensions typically follow the Windows conventions of
`.obj', `.exe', and `.dll' rather than the Unix conventions of `.o', no
extension, and `.so' respectively. This is due to the Windows nature
of IL binaries, and to prevent confusion with native Unix binaries.
The `-o' option can be used to override the defaults.
File: pnettools.info, Node: Language Options, Next: Warning Options, Prev: Overall Options, Up: C# Compiler
Language options
================
Every language supported by cscc has its own set of language,
warning, and other options. The following sections describe the
options for C# only.
`-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.
`-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 ``\033'' will be
processed as in C, with a warning. The `-Wno-octal-chars' option
can be used to disable the warning. Use the `-fno-octal-chars'
option to disable the use of octal character constants.
`-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 `\033' will be
parsed as decimal, and a warning will be displayed. The
`-Wno-octal-constants' or `-fdecimal-constants' options will
disable the warning.
`-fdecimal-constants'
Parse character sequences that look like octal integers as decimal
and suppress the warning. If both `-foctal-constants' and
`-fdecimal-constants' are supplied, then the former takes
precedence.
`-fchecked'
`-funchecked'
Compile arithmetic expressions so that overflow exceptions will or
will not be thrown, respectively. The default is `-funchecked'.
The `checked' and `unchecked' keywords can be used in source files
to override this setting.
`-fsyntax-check'
Parse the input source file to check its syntax, but don't go any
further with compilation.
`-fsemantic-check'
Parse the input source file to check its syntax and perform
semantic analysis, but don't go any further with compilation.
`-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.
File: pnettools.info, Node: Warning Options, Next: Debugging Options, Prev: Language Options, Up: C# Compiler
Warning options
===============
`-Wall'
`-W'
Enable all warnings that are supported by the compiler.
Individual warnings can be disabled with `-Wno-XXX' options. For
example, `-Wall -Wno-empty-input' will enable all warnings except
the "empty input file" warning.
`-Werror'
Convert all warnings into errors.
`-w'
Suppress all warnings.
`-Woctal-chars'
Warn if the programmer uses the octal form of a character. The C#
language standard only supports `\0', but this compiler also
supports sequences such as `\033'.
`-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.
`-Wunknown-escapes'
Warn if an unknown escape sequence is used in a string or
character constant.
`-Winvalid-utf8'
Warn if an invalid UTF-8 sequence is encountered in the input
source file.
`-Wlarge-unicode-chars'
Warn if a character constant uses a Unicode character with a
codepoint value greater than 65535.
`-Wmulti-char-constant'
Warn if a character constant contains more than one character.
`-Wunsafe'
Warn when an unsafe construct is used in the program.
`-Wempty-input'
Warn if the input source file does not contain any declarations.
File: pnettools.info, Node: Debugging Options, Next: Optimization Options, Prev: Warning Options, Up: C# Compiler
Debugging options
=================
`-g'
Enable the generation of debug symbol information in the output
file.
File: pnettools.info, Node: Optimization Options, Next: Preprocessor Options, Prev: Debugging Options, Up: C# Compiler
Optimization options
====================
`-O'
`-O2'
`-O3'
Enable various levels of optimization.
`-O0'
Disable all optimizations.
`-fno-peephole'
Disable peephole optimization of the code.
File: pnettools.info, Node: Preprocessor Options, Next: Assembler Options, Prev: Optimization Options, Up: C# Compiler
Preprocessor options
====================
`-C'
Include comments in pre-processor output. This option is not yet
supported.
`-P'
Don't use `#line' directives in pre-processor output.
`-DSYMBOL'
Define the macro `SYMBOL' prior to pre-processing the input.
C# does not support macros with values. Supplying a command-line
option of `-DSYMBOL=value' will result in a macro called
`SYMBOL=value', which cannot be tested effectively in C# source
code.
`-USYMBOL'
Undefine the macro `SYMBOL' prior to pre-processing the input.
`-undef'
Undefine all standard macros prior to pre-processing the input.
`-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
`-E' option.
`-dN'
Dump both the pre-processor output and the macros that were
defined. This can only be used with the `-E' option.
The standard macro `__CSCC__' is defined to indicate that cscc is
being used to compile the source code.
The standard macros `DEBUG' or `RELEASE' will be defined to indicate
if a debug (`-g') or release version is being built.
The standard macro `__JVM__' is defined to indicate that the output
is JVM code instead of IL code.
File: pnettools.info, Node: Assembler Options, Next: Directory Options, Prev: Preprocessor Options, Up: C# Compiler
Assembler options
=================
`-fno-short-insns'
Causes the `-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.
`-filasm-path=PATHNAME'
Specifies the full pathname of the ilasm assembler. By default,
cscc searches for ilasm along the PATH.
`-mjvm'
Compile to JVM bytecode instead of IL bytecode.
`-fstdlib-name=NAME'
Change the name of the standard library to NAME. The default
value is "mscorlib".
`-fsave-asm'
Do not delete intermediate assembly output files. This is useful
for debugging compiler problems.
File: pnettools.info, Node: Directory Options, Next: Linker Options, Prev: Assembler Options, Up: C# Compiler
Directory options
=================
`-IDIR'
Specify the name of a directory in which the compiler should search
for included files.
`-fnostdinc'
Don't use standard include directories.
`-fnostdinc++'
Don't use standard C++ include directories.
These options are not currently used by the C# compiler. They are
provided for future language plug-ins that may use include files.
File: pnettools.info, Node: Linker Options, Next: Other Options, Prev: Directory Options, Up: C# Compiler
Linker options
==============
`-e ENTRYPOINT'
Specify the name of the entry point for the program. This may
either be a class name (e.g. `MainClass') or a method name (e.g.
`MainClass.Main'). If this option is not supplied, the linker
will search for any class with a static method called `Main'.
`-LDIR'
Specify the name of a directory in which the compiler should search
for libraries that the program will be linked against.
`-nostdlib'
Don't use standard library directories and libraries.
`-lLIBRARY'
Link against the specified library. For example, specifying
`-lSystem.XML' will search for the library `System.XML.dll' along
the library search path.
Unless `-nostdlib' is supplied, the library `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:
`/usr/local/lib/cscc/System.XML.dll' would have the same effect as
`-lSystem.XML'.
`-shared'
Create a shared library (`.dll') instead of an executable (`.exe').
`-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,
`mscorlib.dll' will never be linked statically.
`-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.
`-fresources=RESFILE'
Specify the name of a resource file to be linked with the final
library or executable. Multiple `-fresources' options may be used
to specify multiple resource files.
`-mcui-subsystem'
Tag the output file so that it can run within the command-line
subsystem under Windows. This is the default.
`-mgui-subsystem'
Tag the output file so that it can run within the GUI subsystem
under Windows.
`-gtk'
Link against all of the libraries that are necessary to use Gtk#.
`-gnome'
Link against all of the libraries that are necessary to use Gnome#.
File: pnettools.info, Node: Other Options, Next: Language Plugins, Prev: Linker Options, Up: C# Compiler
Other options
=============
`-dumpversion'
Dump the version of cscc to standard error and then exit.
`--help'
Print a usage message about the supported options and then exit.
`-fplugin-KEY-path=PATHNAME'
Specify the `PATHNAME' of a language plug-in to be used to compile
the language identified by `KEY'.
*Note Language Plugins::, for more information on plug-ins.
File: pnettools.info, Node: Language Plugins, Next: Compiling to the JVM, Prev: Other Options, Up: C# Compiler
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 `cscc-KEY'
or `cscc-KEY-s' where `KEY' is either the file extension or a language
name. e.g. to create a plug-in for a hypothetical `superc' language,
that uses `.sc' as its primary file extension, create an executable
called `cscc-superc', and a symbolic link called `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 `cscc-sc' plug-in will be
passed any file with an extension of `.sc', `.Sc', `.sC', or `.SC'. If
`.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:
cscc -x superc -o hello.obj -c hello.c
Use this when the extension is not the same as the primary extension
for the language type. Note: `-x sc' could also have been used.
The C# compiler is itself implemented as a plug-in called `cscc-cs',
with a symbolic link to it called `cscc-csharp'.
If the name of the executable ends in `-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
`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:
* Look for a `-fplugin-KEY-path=XXX' command-line option. If it is
present, then `XXX' is used as the plug-in executable. For
example, `-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.
* Look in the directories specified by the `CSCC_PLUGINS_PATH'
environment variable for a file called `cscc-KEY' or `cscc-KEY-s'.
* Look in the installation `plugins' directory, which is normally
something like `/usr/local/lib/cscc/plugins' or
`/usr/lib/cscc/plugins'.
* Look in the same directory from which `cscc' was loaded, by
inspecting the `argv[0]' value.
* Search the PATH for the name.
The cscc front-end passes the following options down to the plug-in:
`-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.
`-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.
`-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
`-E' is supplied, or IL assembly code otherwise.
`-g'
Output debug information.
`-O'
`-O2'
`-O3'
`-O0'
Set the optimization level to 1, 2, 3, and 0 respectively.
`-DSYMBOL'
`-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.
`-USYMBOL'
Undefine a symbol within the plug-in language's preprocessor.
`-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 `__CSCC__' and `DEBUG', unless `-undef' was supplied on its
command-line. Thus, the plug-in does not need to handle these
standard macros itself.
`-IDIR'
Specify an include directory that originated on the cscc
command-line.
`-JDIR'
`-KDIR'
Specify a system include directory, or a C++ system include
directory. The front-end adds `-J' options for each of the system
include directories that it knows about. The front-end adds `-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 `-J' options will not appear if the `-nostdinc' option is
present. The `-K' options will not appear if the `-nostdincpp'
option is present.
`-nostdinc'
`-nostdinc++'
Don't use any system include directories, or C++ system include
directories, that the plug-in is aware of.
`-LDIR'
Specify a library directory that originated on the cscc
command-line.
`-MDIR'
Specify a system library directory. The front-end adds `-M'
options for each of the system library directories that it knows
about. This option will not appear if the `-nostdlib' option is
present.
`-nostdlib'
Don't use any system library directories that the plug-in is aware
of.
`-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 `-l' options will be seen by the plug-in unless
the program is being compiled and linked in one step. e.g.
cscc -o testing.exe testing.sc -lSystem
`-Wall'
Enable all warnings.
`-w'
Suppress the display of all warnings.
`-Werror'
Treat warning messages as errors.
`-WNAME, -Wno-NAME'
Enable or disable the warning called `NAME'.
`-fNAME'
Activate or deactive that compiler extension feature called `NAME'.
`-mNAME'
Activate or deactive that machine extension feature called `NAME'.
In gcc(1), the `-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 `-m' options, or can treat them as a
separate set of compiler extension flags that complement the `-f'
options.
The cscc front-end does support some `-m' options for controlling
the output of the assembler. For example, `-m32bit-only' is used
to force the generation of IL binaries that can only run on 32-bit
systems.
`-dM'
`-dN'
Debugging flags used with languages that support preprocessing.
`-P'
Don't output `#line' directives in preprocessor output.
`-C'
Include comments in the preprocessor output.
`-v'
Provide verbose messages for debugging purposes. This can be
safely ignored if the plug-in does not have a verbose mode.
`-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.
The options are followed by the name of the input file, which may be
`-' 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, `-W', `-f', and `-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:
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
This is followed by a call to ilasm:
ilasm --debug -f no-short-insns \
--format obj -o hello.obj hello.il
Note: in this case, the `-fno-short-insns' flag is intended for the
assembler, rather than the plug-in. The plug-in silently ignores any
`-f' options that it doesn't understand. It may also ignore options
like `-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.
File: pnettools.info, Node: Compiling to the JVM, Next: Differences, Prev: Language Plugins, Up: C# Compiler
Compiling to the JVM
====================
The C# compiler supports compiling to either Intermediate Language
(IL) bytecode, or to Java Virtual Machine (JVM) bytecode. The `-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 `.jar' files, which can contain
multiple classes. It can also compile to the `.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 `.jar' is used instead of `.obj', `.dll', or `.exe'.
The file extension `.jl' is used instead of `.il' for assembly code
streams. IL-specific options such as `-m32bit-only' and
`-fno-short-insns' are ignored.
The ilasm assembler supports dual bytecode formats. A method with
the `java' implementation attribute will be assembled using the Java
instruction set instead of the IL instruction set. For example:
.method public instance int32 foo(int32 x) java
{
iload_0
ireturn
}
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:
C# Type Java Type Problematic? Mangled Code
`sbyte' `byte' No
`byte' `int' Yes `B'
`short' `short' No
`ushort' `int' Yes `S'
`int' `int' Sometimes `i'
`uint' `uint' Yes `I'
`long' `long' Sometimes `l'
`ulong' `long' Yes `L'
`char' `char' No
`float' `float' No
`double' `double' No
`bool' `boolean' No
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 `Ename$'. Value types are mapped to object references and the
mangled code is `V'. Regular class types are mapped to object
references and the mangled code is `C'.
If a field is declared with a problematic type, then its name is
converted into `name__code' where `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:
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);
These will be converted into the following Java definitions after
mangling has been applied:
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);
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 `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 `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
`CLI.Events' indicating which methods correspond to events.
The above mangled codes and attributes can be used to recover the
type information when a `.class' file is loaded by a C#-aware compiler
or runtime engine.
File: pnettools.info, Node: Differences, Next: Special Keywords, Prev: Compiling to the JVM, Up: C# Compiler
Differences between cscc and standard C#
========================================
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
File: pnettools.info, Node: Special Keywords, Next: Pre-defined Macros, Prev: Differences, Up: Differences
Special cscc keywords
=====================
The C# standard reserves identifiers that begin with `__' for use by
the language implementation. We provide five such extensions:
`__builtin_constant', `__arglist', `__makeref', `__reftype', and
`__refvalue'.
The `__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.
`__builtin_constant("float_min")'
The minimum value of type `float' that can be represented. This
is approximately -3.40282346638528859e38f.
`__builtin_constant("float_max")'
The maximum value of type `float' that can be represented. This
is approximately 3.40282346638528859e38f.
`__builtin_constant("float_epsilon")'
The smallest positive non-zero value that can be represented by the
`float' type. This is approximately 1.4e-45f.
`__builtin_constant("double_min")'
The minimum value of type `double' that can be represented. This
is approximately -1.7976931348623157e+308.
`__builtin_constant("double_max")'
The maximum value of type `double' that can be represented. This
is approximately 1.7976931348623157e+308.
`__builtin_constant("double_epsilon")'
The smallest positive non-zero value that can be represented by the
`double' type. This is approximately 4.94065645841247e-324.
The programmer will not normally use these constructs. Instead,
they should use the corresponding constants in the `System.Single' and
`System.Double' classes. The `__builtin_constant' keyword is intended
solely for use in implementing the C# library.
The `__arglist' keyword is used to assist interoperation with C code
that uses variable argument lists. For 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));
}
The `__arglist' keyword is typically used in three different places:
* As the last formal parameter in a method declaration. This
indicates that the method takes a variable number of arguments.
* As the parameter to the `System.ArgIterator' constructor. This
initializes an iterator to traverse the variable arguments.
* As the last actual parameter in a method call to specify the
variable arguments to be passed. The construct `__arglist()' is
used when there are no variable arguments to be passed.
The `__makeref' keyword is used to convert a variable into an
instance of `System.TypedReference'. The single argument can be any
l-value that can be passed by reference using the `ref' keyword (local
variables, object fields, array elements, etc). For example:
int x;
TypedReference tref;
...
tref = __makeref(x);
The `__reftype' keyword is used to extract the type component from
an instance of `System.TypedReference'. For example:
TypedReference tref;
Type type;
...
type = __reftype(tref);
The `__refvalue' keyword is used to extract the value component from
an instance of `System.TypedReference', where the second argument
specifies the type to extract. `System.InvalidCastException' will be
thrown if the value component is not of the specified type. For
example:
TypedReference tref;
int x;
...
x = __refvalue(tref, int);
The `__arglist', `__makeref', `__reftype', and `__refvalue'
extensions are present in C# compilers from other vendors. The
`__builtin_constant' extension is unique to cscc.
File: pnettools.info, Node: Pre-defined Macros, Next: Pre-processor Syntax, Prev: Special Keywords, Up: Differences
Pre-defined pre-procesor macros
===============================
The `cscc' compiler defines a number of pre-processor macros prior
to processing source files.
`__CSCC__'
This macro is defined by the compiler to let the source know that
`cscc' is being used to process the source.
`__JVM__'
This macro is defined by the compiler to let the source know that
the output bytecode format is JVM instead of IL.
`DEBUG'
This macro is defined if the `-g' command-line option is present.
`RELEASE'
This macro is defined if the `-g' command-line option is not
present.
The programmer can disable all pre-defined macros using the `-undef'
command-line option.
File: pnettools.info, Node: Pre-processor Syntax, Next: Documentation, Prev: Pre-defined Macros, Up: Differences
Pre-processor syntax
====================
Slight implementation differences between `cscc' and other C#
compilers result in the following issues when using pre-processing
features:
* Multi-line comments using `/*' and `*/' do not have to end on the
same line. The C# standard disallows the following:
#if DEBUG /* multi-line comment on
multiple lines */
...
#endif
Early C# compilers from other vendors did not allow `/*' style
comments on pre-processor lines at all, so programmers who are
writing portable code should always use `//' style comments on
pre-processor lines.
* `#define' and `#undef' directives can appear anywhere in the input
source. The C# standard disallows these directives after the
first line of real code. e.g.
#define A
namespace N
{
#define B
#if B
class Class1 {}
#endif
}
The `cscc' compiler will accept this input.
* In the C# standard, comments within excluded blocks are not
processed. The following will be parsed correctly if `DEBUG' is
defined:
#if DEBUG
CheckConsistency();
#else
/* Do something else
#endif
The `cscc' compiler will report an error because the `#if' does
not have a matching `#endif'.
* `#region' and `#endregion' directives are ignored. Unmatched
region directives will not cause an error.
File: pnettools.info, Node: Documentation, Next: Documentation Sections, Prev: Pre-processor Syntax, Up: Top
Documentation tools
*******************
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 `///' commenting
convention. For 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)
{
...
}
To process documentation, the `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, `csdoc2html', converts the
XML file into a collection of HTML files which can be viewed using a
standard Web browser.
Another such program, `csdoc2texi', converts the XML file into
texinfo, from which online or printed manuals can be derived.
A third program, `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
File: pnettools.info, Node: Documentation Sections, Next: Documentation Markup, Prev: Documentation, Up: Documentation
Documentation sections
======================
The following XML element tags are used to describe the major
features of a program item in separate sections:
`<summary> ... </summary>'
Specify the summarised description for the current program item.
`<remarks> ... </remarks>'
Specify the detailed description for the current program item.
`<param name="NAME"> ... </param>'
Describe a particular method parameter.
`<returns> ... </returns>'
Describe the value that is returned from a method.
`<value> ... </value>'
Describe the value of a property.
`<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 `CREF'.
`<seealso cref="CREF"/>'
`<seealso topic="TOPIC"/>'
Specify an item or topic to be added to the "See Also" section of
a program item's documentation.
`<example> ... </example>'
Specify the text of an example for the current program 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
`<overload>' element provides the description to use in the main
section, and will normally be identical for all variants.
`<devdoc> ... </devdoc>'
Provides supplemental documentation for developers.
`<altcompliant cref="CREF"/>'
Describes an alternative program item that should be used instead
of the current item in CLS-compliant applications. `CREF' is a
cross-reference string that describes the alternative.
`<altmember cref="CREF"/>'
Specifies an alternative that can be used in place of this member.
`<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.
`<nodoc/>'
Indicate that this program item should be ignored when processed
with conversion programs such as `csdoc2texi'.
`<permission cref="CREF"> ... </permission>'
Specifies a security permission that the program item must have to
be executed.
`<platnote platform="PLATFORM"> ... </platnote>'
Specify a note that only applies to a specific platform.
`<threadsafe> ... </threadsafe>'
Specify text that describes the thread-safety (or otherwise) of the
program item.
File: pnettools.info, Node: Documentation Markup, Next: Cross-References, Prev: Documentation Sections, Up: Documentation
Documentation markup
====================
The following XML element tags are used within the body of the above
elements to mark up the text:
`<b> ... </b>'
Format the text between `<b>' and `</b>' in a bold font.
`<block subset="SUBSET" type="TYPE"> ... </block>'
Normally used inside a `<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 `SUBSET' are `none' and `ECMAOnly'. The
typical value for `TYPE' is `note'.
Note blocks are typically formatted as [Note: ...]. If the subset
is something other than `none', then it will also be shown. For
example, [Note (ECMAOnly): ...].
`<c> ... </c>'
Format the text between `<c>' and `</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.
`<code lang="LANG"> ... </code>'
Format the text between `<code>' and `</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 `LANG' value indicates that the text is an example in a
specific programming language. `LANG' is usually `C#'.
`<list type="LTYPE"> ... </list>'
Format a list of terms and descriptions according to `LTYPE'.
Valid types are `bullet', `number', and `table'.
`<item> ... </item>'
Describe an item within a `<list>' element.
`<listheader> ... </listheader>'
An alternative to `<item>' that is used to describe the headers
for a `table' list.
`<term> ... </term>'
Mark the text that indicates a term within an `<item>' element.
This is only needed for definition lists.
`<description> ... </description>'
Mark the text that is describing a term within an `<item>' element.
`<i> ... </i>'
Format the text between `<i>' and `</i>' in an italicized font.
`<note type="TYPE"> ... <note>'
An alternative way to write `<block subset="none" type="TYPE"> ...
</block>'.
`<para> ... </para>'
Mark the start and end of a paragraph within a documentation block.
`<paramref name="NAME"/>'
Refer to a parameter within a documentation block. The name may
be formatted in an alternative font.
`<see cref="CREF"/>'
Insert a link at the current point in the documentation to the
program item referred to by `CREF'. This is used inline within a
documentation block.
`<see langword="WORD"/>'
Insert a reference to a keyword called `WORD' in the C# language.
The keyword will normally be output using the same font as
`<code>'.
`<sub> ... </sub>'
Format the text between `<sub>' and `</sub>' in a subscript font.
`<sup> ... </sup>'
Format the text between `<sup>' and `</sup>' in a superscript font.
`<subscript term="TERM"/>'
An alternative way of specifying `<sub>TERM</sub>'.
`<superscript term="TERM"/>'
An alternative way of specifying `<sup>TERM</sup>'.
File: pnettools.info, Node: Cross-References, Next: csdoc invocation, Prev: Documentation Markup, Up: Documentation
Documentation cross-references
==============================
Cross-reference prefixes:
`E:'
The prefix is followed by the fully-qualified name of an event.
`F:'
The prefix is followed by the fully-qualified name of a field.
`M:'
The prefix is followed by the fully-qualified name of a method.
`P:'
The prefix is followed by the fully-qualified name of a property.
`T:'
The prefix is followed by the fully-qualified name of a type.
`!:'
The prefix is followed by an error string, which resulted because
the cross-reference could not be resolved.
