IKVM.MSBuild 8.3.0-prerelease0394

IKVM - Java Virtual Machine for .NET

What is IKVM?

IKVM is an implementation of Java for the Microsoft .NET platform. It can be used to quickly and easily:

• Execute compiled Java code (bytecode) on .NET Framework or .NET Core
• Convert bytecode to a .NET assembly to directly access its API in a .NET project

These tasks can be done without porting source code to .NET.

IKVM Components

• A Java virtual machine (JVM) implemented in .NET
• A .NET implementation of the Java class libraries
• A tool that translates Java bytecode (JAR files) to .NET IL (DLL or EXE files).
• Tools that enable Java and .NET interoperability
• A full JRE/JDK 8 runtime image.

Run Java Applications with .NET

1. Statically: By compiling a Java application into a .NET assembly using <MavenReference>, <IkvmReference> or ikvmc.
   • Libary assemblies can be referenced by any .NET application with a compatible target framework and platform. Types can be referenced by using the Java package name like a .NET namespace.
   • Executable assemblies can be launched by specifying the class containing the main() method to execute at runtime when building using ikvmc.
2. Dynamically: By running a Java application using the java executable inside of the JDK Runtime Image. The Java bytecode is converted on-the-fly to CIL and executed. The experience should be identical to a normal JDK.

What IKVM is Not

• A converter utility to transform Java source code to C# source code
• A decompiler utitity to transform compiled Java bytecode to C# source code
• A tool that runs .NET code in Java - all IKVM conversions are Java > .NET

Support

• .NET Framework 4.6.1 and higher
• .NET Core 3.1 and higher
• .NET 5 and higher
• Java SE 8

Documentation

See the tutorial to get started or IKVM.NET In Details for a more in-depth look.

Installation

NuGet

PM> Install-Package IKVM

Or, to use MavenReference:

PM> Install-Package IKVM.Maven.Sdk

Tools

The tools are available for download on the Releases page.

Runtime Images

Both a JRE and JDK runtime image are available. These images are standard JRE or JDK directory structures containing all of the standard tools: javac, jdeps, policytool, keytool, etc. Some Java libraries may require either a JRE or JDK, and if so, the IKVM.Image.JRE or IKVM.Image.JDK package should be added to your project respectively.

Also, a standalone JDK distributable is available for download on the Releases page. This directory structure should suffice as a JAVA_HOME path for standard Java applications.

Usage

IKVM supports integration with .NET SDK projects as well as low level tools for running compiled Java code directly or for advanced build scenarios. The 2 main entry points for integration with the .NET SDK are IkvmReference and MavenReference. .NET SDK projects can be built on the command line directly or using an IDE that supports them, such as recent versions Visual Studio or JetBrains Rider.

IkvmReference

IKVM includes build-time support for translating Java libraries to .NET assemblies. Install the IKVM package in a project that requires references to Java libraries. Use IkvmReference within an ItemGroup to indicate which Java libraries your project requires.

Example

<ItemGroup>
  <PackageReference Include="IKVM" Version="8.2.0" />
</ItemGroup>

<ItemGroup>
  <IkvmReference Include="..\..\ext\helloworld-2.0.jar" />
</ItemGroup>

The output assembly will be generated as part of your project's build process and a reference will automatically be added to your project so you can call APIs of the compiled .jar assembly. Additional metadata can be added to IkvmReference to customize the assembly that is generated.

Syntax

<ItemGroup>
   <IkvmReference Include="..\..\ext\helloworld-2.0.jar">
      <AssemblyName>MyAssembly</AssemblyName>
      <AssemblyVersion>3.2.1.0</AssemblyVersion>
      <AssemblyFileVersion>3.0.0.0</AssemblyFileVersion>
      <DisableAutoAssemblyName>true</DisableAutoAssemblyName>
      <DisableAutoAssemblyVersion>true</DisableAutoAssemblyVersion>
      <FallbackAssemblyName>MyAssemblyFallback</FallbackAssemblyName>
      <FallbackAssemblyVersion>3.1.0.0</FallbackAssemblyVersion>
      <KeyFile>MyKey.snk</KeyFile>
      <DelaySign>true</DelaySign>
      <Compile>SomeInternalDependency.jar;SomeOtherInternalDependency.jar</Compile>
      <Sources>MyClass.java;YourClass.java</Sources>
      <References>SomeExternalDependency.jar;SomeOtherExternalDependency.jar</References>
      <Aliases>MyAssemblyAlias;helloworld2_0</Aliases>
      <Debug>true</Debug>
   </IkvmReference>
</ItemGroup>

Attributes and Elements

The following values can be used as either an attribute or a nested element of <IkvmReference>.

IkvmReference is not transitive. Including it in one project and adding a dependency to that project from a second project will not result in the same reference being available on the second project. Instead, add the reference to each project.

For each project to resolve to the same resulting assembly ensure their settings are identical.

Multiple IkvmReference entries can be configured to include each other as references.

<ItemGroup>
   <IkvmReference Include="helloworld.jar">
      <AssemblyVersion>1.0.0.0</AssemblyVersion>
   </IkvmReference>
   <IkvmReference Include="helloworld-2.jar">
      <AssemblyName>helloworld-2</AssemblyName>
      <AssemblyVersion>2.0.0.0</AssemblyVersion>
      <References>helloworld.jar</References>
      <Aliases>helloworld2</Aliases>
   </IkvmReference>
</ItemGroup>

Automatic-Module-Name Specification

The Automatic-Module-Name is either a specified attribute of the JAR manifest, which can be found in the META-INF/MANIFEST.MF file inside the JAR, or a generated value based on the name of the JAR file. See the documentation for more information.

MavenReference

See the ikvm-maven Readme for usage instructions.