From ed1950719b38c2dde6d3c1efe1f216a7d90a04b4 Mon Sep 17 00:00:00 2001 From: "Michael J. Spencer" Date: Tue, 15 Jan 2013 02:00:59 +0000 Subject: [PATCH] [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 +++++++++++++++++++++++++++++++++++++++++++++++ lld/docs/design.rst | 14 ------ lld/docs/development.rst | 7 +++ 3 files changed, 115 insertions(+), 14 deletions(-) create mode 100644 lld/docs/Driver.rst diff --git a/lld/docs/Driver.rst b/lld/docs/Driver.rst new file mode 100644 index 0000000..9f946ae --- /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. diff --git a/lld/docs/design.rst b/lld/docs/design.rst index 6a8d0ff..5ab746e 100644 --- a/lld/docs/design.rst +++ b/lld/docs/design.rst @@ -468,17 +468,3 @@ scan all atoms looking for any Objective-C data structures. This could be done if the lld::File object had an attribute that said if the file had any Objective-C data in it. The Resolving phase would then be required to "merge" that attribute as object files are added. - - -Command Line Processing -~~~~~~~~~~~~~~~~~~~~~~~ - -Eventually, we may want this linker to be able to be a drop in replacement -linker for existing linker tools. That means being able to handle command line -arguments for different platforms (e.g. darwin or linux). Currently, there is -no command line processing code in lld. If clang winds up incorporating the lld -libraries into the clang binary, lld may be able to punt this work because clang -will be responsible for setting up the state for lld. - - - diff --git a/lld/docs/development.rst b/lld/docs/development.rst index bfa50d8..16d9b85 100644 --- a/lld/docs/development.rst +++ b/lld/docs/development.rst @@ -11,6 +11,12 @@ Creating a Reader See the :ref:`Creating a Reader ` guide. +Modifying the Driver +-------------------- + +See :doc:`Driver`. + + Documentation ------------- @@ -24,3 +30,4 @@ information on writing documentation for the project, see the :hidden: Readers + Driver -- 2.7.4