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 The simple version allows for cross-compiling, this requires a Mono
  45 runtime to be installed in the ~/.mono/targets/TARGET/mono to be
  46 available.   You can use the "--local-targets" to list all available
  47 targets, and the "--cross" argument to specify the target, like this:
  48 .nf
  49
  50         $ mkbundle --local-targets
  51         Available targets:
  52                 default - Current System Mono
  53                 4.4.0-macosx-x86
  54                 4.4.0-debian-8-arm64
  55         $ mkbundle --cross 4.4.0-debian-8-powerpc hello.exe -o hello-debian
  56
  57 .fi
  58 .PP
  59 The above will bundle your native library into hello-debian for
  60 a Debian 8 system running on a PowerPC machine.
  61 .PP
  62 We provide pre-packages binaries for Mono for various architectures,
  63 which allow you to cross compile, use the
  64 .B --list-targets
  65 to get a list of all targets supported, and use the
  66 .B --fetch-target
  67 flag to retrieve a target that you do not have installed, like this:
  68 .nf
  69
  70         $ mkbundle --list-targets
  71         Cross-compilation targets available:
  72         4.4.0-linux-libc2.13-amd64
  73         4.4.0-linux-libc2.13-armel
  74         4.4.0-linux-libc2.13-armhf
  75         4.4.0-linux-libc2.13-i386
  76         4.4.0-macos-10.7-amd64
  77         4.4.0-macos-10.7-i386
  78         4.4.2-linux-libc2.13-amd64
  79         4.4.2-linux-libc2.13-armel
  80         4.4.2-linux-libc2.13-armhf
  81         4.4.2-linux-libc2.13-i386
  82         4.4.2-macos-10.7-amd64
  83         4.4.2-macos-10.7-i386
  84
  85         $ mkbundle --fetch-target 4.4.2-macos-10.7-i386
  86
  87 .fi
  88 .PP
  89 And then you can produce a binary that will run on 32-bit Mono on
  90 MacOS:
  91 .nf
  92
  93         $ mkbundle --cross 4.4.2-macos-10.7-i386 hello.exe -o hello-macos
  94
  95 .fi
  96 .PP
  97 Downloaded targets are stored
  98 .B ~/.mono/targets
  99 directory.
 100 .SH OPTIONS
 101 .TP
 102 .I "--config FILE"
 103 Specifies that a machine.config file must be bundled as well.
 104 Typically this is $prefix/etc/mono/1.0/machine.config or
 105 $prefix/etc/mono/2.0/machine.config depending on the profile that you
 106 are using (1.0 or 2.0)
 107 .TP
 108 .I "--config-dir DIR"
 109 When passed, DIR will be set for the MONO_CFG_DIR environment variable
 110 .TP
 111 .I "--cross target"
 112 Creates a bundle for the specified target platform.   The target
 113 must be a directory in ~/.mono/targets/ that contains a "mono"
 114 binary.   You can fetch various targets using the --fetch-target
 115 command line option.
 116 .TP
 117 .I "--deps"
 118 This option will bundle all of the referenced assemblies for the
 119 assemblies listed on the command line option.  This is useful to
 120 distribute a self-contained image.
 121 .TP
 122 .I "--fetch-target target"
 123 Downloads a precompiled runtime for the specified target from the Mono
 124 distribution site.
 125 .TP
 126 .I "--i18n encoding"
 127 Specified which encoding tables to ship with the executable.   By
 128 default, Mono ships the supporting I18N.dll assembly and the
 129 I18N.West.dll assembly.   If your application will use the
 130 System.Text.Encoding.GetEncoding with encodings other than the West
 131 encodings, you should specify them here.
 132 .Sp
 133 You can use the
 134 .B none
 135 parameter to request that no implicit encodings should be bundled,
 136 including the supporting I18N.dll, use this option if you have ran a
 137 linker on your own.
 138 .Sp
 139 You can use the
 140 .B all
 141 flag to bundle all available encodings.
 142 .Sp
 143 Or you can use a comma delimited list of the workds CJK, MidWest,
 144 Other, Rare and West to specificy which encoding assemblies to distribute.
 145 .TP
 146 .TP
 147 .I "-L path"
 148 Adds the `path' do the search list for assemblies.  The rules are the
 149 same as for the compiler -lib: or -L flags.
 150 .I "--lists-targets"
 151 Lists all of the available local cross compilation targets available
 152 as precompiled binaries on the Mono distribution server.
 153 .TP
 154 .I "--local-targets"
 155 Lists all of the available local cross compilation targets.
 156 .TP
 157 .I "--machine-config FILE"
 158 Uses the given FILE as the machine.config file for the generated
 159 application.
 160 .TP
 161 .I  "--nodeps"
 162 This is the default: \fImkbundle\fP will only include the assemblies that
 163 were specified on the command line to reduce the size of the resulting
 164 image created.
 165 .TP
 166 .I "-o filename"
 167 Places the output on `out'.  If the flag -c is specified, this is the
 168 C host program.  If not, this contains the resulting executable.
 169 .TP
 170 .I "--target-server SERVER"
 171 By default the mkbundle tool will download from a Mono server the
 172 target runtimes, you can specify a different server to provide
 173 cross-compiled runtimes.
 174 .SH OLD EMBEDDING
 175 .PP
 176 The old embedding system compiles a small C stub that embeds the
 177 C code and compiles the resulting executable using the system
 178 compiler.   This requires both a working C compiler installation and
 179 only works to bundle binaries for the current host.
 180 .PP
 181 The feature is still available, but we recommend the simpler, faster
 182 and more convenient new mode.
 183 .PP
 184 For example, to create a bundle for hello world, use the following
 185 command:
 186 .nf
 187
 188         $ mkbundle -o hello hello.exe
 189 .fi
 190 .PP
 191 The above will pull hello.exe into a native program called "hello".  Notice
 192 that the produced image still contains the CIL image and no
 193 precompilation is done.
 194 .PP
 195 In addition, it is possible to control whether \fImkbundle\fP should compile
 196 the resulting executable or not with the -c option.  This is useful if
 197 you want to link additional libraries or control the generated output
 198 in more detail. For example, this could be used to link some libraries
 199 statically:
 200 .nf
 201
 202         $ mkbundle -c -o host.c -oo bundles.o --deps hello.exe
 203
 204         $ cc host.c bundles.o /usr/lib/libmono.a -lc -lrt
 205 .fi
 206 .PP
 207 You may also use \fImkbundle\fP to generate a bundle you can use when
 208 embedding the Mono runtime in a native application.  In that case, use
 209 both the -c and --nomain options.  The resulting host.c file will
 210 not have a main() function.  Call mono_mkbundle_init() before
 211 initializing the JIT in your code so that the bundled assemblies
 212 are available to the embedded runtime.
 213 .SH OLD EMBEDDING OPTIONS
 214 These options can only be used instead of using the
 215 .B --cross, --runtime
 216 or
 217 .B --simple
 218 options.
 219 .TP
 220 .I "-c"
 221 Produce the stub file, do not compile the resulting stub.
 222 .TP
 223 .I "-oo filename"
 224 Specifies the name to be used for the helper object file that contains
 225 the bundle.
 226 .TP
 227 .I "--keeptemp"
 228 By default \fImkbundle\fP will delete the temporary files that it uses to
 229 produce the bundle.  This option keeps the file around.
 230 .TP
 231 .I "--nomain"
 232 With the -c option, generate the host stub without a main() function.
 233 .TP
 234 .I "--static"
 235 By default \fImkbundle\fP dynamically links to mono and glib.  This option
 236 causes it to statically link instead.
 237 .TP
 238 .I "-z"
 239 Compresses the assemblies before embedding. This results in smaller
 240 executable files, but increases startup time and requires zlib to be
 241 installed on the target system.
 242 .SH WINDOWS
 243 If you are using the old embedding on Windows systems, it it necessary
 244 to have Unix-like toolchain to be installed for \fImkbundle\fP to
 245 work.  You can use cygwin's and install gcc, gcc-mingw and as
 246 packages.
 247 .SH ENVIRONMENT VARIABLES
 248 .TP
 249 .I "AS"
 250 Assembler command. The default is "as".
 251 .TP
 252 .I "CC"
 253 C compiler command. The default is "cc" under Linux and "gcc"
 254 under Windows.
 255 .TP
 256 .I "MONO_BUNDLED_OPTIONS"
 257 Options to be passed to the bundled
 258 Mono runtime, separated by spaces. See the mono(1) manual page or run mono --help.
 259 .SH FILES
 260 This program will load referenced assemblies from the Mono assembly
 261 cache.
 262 .PP
 263 Targets are loaded from ~/.mono/targets/TARGETNAME/mono
 264 .SH BUGS
 265 The option "--static" is not supported under Windows when using the
 266 old embedding.
 267 Moreover, a full cygwin environment containing at least "gcc" and "as"
 268 is required for the build process. The generated executable does not
 269 depend on cygwin.
 270 .SH MAILING LISTS
 271 Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
 272 .SH WEB SITE
 273 Visit: http://www.mono-project.com for details
 274 .SH SEE ALSO
 275 .BR mcs(1), mono(1), mono-config(5).
 276
 277