/clr (Common Language Runtime Compilation)

Article
04/28/2015

Enables applications and components to use features from the common language runtime (CLR).

/clr[:options]

Arguments

options
One or more of the following switches, comma-separated.
- /clr
  Creates metadata for the application. The metadata can be consumed by other CLR applications, and enables the application to consume types and data in the metadata of other CLR components.
  
  For more information, see
  
  Mixed (Native and Managed) Assemblies and
  
  How to: Migrate to /clr.
- /clr:pure
  Produces a Microsoft Intermediate Language (MSIL)-only output file that has no native executable code. However, it can contain native types compiled to MSIL.
  
  For more information, see Pure and Verifiable Code (C++/CLI).
- /clr:safe
  Produces an MSIL-only (no native executable code), verifiable output file. /clr:safe enables verification diagnostics (PEVerify Tool (Peverify.exe)).
  
  For more information, see Writing Verifiably Type-Safe Code.
- /clr:oldSyntax
  Enables Managed Extensions for C++ syntax, which is the original Visual C++ syntax for CLR programming.
  
  Managed Extensions for C++ syntax is deprecated. Use /clr:oldSyntax only if you are maintaining an application that uses Managed Extensions for C++. If you are developing a new application, use the updated syntax. For more information, see Component Extensions for Runtime Platforms.
  
  If you have a Managed Extensions for C++ application, you can upgrade the project to use the new syntax. For more information, see Porting and Upgrading Programs.
- /clr:noAssembly
  Specifies that an assembly manifest should not be inserted into the output file. By default, the noAssembly option is not in effect.
  
  The noAssembly option is deprecated. Use /LN (Create MSIL Module) instead. For more information, see Deprecated Compiler Options.
  
  A managed program that does not have assembly metadata in the manifest is known as a module. The noAssembly option can be used only to produce a module. If you compile by using /c and /clr:noAssembly, then specify the /NOASSEMBLY option in the linker phase to create a module.
  
  Before Visual C++ 2005, /clr:noAssembly implied /clr. However, /clr now also supports /clr:oldSyntax, so you must specify the /clr form when you specify /clr:noAssembly. For example, /clr:noAssembly /clr creates a module by using the new Visual C++ CLR syntax and /clr:noAssembly,oldSyntax creates a module by using Managed Extensions for C++.
  
  Before Visual C++ 2005, /clr:noAssembly required /LD. /LD is now implied when you specify /clr:noAssembly.
- /clr:initialAppDomain
  Enables a Visual C++ application to run on version 1 of the CLR. If you use initialAppDomain, then you may see some of the problems that are discussed in BUG: AppDomainUnloaded exception when you use managed extensions for Visual C++ components on the Microsoft Support Web site.
  
  An application that is compiled by using initialAppDomain should not be used by an application that uses ASP.NET because it is not supported in version 1 of the CLR.
- /clr:nostdlib
  Instructs the compiler to ignore the default \clr directory. The compiler produces errors if you are including multiple versions of a DLL such as System.dll. Using this option lets you specify the specific framework to use during compilation.

Remarks

Managed code is code that can be inspected and managed by the CLR. Managed code can access managed objects. For more information, see /clr Restrictions.

For information about how to develop applications that define and consume managed types, see Component Extensions for Runtime Platforms.

An application compiled by using /clr may or may not contain managed data.

To enable debugging on a managed application, see /ASSEMBLYDEBUG (Add DebuggableAttribute).

Only CLR types will be instantiated on the garbage-collected heap. For more information, see Classes and Structs (C++ Component Extensions). To compile a function to native code, use the unmanaged pragma. For more information, see managed, unmanaged.

By default, /clr is not in effect. When /clr is in effect, /MD is also in effect. For more information, see /MD, /MT, /LD (Use Run-Time Library). /MD ensures that the dynamically linked, multithreaded versions of the runtime routines are selected from the standard header (.h) files. Multithreading is required for managed programming because the CLR garbage collector runs finalizers in an auxiliary thread.

If you compile by using /c, you can specify the CLR type (IJW, safe, or pure) of the resulting output file with /CLRIMAGETYPE.

/clr implies /EHa, and no other /EH options are supported for /clr. For more information, see /EH (Exception Handling Model).

For information about how to determine the CLR image type of a file, see /CLRHEADER.

All modules passed to a given invocation of the linker must be compiled by using the same run-time library compiler option (/MD or /LD).

Use the /ASSEMBLYRESOURCE linker option to embed a resource in an assembly. /DELAYSIGN, /KEYCONTAINER, and /KEYFILE linker options also let you customize how an assembly is created.

When /clr is used, the _MANAGED symbol is defined to be 1. For more information, see Predefined Macros.

The global variables in a native object file are initialized first (during DllMain if the executable is a DLL), and then the global variables in the managed section are initialized (before any managed code is run). #pragmainit_seg only affects the order of initialization in the managed and unmanaged categories.

Compiling by using /clr:safe is analogous to compiling by using /platform:anycpu in languages such as C#.

Safe and Pure Images

A pure image uses a CLR version of the C run-time (CRT) library. However, the CRT is not verifiable, so you cannot use the CRT when you compile by using /clr:safe. For more information, see CRT Library Features.

Examples of native code that cannot appear in a pure image include inline assembly, setjmp, and longjmp.

Every entry point of a pure or safe image is managed. When you compile by using /clr, the entry point is native. For more information, see __clrcall.

When you compile by using /clr:safe, by default, variables are appdomain and cannot be per-process. For /clr:pure, although appdomain is the default, you can use process variables.

When running a 32-bit .exe file that was compiled by using /clr or /clr:pure on a 64-bit operating system, the application will be run under WOW64, which enables a 32-bit application to run on the 32-bit CLR on a 64-bit operating system. By default, an .exe file that is compiled by using /clr:safe will be run on the 64-bit CLR on a computer that is running a 64-bit operating system. (On a 32-bit operating system, the same .exe file would run on the 32-bit CLR.) However, a safe application could load a 32-bit component. In that case, a safe image running under operating system 64-bit support will fail when it loads the 32-bit application (BadFormatException). To ensure that a safe image continues to run when it loads a 32-bit image on a 64-bit operating system, you must use /CLRIMAGETYPE to change the metadata (.corflags), and mark it to be run under WOW64. The following command line is an example. (Substitute your own entry symbol.)

cl /clr:safe t.cpp /link /clrimagetype:pure /entry:?main@@$$HYMHXZ /subsystem:console

For information about how to get a decorated name, see Using a Listing to View Decorated Names. For more information about 64-bit programming, see Configuring Programs for 64-Bit (Visual C++).

For samples, walkthroughs, and more information, see:

Metadata and Unnamed Classes

Unnamed classes will appear in metadata named as follows: $UnnamedClass$crc-of-current-file-name$index$, where index is a sequential count of the unnamed classes in the compilation. For example, the following code sample generates an unnamed class in metadata.

// clr_unnamed_class.cpp
// compile by using: /clr /LD
class {} x;

Use ildasm.exe to view metadata.

To set this compiler option in Visual Studio

In Solution Explorer, right-click the project name, and then click Properties to open the project Property Pages dialog box.
Select the Configuration Properties folder.
On the General property page, modify the Common Language Runtime support property.

Note

When /clr is enabled in the Property Pages dialog box, compiler option properties that are not compatible with /clr are also adjusted, as required. For example, if /RTC is set and then /clr is enabled, /RTC will be turned off.

Also, when you debug a /clr application, set the Debugger Type property to Mixed or Managed only. For more information, see Project Settings for a C++ Debug Configuration.

For information about how the create a module, see /NOASSEMBLY (Create a MSIL Module).

To set this compiler option programmatically

See CompileAsManaged.

Share via