[mkbundle] add support for distributing I18N encoding files and improved the man page

1 files changed, 150 insertions, 62 deletions

diff --git a/man/mkbundle.1 b/man/mkbundle.1
index d61fc1757b1..160786d94f6 100644
--- a/man/mkbundle.1
+++ b/man/mkbundle.1
@@ -21,16 +21,24 @@ 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
-There are two modes of operation, the default one uses the
-C compiler to create a bundle and requires a complete C and Mono SDK
-to produced executables.   The simple mode (enabled when using the
-"--simple") command line option does not require this, and also allows
-for cross compilation.
+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
+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
 The simple version allows for cross-compiling, this requires a Mono
@@ -38,21 +46,145 @@ 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"
+Creates a bundle for the specified target platform.   The target
+must be a directory in ~/.mono/targets/ that contains a "mono"
+binary.   You can fetch various targets using the --fetch-target
+command line option.
+.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 "--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
+.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.
+.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 "--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
@@ -66,6 +198,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
@@ -77,86 +210,40 @@ 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 "--cross target"
-Creates a bundle for the specified target platform.   The target
-must be a directory in ~/.mono/targets/ that contains a "mono"
-binary.   You can fetch various targets using the --fetch-target
-command line option.
-.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 "--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 "--fetch-target target"
-Downloads a precompiled runtime for the specified target from the Mono
-distribution site.
-.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 "--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 "--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 "--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
-.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.
-.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"
@@ -175,7 +262,8 @@ 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.