man/mkbundle.1

   1 .\"
   2 .\" mkbundle manual page.
   3 .\" (C) 2004 Ximian, Inc.
   4 .\" Author:
   5 .\"   Miguel de Icaza (miguel@gnu.org)
   6 .\"
   7 .de Sp \" Vertical space (when we can't use .PP)
   8 .if t .sp .5v
   9 .if n .sp
  10 ..
  11 .TH mkbundle "mkbundle 1.0"
  12 .SH NAME
  13 mkbundle, mkbundle2 \- Creates a bundled executable.
  14 .SH SYNOPSIS
  15 .PP
  16 .B mkbundle [options] assembly1 [assembly2 ...]
  17 .SH DESCRIPTION
  18 \fImkbundle\fP generates an executable program that will contain
  19 static copies of the assemblies listed on the command line.  By
  20 default only the assemblies specified in the command line will be
  21 included in the bundle.  To automatically include all of the
  22 dependencies referenced, use the "--deps" command line option.
  23 .PP
  24 There are two modes of operation, one uses an existing Mono binary or
  25 a server-hosted list of binaries and is enabled when you use either
  26 the
  27 .B --cross
  28 or the
  29 .B --runtime
  30 command line options.
  31 .PP
  32 An older mechanism creates a small C stub that links against the
  33 libmono library to produce a self-contained executable and requires a
  34 C compiler.   It is described in the "OLD EMBEDDING" section below.
  35 .PP
  36 For example, to create a bundle for hello world, use the following
  37 command:
  38 .nf
  39
  40         $ mkbundle -o hello --simple hello.exe
  41
  42 .fi
  43 .PP
  44 You can configure options to be passed to the Mono runtime directly
  45 into your executable, for this, use the
  46 .I --options
  47 flag.  For example, the following disables inlining, by passing the
  48 "-O=-inline" command line option to the embedded executable:
  49 .nf
  50
  51         $ mkbundle -o hello --options -O=-inline --simple hello.exe
  52
  53 .PP
  54 The simple version allows for cross-compiling, this requires a Mono
  55 runtime to be installed in the ~/.mono/targets/TARGET/mono to be
  56 available.   You can use the "--local-targets" to list all available
  57 targets, and the "--cross" argument to specify the target, like this:
  58 .nf
  59
  60         $ mkbundle --local-targets
  61         Available targets:
  62                 default - Current System Mono
  63                 4.4.0-macosx-x86
  64                 4.4.0-debian-8-arm64
  65         $ mkbundle --cross 4.4.0-debian-8-powerpc hello.exe -o hello-debian
  66
  67 .fi
  68 .PP
  69 The above will bundle your native library into hello-debian for
  70 a Debian 8 system running on a PowerPC machine.
  71 .PP
  72 We provide pre-packages binaries for Mono for various architectures,
  73 which allow you to cross compile, use the
  74 .B --list-targets
  75 to get a list of all targets supported, and use the
  76 .B --fetch-target
  77 flag to retrieve a target that you do not have installed, like this:
  78 .nf
  79
  80         $ mkbundle --list-targets
  81         Cross-compilation targets available:
  82         4.4.0-linux-libc2.13-amd64
  83         4.4.0-linux-libc2.13-armel
  84         4.4.0-linux-libc2.13-armhf
  85         4.4.0-linux-libc2.13-i386
  86         4.4.0-macos-10.7-amd64
  87         4.4.0-macos-10.7-i386
  88         4.4.2-linux-libc2.13-amd64
  89         4.4.2-linux-libc2.13-armel
  90         4.4.2-linux-libc2.13-armhf
  91         4.4.2-linux-libc2.13-i386
  92         4.4.2-macos-10.7-amd64
  93         4.4.2-macos-10.7-i386
  94
  95         $ mkbundle --fetch-target 4.4.2-macos-10.7-i386
  96
  97 .fi
  98 .PP
  99 And then you can produce a binary that will run on 32-bit Mono on
 100 MacOS:
 101 .nf
 102
 103         $ mkbundle --cross 4.4.2-macos-10.7-i386 hello.exe -o hello-macos
 104
 105 .fi
 106 .PP
 107 Downloaded targets are stored
 108 .B ~/.mono/targets
 109 directory.
 110 .SH OPTIONS
 111 .TP
 112 .I "--config FILE"
 113 Specifies that a machine.config file must be bundled as well.
 114 Typically this is $prefix/etc/mono/1.0/machine.config or
 115 $prefix/etc/mono/2.0/machine.config depending on the profile that you
 116 are using (1.0 or 2.0)
 117 .TP
 118 .I "--config-dir DIR"
 119 When passed, DIR will be set for the MONO_CFG_DIR environment variable
 120 .TP
 121 .I "--cross target"
 122 Creates a bundle for the specified target platform.   The target
 123 must be a directory in ~/.mono/targets/ that contains a "mono"
 124 binary.   You can fetch various targets using the --fetch-target
 125 command line option.
 126 .TP
 127 .I "--deps"
 128 This option will bundle all of the referenced assemblies for the
 129 assemblies listed on the command line option.  This is useful to
 130 distribute a self-contained image.
 131 .TP
 132 .I "--env KEY=VALUE"
 133 Use this to hardcode an environment variable at runtime for KEY to be
 134 mapped to VALUE.   This is useful in scenarios where you want to
 135 enable certain Mono runtime configuration options that are controlled
 136 by environment variables.
 137 .TP
 138 .I "--fetch-target target"
 139 Downloads a precompiled runtime for the specified target from the Mono
 140 distribution site.
 141 .TP
 142 .I "--i18n encoding"
 143 Specified which encoding tables to ship with the executable.   By
 144 default, Mono ships the supporting I18N.dll assembly and the
 145 I18N.West.dll assembly.   If your application will use the
 146 System.Text.Encoding.GetEncoding with encodings other than the West
 147 encodings, you should specify them here.
 148 .Sp
 149 You can use the
 150 .B none
 151 parameter to request that no implicit encodings should be bundled,
 152 including the supporting I18N.dll, use this option if you have ran a
 153 linker on your own.
 154 .Sp
 155 You can use the
 156 .B all
 157 flag to bundle all available encodings.
 158 .Sp
 159 Or you can use a comma delimited list of the workds CJK, MidWest,
 160 Other, Rare and West to specificy which encoding assemblies to distribute.
 161 .TP
 162 .I "-L path"
 163 Adds the `path' do the search list for assemblies.  The rules are the
 164 same as for the compiler -lib: or -L flags.
 165 .TP
 166 .I "--library [LIB,]PATH"
 167 Embeds the dynamic library file pointed to by `PATH' and optionally
 168 give it the name `LIB' into the bundled executable.   This is used to
 169 ship native library dependencies that are unpacked at startup and
 170 loaded from the runtime.
 171 .TP
 172 .I "--lists-targets"
 173 Lists all of the available local cross compilation targets available
 174 as precompiled binaries on the Mono distribution server.
 175 .TP
 176 .I "--local-targets"
 177 Lists all of the available local cross compilation targets.
 178 .TP
 179 .I "--machine-config FILE"
 180 Uses the given FILE as the machine.config file for the generated
 181 application.
 182 .TP
 183 .I  "--nodeps"
 184 This is the default: \fImkbundle\fP will only include the assemblies that
 185 were specified on the command line to reduce the size of the resulting
 186 image created.
 187 .TP
 188 .I "-o filename"
 189 Places the output on `out'.  If the flag -c is specified, this is the
 190 C host program.  If not, this contains the resulting executable.
 191 .TP
 192 .I "--options OPTS"
 193 Since the resulting executable will be treated as a standalone
 194 program, you can use this option to pass configuration options to the
 195 Mono runtime and bake those into the resulting executable.  These
 196 options are specified as
 197 .I OPTS.
 198 .Sp
 199 You can use the above to configure options that you would typically
 200 pass on the command line to Mono, before the main program is
 201 executed.
 202 .Sp
 203 Additionally, users of your binary can still configure their own
 204 options by setting the
 205 .I MONO_ENV_OPTIONS
 206 environment variable.
 207 .TP
 208 .I "--target-server SERVER"
 209 By default the mkbundle tool will download from a Mono server the
 210 target runtimes, you can specify a different server to provide
 211 cross-compiled runtimes.
 212 .SH OLD EMBEDDING
 213 .PP
 214 The old embedding system compiles a small C stub that embeds the
 215 C code and compiles the resulting executable using the system
 216 compiler.   This requires both a working C compiler installation and
 217 only works to bundle binaries for the current host.
 218 .PP
 219 The feature is still available, but we recommend the simpler, faster
 220 and more convenient new mode.
 221 .PP
 222 For example, to create a bundle for hello world, use the following
 223 command:
 224 .nf
 225
 226         $ mkbundle -o hello hello.exe
 227 .fi
 228 .PP
 229 The above will pull hello.exe into a native program called "hello".  Notice
 230 that the produced image still contains the CIL image and no
 231 precompilation is done.
 232 .PP
 233 In addition, it is possible to control whether \fImkbundle\fP should compile
 234 the resulting executable or not with the -c option.  This is useful if
 235 you want to link additional libraries or control the generated output
 236 in more detail. For example, this could be used to link some libraries
 237 statically:
 238 .nf
 239
 240         $ mkbundle -c -o host.c -oo bundles.o --deps hello.exe
 241
 242         $ cc host.c bundles.o /usr/lib/libmono.a -lc -lrt
 243 .fi
 244 .PP
 245 You may also use \fImkbundle\fP to generate a bundle you can use when
 246 embedding the Mono runtime in a native application.  In that case, use
 247 both the -c and --nomain options.  The resulting host.c file will
 248 not have a main() function.  Call mono_mkbundle_init() before
 249 initializing the JIT in your code so that the bundled assemblies
 250 are available to the embedded runtime.
 251 .SH OLD EMBEDDING OPTIONS
 252 These options can only be used instead of using the
 253 .B --cross, --runtime
 254 or
 255 .B --simple
 256 options.
 257 .TP
 258 .I "-c"
 259 Produce the stub file, do not compile the resulting stub.
 260 .TP
 261 .I "-oo filename"
 262 Specifies the name to be used for the helper object file that contains
 263 the bundle.
 264 .TP
 265 .I "--keeptemp"
 266 By default \fImkbundle\fP will delete the temporary files that it uses to
 267 produce the bundle.  This option keeps the file around.
 268 .TP
 269 .I "--nomain"
 270 With the -c option, generate the host stub without a main() function.
 271 .TP
 272 .I "--static"
 273 By default \fImkbundle\fP dynamically links to mono and glib.  This option
 274 causes it to statically link instead.
 275 .TP
 276 .I "-z"
 277 Compresses the assemblies before embedding. This results in smaller
 278 executable files, but increases startup time and requires zlib to be
 279 installed on the target system.
 280 .SH WINDOWS
 281 If you are using the old embedding on Windows systems, it it necessary
 282 to have Unix-like toolchain to be installed for \fImkbundle\fP to
 283 work.  You can use cygwin's and install gcc, gcc-mingw and as
 284 packages.
 285 .SH ENVIRONMENT VARIABLES
 286 .TP
 287 .I "AS"
 288 Assembler command. The default is "as".
 289 .TP
 290 .I "CC"
 291 C compiler command. The default is "cc" under Linux and "gcc"
 292 under Windows.
 293 .TP
 294 .I "MONO_BUNDLED_OPTIONS"
 295 Options to be passed to the bundled
 296 Mono runtime, separated by spaces. See the mono(1) manual page or run mono --help.
 297 .SH FILES
 298 This program will load referenced assemblies from the Mono assembly
 299 cache.
 300 .PP
 301 Targets are loaded from ~/.mono/targets/TARGETNAME/mono
 302 .SH BUGS
 303 The option "--static" is not supported under Windows when using the
 304 old embedding.
 305 Moreover, a full cygwin environment containing at least "gcc" and "as"
 306 is required for the build process. The generated executable does not
 307 depend on cygwin.
 308 .SH MAILING LISTS
 309 Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
 310 .SH WEB SITE
 311 Visit: http://www.mono-project.com for details
 312 .SH SEE ALSO
 313 .BR mcs(1), mono(1), mono-config(5).
 314
 315