bluebonnet/README.md
2020-08-26 11:23:24 +03:00

63 lines
3.6 KiB
Markdown

# Bluebonnet
This is an initial release of a partial implementation of the .NET platform on top of the Java Virtual Machine, and compatible with Android runtime. The **Bluebonnet** bytecode compiler translates .NET [CIL](https://en.wikipedia.org/wiki/Common_Intermediate_Language) into [Java bytecode](https://en.wikipedia.org/wiki/Java_bytecode) in Java classes, and additional run-time support is provided by the **Baselib** library.
## Highlights
- 100% Java 8 bytecode with no native code.
- Compatible with all Android API levels through [desugaring](https://developer.android.com/studio/write/java8-support).
- Runtime library translated from the .NET Base Class Library.
- Simple interoperability with Java APIs.
- Tested with C# and F# programs.
## Requirements
- Java 8 is required during building, to import Java classes from the `rt.jar` file.
- Importing from Java 9 modules is not yet supported.
- The translated code can run on Java 8 or later version.
- Alternatively, `(ANDROID_HOME)/platforms/android-XX/android.jar` from Android SDK can be copied as `(JAVA_HOME)\jre\lib\rt.jar` file.
- Android build tools with support for `D8`/`R8` desugaring.
- Tested with build tools version 30.0.2 and platform API version 28.
- .NET Framework 4.7.2
- Tested only on Windows at this time. Not thoroughly tested with .NET Core.
## Building
- Set `JAVA_HOME` environment variable to the Java 8 home directory.
- Open `Bluebonnet.sln` in Visual Studio 2017 or later, and build in Release configuration.
- Building from the command line is also possible:
- Open a Visual Studio Developer command prompt.
- Change to the solution directory.
- Restore packages using [nuget](https://www.nuget.org/downloads): `nuget restore`
- Build the project: `msbuild -p:Configuration=Release`
- This should produce `Bluebonnet.exe` and `Baselib.jar` in the `.obj` sub-directory of the solution directory.
- `Bluebonnet.exe` translates compiled .NET assemblies into Java classes.
- `Baselib.jar` is required on the classpath when running the generated Java classes.
## Demo
Building a simple Hello World example. The sample `HelloWorld.cs` in the `Demos` sub-directory uses parallel LINQ, so it exercises generics, delegates, and threads, among many other .NET features.
- Open a Visual Studio Developer command prompt.
- Make sure the `JAVA_HOME` environment variable is set properly.
- Change to the solution directory.
- Compile the demo: `csc -out:.obj\HelloWorld.exe Demos\HelloWorld.cs`
- Test the demo: `.obj\HelloWorld.exe`
- It should print `Hello, World!`, one character at a time.
- Translate the demo: `.obj\Bluebonnet .obj\HelloWorld.exe .obj\HelloWorld.jar`
- Run the translation: `"%JAVA_HOME%\bin\java" -classpath ".obj\HelloWorld.jar;.obj\Baselib.jar" spaceflint.demos.HelloWorld`
Note that Java package names are lowercase, so .NET namespaces are translated to lowercase, e.g. `SpaceFlint.Demos -> spaceflint.demos`.
There are some additional demos:
- Change to the `Demos` directory inside the solution directory.
- Restore packages using [nuget](https://www.nuget.org/downloads): `nuget restore`
- Build and run each demo: `msbuild -p:Configuration=Release -t:RunDemo`
- Note that the Android demos require the `ANDROID_HOME` environment directory, and the project is hard-coded to use Android platform version 28, and build-tools 30.0.2
- Note also that the Android demos build an APK file, but do not install it.
## Usage
For more information about using Bluebonnet, please see the [USAGE.md](USAGE.md) file. That document also records any known differences and deficiencies, compared to a proper .NET implementation.