1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7 <title>Bold - The Byte Optimized Linker</title>
8 <meta name="author" content="Amand Tihon" />
9 <meta name="date" content="Aug 8, 2009" />
10 <meta name="copyright" content="GNU GPL version 3 + Exception, see copyright file." />
11 <style type="text/css">
14 :Author: David Goodger (goodger@python.org)
15 :Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
16 :Copyright: This stylesheet has been placed in the public domain.
18 Default cascading style sheet for the HTML output of Docutils.
20 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
21 customize this style sheet.
24 /* used to remove borders from tables and images */
25 .borderless, table.borderless td, table.borderless th {
28 table.borderless td, table.borderless th {
29 /* Override padding for "table.docutils td" with "! important".
30 The right padding separates the table cells. */
31 padding: 0 0.5em 0 0 ! important }
34 /* Override more specific margin styles with "! important". */
35 margin-top: 0 ! important }
37 .last, .with-subtitle {
38 margin-bottom: 0 ! important }
44 text-decoration: none ;
51 margin-bottom: 0.5em }
53 /* Uncomment (and remove this text!) to get bold-faced definition list terms
61 div.abstract p.topic-title {
65 div.admonition, div.attention, div.caution, div.danger, div.error,
66 div.hint, div.important, div.note, div.tip, div.warning {
68 border: medium outset ;
71 div.admonition p.admonition-title, div.hint p.admonition-title,
72 div.important p.admonition-title, div.note p.admonition-title,
73 div.tip p.admonition-title {
75 font-family: sans-serif }
77 div.attention p.admonition-title, div.caution p.admonition-title,
78 div.danger p.admonition-title, div.error p.admonition-title,
79 div.warning p.admonition-title {
82 font-family: sans-serif }
84 /* Uncomment (and remove this text!) to get reduced vertical space in
86 div.compound .compound-first, div.compound .compound-middle {
87 margin-bottom: 0.5em }
89 div.compound .compound-last, div.compound .compound-middle {
98 div.dedication p.topic-title {
106 div.footer, div.header {
115 div.line-block div.line-block {
121 margin: 0 0 0.5em 1em ;
122 border: medium outset ;
124 background-color: #ffffee ;
129 div.sidebar p.rubric {
130 font-family: sans-serif ;
133 div.system-messages {
136 div.system-messages h1 {
140 border: medium outset ;
143 div.system-message p.system-message-title {
150 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
151 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
169 ol.simple, ul.simple {
173 list-style: decimal }
176 list-style: lower-alpha }
179 list-style: upper-alpha }
182 list-style: lower-roman }
185 list-style: upper-roman }
199 white-space: nowrap }
208 font-family: sans-serif ;
213 font-family: sans-serif ;
225 pre.literal-block, pre.doctest-block {
230 font-family: sans-serif ;
231 font-style: oblique }
233 span.classifier-delimiter {
234 font-family: sans-serif ;
238 font-family: sans-serif }
241 white-space: nowrap }
249 span.section-subtitle {
250 /* font-size relative to parent (h1..h6 element) */
254 border-left: solid 1px gray;
262 margin-bottom: 0.5em }
265 border-left: solid 1px black;
268 table.docutils td, table.docutils th,
269 table.docinfo td, table.docinfo th {
270 padding-left: 0.5em ;
271 padding-right: 0.5em ;
272 vertical-align: top }
274 table.docutils th.field-name, table.docinfo th.docinfo-name {
277 white-space: nowrap ;
280 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
281 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
285 list-style-type: none }
290 <div class="document" id="bold-the-byte-optimized-linker">
291 <h1 class="title">Bold - The Byte Optimized Linker</h1>
292 <table class="docinfo" frame="void" rules="none">
293 <col class="docinfo-name" />
294 <col class="docinfo-content" />
296 <tr><th class="docinfo-name">Author:</th>
297 <td>Amand Tihon</td></tr>
298 <tr><th class="docinfo-name">Contact:</th>
299 <td><<a class="reference external" href="mailto:amand.tihon@alrj.org">amand.tihon@alrj.org</a>></td></tr>
300 <tr><th class="docinfo-name">Version:</th>
302 <tr><th class="docinfo-name">Date:</th>
303 <td>Aug 8, 2009</td></tr>
304 <tr><th class="docinfo-name">Copyright:</th>
305 <td>GNU GPL version 3 + Exception, see copyright file.</td></tr>
308 <!-- HTML version generated with LC_ALL=C rst2html -t README > README.html -->
309 <div class="contents topic" id="table-of-contents">
310 <p class="topic-title first">Table of contents</p>
311 <ul class="auto-toc simple">
312 <li><a class="reference internal" href="#abstract" id="id1">1 Abstract</a></li>
313 <li><a class="reference internal" href="#rationale" id="id2">2 Rationale</a></li>
314 <li><a class="reference internal" href="#getting-bold" id="id3">3 Getting Bold</a></li>
315 <li><a class="reference internal" href="#requirements" id="id4">4 Requirements</a></li>
316 <li><a class="reference internal" href="#installation" id="id5">5 Installation</a></li>
317 <li><a class="reference internal" href="#using-bold" id="id6">6 Using Bold</a><ul class="auto-toc">
318 <li><a class="reference internal" href="#synopsys" id="id7">6.1 Synopsys</a></li>
319 <li><a class="reference internal" href="#description" id="id8">6.2 Description</a></li>
320 <li><a class="reference internal" href="#options" id="id9">6.3 Options</a></li>
321 <li><a class="reference internal" href="#notes" id="id10">6.4 Notes</a></li>
324 <li><a class="reference internal" href="#internals" id="id11">7 Internals</a><ul class="auto-toc">
325 <li><a class="reference internal" href="#external-symbols-resolution" id="id12">7.1 External symbols resolution</a></li>
326 <li><a class="reference internal" href="#calling-from-c" id="id13">7.2 Calling from C</a></li>
327 <li><a class="reference internal" href="#aligning" id="id14">7.3 Aligning</a></li>
328 <li><a class="reference internal" href="#additional-trick-1-dt-debug" id="id15">7.4 Additional Trick 1: DT_DEBUG</a></li>
329 <li><a class="reference internal" href="#additional-trick-2-short-dynamic-table" id="id16">7.5 Additional Trick 2: Short DYNAMIC table</a></li>
332 <li><a class="reference internal" href="#examples" id="id17">8 Examples</a></li>
335 <div class="section" id="abstract">
336 <h1>1 Abstract</h1>
337 <p>Bold is an ELF linker, currently only targetting x86_64 under Linux. Being
338 limited in capabilities, it should not be considered as an all-purpose linker.</p>
340 <div class="section" id="rationale">
341 <h1>2 Rationale</h1>
342 <p>Bold's main purpose is to generate very small executable programs.</p>
343 <p>While <tt class="docutils literal"><span class="pre">ld</span></tt> from the GNU binutils can do almost anything anyone would ever
344 need, some specific goals need an awful lot of tweaking, or can simply not be
345 achieved. Bold uses several tricks to reduce the size of the final executable
348 <div class="section" id="getting-bold">
349 <h1>3 Getting Bold</h1>
350 <p>You can download the tarball from <a class="reference external" href="http://www.alrj.org/projects/bold">http://www.alrj.org/projects/bold</a>
351 or get the latest development version with the following git command:</p>
352 <pre class="literal-block">
353 git clone http://git.alrj.org/git/bold.git
355 <p>A gitweb interface is also available at <a class="reference external" href="http://git.alrj.org/">http://git.alrj.org/</a></p>
357 <div class="section" id="requirements">
358 <h1>4 Requirements</h1>
359 <p>Bold itself is entirely written in Python. There are no additionnal
361 <p>The runtime library that contains the external symbols resolver is written
362 in assembler (Intel syntax). An assembler like Nasm or Yasm is needed to
363 recompile the source code into an object file.</p>
365 <div class="section" id="installation">
366 <h1>5 Installation</h1>
367 <p>Go into Bold's directory, and run</p>
368 <pre class="literal-block">
369 python setup.py build
371 <p>Then, as root or using sudo, run</p>
372 <pre class="literal-block">
373 python setup.py install
376 <div class="section" id="using-bold">
377 <h1>6 Using Bold</h1>
378 <div class="section" id="synopsys">
379 <h2>6.1 Synopsys</h2>
381 bold [options] objfile...</blockquote>
383 <div class="section" id="description">
384 <h2>6.2 Description</h2>
385 <p>Bold combines a number of object files, relocate their data and resolves their
386 symbols references, in order to generate executable binaries.</p>
387 <p>Bold has only one, very specific purpose: making small executables.</p>
389 <div class="section" id="options">
390 <h2>6.3 Options</h2>
391 <table class="docutils option-list" frame="void" rules="none">
392 <col class="option" />
393 <col class="description" />
395 <tr><td class="option-group">
396 <kbd><span class="option">--version</span></kbd></td>
397 <td>Show program's version and exit.</td></tr>
398 <tr><td class="option-group">
399 <kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
400 <td>Show help message and exit.</td></tr>
401 <tr><td class="option-group" colspan="2">
402 <kbd><span class="option">-e <var>SYMBOL</var></span>, <span class="option">--entry=<var>SYMBOL</var></span></kbd></td>
404 <tr><td> </td><td>Use SYMBOL as the explicit symbol for beginning execution of your program.
405 If <tt class="docutils literal"><span class="pre">--raw</span></tt> is specified, it defaults to <tt class="docutils literal"><span class="pre">_start</span></tt>.</td></tr>
406 <tr><td class="option-group" colspan="2">
407 <kbd><span class="option">-l <var>LIBNAME</var></span>, <span class="option">--library=<var>LIBNAME</var></span></kbd></td>
409 <tr><td> </td><td>Link against the shared library specified by LIBNAME. Bold relies on python's
410 ctypes module to find the libraries. This option may be used any number of
412 <tr><td class="option-group" colspan="2">
413 <kbd><span class="option">-L <var>DIRECTORY</var></span>, <span class="option">--library-path=<var>DIRECTORY</var></span></kbd></td>
415 <tr><td> </td><td>This option does nothing, and is present ony for compatibility reasons. It
416 MAY get implemented in the future, though. This option may be used any number
418 <tr><td class="option-group" colspan="2">
419 <kbd><span class="option">-o <var>FILE</var></span>, <span class="option">--output=<var>FILE</var></span></kbd></td>
421 <tr><td> </td><td>Set the output file name (default value is a.out).</td></tr>
422 <tr><td class="option-group">
423 <kbd><span class="option">--raw</span></kbd></td>
424 <td>Don't include the builtin external symbols resolution code. This is
425 described in details further in this document.</td></tr>
426 <tr><td class="option-group">
427 <kbd><span class="option">-c</span>, <span class="option">--ccall</span></kbd></td>
428 <td>Make external symbols directly callable by C, without having to declare the
429 pointers on functions. This option adds 6 bytes for each externally defined
430 function. This is described in details further in this document.</td></tr>
431 <tr><td class="option-group">
432 <kbd><span class="option">-a</span>, <span class="option">--align</span></kbd></td>
433 <td>Align the wrappers for external symbols on an 8 byte boundary, to take
434 advantage of the RIP-relative addressing. This is described in details
435 further in this document.</td></tr>
439 <div class="section" id="notes">
440 <h2>6.4 Notes</h2>
441 <p>The <tt class="docutils literal"><span class="pre">LD_PRELOAD</span></tt> environment variable may not always work (as expected or
443 <p>The <tt class="docutils literal"><span class="pre">main()</span></tt> function is called without any argument. Its return code is used
444 as exit code, though.</p>
447 <div class="section" id="internals">
448 <h1>7 Internals</h1>
449 <div class="section" id="external-symbols-resolution">
450 <h2>7.1 External symbols resolution</h2>
451 <p>The "import by hash" method is from parapete, leblane, las, as described on
452 <a class="reference external" href="http://www.pouet.net/topic.php?which=5392">http://www.pouet.net/topic.php?which=5392</a></p>
454 <div class="section" id="calling-from-c">
455 <h2>7.2 Calling from C</h2>
456 <p>If you write your code in C and need to call the external symbols, you
457 basically have two options. The first one is to redefine them (or define new
458 ones) to call by pointers. For instance,</p>
459 <pre class="literal-block">
463 <pre class="literal-block">
464 int (*SDL_Init)(int);
466 <p>Repeat it for all functions, or write a tool to automate it (hint: look at
467 <a class="reference external" href="http://research.mercury-labs.org/ibh-i386-0.2.2.tar.gz">http://research.mercury-labs.org/ibh-i386-0.2.2.tar.gz</a> for help).</p>
468 <p>There's a second possibility however, and it's the one used by Bold when you
469 specify the <tt class="docutils literal"><span class="pre">--ccall</span></tt> option: make the resolved symbol point, not to the
470 address of the function, but to a JMP instruction to the actual address:</p>
471 <pre class="literal-block">
476 SDL_Init: jmp [rel _bold__SDL_Init]
477 SDL_SetVideoMode: jmp [rel _bold__SDL_SetVideoMode]
481 _bold__SDL_Init resq ; Filled by the import by hash code
482 _bold__SDL_SetVideoMode resq
484 <p>This approach takes 6 bytes (the JMP instruction) for each external function
487 <div class="section" id="aligning">
488 <h2>7.3 Aligning</h2>
489 <p>The x86_64 architecture has this nice thing called "RIP-relative addressing".
490 If all the JMP instructions are in the same order than the pointers to the
491 functions they refer to, having them aligned with the pointers would result
492 in identical instructions. This is done with the <tt class="docutils literal"><span class="pre">--align</span></tt> option.</p>
493 <p>Adding two null bytes between each JMP enlarges the final executable by
494 2 x (number of function - 1) bytes, and may seem to go against our goal.
495 However, the result is a repetition of the <em>same eight bytes</em>, something that
496 can improve compression a lot!</p>
498 <div class="section" id="additional-trick-1-dt-debug">
499 <h2>7.4 Additional Trick 1: DT_DEBUG</h2>
500 <p>Bold declares a global symbol named <tt class="docutils literal"><span class="pre">_dt_debug</span></tt>, that points to the value of
501 the <tt class="docutils literal"><span class="pre">DT_DEBUG</span></tt> entry of the <tt class="docutils literal"><span class="pre">DYNAMIC</span></tt> table, for easy access. Just in case,
502 the <tt class="docutils literal"><span class="pre">DYNAMIC</span></tt> table can also be reached using the global <tt class="docutils literal"><span class="pre">_DYNAMIC</span></tt> symbol.</p>
504 <div class="section" id="additional-trick-2-short-dynamic-table">
505 <h2>7.5 Additional Trick 2: Short DYNAMIC table</h2>
506 <p>Executables generated by <tt class="docutils literal"><span class="pre">ld</span></tt> usually have a lot of entries in their
507 <tt class="docutils literal"><span class="pre">DYNAMIC</span></tt> table. Bold puts only the strict necessary:</p>
509 <li>One <tt class="docutils literal"><span class="pre">DT_NEEDED</span></tt> entry for each shared library to load (obviously).</li>
510 <li>A <tt class="docutils literal"><span class="pre">DT_SYMTAB</span></tt> entry, with null-pointer. Without this one, the interpreter
511 wouldn't do its job.</li>
512 <li>a <tt class="docutils literal"><span class="pre">DT_DEBUG</span></tt> entry, that will be used for symbol resolution.</li>
514 <p>And that's it!</p>
517 <div class="section" id="examples">
518 <h1>8 Examples</h1>
519 <p>The <tt class="docutils literal"><span class="pre">examples/</span></tt> directory contains a port of the <em>flow2</em> intro
520 (<a class="reference external" href="http://www.pouet.net/prod.php?which=30589">http://www.pouet.net/prod.php?which=30589</a>). Adding the dropper is left as an
521 exercise for the reader.</p>
525 <hr class="footer" />
526 Generated on: 2009-08-08 18:30 UTC.