.TH mcs 1 "6 January 2001"
.SH NAME
-mcs, gmcs \- Mono Compiler Suite.
+mcs, gmcs, smcs \- Mono C# Compiler (1.0, 2.0, Moonlight)
.SH SYNOPSIS
.B mcs
[option] [source-files]
The
.I mcs
compiler is used to compile against the 1.x profile and implements
-C# 1.0 and 2.0 with the exception of generics and nullable types. The
+C# 1.0 and 2.0 with the exception of generics and nullable types.
+.PP
+The
.I gmcs
-compiler is used to compile against the 2.x profile and implements
-the complete C# 2.0 specification.
+compiler is used to compile against the 2.0 profile and implements
+the complete C# 2.0 specification including generics.
+.PP
+The
+.I smcs
+compiler is used to compile against the Silverlight/Moonlight profile.
+This profile is designed to be used for creating Silverlight/Moonlight
+applications that will run on a web browser. The API exposed by this
+profile is a small subset of the 3.5 API (even if it is commonly
+referred as the 2.1 API, this API is a small subset of 2.0 with a few
+extensions), in addition this profile by default runs with
+-langversion:linq which turns on the C# 3.0 language by default.
+.PP
+See the section on packages for more information.
.PP
-The Mono C# compiler accepts the same options than the Microsoft C#
-compiler does. Those options can start with a slash or a dash
-(/checked is the same as -checked). Additionally to this, the
-GNU-like options are supported, those begin with "--". All
-MCS-specific flags which are not available in the Microsoft C#
-compiler are available only with the GNU-style options.
+The Mono C# compiler accepts the same command line options that the
+Microsoft C# compiler does. Those options can start with a slash or a
+dash (/checked is the same as -checked). Additionally some GNU-like
+options are supported, those begin with "--". All MCS-specific flags
+which are not available in the Microsoft C# compiler are available
+only with the GNU-style options.
.PP
C# source files must end with a ".cs" extension. Compilation of C#
source code requires all the files that make up a library, module or
.I -codepage:ID
Specifies the code page used to process the input files from the
point it is specified on. By default files will be processed in the
-Latin-1 code page. The compiler will also automatically detect
-Unicode files that have an embedded byte mark at the beginning.
-.TP
+environment-dependent native code page. The compiler will also automatically
+detect Unicode files that have an embedded byte mark at the beginning.
+.Sp
Other popular encodings are 28591 (Latin1), 1252 (iso-8859-1) and 65001 (UTF-8).
-.TP
+.Sp
MCS supports a couple of shorthands: "utf8" can be used to specify utf-8 instead
of using the cryptic 65001 and "reset" restores the automatic handling of
code pages. These shorthands are not available on the Microsoft compiler.
.TP
.I \-define:SYMLIST, -d:SYMLIST
-Defines the symbol listed by the semi-colon separeted list SYMLIST
+Defines the symbol listed by the semi-colon separated list SYMLIST
SYMBOL. This can be tested in the source code by the pre-processor,
or can be used by methods that have been tagged with the Conditional
attribute.
set is different in each C# version. This switch can be used to force
the compiler to allow only a subset of the features.
The possible values are:
-.nf
-
-Default - Instruct compiler to use the latest version. Equivalent
-is to omit the switch.
-
-ISO-1 - Restrict compiler to use only ISO standardized features.
+.RS
+.ne 8
+.TP
+.I "Default"
+Instruct compiler to use the latest version. Equivalent is to omit the
+switch (this currently defaults to the C# 2.0 language specification).
+.TP
+.I "ISO-1"
+Restrict compiler to use only first ISO standardized features.
The usage of features such as generics, static classes, anonymous
methods will lead to error.
.TP
+.I "ISO-2"
+Restrict compiler to use only the second ISO standardized features.
+This allows the use of generics, static classes, iterators and
+anonymous methods for example.
+.TP
+.I "linq"
+This enables the C# 3.0 support. Only a few features of C# 3.0 have
+been implemented in the Mono C# compiler, so not everything is
+available.
+.PP
+Notice that this flag only controls the language features available to
+the programmer, it does not control the kind of assemblies produced.
+Programs compiled with mcs will reference the 1.1 APIs, Programs
+compiled with gmcs reference the 2.0 APIs.
+.ne
+.RE
+.TP
.I -lib:PATHLIST
Each path specified in the comma-separated list will direct the
compiler to look for libraries in that specified path.
compiler by default has references to the system assemblies.
.TP
.I \-nowarn:WARNLIST
-Makes the compiler ignore warnings specified in the comma-separeted
+Makes the compiler ignore warnings specified in the comma-separated
list WARNLIST>
.TP
.I -optimize, -optimize+, -optimize-
Used for benchmarking. The compiler will only parse its input files.
.TP
.I \-pkg:package1[,packageN]
+Reference assemblies for the given packages.
+.Sp
The compiler will invoke pkg-config --libs on the set of packages
specified on the command line to obtain libraries and directories to
compile the code.
-.PP
+.Sp
This is typically used with third party components, like this:
.nf
+
$ mcs -pkg:gtk-sharp demo.cs
.fi
-.TP
+.RS
+.ne 8
.TP
.I \-pkg:dotnet
This will instruct the compiler to reference the System.* libraries
available on a typical dotnet framework installation, notice that this
-does not include all of the Mono libraies, only the System.* ones. This
+does not include all of the Mono libraries, only the System.* ones. This
is a convenient shortcut for those porting code.
.TP
+.I \-pkg:olive
+Use this to reference the "Olive" libraries (the 3.0 and 3.5 extended
+libraries).
+.TP
+.I \-pkg:silver
+References the assemblies for creating Moonlight/Silverlight
+applications. This is automatically used when using the
+.I smcs
+compiler, but it is here when developers want to use it with the
+.I gmcs
+compiler.
+.TP
+.I \-pkg:silverdesktop
+Use this option to create Moonlight/Silverlight applications that
+target the desktop. This option allows developers to consume the
+Silverlight APIs with the full 2.0 profile API available to them,
+unlike
+.I smcs
+it gives full access to all the APIs that are part of Mono. The only
+downside is that applications created with silverdesktop will not run
+on the browser. Typically these applications will be launched
+with the
+.I mopen
+command line tool.
+.TP
+For more details see the PACKAGE section in this document
+.ne
+.RE
+.TP
.I -resource:RESOURCE[,ID]
Embeds to the given resource file. The optional ID can be used to
give a different name to the resource. If not specified, the resource
.TP
.I \-recurse:PATTERN, --recurse PATTERN
Does recursive compilation using the specified pattern. In Unix the
-shell will perform globbing, so you migth want to use it like this:
+shell will perform globbing, so you might want to use it like this:
.PP
.nf
$ mcs -recurse:'*.cs'
Use this to stop option parsing, and allow option-looking parameters
to be passed on the command line.
.PP
+.SH PACKAGES
+Depending on the invocation for the C# compiler (mcs, gmcs, or smcs)
+you will get a default set of libraries and versions of those
+libraries that are referenced.
+.PP
+The compiler uses the library path to locate libraries, and is able to
+reference libraries from a particular package if that directory is
+used. To simplify the use of packages, the C# compiler includes the
+-pkg: command line option that is used to load specific collections of
+libraries.
+.PP
+Libraries visible to the compiler are stored relative to the
+installation prefix under PREFIX/lib/mono/ called the PACKAGEBASE and the
+defaults for mcs, gmcs and smcs are as follows:
+.TP
+.I mcs
+References the PACKAGEBASE/1.0 directory
+.TP
+.I gmcs
+References the PACKAGEBASE/2.0 directory
+.TP
+.I smcs
+References the PACKAGEBASE/2.1 directory
+.PP
+Those are the only runtime profiles that exist. Although other
+directories exist (like 3.0 and 3.5) those are not really runtime
+profiles, they are merely placeholders for extra libraries that build
+on the 2.0 foundation.
+.PP
+Software providers will distribute software that is installed relative
+to the PACKAGEBASE directory. This is integrated into the
+.I gacutil
+tool that not only installs public assemblies into the Global Assembly
+Cache (GAC) but also installs them into the PACKAGEBASE/PKG directory
+(where PKG is the name passed to the -package flag to gacutil).
+.PP
+As a developer, if you want to consume the Gtk# libraries, you would
+invoke the compiler like this:
+.nf
+
+ $ mcs -pkg:gtk-sharp-2.0 main.cs
+
+.fi
+The -pkg: option instructs the compiler to fetch the definitions for
+gtk-sharp-2.0 from pkg-config, this is equivalent to passing to the C#
+compiler the output of:
+.nf
+
+ $ pkg-config --libs gtk-sharp-2.0
+
+.fi
+Usually this merely references the libraries from PACKAGEBASE/PKG.
+.PP
+Although there are directory names for 3.0 and 3.5, that does not mean
+that there are 3.0 and 3.5 compiler editions or profiles. Those are
+merely new libraries that must be manually referenced either with the
+proper -pkg: invocation, or by referencing the libraries directly.
+.PP
.SH SPECIAL DEFINES
The
.B TRACE
even if they are only defined in a single file.
.PP
.SH DEBUGGING SUPPORT
-When use the "--debug" or "-g" flag, MCS will create an assembler file
-FILE-debug.s containing debugging information where FILE is the name of
-the generated assembly. You need to run this file through the assembler
-to get a object file FILE-debug.o. See mono's "--dwarf-plus" argument
-for details on how to use this file.
+When using the "-debug" flag, MCS will generate a file with the
+extension .mdb that contains the debugging information for the
+generated assembly. This file is consumed by the Mono debugger (mdb).
+.SH ENVIRONMENT VARIABLES
+.TP
+.I "MCS_COLORS"
+If this variable is set, it contains a string in the form
+"foreground,background" that specifies which color to use to display
+errors on some terminals.
+.Sp
+The background is optional and defaults to your terminal current
+background. The possible colors for foreground are:
+.B black, red, brightred, green, brightgreen, yellow, brightyellow,
+blue, brightblue, magenta, brightmagenta, cyan, brightcyan, grey,
+white and brightwhite.
+.Sp
+The possible colors for background are: black, red, green, yellow,
+blue, magenta, cyan, grey and white.
+.Sp
+For example, you could set these variable from your shell:
+.nf
+ export MCS_COLORS
+ MCS_COLORS=errors=brightwhite,red
+.fi
+.Sp
+You can disable the built-in color scheme by setting this variable to
+"disable".
.SH NOTES
During compilation the MCS compiler defines the __MonoCS__ symbol,
this can be used by pre-processor instructions to compile Mono C#
compiler specific code. Please note that this symbol is only to test
for the compiler, and is not useful to distinguish compilation or
-deployment platforms.
+deployment platforms.
.SH AUTHORS
-The Mono C# Compiler was written by Miguel de Icaza, Ravi Pratap and
-Martin Baulig at Ximian.
+The Mono C# Compiler was written by Miguel de Icaza, Ravi Pratap,
+Martin Baulig, Marek Safar and Raja Harinath. The development was
+funded by Ximian, Novell and Marek Safar.
.PP
.SH LICENSE
The Mono Compiler Suite is released under the terms of the GNU GPL.
Please read the accompanying `COPYING' file for details. Alternative
-licenses are available from Ximian.
+licensing for the compiler is available from Novell.
.PP
.SH SEE ALSO
-mono(1), mint(1), sn(1)
+mdb(1), mono(1), mopen(1), mint(1), sn(1)
.PP
.SH BUGS
-To report bugs in the compiler, you can use `bug-buddy', or you can
-file bug reports in our bug tracking system:
-http://bugzilla.ximian.com.
+To report bugs in the compiler, you must file them on our bug tracking
+system, at:
+http://www.mono-project.com/Bugs
.SH MAILING LIST
-The Mono Mailing List is available at: mono-list-request@ximian.com
+The Mono Mailing lists are listed at http://www.mono-project.com/Mailing_Lists
.SH MORE INFORMATION
-The Mono C# compiler is developed by Ximian, Inc
-(http://www.ximian.com) (http://www.ximian.com) and is based on the
+The Mono C# compiler was developed by Novell, Inc
+(http://www.novell.com, http) and is based on the
ECMA C# language standard available here:
http://www.ecma.ch/ecma1/STAND/ecma-334.htm
-
-
+.PP
+The home page for the Mono C# compiler is at http://www.mono-project.com/CSharp_Compiler
projects / mono.git / blobdiff