From ed1950719b38c2dde6d3c1efe1f216a7d90a04b4 Mon Sep 17 00:00:00 2001 From: "Michael J. Spencer" Date: Tue, 15 Jan 2013 02:00:59 +0000 Subject: [docs] Add driver documentation. This gives an overview of the driver and explains how to add options and driver flavors. llvm-svn: 172502 --- lld/docs/Driver.rst | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 lld/docs/Driver.rst (limited to 'lld/docs/Driver.rst') diff --git a/lld/docs/Driver.rst b/lld/docs/Driver.rst new file mode 100644 index 00000000000..9f946ae150c --- /dev/null +++ b/lld/docs/Driver.rst @@ -0,0 +1,108 @@ +====== +Driver +====== + +.. contents:: + :local: + +Introduction +============ + +This document describes the lld driver. The purpose of this document is to +describe both the motivation and design goals for the driver, as well as details +of the internal implementation. + +Overview +======== + +The lld driver is designed to support a number of different command line +interfaces. The main interfaces we plan to support are binutils ld, Apple's +ld64, and Microsoft's link.exe. + +Flavors +------- + +Each of these different interfaces is refered to as a flavor. There is also an +extra flavor for ``lld -core``. This is eqivilent to ``-cc1`` in clang. +The current flavors are. + +* ld +* ld64 +* link +* core + +Selecting a Flavor +^^^^^^^^^^^^^^^^^^ + +There are two different ways to tell lld which flavor to be. They are checked in +order, so the second overrides the first. The first is to symlink :program:`lld` +as :program:`lld-{flavor}` or just :program:`{flavor}`. You can also specify +it as the first command line argument using ``-flavor``:: + + $ lld -flavor ld + +There is a shortcut for ``-flavor core`` as ``-core``. + +Argument translation and lld -core +---------------------------------- + +Due to the different driver flavors and the need to write portable tests, there +is ``lld -core``. Driver flavors translate options into ``lld -core`` options. +These options are then forwarded to ``lld -core`` to run the actual link. The +options passed to ``lld -core`` can be seen by passing ``-###`` to any driver +flavor. + +Targets +------- + +The ``-target `` option can be passed to any driver flavor to +link for a specific target. You can also prefix the :program:`lld` symlink with +a target triple to default to that target. If neither of these is set, the +default target is the target LLVM was configured for. + +Adding an Option +================ + +#. Add the option to the desired :file:`lib/Driver/{flavor}Options.td`. + +#. If there is no ``lld -core`` option, add the option to + :file:`lib/Driver/CoreOptions.td`. All ``lld -core`` start with a single - + and if they have a value, it is joined with a =. ``lld -core`` options should + have sensible, non-abbrivated names and should be shared between flavors + where possible. + +#. Modify the ``{flavor}Driver::transform`` function to transform the added + option into one or more core options. + +#. Add the option to :cpp:class:`lld::LinkerOptions` in + :file:`include/lld/Driver/LinkerOptions.h` and modify the move constructor to + move the option value. + +#. Modify :cpp:func:`lld::parseCoreArgs` in :file:`lib/Driver/Drivers.cpp` to + fill the :cpp:class:`lld::LinkerOptions` with the new option. + +#. Modify lld to use the new option. + +Adding a Flavor +=============== + +#. Add an entry for the flavor in :file:`include/lld/Driver/Driver.h` to + :cpp:class:`lld::Driver::Flavor`. + +#. Add an entry in :file:`tools/lld/lld.cpp` to + :cpp:func:`lld::Driver::strToFlavor`. This allows the + flavor to be selected via symlink and :option:`-flavor`. + +#. Add a tablegen file called :file:`lib/Driver/{flavor}Options.td` that + describes the options. If the options are a superset of another driver, that + driver's td file can simply be included. The :file:`{flavor}Options.td` file + must also be added to :file:`lib/Driver/CMakeListst.txt`. + +#. Add a ``{flavor}::{flavor}OptTable`` as a subclass of + :cpp:class:`llvm::opt::OptTable` in :file:`lib/Driver/Drivers.cpp`. + +#. Add a ``{flavor}Driver`` as a subclass of :cpp:class:`lld::Driver` + in :file:`lib/Driver/Drivers.cpp`. It must have a :cpp:func:`transform` + function which takes argc/argv and returns a ``lld -core`` ArgList. + +#. Modify :cpp:func:`Driver::create` to create an instance of the new driver. -- cgit v1.2.1