Driver.rst revision 360784 
1======
2Driver
3======
4
5Note: this document discuss Mach-O port of LLD. For ELF and COFF,
6see :doc:`index`.
7
8.. contents::
9   :local:
10
11Introduction
12============
13
14This document describes the lld driver. The purpose of this document is to
15describe both the motivation and design goals for the driver, as well as details
16of the internal implementation.
17
18Overview
19========
20
21The lld driver is designed to support a number of different command line
22interfaces. The main interfaces we plan to support are binutils' ld, Apple's
23ld, and Microsoft's link.exe.
24
25Flavors
26-------
27
28Each of these different interfaces is referred to as a flavor. There is also an
29extra flavor "core" which is used to exercise the core functionality of the
30linker it the test suite.
31
32* gnu
33* darwin
34* link
35* core
36
37Selecting a Flavor
38^^^^^^^^^^^^^^^^^^
39
40There are two different ways to tell lld which flavor to be. They are checked in
41order, so the second overrides the first. The first is to symlink :program:`lld`
42as :program:`lld-{flavor}` or just :program:`{flavor}`. You can also specify
43it as the first command line argument using ``-flavor``::
44
45  $ lld -flavor gnu
46
47There is a shortcut for ``-flavor core`` as ``-core``.
48
49
50Adding an Option to an existing Flavor
51======================================
52
53#. Add the option to the desired :file:`lib/Driver/{flavor}Options.td`.
54
55#. Add to :cpp:class:`lld::FlavorLinkingContext` a getter and setter method
56   for the option.
57
58#. Modify :cpp:func:`lld::FlavorDriver::parse` in :file:
59   `lib/Driver/{Flavor}Driver.cpp` to call the targetInfo setter
60   for the option.
61
62#. Modify {Flavor}Reader and {Flavor}Writer to use the new targetInfo option.
63
64
65Adding a Flavor
66===============
67
68#. Add an entry for the flavor in :file:`include/lld/Common/Driver.h` to
69   :cpp:class:`lld::UniversalDriver::Flavor`.
70
71#. Add an entry in :file:`lib/Driver/UniversalDriver.cpp` to
72   :cpp:func:`lld::Driver::strToFlavor` and
73   :cpp:func:`lld::UniversalDriver::link`.
74   This allows the flavor to be selected via symlink and `-flavor`.
75
76#. Add a tablegen file called :file:`lib/Driver/{flavor}Options.td` that
77   describes the options. If the options are a superset of another driver, that
78   driver's td file can simply be included. The :file:`{flavor}Options.td` file
79   must also be added to :file:`lib/Driver/CMakeLists.txt`.
80
81#. Add a ``{flavor}Driver`` as a subclass of :cpp:class:`lld::Driver`
82   in :file:`lib/Driver/{flavor}Driver.cpp`.
83