/clr (Common Language Runtime Compilation)

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

/clr[:options]

Arguments

• options
  One or more of the following, separated by a comma:

  • /clr
    Creates metadata for your application that can be consumed by other CLR applications, and allows your application to consume types and data in the metadata of other CLR components.

    For more information, see:

    • Mixed (Native and Managed) Assemblies

    • How To: Migrate to /clr

  • /clr:pure
    Produces an MSIL-only output file with no native executable code, although 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) and 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, the original Visual C++ syntax for CLR programming.

    Note   Managed Extensions for C++ syntax is deprecated in Microsoft Visual C++ 2005. You should use /clr:oldSyntax only if you are maintaining a Visual C++ application that uses Managed Extensions for C++. If you are developing a new application, use the updated syntax; see Language Features for Targeting the CLR for more information.

    If you have a Managed Extensions for C++ application, you can begin to port your project to use the new syntax; see Porting and Upgrading Programs for more information.

  • /clr:noAssembly
    The noAssembly option specifies that an assembly manifest should not be inserted into the output file. By default, the noAssembly option is not in effect.

    Note   The noAssembly option is deprecated in Visual C++ 2005. Use /LN (Create MSIL Module) instead. For more information, see Deprecated Compiler Options in Visual C++ 2005.

    A managed program that does not have assembly metadata in the manifest is called a module. The noAssembly option can be used only to produce a module. If you compile with /c (Compile Without Linking) and /clr:noAssembly, then specify the /NOASSEMBLY (Create a MSIL Module) 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 one /clr form when you specify /clr:noAssembly. For example, /clr:noAssembly /clr creates a module using the new Visual C++ CLR syntax and /clr:noAssembly,oldSyntax creates a module using Managed Extensions for C++.

    Before Visual C++ 2005, /clr:noAssembly required /LD. /LD is now implied with you specify /clr:noAssembly.

  • /clr:initialAppDomain
    Allows a Visual C++ application to run on version 1 of the common language runtime. If you use initialAppDomain, then you may see some of the problems discussed in Knowledge Base article Q309694. You can find Knowledge Base articles on the MSDN Library media or at https://support.microsoft.com/support/.

    An application compiled with initialAppDomain should never be used by an application using ASP.NET. Upgrade to a newer runtime to do ASP.NET work with C++.

Remarks

Managed code is code that can be inspected and managed by the common language runtime. Managed code can access managed objects.

Also see /clr Restrictions.

See Language Features for Targeting the CLR for information on how to develop applications that define and consume managed types.

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

To allow 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 (Managed). 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). /MD ensures that the dynamically linked, multithreaded versions of the runtime routines are selected from the standard header (.h) files. Multithreading is necessary for managed programming in part because the CLR garbage collector runs finalizers in an auxiliary thread.

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

/clr implies /EHa, and no other /EH options are allowed with /clr. See /EH (Exception Handling Model) for more information.

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

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

Use the /ASSEMBLYRESOURCE (Embed a Managed Resource) linker option to embed a resource in an assembly. /DELAYSIGN (Partially Sign an Assembly), /KEYCONTAINER (Specify a Key Container to Sign an Assembly), and /KEYFILE (Specify Key or Key Pair to Sign an Assembly) 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 files will be initialized first (during DllMain if the executable is a DLL), and then the global variables in the managed section will be initialized (before any managed code is run). #pragmainit_seg only affects the order of initialization within the managed and unmanaged categories.

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

Safe and Pure Images

A pure image will use a CLR version of the C run-time library. However, the CRT is not verifiable, so you cannot use the CRT when compiling with /clr:safe. For more information, see C Run-Time Libraries.

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

Each entry point of a pure or safe image is managed. When compiling with /clr, the entry point is native. For more information, see __clrcall.

When compiling with /clr:safe, variables are by default appdomain, and cannot be per process. With /clr:pure, appdomain is the default, but you can use process variables.

When running a 32-bit .exe that was compiled /clr or /clr:pure on a 64-bit operating system, the application will be run under WOW64, which allows a 32-bit application to run by the 32-bit CLR on a 64-bit operating system. By default, an .exe compiled with /clr:safe will be run in the 64-bit CLR on a computer running a 64-bit operating system (on a 32-bit operating system the same .exe would run in the 32-bit CLR). However, it is possible that your safe application loads a 32-bit component. In that case, a safe image running under the operating system's 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 (Specify Type of CLR Image) to change the metadata (.corflags), marking it to be run under WOW64. A sample command line follows (substitute your own entry symbol):

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

For information on getting a decorated name, see Using a Listing to View Decorated Names. For more information on 64-bit programming, see 64-bit Programming (How Do I in Visual C+).

For samples, walkthroughs and more information, see:

• Walkthrough: Using /clr:pure Features

• How to: Migrate to /clr:pure (C++/CLI)

• CppLangFeat Sample: Language Features Overview

• Pure and Verifiable Code (C++/CLI)

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 will generate an unnamed class in metadata:

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

Use ildasm.exe to view metadata.

To set this compiler option in the Visual Studio development environment

1. Open the project's Property Pages dialog box. For details, see How to: Open Project Property Pages.

2. Click the Configuration Properties folder.

3. Click the General property page.

4. Modify the Common Language Runtime support property.

   See /NOASSEMBLY (Create a MSIL Module) for information about how to create a module.

   Note

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

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

To set this compiler option programmatically

• See CompileAsManaged.

See Also

Reference

Compiler Options

Setting Compiler Options