Driver.rst revision 360784
11638Srgrimes====== 21638SrgrimesDriver 31638Srgrimes====== 41638Srgrimes 51638SrgrimesNote: this document discuss Mach-O port of LLD. For ELF and COFF, 61638Srgrimessee :doc:`index`. 71638Srgrimes 81638Srgrimes.. contents:: 91638Srgrimes :local: 101638Srgrimes 111638SrgrimesIntroduction 121638Srgrimes============ 131638Srgrimes 141638SrgrimesThis document describes the lld driver. The purpose of this document is to 151638Srgrimesdescribe both the motivation and design goals for the driver, as well as details 161638Srgrimesof the internal implementation. 171638Srgrimes 181638SrgrimesOverview 191638Srgrimes======== 201638Srgrimes 211638SrgrimesThe lld driver is designed to support a number of different command line 221638Srgrimesinterfaces. The main interfaces we plan to support are binutils' ld, Apple's 231638Srgrimesld, and Microsoft's link.exe. 241638Srgrimes 251638SrgrimesFlavors 261638Srgrimes------- 271638Srgrimes 281638SrgrimesEach of these different interfaces is referred to as a flavor. There is also an 291638Srgrimesextra flavor "core" which is used to exercise the core functionality of the 301638Srgrimeslinker it the test suite. 311638Srgrimes 321638Srgrimes* gnu 331638Srgrimes* darwin 341638Srgrimes* link 351638Srgrimes* core 361638Srgrimes 371638SrgrimesSelecting a Flavor 381638Srgrimes^^^^^^^^^^^^^^^^^^ 391638Srgrimes 401638SrgrimesThere are two different ways to tell lld which flavor to be. They are checked in 411638Srgrimesorder, so the second overrides the first. The first is to symlink :program:`lld` 421638Srgrimesas :program:`lld-{flavor}` or just :program:`{flavor}`. You can also specify 431638Srgrimesit as the first command line argument using ``-flavor``:: 441638Srgrimes 451638Srgrimes $ lld -flavor gnu 461638Srgrimes 471638SrgrimesThere is a shortcut for ``-flavor core`` as ``-core``. 481638Srgrimes 491638Srgrimes 501638SrgrimesAdding an Option to an existing Flavor 511638Srgrimes====================================== 521638Srgrimes 531638Srgrimes#. Add the option to the desired :file:`lib/Driver/{flavor}Options.td`. 541638Srgrimes 551638Srgrimes#. Add to :cpp:class:`lld::FlavorLinkingContext` a getter and setter method 561638Srgrimes for the option. 571638Srgrimes 581638Srgrimes#. Modify :cpp:func:`lld::FlavorDriver::parse` in :file: 591638Srgrimes `lib/Driver/{Flavor}Driver.cpp` to call the targetInfo setter 601638Srgrimes for the option. 611638Srgrimes 621638Srgrimes#. Modify {Flavor}Reader and {Flavor}Writer to use the new targetInfo option. 631638Srgrimes 641638Srgrimes 651638SrgrimesAdding a Flavor 661638Srgrimes=============== 671638Srgrimes 681638Srgrimes#. Add an entry for the flavor in :file:`include/lld/Common/Driver.h` to 691638Srgrimes :cpp:class:`lld::UniversalDriver::Flavor`. 701638Srgrimes 711638Srgrimes#. Add an entry in :file:`lib/Driver/UniversalDriver.cpp` to 721638Srgrimes :cpp:func:`lld::Driver::strToFlavor` and 731638Srgrimes :cpp:func:`lld::UniversalDriver::link`. 741638Srgrimes This allows the flavor to be selected via symlink and `-flavor`. 751638Srgrimes 761638Srgrimes#. Add a tablegen file called :file:`lib/Driver/{flavor}Options.td` that 771638Srgrimes describes the options. If the options are a superset of another driver, that 781638Srgrimes driver's td file can simply be included. The :file:`{flavor}Options.td` file 791638Srgrimes must also be added to :file:`lib/Driver/CMakeLists.txt`. 801638Srgrimes 811638Srgrimes#. Add a ``{flavor}Driver`` as a subclass of :cpp:class:`lld::Driver` 821638Srgrimes in :file:`lib/Driver/{flavor}Driver.cpp`. 831638Srgrimes