X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=man%2Fmkbundle.1;h=adcc3adff0cc13aa51b8dd2ec5f3669c7340d19a;hb=9cba093c6301a327c49d570f34c46a6311445518;hp=392ab7b065899eb52f39f4afe30fc1fb2ec56076;hpb=4eb352bcb3ef7a71dc9ab62c5cd2d5e7598619f7;p=mono.git diff --git a/man/mkbundle.1 b/man/mkbundle.1 index 392ab7b0658..adcc3adff0c 100644 --- a/man/mkbundle.1 +++ b/man/mkbundle.1 @@ -8,9 +8,9 @@ .if t .sp .5v .if n .sp .. -.TH mkbundle "mkbundle 1.0" +.TH Mono "mkbundle" .SH NAME -mkbundle \- Creates a bundled executable. +mkbundle, mkbundle2 \- Creates a bundled executable. .SH SYNOPSIS .PP .B mkbundle [options] assembly1 [assembly2 ...] @@ -21,89 +21,318 @@ 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 hello.exe + + $ mkbundle -o hello --simple hello.exe + .fi .PP -The above will pull hello.exe native program called "hello". Notice -that the produced image still contains the CIL image and no -precompilation is done. +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 -In addition, it is possible to control whether mkbundle should compile -the resulting executable or not. 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: +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 -o host.c -oo bundles.o --deps hello.exe - $ cc host.c bundles.o /usr/lib/libmono.a -lc -lrt + $ 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 "-c" -Produce the stub file, do not compile the resulting stub. +.I "--config-dir DIR" +When passed, DIR will be set for the MONO_CFG_DIR environment variable .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. +.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 "-oo filename" -Specifies the name to be used for the helper object file that contains -the bundle. +.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 "--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 "--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: mkbundle will only include the assemblies that +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. +.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 mkbundle will delete the temporary files that it uses to +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 mkbundle dynamically links to mono and glib. This option +By default \fImkbundle\fP dynamically links to mono and glib. This option causes it to statically link instead. .TP -.I "--config-dir DIR" -When passed, DIR will be set for the MONO_CFG_DIR environment variable -.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 mkbundle 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" Assembler command. The default is "as". .TP .I "CC" -C compiler command. The default is "cc" under Linux and "gcc -mno-cygwin" +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. +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.