2 .\" mkbundle manual page.
3 .\" (C) 2004 Ximian, Inc.
5 .\" Miguel de Icaza (miguel@gnu.org)
7 .de Sp \" Vertical space (when we can't use .PP)
11 .TH mkbundle "mkbundle 1.0"
13 mkbundle, mkbundle2 \- Creates a bundled executable.
16 .B mkbundle [options] assembly1 [assembly2 ...]
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.
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
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.
36 For example, to create a bundle for hello world, use the following
40 $ mkbundle -o hello --simple hello.exe
44 You can configure options to be passed to the Mono runtime directly
45 into your executable, for this, use the
47 flag. For example, the following disables inlining, by passing the
48 "-O=-inline" command line option to the embedded executable:
51 $ mkbundle -o hello --options -O=-inline --simple hello.exe
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:
60 $ mkbundle --local-targets
62 default - Current System Mono
65 $ mkbundle --cross 4.4.0-debian-8-powerpc hello.exe -o hello-debian
69 The above will bundle your native library into hello-debian for
70 a Debian 8 system running on a PowerPC machine.
72 We provide pre-packages binaries for Mono for various architectures,
73 which allow you to cross compile, use the
75 to get a list of all targets supported, and use the
77 flag to retrieve a target that you do not have installed, like this:
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
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
95 $ mkbundle --fetch-target 4.4.2-macos-10.7-i386
99 And then you can produce a binary that will run on 32-bit Mono on
103 $ mkbundle --cross 4.4.2-macos-10.7-i386 hello.exe -o hello-macos
107 Downloaded targets are stored
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)
118 .I "--config-dir DIR"
119 When passed, DIR will be set for the MONO_CFG_DIR environment variable
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
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.
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.
138 .I "--fetch-target target"
139 Downloads a precompiled runtime for the specified target from the Mono
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.
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
157 flag to bundle all available encodings.
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.
164 Adds the `path' do the search list for assemblies. The rules are the
165 same as for the compiler -lib: or -L flags.
167 Lists all of the available local cross compilation targets available
168 as precompiled binaries on the Mono distribution server.
171 Lists all of the available local cross compilation targets.
173 .I "--machine-config FILE"
174 Uses the given FILE as the machine.config file for the generated
178 This is the default: \fImkbundle\fP will only include the assemblies that
179 were specified on the command line to reduce the size of the resulting
183 Places the output on `out'. If the flag -c is specified, this is the
184 C host program. If not, this contains the resulting executable.
187 Since the resulting executable will be treated as a standalone
188 program, you can use this option to pass configuration options to the
189 Mono runtime and bake those into the resulting executable. These
190 options are specified as
193 You can use the above to configure options that you would typically
194 pass on the command line to Mono, before the main program is
197 Additionally, users of your binary can still configure their own
198 options by setting the
200 environment variable.
202 .I "--target-server SERVER"
203 By default the mkbundle tool will download from a Mono server the
204 target runtimes, you can specify a different server to provide
205 cross-compiled runtimes.
208 The old embedding system compiles a small C stub that embeds the
209 C code and compiles the resulting executable using the system
210 compiler. This requires both a working C compiler installation and
211 only works to bundle binaries for the current host.
213 The feature is still available, but we recommend the simpler, faster
214 and more convenient new mode.
216 For example, to create a bundle for hello world, use the following
220 $ mkbundle -o hello hello.exe
223 The above will pull hello.exe into a native program called "hello". Notice
224 that the produced image still contains the CIL image and no
225 precompilation is done.
227 In addition, it is possible to control whether \fImkbundle\fP should compile
228 the resulting executable or not with the -c option. This is useful if
229 you want to link additional libraries or control the generated output
230 in more detail. For example, this could be used to link some libraries
234 $ mkbundle -c -o host.c -oo bundles.o --deps hello.exe
236 $ cc host.c bundles.o /usr/lib/libmono.a -lc -lrt
239 You may also use \fImkbundle\fP to generate a bundle you can use when
240 embedding the Mono runtime in a native application. In that case, use
241 both the -c and --nomain options. The resulting host.c file will
242 not have a main() function. Call mono_mkbundle_init() before
243 initializing the JIT in your code so that the bundled assemblies
244 are available to the embedded runtime.
245 .SH OLD EMBEDDING OPTIONS
246 These options can only be used instead of using the
247 .B --cross, --runtime
253 Produce the stub file, do not compile the resulting stub.
256 Specifies the name to be used for the helper object file that contains
260 By default \fImkbundle\fP will delete the temporary files that it uses to
261 produce the bundle. This option keeps the file around.
264 With the -c option, generate the host stub without a main() function.
267 By default \fImkbundle\fP dynamically links to mono and glib. This option
268 causes it to statically link instead.
271 Compresses the assemblies before embedding. This results in smaller
272 executable files, but increases startup time and requires zlib to be
273 installed on the target system.
275 If you are using the old embedding on Windows systems, it it necessary
276 to have Unix-like toolchain to be installed for \fImkbundle\fP to
277 work. You can use cygwin's and install gcc, gcc-mingw and as
279 .SH ENVIRONMENT VARIABLES
282 Assembler command. The default is "as".
285 C compiler command. The default is "cc" under Linux and "gcc"
288 .I "MONO_BUNDLED_OPTIONS"
289 Options to be passed to the bundled
290 Mono runtime, separated by spaces. See the mono(1) manual page or run mono --help.
292 This program will load referenced assemblies from the Mono assembly
295 Targets are loaded from ~/.mono/targets/TARGETNAME/mono
297 The option "--static" is not supported under Windows when using the
299 Moreover, a full cygwin environment containing at least "gcc" and "as"
300 is required for the build process. The generated executable does not
303 Visit http://lists.ximian.com/mailman/listinfo/mono-devel-list for details.
305 Visit: http://www.mono-project.com for details
307 .BR mcs(1), mono(1), mono-config(5).