This article has been excerpted from book "Visual C# Programmer's Guide"
When you have to compile complex applications, you need to pass several other parameters to the compiler. Let's address each of the C# compiler options.
The @ Option
As shown in Listing 1, the @ option is used to specify a response file (denoted with the extension .rsp) that contains the compiler options to be used while compiling.
The response file is a normal text file that can contain compiler switches and/or file names to be compiled. The pound symbol (#) is used to write comments. Writing options in a response file is similar to typing them at the command prompt. Specifying these options in a response file comes in handy when you want to perform complex compilations during application design. For example, if you have to specify many assemblies to be referenced in your application, a normal compile statement would span many lines! You can write a response file containing the reference to all the assemblies and reuse this file every time you compile the code.
You can specify additional options along with the response file. The compiler processes these options sequentially as they are encountered. Therefore, command-line arguments can override previously listed options in response files. Conversely, options in a response file will override options listed previously on the command line or in other response files.
Listing 1:Sample Response File (winform.rsp)
#Sample file containing general compiler options for Windows forms #Usage: csc @winform.rsp yourCode.cs
#Usage 2: csc @winform.rsp /out:MyApplication.exe yourCode.cs
/target:winexe /r:System.dll;System.Windows.Forms.dll;System.Data.dll;System.Drawing.dll
The /? or /help Option
The /? or /help option displays on the console a list of all the compiler options and their usage.
The /addmodule Option
The /addmodule option prompts the compiler to import metadata from the specified modules into the assembly you are compiling. You can specify two or more modules in a single statement by separating them with a comma or a semicolon, as shown.
csc /addmodule:module1.netmodule;module2.netmodule myAssembly.cs
The /baseaddress Option
The /baseaddress option lets you specify in hexadecimal, decimal, or octal form the preferred memory base address at which the .NET runtime should load your dynamic-link library (DLL).
csc /t:library /baseaddress:0x1111000 urClass.cs
Generally, the base address is determined by the .NET runtime. This option is ignored if your output file is not a DLL.
The /bugreport Option
As its name suggests, the /bugreport option is used to report source code bugs. It creates a text file containing the source code; versions of the operating system, compiler, and .NET runtime; and the programmer's description of the problem and the expected result. The following example shows how to use the /bugreport option.
csc /bugreport:report.txt myCode.cs
The /checked Option
Sometimes the results of an integral value fall outside the permissible range of the data type and cause a runtime exception. The /checked option eliminates the potentially drastic effects that can occur when a value falls outside the range allowed. For example, the range of the type Int16 extends to 32767. Generally, during runtime, if a variable of type Int16 is assigned a value greater than 32767 and if that value is not within the scope of the checked statement, the variable's value is automatically set to zero and the program executes normally. If it's important for you to that you always have the right value assigned to your variables, then compile with the option /checked+. This results in a runtime exception every time the variable exceeds its maximum value.
The /codepage Option
The /codepage option is useful when you have written source code in code pages in a format other than Unicode or UTF-8. Code pages are character sets, and they vary for different languages. For example, the Hindi language has multibyte characters. The /codepage option takes the ID of the code page to be used to compile the source code.
The /debug Option
You can use the /debug option to produce additional debugging information for your application. This option accepts either + or - to indicate creation or omission of debugging information. To expand the functionality, you can specify /debug:full to create debugging information along with capabilities of attaching it to a debugger. As an alternative, /debug:pdbonly does not allow you to debug the source code if you attach the debugger to a running program. The pdbonly option will only display assembly code from the running program
The /define Option
When you use preprocessor directives in your code, you can define multiple symbols for your program via the /define option. Preprocessor directives are used to perform conditional compilation-that is, they mark sections of the code to be compiled as per the options defined during compilation time. For example, suppose you mark the debugging counters and trace statements with the DEBUG preprocessor directive. Only if you define the DEBUG directive during compile-time (as shown) will these statements get compiled. 32 C# Corner csc /define:DEBUG;Test myCode.cs
The /doc Option
The /doc option allows you to produce an Extensible Markup Language (XML) file containing the documentation you have defined within your source code using the special documentation comments. This option does not work when you are using the /increment+ option. An example of the syntax follows.
csc /doc:MyCode.xml myCode.cs
The /filealign Option
The /filealign option lets you specify the size of different sections within the compiled file. The sizes you can specify in byte form are 512, 1024, 2048, 4096, 8192, and 16384. If a section cannot fit within the given size, then two or more sections will be created in multiples of the size specified. This option is useful, for example, if your code is to be used on small mobile devices.
The /fullpaths Option
Enabled by default, the /fullpaths option is used to show the full path to the source code file that is causing errors or warnings during compilation.
The /incremental Option
The /incremental option incrementally builds your applications and can be used along with the /debug+ option. The first time you use this option along with the compiled assembly, an .incr file is created to contain all the information about the current build. The next time you compile your code, only those portions of the code that have changed are recompiled and the .incr file will be updated. This option has significant impact only when you compile many small files.
The /lib Option
You use the /lib option to specify additional directories where the compiler can find the libraries to be referenced during compilation. If you store your DLL assemblies in various directories, use this option to supply the C# compiler with the path to those directories, as in the following example:
csc /lib:c:\csharp\libraries /r:myLibrary.dll myCode.cs
The /linkresource Option
The /linkresource option provides a link to the resource file in the assembly you are compiling. It does not store the resource file within the assembly; it only provides a reference to the resource file. Therefore, you must distribute the resource file along with your application files. The following example shows how you might use this option:
csc /linkresource:myrs.resource myCode.cs
The /main Option
The /main option is useful only when you compile an executable (.exe) application and your source code has multiple classes that define the Main method. Because an application can have only one entry point, you use this option (as shown in the example) to specify to the compiler which class's Main method should be treated as the entry point into an application.
csc /main:myCode myCode.cs yourCode.cs
The /nologo Option
You use /nologo to suppress the Microsoft banner that usually appears every time you use the compiler.
The /nostdlib Option
If you have created your own System namespace implementation, you may use the /nostdlib option to prevent the compiler from loading the mscorlib.dll that holds the System namespace.
The /noconfig Option
The /noconfig option prevents the compiler from using the global and local response files defined within the csc.rsp file. If you do not need the default compiler options that are defined in csc.rsp, you can use the /noconfig compiler option.
The /nowarn Option
The /nowarn option forces the C# compiler to suppress the specific warnings you've specified. The C# reference documentation lists all the numbers associated with C# warnings. With /nowarn, you can specify the number of any warning you don't want to display during compilation. The following example shows how to compress the warning CS0029 - Cannot implicitly convert type 'type' to 'type':
csc /nowarn:29 myCode.cs
The /optimize Option
The /optimize option allows the compiler to optimize compiled code to make it execute faster and more efficiently. Use this option when compiling the release versions of your assemblies.
The /out Option
You use the /out option to specify the output file name of the file compiled by the C# compiler. As shown in the following example, you can also specify the path name along with the file name after the out directive to specify where the compiled file will be stored:
csc /out:.\bin\website.dll /t:library myCode.cs
The /recurse Option
The /recurse option is used to compile all files bearing the specified file name within the specified directory and its child directories. You can also use wild cards to specify the names of files to be compiled, as shown in this example:
csc /recurse:*.cs /out:myCode.dll /t:library
The /reference Option
The /reference option is used to reference the external assemblies you have used in your code. The compiler reads the public type information from the external assemblies and provides the necessary metadata within the assembly you are currently compiling. The following example shows the syntax used with /reference:
csc /reference:urCode.dll myCode.cs
The /resource Option
You can use the /resource option as shown to embed the resource file within the assembly you are compiling.
csc /resource:fileres.resource myCode.cs
Unlike the /linkresource option that merely links the resource file, /resource actually embeds the resource into the assembly.
The /target Option
You use the /target option to tell the compiler which of four kinds of output files you want to produce:
exe-a console application (.exe).
winexe-a Windows application (.exe).
library-a library DLL (.dll).
module-a .NET module (.netmodule).
The example specifies creation of a Windows application:
csc /target:winexe /out:Application.exe myFile.cs
The /unsafe Option
When you have included unsafe code (e.g., pointers) within your C# source code, the source code will not compile unless you use the /unsafe option.
The /utf8output Option
The /utf8output option is used for situations in which the output generated by the compiler does not render properly on certain international language packs. You may use this option to redirect the output to a separate file in UTF-8 format.
The /warn Option
With the /warn option, you can set the warning level displayed by the C# compiler. Values range from 0, which turns off the warnings, to 4, which reports all warnings and includes additional information.
The /warnaserror Option
The /warnaserror option reports all warnings as errors at compile-time. When you use this option, any warning issued by the compiler causes the code not to compile.
The /win32icon Option
You use the /win32icon option as shown to specify inclusion of an icon file when you compile a Windows executable file.
csc /win32icon:myApp.ico /target:winexe /out:Application.exe myCode.cs
This option gives the Windows application the desired look in Windows Explorer.
The /win32res Option
You use the /win32res option to include a Win32 resource file in your compiled code. The Win32 resource file can contain icons, cursors and bitmaps. An example of the syntax for this option follows:
csc /win32res:oldres.res /target:winexe myCode.cs
To include .NET resource files rather than Win32 resource files, use the /addresource option.
Conclusion
Hope this article would have helped you in understanding C# Command-Line Compiler Options in .NET. See my other articles on the website on .NET and C#.