Skip to content

Latest commit

 

History

History
82 lines (71 loc) · 7.83 KB

CONTRIBUTING.md

File metadata and controls

82 lines (71 loc) · 7.83 KB
Raw

IKVM - Java Virtual Machine for .NET

Build

The project can be opened in Visual Studio, or it can be be built with MSBuild on a Windows host. The project cannot currently be built on a Linux host, nor with an exclusively .NET Core version of MSBuild.

Prerequisites for building the project:

  • A clone of the IKVM repository which includes submodules (e.g. git clone --recurse-submodules https://github.com/ikvmnet/ikvm.git)
  • Visual Studio configured for: .NET desktop development, Desktop development with C++ (including C++ Clang tools for Windows), Linux and Embedded Development with C++, and Windows SDK with the appropriate libraries for x86, AMD64 and ARM64 development.
  • A JDK 8 installation. The JAVA_HOME environment variable needs to be point to the JDK 8 directory, or the version of javac available on the path needs to be from JDK 8 (You can download a suitable JDK from Adoptium)
  • The OpenJDK JDK8u build result for Linux/x64. This build artifact cannot be built on Windows, or modern Linux hosts. Instead, it must be built on a host with GCC 4.3 available. (Debian Lenny is known to work acceptably, the CI/CD GitHub action can serve as a demonstration of this). The easiest way to acquire this artifact without building it yourself is to use one generated by the IKVM respository's GitHub Actions. Click on a build result for a relevant branch (typically you'll want to use develop) and scroll down to the bottom of the list to locate openjdk-build-linux-x86_64-normal-server-release. Download this zip file from this link and unzip into openjdk/build.
  • SDK Toolkits: These are located in the ext/ikvm-native-sdk/ directory, and consist of a Windows SDK (windows), Linux SDK (linux) and Mac OS X SDK (macosx). The SDKs can be retrieved from the releases of the ikvm-native-sdk project.
    • We use IKVM.Clang projects to build the native libraries. This project type supports inner builds for TargetMachine, much as .NET supports inner builds for TFMs.
    • There is an IKVM.Clang Visual Studio extension for these projects to load properly in Visual Studio: https://marketplace.visualstudio.com/items?itemName=ikvm.clang
    • When on Windows, the Windows SDK distributed through this project is not required. But it is required that you have a Windows SDK installed. Building on other operating systems requires all of the SDKs.
      • A few of the SDKs contain symlinks for which there is no way to extract them properly (osx) on Windows. We find 7zip has the best capability to produce SYMLINK files, though it incorrectly interpretes symlinks to directories as symlinks to files. The Fix-SymbolicLinks.ps1 script is provided to patch these up post extraction.
    • The Linux SDK contains a version for all of the required platforms. These are required to cross compile to each supported platform. They must all be present.
  • LLVM installed with clang available on the path. LLVM is shipped with Visual Studio, but you will need to update your PATH to include the relevant bin directory (typically: C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\Llvm\bin) or you can install a standalone distribution of LLVM. If building on Windows, ensure you do not build within the Visual Studio Developer Command Prompt as clang is unable to properly discover the Windows SDK when this is applied.
  • 200GB of free disk space

Once the prerequisites are in place, to build IKVM from the command line you will use the following commands:

dotnet restore IKVM.sln
msbuild IKVM.dist.msbuildproj

Project

  • IKVM.sln Main solution file for the project.
  • IKVM.dist.msbuildproj MSBuild project file that builds the output artifacts, including the NuGet packages.
  • IKVM.Runtime The main executable core of IKVM. Provides services used by IKVM.Java.
  • IKVM.Java The OpenJDK distribution included with IKVM. This project is heavily customized to compile the OpenJDK Java source files and produce a .NET assembly from them.
  • IKVM.Image Outputs the files that make up the Java Runtime Image base. That is, the lib/ directory.
  • IKVM.Image.JRE Outputs the files that make up the Java Runtime Image JRE. That is, the contents of the bin/ directory typically associated with a JRE (java.exe, policytool.exe, etc).
  • IKVM.Image.JRE.runtime.* Outputs the runtime-specific files that make up the Java Runtime Image JRE.
  • IKVM.Image.JDK Outputs the files that make up the Java Runtime Image JDK. That is, the contents of the bin/ directory typically associated with a JDK (javac.exe, etc).
  • IKVM.Image.JDK.runtime.* Outputs the runtime-specific files that make up the Java Runtime Image JDK.
  • ikvmc ikvmc executable. Transforms Java class files or JAR files into .NET libraries or executables.
  • ikvmstub ikvmstub executable. Generates Java JAR files for .NET assemblies. When building Java code that depends on .NET code, these stubs can be used as references.
  • IKVM.Tests Various unit tests against IKVM functionality.
  • IKVM.Runtime-ref "Reference" version of the IKVM.Runtime project. Due to a circular dependency between IKVM.Java and IKVM.Runtime, IKVM.Java must build against a partial copy of IKVM.Runtime.
  • IKVM.Java-ref "Reference" version of the IKVM.Java project. Due to the circular dependency between IKVM.Java and IKVM.Runtime, IKVM.Runtime must build against a partial copy of IKVM.Java.
  • IKVM To untangle the ProjectReferences between the circular dependencies, this project generates the NuGet package output, including all of it's required dependencies, and the full version of the underlying IKVM assemblies.
  • ikvm-native-* Native vcxproj files for building 'ikvm-native'. This code facilitates the functionality of IKVM.Runtime.JNI.
  • IKVM.MSBuild Contains tasks and targets used by both the IKVM package and the IKVM.NET.Sdk package. Two divergent paths exist: Tasks and NoTasks. When doing in-tree builds, NoTasks is used.
  • IKVM.MSBuild.Tasks Source code for the task contained within IKVM.MSBuild.
  • IKVM.NET.Sdk MSBuild SDK package which provides support for building managed code form Java sources. To divergent paths exist: Tasks and NoTasks. When doing in-tree builds, NoTasks is used.
  • dist-* Outputs content files that describe the summation of various directories to be produced when doing a distribution build.
  • IKVM.Tools.Runner Various .NET libraries for executing the IKVM tools programatically. These are used by the MSBuild Tasks to launch ikvmc.exe and ikvmstub.exe.
  • IKVM.Java.Extensions Various extension methods and such for bridiging IKVM.Java with .NET patterns and practices.

Versioning

IKVM uses the Semantic Versioning specification, with a unique twist. Since the project tracks compatibility with the Java SE specification, the major version is always the version of the JDK we claim to support. Otherwise major/breaking IKVM releases are denoted by an increment of the minor version. Other releases are denoted by an increment of the patch version.

Semantic Versioning is accomplished automatically by GitVersion in Mainline mode. The main branch functions as the release branch. Every commit to main results in an increment of the patch version and a release. The develop branch represents a prerelease staging area. Builds within the develop branch inherit the NEXT version number of the main branch, with a prerelease tag followed by the number of commit separating develop from the last release.

Increases in the major and minor version are accomplished manually by introducing a commit with a message containing a line such as +semver: major or +semver: minor. The process of creating a new major or minor release is simply to bump the version with the introduction of a commit message. The GitHub Actions should automatically generate the git tag and GitHub release, and publish the proper NuGet packages to the proper places.