man/monolinker.1

   1 .\"
   2 .\" The Mono Linker manual page.
   3 .\"
   4 .\" Author:
   5 .\"     Jb Evain  <jbevain@novell.com>
   6 .\"
   7 .\" Copyright (C) 2007 Novell, Inc (http://www.novell.com)
   8 .\"
   9 .de Sp \"
  10 .if t .sp .5v
  11 .if n .sp
  12 ..
  13 .TH CIL Linker "monolinker"
  14 .SH NAME
  15 Mono CIL Linker
  16 .SH SYNOPSIS
  17 .PP
  18 .B monolinker [-o output_directory][-l i18n_assemblies][-c skip | copy | link] -x descriptor | -a assembly | -i info_file ...
  19 .SH DESCRIPTION
  20 \fImonolinker\fP is a CIL Linker.
  21 .PP.
  22 The linker is a tool one can use to only ship the minimal possible set of
  23 functions that a set of programs might require to run as opposed to the full
  24 libraries.
  25 .PP
  26 The linker analyses the intermediate code (CIL) produced by every
  27 compiler targeting the Mono platform like mcs, gmcs, vbnc, booc or
  28 others. It will walk through all the code that it is given to it, and
  29 remove all the unused methods and classes.  This is done using a mark
  30 and sweep operation on all the code that it is referenced.
  31 .PP
  32 The generated output from the monolinker can be later processed by the
  33 .I mkbundle
  34 tool to generate small native self-contained executables.
  35 .PP
  36 Do not confuse this with the Assembly Linker (al) which creates
  37 assemblies from manifests, modules and resource files.
  38 .SH OPTIONS
  39 .TP
  40 .I "-d search_directory"
  41 Specify a directory to the linker where to look for assemblies.
  42 .TP
  43 .I "-o output_directory"
  44 Specify the output directory, default is 'output'.
  45 .Sp
  46 If you specify the directory `.', please ensure that you won't write over
  47 important assemblies of yours.
  48 .TP
  49 .I "-b true | false"
  50 Specify whether to generate debug symbols or not, default is false.
  51 .TP
  52 .I "-g true | false"
  53 Specify whether to generate a new guid for each linked module or reuse the
  54 existing one, default is true.
  55 .TP
  56 .I "-l i18n_assemblies"
  57 Specify what to do with the region specific assemblies
  58 .Sp
  59 Mono have a few assemblies which contains everything region specific:
  60 .nf
  61         I18N.CJK.dll
  62         I18N.MidEast.dll
  63         I18N.Other.dll
  64         I18N.Rare.dll
  65         I18N.West.dll
  66 .fi
  67 .Sp
  68 By default, they will all be copied to the output directory, but you can
  69 specify which one you want using this command. The choice can
  70 either be: none, all, cjk, mideast, other, rare or west. You can
  71 combine the values with a comma.
  72 .TP
  73 .I "-c action"
  74 Specify the action to apply to the core assemblies.
  75 .Sp
  76 Core assemblies are the assemblies that belongs to the base class library,
  77 like mscorlib.dll, System.dll or System.Windows.Forms.dll.
  78 .Sp
  79 The linker supports three operations on these assemblies, you can
  80 specify one of the following actions:
  81 .RS
  82 .ne 8
  83 .TP
  84 .I skip
  85 This instructs the linker to skip them and do nothing with them.
  86 .TP
  87 .I copy
  88 This instructs the linker to copy them to the output directory,
  89 .TP
  90 .I link
  91 This instructs the linker to apply the linking process and reduce
  92 their size.
  93 .ne
  94 .RE
  95 .Sp
  96 .TP
  97 .I "-p action assembly"
  98 Specify per assembly which action to apply.
  99 .TP
 100 .I "-x descriptor"
 101 Use an XML descriptor as a source for the linker.
 102 .Sp
 103 Here is an example that shows all the possibilities of this format:
 104 .Sp
 105 .nf
 106 <linker>
 107         <assembly fullname="Library">
 108                 <type fullname="Foo" />
 109                 <type fullname="Bar" preserve="nothing" required="false" />
 110                 <type fullname="Baz" preserve="fields" required="false" />
 111                 <type fullname="Gazonk">
 112                         <method signature="System.Void .ctor(System.String)" />
 113                         <field signature="System.String _blah" />
 114                         <field name="someFieldName" />
 115                 </type>
 116         </assembly>
 117 </linker>
 118 .fi
 119 .Sp
 120 In this example, the linker will link the types Foo, Bar, Baz and Gazonk.
 121 .Sp
 122 The preserve attribute ensures that all the fields of the type Baz will be
 123 always be linked, not matter if they are used or not, but that neither the
 124 fields or the methods of Bar will be linked if they are not used. Not
 125 specifying a preserve attribute implies that we are preserving everything in
 126 the specified type.
 127 .Sp
 128 The required attribute specifies that if the type is not marked, during the
 129 mark operation, it will not be linked.
 130 .Sp
 131 The type Gazonk will be linked, as well as its constructor taking a string as a
 132 parameter, and it's _blah field.
 133 .Sp
 134 You can have multiple assembly nodes.
 135 .TP
 136 .I "-a assemblies"
 137 use an assembly as a source for the linker.
 138 .Sp
 139 The linker will walk through all the methods of the assembly to generate only what
 140 is necessary for this assembly to run.
 141 .TP
 142 .I "-i info_file"
 143 use a .info xml file as a source for the linker.
 144 .Sp
 145 An info file is a file produced by the tool mono-api-info. The linker will use it to
 146 generate an assembly that contains only what the public API defined in the info file
 147 needs.
 148 .TP
 149 .I "-s [StepBefore:]StepFullName,StepAssembly[:StepAfter]"
 150 .Sp
 151 You can ask the linker to execute custom steps by using the -s command. This command
 152 takes the standard TypeFullName,Assembly format to locate the step. You can customize
 153 its position in the pipeline by either adding it before a step, or after.
 154 .Sp
 155 Example:
 156 .Sp
 157 .nf
 158 using System;
 159
 160 using Mono.Linker;
 161 using Mono.Linker.Steps;
 162
 163 namespace Foo {
 164
 165         public class FooStep : IStep {
 166
 167                 public void Process (LinkContext context)
 168                 {
 169                         foreach (IStep step in context.Pipeline.GetSteps ()) {
 170                                 Console.WriteLine (step.GetType ().Name);
 171                         }
 172                 }
 173         }
 174 }
 175 .fi
 176 .Sp
 177 If you compile this custom against monolinker to a Foo.dll assembly, you
 178 can use the
 179 .I -s
 180 switch as follows.   To add the FooStep at the end of the pipeline:
 181 .Sp
 182 .nf
 183         monolinker -s Foo.FooStep,Foo -a program.exe
 184 .fi
 185 .Sp
 186 This commanand will add the FooStep after the MarkStep:
 187 .Sp
 188 .nf
 189         monolinker -s MarkStep:Foo.FooStep,Foo -a program.exe
 190 .fi
 191 .Sp
 192 This command will add the FooStep before the MarkStep:
 193 .Sp
 194 .nf
 195         monolinker -s Foo.FooStep,Foo:MarkStep -a program.exe
 196 .fi
 197 .Sp
 198 This command will add the FooStep before the MarkStep
 199 .TP
 200 .I "-m CustomParam ParamValue"
 201 Specify a parameter for a custom step.
 202 .SH COPYRIGHT
 203 Copyright (C) 2007 Novell, Inc (http://www.novell.com)
 204 .SH BUGS
 205 Bugs report are welcome at http://bugzilla.xamarin.com
 206 .PP
 207 Product Mono Tools, Component linker.
 208 .SH MAILING LISTS
 209 Mailing lists are listed at http://www.mono-project.com/community/help/mailing-lists/
 210 .SH WEB SITE
 211 http://www.mono-project.com/docs/tools+libraries/tools/linker/
 212 .SH AUTHORS
 213 The linker has been written by Jb Evain, and have been partially founded by
 214 the Google Summer of Code.
 215 .SH LICENSE
 216 The linker is licensed under the MIT/X11 license. Please read the accompayning
 217 MIT.X11 file for details.
 218 .SH SEE ALSO
 219 .BR al(1),mkbundle(1),mono(1),mcs(1).