X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=man%2Fmcs.1;h=227834b7b5e1c59ba7d61dd10dc7d498a44e22c4;hb=60ab1884daac98d4a95642471f848ed43c4b613f;hp=3c1ada34ece8d96534cf0e47e834fe19705a4c3a;hpb=1b2cc7767c843d81eb66c2603a6149e2802ec3e6;p=mono.git diff --git a/man/mcs.1 b/man/mcs.1 old mode 100755 new mode 100644 index 3c1ada34ece..227834b7b5e --- a/man/mcs.1 +++ b/man/mcs.1 @@ -1,16 +1,31 @@ .TH mcs 1 "6 January 2001" .SH NAME -mcs \- Mono Compiler Suite. +mcs, gmcs \- Mono Compiler Suite. .SH SYNOPSIS .B mcs [option] [source-files] .SH DESCRIPTION mcs is the Mono C# compiler, an implementation of the ECMA-334 -specification. You can pass one or more options to drive the +language specification. You can pass one or more options to drive the compiler, and a set of source files. Extra options or arguments can be provided in a response file. Response files are referenced by prepending the @ symbol to the response file name. .PP +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 +.I gmcs +compiler is used to compile against the 2.x profile and implements +the complete C# 2.0 specification. +.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. +.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 executable to be provided on the command line. There is no support @@ -24,96 +39,282 @@ Language Infrastructure virtual machine such as the Microsoft .NET runtime engine on Windows or the Mono runtime engine on Unix systems. Executables are not bound to a specific CPU or operating system. .PP +The Mono C# compiler by default only references three assemblies: +mscorlib.dll, System.dll and System.Xml.dll. If you want to +reference extra libraries you must manually specify them using the +-pkg: command line option or the -r: command line option. +Alternatively if you want to get all of the System libraries, you can +use the -pkg:dotnet command line option. +.PP .SH OPTIONS .TP .I \-\-about Displays information about the Mono C# compiler .TP -.I \-\-checked +.I \-\-addmodule:MODULE1[,MODULE2] +Includes the specified modules in the resulting assembly. +.TP +.I -checked, -checked+ Sets the default compilation mode to `checked'. This makes all the math operations checked (the default is unchecked). .TP -.I \-\-define SYMBOL -Defines a symbol named SYMBOL. This can be tested in the source code -by the pre-processor. +.I -checked- +Sets the default compilation mode to `unchecked'. This makes all +the math operations unchecked (this is the default). +.TP +.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 +Other popular encodings are 28591 (Latin1), 1252 (iso-8859-1) and 65001 (UTF-8). +.TP +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 +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. +.TP +.I \-debug, \-debug+, \-g +Generate debugging information. To obtain stack traces with debugging +information, you need to invoke the mono runtime with the `--debug' +flag. This debugging information is stored inside the assembly as a +resource. +.TP +.I \-debug- +Do not generate debugging information. +.TP +.I \-delaysign+ +Only embed the strongname public key into the assembly. The actual +signing must be done in a later stage using the SN tool. This is useful +to protect the private key during development. Note that delay signing +can only be done using a strongname key file (not a key container). The +option is equivalent to including [assembly: AssemblyDelaySign (true)] +in your source code. Compiler option takes precedence over the +attributes. +.TP +.I \-delaysign- +Default. Strongname (sign) the assembly using the strong name key file +(or container). The option is equivalent to including [assembly: +AssemblyDelaySign (false)] in your source code. Compiler option takes +precedence over the attributes. +.TP +.I \-doc:FILE +Extracts the C#/XML documentation from the source code and stores in in +the given FILE. .TP +.I \-\-expect-error X L +The compiler will expect the code to generate an error +named `X' in line `L'. This is only used by the test suite. +.TP .I \-\-fatal This is used for debugging the compiler. This makes the error emission generate an exception that can be caught by a debugger. .TP -.I \-\-stacktrace -Generates a stack trace at the time the error is reported, useful for -debugging the compiler. +.I \-keyfile:KEYFILE +Strongname (sign) the output assembly using the key pair present in +the specified strong name key file (snk). A full key pair is required +by default (or when using delaysign-). A file containing only the +public key can be used with delaysign+. The option is equivalent to +including [assembly: AssemblyKeyFile ("KEYFILE")] in your source code. +Compiler option takes precedence over the attributes. +.TP +.I \-keycontainer:CONTAINER +Strongname (sign) the output assembly using the key pair present in +the specified container. Note that delaysign+ is ignored when using +key containers. The option is equivalent to including [assembly: +AssemblyKeyName ("CONTAINER")] in your source code. Compiler option +takes precedence over the attributes. +.TP +.I \-langversion:TEXT +The option specifies the version of the language to use. The feature +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. +The usage of features such as generics, static classes, anonymous +methods will lead to error. +.TP +.I -lib:PATHLIST +Each path specified in the comma-separated list will direct the +compiler to look for libraries in that specified path. .TP .I \-L PATH Directs the compiler to look for libraries in the specified path. -Multiple paths can be provided. +Multiple paths can be provided by using the option multiple times. +.TP +.I \-main:CLASS +Tells the compiler which CLASS contains the entry point. Useful when +you are compiling several classes with a Main method. .TP -.I \-\-nostdlib +.I \-nostdlib, -nostdlib+ Use this flag if you want to compile the core library. This makes the compiler load its internal types from the assembly being compiled. .TP -.I \-\-nowarn XXX -Makes the compiler ignore warning XXX. +.I \-noconfig, \-noconfig+ +Disables the default compiler configuration to be loaded. The +compiler by default has references to the system assemblies. .TP -.I \-o FNAME -Names the output file to be generated. +.I \-nowarn:WARNLIST +Makes the compiler ignore warnings specified in the comma-separeted +list WARNLIST> +.TP +.I -optimize, -optimize+, -optimize- +Controls whether to perform optimizations on the code. -optimize and +-optimize+ will turn on optimizations, -optimize- will turn it off. +The default in mcs is to optimize+. .TP -.I \-\-optimize -Turns on optimizations in the compiler. +.I -out:FNAME, -o FNAME +Names the output file to be generated. .TP .I \-\-parse Used for benchmarking. The compiler will only parse its input files. .TP -.I \-\-probe X L -Probes for the code to generate an error named `X' in line `L'. This -is only used by the test suite. +.I \-pkg:package1[,packageN] +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 +This is typically used with third party components, like this: +.nf + $ mcs -pkg:gtk-sharp demo.cs +.fi +.TP +.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 +is a convenient shortcut for those porting code. +.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 +name will be the file name. +.TP +.I -linkresource:RESOURCE[,ID] +Links to the specified RESOURCE. The optional ID can be used to give +a name to the linked resource. +.TP +.I -r:ASSEMBLY1[,ASSEMBLY2], \-r ASSEMBLY1[,ASSEMBLY2] +Reference the named assemblies. Use this to use classes from the named +assembly in your program. The assembly will be loaded from either the +system directory where all the assemblies live, or from the path +explicitly given with the -L option. +.PP +You can also use a semicolon to separate the assemblies instead of a +comma. +.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: +.PP +.nf + $ mcs -recurse:'*.cs' +.fi .TP -.I \-\- resource FILE -Adds FILE as a resource of the resulting assembly. +.I \-\-stacktrace +Generates a stack trace at the time the error is reported, useful for +debugging the compiler. .TP -.I \-\-target KIND -Used to specify the desired target. The possible values are: exe, -winexe, library and module. +.I \-target:KIND, \-t:KIND +Used to specify the desired target. The possible values are: exe +(plain executable), winexe (Windows.Forms executable), library +(component libraries) and module (partial library). .TP .I \-\-timestamp Another debugging flag. Used to display the times at various points in the compilation process. .TP -.I \-\-unsafe +.I \-unsafe, -unsafe+ Enables compilation of unsafe code. .TP -.I \-\-werror +.I \-v +Debugging. Turns on verbose yacc parsing. +.TP +.I \-v2 +Turns on C# 2.0 language features. +.TP +.I \-\-version +Shows the compiler version. +.TP +.I \-warnaserror, \-warnaserror+ Treat warnings as errors. .TP -.I \-\-wlevel LEVEL +.I \-warn:LEVEL Sets the warning level. 0 is the lowest warning level, and 4 is the highest. The default is 2. .TP -.I \-r ASSEMBLY -Reference the named assembly. Use this to use classes from the named -assembly in your program. +.I \-win32res:FILE +Specifies a Win32 resource file (.res) to be bundled into the +resulting assembly. .TP -.I \-v -Debugging. Turns on verbose yacc parsing. +.I \-win32icon:FILE +Attaches the icon specified in FILE on the output into the resulting +assembly. .TP .I \-\- Use this to stop option parsing, and allow option-looking parameters to be passed on the command line. .PP +.SH SPECIAL DEFINES +The +.B TRACE +and +.B DEBUG +defines have a special meaning to the compiler. +.PP +By default calls to methods and properties in the +System.Diagnostics.Trace class are not generated unless the TRACE +symbol is defined (either through a "#define TRACE") in your source +code, or by using the +.I "--define TRACE" +in the command line. +.PP +By default calls to methods and properties in the +System.Diagnostics.Debug class are not generated unless the DEBUG +symbol is defined (either through a "#define DEBUG") in your source +code, or by using the +.I "--define DEBUG" +in the command line. +.PP +Note that the effect of defining TRACE and DEBUG is a global setting, +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. .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. +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. .SH AUTHORS -The Mono C# Compiler was written by Miguel de Icaza and Ravi Pratap at -Ximian. +The Mono C# Compiler was written by Miguel de Icaza, Ravi Pratap and +Martin Baulig at Ximian. .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. .PP +.SH SEE ALSO +mono(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: