X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=man%2Fmkbundle.1;h=adcc3adff0cc13aa51b8dd2ec5f3669c7340d19a;hb=HEAD;hp=9fe5540734e760db6e417653c5c3f84e2f6adb37;hpb=ad5f8957f6efa5c2dc2f2aa9a2409994375a8d17;p=mono.git diff --git a/man/mkbundle.1 b/man/mkbundle.1 index 9fe5540734e..adcc3adff0c 100644 --- a/man/mkbundle.1 +++ b/man/mkbundle.1 @@ -8,7 +8,7 @@ .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 @@ -21,13 +21,239 @@ 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 -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 @@ -41,6 +267,7 @@ 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 @@ -52,85 +279,60 @@ 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 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" 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.