diff --git a/docs/tools/ikvmc.md b/docs/tools/ikvmc.md index 4107d2a563..c27db5711d 100644 --- a/docs/tools/ikvmc.md +++ b/docs/tools/ikvmc.md @@ -1,6 +1,8 @@ # ikvmc Tool -The `ikvmc` tool converts Java bytecode to .NET dll's and exe's. +> The `ikvmc` tool is considered an advanced option and it is recommended that new projects use the `IkvmReference` for the .NET SDK for most use cases. + +The `ikvmc` tool converts Java bytecode to .NET DLL and EXE files. - [Usage](#usage) - [Options](#options) @@ -27,50 +29,87 @@ Name of a Java `.class` or `.jar file`. May contain wildcards (`*.class`). ## Options -| Source | Description | +### Command Help + +|                           Source                           |                                                              Description                                                               | |---|---| | `-?\|-help` | Displays command syntax and options for the tool. | -| `@` | Read more options from the provided file. | + +### Output Files + +|                           Source                           |                                                              Description                                                               | +|---|---| | `-out:` | Specifies the name of the `outputfile`. Should have a .dll extension (if -target is library) or an .exe extension (if -target is exe or winexe). In most cases, if you omit this option, `ikvmc` will choose an output name based on the -target and the name of the input files. However, if you specify input files using wildcards, you must use this option to specify the output file. | | `-assembly:` | Specifies the name of the generated assembly. If omitted, the assembly name is (usually) the output filename. | +| `-version:` | Specifies the output assembly version. | +| `-fileversion:` | Specifies the output assembly file version. | | `-target:` | Specifies whether to generate an .exe or .dll. `target-type` is one of
  • `exe` - generates an executable that runs in a Windows command window
  • `winexe` - generates an .exe for GUI applications
  • `library` - generates a .dll
  • `module` - generates a .netmodule
On Linux, there is no difference between exe and winexe. | | `-platform:` | Limit which platforms this code can run on:
  • `x86` - 32 bit
  • `Itanium`
  • `x64`
  • `anycpu`
The default is `anycpu`. This can be helpful if your Java code use a dll via JNI. For example a 32 bit dll should also run on a 64 bit system as 32 bit application. | | `-keyfile:` | Uses `keyfilename` to sign the resulting assembly. | | `-key` | Use `keycontainer` to sign the assembly. | | `-delaysign` | Delay-sign the assembly. | -| `-version:` | Specifies the output assembly version. | -| `-fileversion:` | Specifies the output assembly file version. | -| `-main:` | Specifies the name of the class containing the main method. If omitted and the -target is exe or winexe, ikvmc searches for a qualifying main method and reports if it finds one. | -| `-r:\|-reference:` | If your Java code uses .NET API's, specify the dll's using this option. This option can appear more than once if more than one library is referenced. Wildcards are permitted (e.g. `C:\libs\*.dll`). | -| `-recurse:` | Processes all files matching `filespec` in and under the directory specified by filespec. Example: `-recurse:*.class` | -| `-nojni` | Do not generate JNI stub for native methods. | -| `-resource:=` | Includes path as a Java resource named `name`. | -| `-externalresource:=` | Reference file as Java resource. | + +### Input Files + + +|                           Source                           |                                                              Description                                                               | +|---|---| +| `-r:\|-reference:` | Add a reference to a class library DLL (.NET assembly). When building Java projects (`.jar` or `.class` files), this can be used to add dependent projects that had previously been compiled. The dependency must be compiled first. This option can appear more than once to reference multiple libraries. | +| `-recurse:` | Processes all files matching `filespec` in and under the directory specified by `filespec`. Example: `-recurse:*.class` | +| `-exclude:` | `filename` is a file containing a list of classes to exclude. | + +### Resources + +|                           Source                           |                                                              Description                                                               | +|---|---| | `-win32icon:` | Embed specified icon in output. | | `-win32manifest:` | Specify a Win32 manifest file (.xml). | +| `-resource:=` | Includes path as a Java resource named `name`. | +| `-externalresource:=` | Reference file as Java resource. | | `-compressresources` | Compress resources. | -| `-exclude:` | `filename` is a file containing a list of classes to exclude. | -| `-debug` | Generates debugging information in the output. Note that this is only helpful if the `.class` files contain debug information (compiled with the `javac -g` option). | -| `-srcpath:` | Specifies the location of source code. Use with `-debug`. The package of the class is appended to the specified `path` to locate the source code for the class. | -| `-Xtrace:` | Displays all trace points with `name`. | -| `-Xmethodtrace:` | Builds method trace into the specified output method. | + +### Code Generation + +|                           Source                           |                                                              Description                                                               | +|---|---| +| `-debug` | Generates debugging information in the output. Note that this is only helpful if the `.class` files contain debug information (compiled with the `javac -g` option). This option also produces somewhat less efficient CIL code. | | `-noautoserialization` | Disable automatic .NET serialization support. | | `-noglobbing` | Don't glob the arguments passed to `-main`. | | `-nojni` | Do not generate JNI stub for native methods. | | `-opt:fields` | Remove unused private fields. | | `-removeassertions` | Remove all assert statements. | | `-strictfinalfieldsemantics` | Don't allow final fields to be modified outside of initializer methods. | + +### Errors and Warnings + +|                           Source                           |                                                              Description                                                               | +|---|---| | `-nowarn:` | Suppress specified warnings. | | `-warnaserror` | Treat all warnings as errors. | | `-warnaserror:` | Treat specified warnings as errors. | | `-writeSuppressWarningsFile:` | Write response file with `-nowarn:` options to suppress all encountered warnings. | + + +### Miscellaneous + +|                           Source                           |                                                              Description                                                               | +|---|---| +| `@` | Read more options from the provided file. | | `-nologo` | Suppress compiler copyright message. | -| `-srcpath:` | Prepend path and package name to source file. | + +### Advanced + +|                           Source                           |                                                              Description                                                               | +|---|---| +| `-main:` | Specifies the name of the class containing the main method. If omitted and the -target is exe or winexe, ikvmc searches for a qualifying main method and reports if it finds one. | +| `-srcpath:` | Specifies the location of source code. Use with `-debug`. The package of the class is appended to the specified `path` to locate the source code for the class. | | `-apartment:` | Apply a thread apartment state attribute to `-main` based on the selected option:
  • `sta` - Apply `STAThreadAttribute`
  • `mta` - Apply `MTAThreadAttribute`
  • `none` - Apply no attribute
The default option is `sta`. | | `-D=` | Set a Java system property (at runtime). | -| `-ea\|-enableassertions[: [...] \|:]` | Set Java system property to enable assertions. | -| `-da\|-disableassertions[: [...] \|:]` | Set Java system property to disable assertions. | +| `-ea\|-enableassertions[:[\|]]` | Set Java system property to enable assertions. A class name or package name can be specified to enable assertions for a specific class or package. | +| `-da\|-disableassertions[:[\|]]` | Set Java system property to disable assertions. A class name or package name can be specified to disable assertions for a specific class or package. | | `-nostacktraceinfo` | Don't create metadata to emit rich stack traces. | +| `-Xtrace:` | Displays all trace points with `name`. | +| `-Xmethodtrace:` | Builds method trace into the specified output method. | | `-privatepackage:` | Mark all classes with a package name starting with `prefix` as internal to the assembly. | | `-publicpackage:` | Mark all classes with a package name starting with `prefix` as public to the assembly. | | `-time` | Display timing statistics. | @@ -87,12 +126,13 @@ Name of a Java `.class` or `.jar file`. May contain wildcards (`*.class`). | `-proxy:` | Undocumented. | | `-nojarstubs` | Undocumented temporary option to mitigate risk. | | `-w4` | Undocumented option to compile core class libraries with, to disable MethodParameter attribute. | -| `-strictfinalfieldsemantics` | Undocumented. | -| `-remap` | Undocumented. | +| `-strictfinalfieldsemantics` | Undocumented. For internal use. | +| `-remap` | Undocumented. For internal use. | +| `-runtime` | Specifies the `IKVM.Runtime.dll` library to use. Not fully functional. | ## Notes -The ikvmc tool generates .NET assemblies from Java class files and jar files. It converts the Java bytecode in the input files to .NET CIL. Use it to produce +The `ikvmc` tool generates .NET assemblies from Java class files and jar files. It converts the Java bytecode in the input files to .NET CIL. Use it to produce - .NET executables (`-target:exe` or `-target:winexe`) - .NET libraries (`-target:library`)