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 Mono "mkbundle"
  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 .B --sdk
  29 or the
  30 .B --runtime
  31 command line options.
  32 .PP
  33 An older mechanism creates a small C stub that links against the
  34 libmono library to produce a self-contained executable and requires a
  35 C compiler.   It is described in the "OLD EMBEDDING" section below.
  36 .PP
  37 For example, to create a bundle for hello world, use the following
  38 command:
  39 .nf
  40
  41         $ mkbundle -o hello --simple hello.exe
  42
  43 .fi
  44 .PP
  45 You can configure options to be passed to the Mono runtime directly
  46 into your executable, for this, use the
  47 .I --options
  48 flag.  For example, the following disables inlining, by passing the
  49 "-O=-inline" command line option to the embedded executable:
  50 .nf
  51
  52         $ mkbundle -o hello --options -O=-inline --simple hello.exe
  53
  54 .PP
  55 The simple version allows for cross-compiling, this requires a Mono
  56 runtime to be installed in the ~/.mono/targets/TARGET/mono to be
  57 available.   You can use the "--local-targets" to list all available
  58 targets, and the "--cross" argument to specify the target, like this:
  59 .nf
  60
  61         $ mkbundle --local-targets
  62         Available targets:
  63                 default - Current System Mono
  64                 4.4.0-macosx-x86
  65                 4.4.0-debian-8-arm64
  66         $ mkbundle --cross 4.4.0-debian-8-powerpc hello.exe -o hello-debian
  67
  68 .fi
  69 .PP
  70 The above will bundle your native library into hello-debian for
  71 a Debian 8 system running on a PowerPC machine.
  72 .PP
  73 We provide pre-packages binaries for Mono for various architectures,
  74 which allow you to cross compile, use the
  75 .B --list-targets
  76 to get a list of all targets supported, and use the
  77 .B --fetch-target
  78 flag to retrieve a target that you do not have installed, like this:
  79 .nf
  80
  81         $ mkbundle --list-targets
  82         Cross-compilation targets available:
  83         4.4.0-linux-libc2.13-amd64
  84         4.4.0-linux-libc2.13-armel
  85         4.4.0-linux-libc2.13-armhf
  86         4.4.0-linux-libc2.13-i386
  87         4.4.0-macos-10.7-amd64
  88         4.4.0-macos-10.7-i386
  89         4.4.2-linux-libc2.13-amd64
  90         4.4.2-linux-libc2.13-armel
  91         4.4.2-linux-libc2.13-armhf
  92         4.4.2-linux-libc2.13-i386
  93         4.4.2-macos-10.7-amd64
  94         4.4.2-macos-10.7-i386
  95
  96         $ mkbundle --fetch-target 4.4.2-macos-10.7-i386
  97
  98 .fi
  99 .PP
 100 And then you can produce a binary that will run on 32-bit Mono on
 101 MacOS:
 102 .nf
 103
 104         $ mkbundle --cross 4.4.2-macos-10.7-i386 hello.exe -o hello-macos
 105
 106 .fi
 107 .PP
 108 Downloaded targets are stored
 109 .B ~/.mono/targets
 110 directory.
 111 .SH OPTIONS
 112 .TP
 113 .I "--config FILE"
 114 Specifies that a machine.config file must be bundled as well.
 115 Typically this is $prefix/etc/mono/1.0/machine.config or
 116 $prefix/etc/mono/2.0/machine.config depending on the profile that you
 117 are using (1.0 or 2.0)
 118 .TP
 119 .I "--config-dir DIR"
 120 When passed, DIR will be set for the MONO_CFG_DIR environment variable
 121 .TP
 122 .I "--cross target"
 123 Use this to request mkbundle generate a cross-compiled binary.  It
 124 Creates a bundle for the specified target platform.  The target must
 125 be a directory in ~/.mono/targets/ that contains an SDK installation
 126 as produced by the mono-package-runtime tool.  You can get a list of
 127 the precompiled versions of the runtime using --list-targets and you
 128 can fetch a specific target using the --fetch-target command line
 129 option.
 130 .Sp
 131 This flag is mutually exclusive with
 132 .I --sdk
 133 which is used to specify an absolute path to resolve the Mono runtime
 134 from and the --runtime option which is used to manually construct the
 135 cross-platform package.
 136 .TP
 137 .I "--deps"
 138 This option will bundle all of the referenced assemblies for the
 139 assemblies listed on the command line option.  This is useful to
 140 distribute a self-contained image.
 141 .TP
 142 .I "--env KEY=VALUE"
 143 Use this to hardcode an environment variable at runtime for KEY to be
 144 mapped to VALUE.   This is useful in scenarios where you want to
 145 enable certain Mono runtime configuration options that are controlled
 146 by environment variables.
 147 .TP
 148 .I "--fetch-target target"
 149 Downloads a precompiled runtime for the specified target from the Mono
 150 distribution site.
 151 .TP
 152 .I "--i18n encoding"
 153 Specified which encoding tables to ship with the executable.   By
 154 default, Mono ships the supporting I18N.dll assembly and the
 155 I18N.West.dll assembly.   If your application will use the
 156 System.Text.Encoding.GetEncoding with encodings other than the West
 157 encodings, you should specify them here.
 158 .Sp
 159 You can use the
 160 .B none
 161 parameter to request that no implicit encodings should be bundled,
 162 including the supporting I18N.dll, use this option if you have ran a
 163 linker on your own.
 164 .Sp
 165 You can use the
 166 .B all
 167 flag to bundle all available encodings.
 168 .Sp
 169 Or you can use a comma delimited list of the workds CJK, MidWest,
 170 Other, Rare and West to specificy which encoding assemblies to distribute.
 171 .TP
 172 .I "-L path"
 173 Adds the `path' do the search list for assemblies.  The rules are the
 174 same as for the compiler -lib: or -L flags.
 175 .TP
 176 .I "--library [LIB,]PATH"
 177 Embeds the dynamic library file pointed to by `PATH' and optionally
 178 give it the name `LIB' into the bundled executable.   This is used to
 179 ship native library dependencies that are unpacked at startup and
 180 loaded from the runtime.
 181 .TP
 182 .I "--lists-targets"
 183 Lists all of the available local cross compilation targets available
 184 as precompiled binaries on the Mono distribution server.
 185 .TP
 186 .I "--local-targets"
 187 Lists all of the available local cross compilation targets.
 188 .TP
 189 .I "--cil-strip PATH"
 190 Provides a CIL stripper that mkbundle will use if able to.
 191 The intended use is to help reduce file size on AOT.
 192 .TP
 193 .I "--in-tree path/to/mono/source/root"
 194 Provides mkbundle with a mono source repository from which to pull the necessary headers for compilation.
 195 This allows mkbundle to run out of the project's source tree, useful for working with multiple runtimes and for
 196 testing without installing.
 197 .TP
 198 .I "--managed-linker PATH"
 199 Provides mkbundle access to a managed linker to preprocess the assemblies.
 200 .TP
 201 .I "--machine-config FILE"
 202 Uses the given FILE as the machine.config file for the generated
 203 application.
 204 .TP
 205 .I  "--nodeps"
 206 This is the default: \fImkbundle\fP will only include the assemblies that
 207 were specified on the command line to reduce the size of the resulting
 208 image created.
 209 .TP
 210 .I "-o filename"
 211 Places the output on `out'.  If the flag -c is specified, this is the
 212 C host program.  If not, this contains the resulting executable.
 213 .TP
 214 .I "--options OPTS"
 215 Since the resulting executable will be treated as a standalone
 216 program, you can use this option to pass configuration options to the
 217 Mono runtime and bake those into the resulting executable.  These
 218 options are specified as
 219 .I OPTS.
 220 .Sp
 221 You can use the above to configure options that you would typically
 222 pass on the command line to Mono, before the main program is
 223 executed.
 224 .Sp
 225 Additionally, users of your binary can still configure their own
 226 options by setting the
 227 .I MONO_ENV_OPTIONS
 228 environment variable.
 229 .TP
 230 .I "--sdk SDK_PATH"
 231 Use this flag to specify a path from which mkbundle will resolve the
 232 Mono SDK from.   The SDK path should be the prefix path that you used
 233 to configure a Mono installation.   And would typically contain files
 234 lik
 235 .I SDK_PATH/bin/mono
 236 ,
 237 .I SDK_PATH/lib/mono/4.5
 238 and so on.
 239 .Sp
 240 When this flag is specified,
 241 .I mkbundle
 242 will resolve the runtime, the framework libraries, unmanaged resources
 243 and configuration files from the files located in this directory.
 244 .Sp
 245 This flag is mutually exlusive with
 246 .I --cross
 247 .
 248 .TP
 249 .I "--target-server SERVER"
 250 By default the mkbundle tool will download from a Mono server the
 251 target runtimes, you can specify a different server to provide
 252 cross-compiled runtimes.
 253 .SH OLD EMBEDDING
 254 .PP
 255 The old embedding system compiles a small C stub that embeds the
 256 C code and compiles the resulting executable using the system
 257 compiler.   This requires both a working C compiler installation and
 258 only works to bundle binaries for the current host.
 259 .PP
 260 The feature is still available, but we recommend the simpler, faster
 261 and more convenient new mode.
 262 .PP
 263 For example, to create a bundle for hello world, use the following
 264 command:
 265 .nf
 266
 267         $ mkbundle -o hello hello.exe
 268 .fi
 269 .PP
 270 The above will pull hello.exe into a native program called "hello".  Notice
 271 that the produced image still contains the CIL image and no
 272 precompilation is done.
 273 .PP
 274 In addition, it is possible to control whether \fImkbundle\fP should compile
 275 the resulting executable or not with the -c option.  This is useful if
 276 you want to link additional libraries or control the generated output
 277 in more detail. For example, this could be used to link some libraries
 278 statically:
 279 .nf
 280
 281         $ mkbundle -c -o host.c -oo bundles.o --deps hello.exe
 282
 283         $ cc host.c bundles.o /usr/lib/libmono.a -lc -lrt
 284 .fi
 285 .PP
 286 You may also use \fImkbundle\fP to generate a bundle you can use when
 287 embedding the Mono runtime in a native application.  In that case, use
 288 both the -c and --nomain options.  The resulting host.c file will
 289 not have a main() function.  Call mono_mkbundle_init() before
 290 initializing the JIT in your code so that the bundled assemblies
 291 are available to the embedded runtime.
 292 .SH OLD EMBEDDING OPTIONS
 293 These options can only be used instead of using the
 294 .B --cross, --runtime
 295 or
 296 .B --simple
 297 options.
 298 .TP
 299 .I "-c"
 300 Produce the stub file, do not compile the resulting stub.
 301 .TP
 302 .I "-oo filename"
 303 Specifies the name to be used for the helper object file that contains
 304 the bundle.
 305 .TP
 306 .I "--keeptemp"
 307 By default \fImkbundle\fP will delete the temporary files that it uses to
 308 produce the bundle.  This option keeps the file around.
 309 .TP
 310 .I "--nomain"
 311 With the -c option, generate the host stub without a main() function.
 312 .TP
 313 .I "--static"
 314 By default \fImkbundle\fP dynamically links to mono and glib.  This option
 315 causes it to statically link instead.
 316 .TP
 317 .I "-z"
 318 Compresses the assemblies before embedding. This results in smaller
 319 executable files, but increases startup time and requires zlib to be
 320 installed on the target system.
 321
 322 .SH AOT Options
 323 These options support an mkbundle using AOT compilation with static linking. A native compiler
 324 toolchain is required.
 325 .TP
 326 .I "--aot-runtime PATH"
 327 Provide the path to the mono runtime to use for AOTing assemblies.
 328 .TP
 329 .I "--aot-dedup"
 330 (Experimental) Deduplicate AOT'ed methods based on a unique mangling of method names.
 331 .TP
 332 .I "--aot-mode MODE"
 333 MODE can be either "full" or "llvmonly" at this time.
 334 Currently, mkbundle supports three AOT modes. The default mode (this option unset)
 335 will AOT methods but will fall back on runtime codegen where it is much faster or offers
 336 a more full compatibility profile. The "full" setting will generate the necessary stubs to
 337 not require runtime code generation. The "llvmonly" setting does the same, but forces all codegen
 338 to go through the llvm backend.
 339
 340 .SH WINDOWS
 341 If you are using the old embedding on Windows systems, it it necessary
 342 to have Unix-like toolchain to be installed for \fImkbundle\fP to
 343 work.  You can use cygwin's and install gcc, gcc-mingw and as
 344 packages.
 345 .SH ENVIRONMENT VARIABLES
 346 .TP
 347 .I "AS"
 348 Assembler command. The default is "as".
 349 .TP
 350 .I "CC"
 351 C compiler command. The default is "cc" under Linux and "gcc"
 352 under Windows.
 353 .TP
 354 .I "MONO_BUNDLED_OPTIONS"
 355 Options to be passed to the bundled
 356 Mono runtime, separated by spaces. See the mono(1) manual page or run mono --help.
 357 .SH FILES
 358 This program will load referenced assemblies from the Mono assembly
 359 cache.
 360 .PP
 361 Targets are loaded from ~/.mono/targets/TARGETNAME/mono
 362 .SH BUGS
 363 The option "--static" is not supported under Windows when using the
 364 old embedding.
 365 Moreover, a full cygwin environment containing at least "gcc" and "as"
 366 is required for the build process. The generated executable does not
 367 depend on cygwin.
 368 .SH MAILING LISTS
 369 Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
 370 .SH WEB SITE
 371 Visit: http://www.mono-project.com for details
 372 .SH SEE ALSO
 373 .BR mcs(1), mono(1), mono-config(5).
 374
 375