2 .\" The Mono Linker manual page.
5 .\" Jb Evain <jbevain@novell.com>
7 .\" Copyright (C) 2007 Novell, Inc (http://www.novell.com)
13 .TH CIL Linker "monolinker"
18 .B monolinker [-o output_directory][-l i18n_assemblies][-c skip | copy | link] -x descriptor | -a assembly | -i info_file ...
20 \fImonolinker\fP is a CIL Linker.
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
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.
32 The generated output from the monolinker can be later processed by the
34 tool to generate small native self-contained executables.
36 Do not confuse this with the Assembly Linker (al) which creates
37 assemblies from manifests, modules and resource files.
40 .I "-d search_directory"
41 Specify a directory to the linker where to look for assemblies.
43 .I "-o output_directory"
44 Specify the output directory, default is 'output'.
46 If you specify the directory `.', please ensure that you won't write over
47 important assemblies of yours.
49 .I "-l i18n_assemblies"
50 Specify what to do with the region specific assemblies
52 Mono have a few assemblies which contains everything region specific:
61 By default, they will all be copied to the output directory, but you can
62 specify which one you want using this command. The choice can
63 either be: none, all, cjk, mideast, other, rare or west. You can
64 combine the values with a comma.
67 Specify the action to apply to the core assemblies.
69 Core assemblies are the assemblies that belongs to the base class library,
70 like mscorlib.dll, System.dll or System.Windows.Forms.dll.
72 The linker supports three operations on these assemblies, you can
73 specify one of the following actions:
78 This instructs the linker to skip them and do nothing with them.
81 This instructs the linker to copy them to the output directory,
84 This instructs the linker to apply the linking process and reduce
91 Use an XML descriptor as a source for the linker.
93 Here is an example that shows all the possibilities of this format:
97 <assembly fullname="Library">
98 <type fullname="Foo" />
99 <type fullname="Bar" preserve="nothing" required="false" />
100 <type fullname="Baz" preserve="fields" required="false" />
101 <type fullname="Gazonk">
102 <method signature="System.Void .ctor(System.String)" />
103 <field signature="System.String _blah" />
109 In this example, the linker will link the types Foo, Bar, Baz and Gazonk.
111 The preserve attribute ensures that all the fields of the type Baz will be
112 always be linked, not matter if they are used or not, but that neither the
113 fields or the methods of Bar will be linked if they are not used. Not
114 specifying a preserve attribute implies that we are preserving everything in
117 The required attribute specifies that if the type is not marked, during the
118 mark operation, it will not be linked.
120 The type Gazonk will be linked, as well as its constructor taking a string as a
121 parameter, and it's _blah field.
123 You can have multiple assembly nodes.
126 use an assembly as a source for the linker.
128 The linker will walk through all the methods of the assembly to generate only what
129 is necessary for this assembly to run.
132 use a .info xml file as a source for the linker.
134 An info file is a file produced by the tool mono-api-info. The linker will use it to
135 generate an assembly that contains only what the public API defined in he info file
136 needs. It will also adjust the visibility of the types that have to be present in the
137 assembly, but that are not visibile from the public API.
139 .I "-s [StepBefore:]StepFullName,StepAssembly[:StepAfter]"
141 You can ask the linker to execute custom steps by using the -s command. This command
142 takes the standard TypeFullName,Assembly format to locate the step. You can customize
143 its position in the pipeline by either adding it before a step, or after.
151 using Mono.Linker.Steps;
155 public class FooStep : IStep {
157 public void Process (LinkContext context)
159 foreach (IStep step in context.Pipeline.GetSteps ()) {
160 Console.WriteLine (step.GetType ().Name);
167 If you compile this custom against monolinker to a Foo.dll assembly, you
170 switch as follows. To add the FooStep at the end of the pipeline:
173 monolinker -s Foo.FooStep,Foo -a program.exe
176 This commanand will add the FooStep after the MarkStep:
179 monolinker -s MarkStep:Foo.FooStep,Foo -a program.exe
182 This command will add the FooStep before the MarkStep:
185 monolinker -s Foo.FooStep,Foo:MarkStep -a program.exe
188 This command will add the FooStep before the MarkStep
190 Copyright (C) 2007 Novell, Inc (http://www.novell.com)
192 Bugs report are welcome at http://bugzilla.ximian.com
194 Product Mono Tools, Component linker.
196 Mailing lists are listed at http://www.mono-project.com/Mailing_Lists
198 http://www.mono-project.com/Linker
200 The linker has been written by Jb Evain, and have been partially founded by
201 the Google Summer of Code.
203 The linker is licensed under the MIT/X11 license. Please read the accompayning
204 MIT.X11 file for details.
206 .BR al(1),mkbundle(1),mono(1),mcs(1).