345 lines
11 KiB
Groff
345 lines
11 KiB
Groff
.\"
|
|
.\" mkbundle manual page.
|
|
.\" (C) 2004 Ximian, Inc.
|
|
.\" Author:
|
|
.\" Miguel de Icaza (miguel@gnu.org)
|
|
.\"
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.TH Mono "mkbundle"
|
|
.SH NAME
|
|
mkbundle, mkbundle2 \- Creates a bundled executable.
|
|
.SH SYNOPSIS
|
|
.PP
|
|
.B mkbundle [options] assembly1 [assembly2 ...]
|
|
.SH DESCRIPTION
|
|
\fImkbundle\fP generates an executable program that will contain
|
|
static copies of the assemblies listed on the command line. By
|
|
default only the assemblies specified in the command line will be
|
|
included in the bundle. To automatically include all of the
|
|
dependencies referenced, use the "--deps" command line option.
|
|
.PP
|
|
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.
|
|
.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
|
|
The above will pull hello.exe into a native program called "hello". Notice
|
|
that the produced image still contains the CIL image and no
|
|
precompilation is done.
|
|
.PP
|
|
In addition, it is possible to control whether \fImkbundle\fP should compile
|
|
the resulting executable or not with the -c option. This is useful if
|
|
you want to link additional libraries or control the generated output
|
|
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
|
|
.fi
|
|
.PP
|
|
You may also use \fImkbundle\fP to generate a bundle you can use when
|
|
embedding the Mono runtime in a native application. In that case, use
|
|
both the -c and --nomain options. The resulting host.c file will
|
|
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 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 "-oo filename"
|
|
Specifies the name to be used for the helper object file that contains
|
|
the bundle.
|
|
.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 "--nomain"
|
|
With the -c option, generate the host stub without a main() function.
|
|
.TP
|
|
.I "--static"
|
|
By default \fImkbundle\fP dynamically links to mono and glib. This option
|
|
causes it to statically link instead.
|
|
.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
|
|
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"
|
|
Assembler command. The default is "as".
|
|
.TP
|
|
.I "CC"
|
|
C compiler command. The default is "cc" under Linux and "gcc"
|
|
under Windows.
|
|
.TP
|
|
.I "MONO_BUNDLED_OPTIONS"
|
|
Options to be passed to the bundled
|
|
Mono runtime, separated by spaces. See the mono(1) manual page or run mono --help.
|
|
.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 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.
|
|
.SH MAILING LISTS
|
|
Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
|
|
.SH WEB SITE
|
|
Visit: http://www.mono-project.com for details
|
|
.SH SEE ALSO
|
|
.BR mcs(1), mono(1), mono-config(5).
|
|
|
|
|