.if t .sp .5v
.if n .sp
..
-.TH mkbundle "mkbundle 1.0"
+.TH Mono "mkbundle"
.SH NAME
mkbundle, mkbundle2 \- Creates a bundled executable.
.SH SYNOPSIS
included in the bundle. To automatically include all of the
dependencies referenced, use the "--deps" command line option.
.PP
-Use \fImkbundle\FP when you want the startup runtime to load the 1.0
-profile, and use \fImkbundle2\fP when you want the startup runtime to load
-the 2.0 profile.
+There are two modes of operation, one uses an existing Mono binary or
+a server-hosted list of binaries and is enabled when you use either
+the
+.B --cross,
+.B --sdk
+or the
+.B --runtime
+command line options.
+.PP
+An older mechanism creates a small C stub that links against the
+libmono library to produce a self-contained executable and requires a
+C compiler. It is described in the "OLD EMBEDDING" section below.
+.PP
+For example, to create a bundle for hello world, use the following
+command:
+.nf
+
+ $ mkbundle -o hello --simple hello.exe
+
+.fi
+.PP
+You can configure options to be passed to the Mono runtime directly
+into your executable, for this, use the
+.I --options
+flag. For example, the following disables inlining, by passing the
+"-O=-inline" command line option to the embedded executable:
+.nf
+
+ $ mkbundle -o hello --options -O=-inline --simple hello.exe
+
+.PP
+The simple version allows for cross-compiling, this requires a Mono
+runtime to be installed in the ~/.mono/targets/TARGET/mono to be
+available. You can use the "--local-targets" to list all available
+targets, and the "--cross" argument to specify the target, like this:
+.nf
+
+ $ mkbundle --local-targets
+ Available targets:
+ default - Current System Mono
+ 4.4.0-macosx-x86
+ 4.4.0-debian-8-arm64
+ $ mkbundle --cross 4.4.0-debian-8-powerpc hello.exe -o hello-debian
+
+.fi
+.PP
+The above will bundle your native library into hello-debian for
+a Debian 8 system running on a PowerPC machine.
+.PP
+We provide pre-packages binaries for Mono for various architectures,
+which allow you to cross compile, use the
+.B --list-targets
+to get a list of all targets supported, and use the
+.B --fetch-target
+flag to retrieve a target that you do not have installed, like this:
+.nf
+
+ $ mkbundle --list-targets
+ Cross-compilation targets available:
+ 4.4.0-linux-libc2.13-amd64
+ 4.4.0-linux-libc2.13-armel
+ 4.4.0-linux-libc2.13-armhf
+ 4.4.0-linux-libc2.13-i386
+ 4.4.0-macos-10.7-amd64
+ 4.4.0-macos-10.7-i386
+ 4.4.2-linux-libc2.13-amd64
+ 4.4.2-linux-libc2.13-armel
+ 4.4.2-linux-libc2.13-armhf
+ 4.4.2-linux-libc2.13-i386
+ 4.4.2-macos-10.7-amd64
+ 4.4.2-macos-10.7-i386
+
+ $ mkbundle --fetch-target 4.4.2-macos-10.7-i386
+
+.fi
+.PP
+And then you can produce a binary that will run on 32-bit Mono on
+MacOS:
+.nf
+
+ $ mkbundle --cross 4.4.2-macos-10.7-i386 hello.exe -o hello-macos
+
+.fi
+.PP
+Downloaded targets are stored
+.B ~/.mono/targets
+directory.
+.SH OPTIONS
+.TP
+.I "--config FILE"
+Specifies that a machine.config file must be bundled as well.
+Typically this is $prefix/etc/mono/1.0/machine.config or
+$prefix/etc/mono/2.0/machine.config depending on the profile that you
+are using (1.0 or 2.0)
+.TP
+.I "--config-dir DIR"
+When passed, DIR will be set for the MONO_CFG_DIR environment variable
+.TP
+.I "--cross target"
+Use this to request mkbundle generate a cross-compiled binary. It
+Creates a bundle for the specified target platform. The target must
+be a directory in ~/.mono/targets/ that contains an SDK installation
+as produced by the mono-package-runtime tool. You can get a list of
+the precompiled versions of the runtime using --list-targets and you
+can fetch a specific target using the --fetch-target command line
+option.
+.Sp
+This flag is mutually exclusive with
+.I --sdk
+which is used to specify an absolute path to resolve the Mono runtime
+from and the --runtime option which is used to manually construct the
+cross-platform package.
+.TP
+.I "--deps"
+This option will bundle all of the referenced assemblies for the
+assemblies listed on the command line option. This is useful to
+distribute a self-contained image.
+.TP
+.I "--env KEY=VALUE"
+Use this to hardcode an environment variable at runtime for KEY to be
+mapped to VALUE. This is useful in scenarios where you want to
+enable certain Mono runtime configuration options that are controlled
+by environment variables.
+.TP
+.I "--fetch-target target"
+Downloads a precompiled runtime for the specified target from the Mono
+distribution site.
+.TP
+.I "--i18n encoding"
+Specified which encoding tables to ship with the executable. By
+default, Mono ships the supporting I18N.dll assembly and the
+I18N.West.dll assembly. If your application will use the
+System.Text.Encoding.GetEncoding with encodings other than the West
+encodings, you should specify them here.
+.Sp
+You can use the
+.B none
+parameter to request that no implicit encodings should be bundled,
+including the supporting I18N.dll, use this option if you have ran a
+linker on your own.
+.Sp
+You can use the
+.B all
+flag to bundle all available encodings.
+.Sp
+Or you can use a comma delimited list of the workds CJK, MidWest,
+Other, Rare and West to specificy which encoding assemblies to distribute.
+.TP
+.I "-L path"
+Adds the `path' do the search list for assemblies. The rules are the
+same as for the compiler -lib: or -L flags.
+.TP
+.I "--library [LIB,]PATH"
+Embeds the dynamic library file pointed to by `PATH' and optionally
+give it the name `LIB' into the bundled executable. This is used to
+ship native library dependencies that are unpacked at startup and
+loaded from the runtime. Multiple libraries should be specified in
+dependency order, where later ones on the command line depend on
+earlier ones.
+.TP
+.I "--lists-targets"
+Lists all of the available local cross compilation targets available
+as precompiled binaries on the Mono distribution server.
+.TP
+.I "--local-targets"
+Lists all of the available local cross compilation targets.
+.TP
+.I "--machine-config FILE"
+Uses the given FILE as the machine.config file for the generated
+application.
+.TP
+.I "--nodeps"
+This is the default: \fImkbundle\fP will only include the assemblies that
+were specified on the command line to reduce the size of the resulting
+image created.
+.TP
+.I "-o filename"
+Places the output on `out'. If the flag -c is specified, this is the
+C host program. If not, this contains the resulting executable.
+.TP
+.I "--options OPTS"
+Since the resulting executable will be treated as a standalone
+program, you can use this option to pass configuration options to the
+Mono runtime and bake those into the resulting executable. These
+options are specified as
+.I OPTS.
+.Sp
+You can use the above to configure options that you would typically
+pass on the command line to Mono, before the main program is
+executed.
+.Sp
+Additionally, users of your binary can still configure their own
+options by setting the
+.I MONO_ENV_OPTIONS
+environment variable.
+.TP
+.I "--sdk SDK_PATH"
+Use this flag to specify a path from which mkbundle will resolve the
+Mono SDK from. The SDK path should be the prefix path that you used
+to configure a Mono installation. And would typically contain files
+lik
+.I SDK_PATH/bin/mono
+,
+.I SDK_PATH/lib/mono/4.5
+and so on.
+.Sp
+When this flag is specified,
+.I mkbundle
+will resolve the runtime, the framework libraries, unmanaged resources
+and configuration files from the files located in this directory.
+.Sp
+This flag is mutually exlusive with
+.I --cross
+.
+.TP
+.I "--target-server SERVER"
+By default the mkbundle tool will download from a Mono server the
+target runtimes, you can specify a different server to provide
+cross-compiled runtimes.
+.SH OLD EMBEDDING
+.PP
+The old embedding system compiles a small C stub that embeds the
+C code and compiles the resulting executable using the system
+compiler. This requires both a working C compiler installation and
+only works to bundle binaries for the current host.
+.PP
+The feature is still available, but we recommend the simpler, faster
+and more convenient new mode.
.PP
For example, to create a bundle for hello world, use the following
command:
.nf
+
$ mkbundle -o hello hello.exe
.fi
.PP
in more detail. For example, this could be used to link some libraries
statically:
.nf
+
$ mkbundle -c -o host.c -oo bundles.o --deps hello.exe
$ cc host.c bundles.o /usr/lib/libmono.a -lc -lrt
not have a main() function. Call mono_mkbundle_init() before
initializing the JIT in your code so that the bundled assemblies
are available to the embedded runtime.
-.SH OPTIONS
+.SH OLD EMBEDDING OPTIONS
+These options can only be used instead of using the
+.B --cross, --runtime
+or
+.B --simple
+options.
.TP
.I "-c"
Produce the stub file, do not compile the resulting stub.
.TP
-.I "-o filename"
-Places the output on `out'. If the flag -c is specified, this is the
-C host program. If not, this contains the resulting executable.
-.TP
.I "-oo filename"
Specifies the name to be used for the helper object file that contains
the bundle.
.TP
-.I "-L path"
-Adds the `path' do the search list for assemblies. The rules are the
-same as for the compiler -lib: or -L flags.
-.TP "--config FILE"
-Specifies that a machine.config file must be bundled as well.
-Typically this is $prefix/etc/mono/1.0/machine.config or
-$prefix/etc/mono/2.0/machine.config depending on the profile that you
-are using (1.0 or 2.0)
-.TP
-.I "--nodeps"
-This is the default: \fImkbundle\fP will only include the assemblies that
-were specified on the command line to reduce the size of the resulting
-image created.
-.TP
-.I "--deps"
-This option will bundle all of the referenced assemblies for the
-assemblies listed on the command line option. This is useful to
-distribute a self-contained image.
-.TP
.I "--keeptemp"
By default \fImkbundle\fP will delete the temporary files that it uses to
produce the bundle. This option keeps the file around.
.TP
-.I "--machine-config FILE"
-Uses the given FILE as the machine.config file for the generated
-application.
-.TP
.I "--nomain"
With the -c option, generate the host stub without a main() function.
.TP
-.I "--config-dir DIR"
-When passed, DIR will be set for the MONO_CFG_DIR environment variable
-.TP
.I "--static"
By default \fImkbundle\fP dynamically links to mono and glib. This option
causes it to statically link instead.
.TP
-.B Important:
-Since the Mono runtime is licensed under the LGPL, even if you use
-static you should transfer the component pieces of the mkbundle to
-your users so they are able to upgrade the Mono runtime on their own.
-.TP
-If you want to use this for commercial licenses, you must obtain a
-proprietary license for Mono from mono@novell.com
-.TP
.I "-z"
Compresses the assemblies before embedding. This results in smaller
executable files, but increases startup time and requires zlib to be
installed on the target system.
.SH WINDOWS
-On Windows systems, it it necessary to have Unix-like toolchain to be
-installed for \fImkbundle\fP to work. You can use cygwin's and install gcc,
-gcc-mingw and as packages.
+If you are using the old embedding on Windows systems, it it necessary
+to have Unix-like toolchain to be installed for \fImkbundle\fP to
+work. You can use cygwin's and install gcc, gcc-mingw and as
+packages.
.SH ENVIRONMENT VARIABLES
.TP
.I "AS"
.SH FILES
This program will load referenced assemblies from the Mono assembly
cache.
+.PP
+Targets are loaded from ~/.mono/targets/TARGETNAME/mono
.SH BUGS
-The option "--static" is not supported under Windows.
+The option "--static" is not supported under Windows when using the
+old embedding.
Moreover, a full cygwin environment containing at least "gcc" and "as"
is required for the build process. The generated executable does not
depend on cygwin.
projects / mono.git / blobdiff