[llvm-commits] [lld] r172502 - in /lld/trunk/docs: Driver.rst design.rst development.rst

[Michael J. Spencer]

Author: mspencer
Date: Mon Jan 14 20:00:59 2013
New Revision: 172502

URL: http://llvm.org/viewvc/llvm-project?rev=172502&view=rev
Log:
[docs] Add driver documentation.

This gives an overview of the driver and explains how to add options and driver flavors.

Added:
    lld/trunk/docs/Driver.rst
Modified:
    lld/trunk/docs/design.rst
    lld/trunk/docs/development.rst

Added: lld/trunk/docs/Driver.rst
URL: http://llvm.org/viewvc/llvm-project/lld/trunk/docs/Driver.rst?rev=172502&view=auto
==============================================================================
--- lld/trunk/docs/Driver.rst (added)
+++ lld/trunk/docs/Driver.rst Mon Jan 14 20:00:59 2013
@@ -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 <llvm-triple>`` 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.

Modified: lld/trunk/docs/design.rst
URL: http://llvm.org/viewvc/llvm-project/lld/trunk/docs/design.rst?rev=172502&r1=172501&r2=172502&view=diff
==============================================================================
--- lld/trunk/docs/design.rst (original)
+++ lld/trunk/docs/design.rst Mon Jan 14 20:00:59 2013
@@ -468,17 +468,3 @@
 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.
-
-
-

Modified: lld/trunk/docs/development.rst
URL: http://llvm.org/viewvc/llvm-project/lld/trunk/docs/development.rst?rev=172502&r1=172501&r2=172502&view=diff
==============================================================================
--- lld/trunk/docs/development.rst (original)
+++ lld/trunk/docs/development.rst Mon Jan 14 20:00:59 2013
@@ -11,6 +11,12 @@
 See the :ref:`Creating a Reader <Readers>` guide.
 
 
+Modifying the Driver
+--------------------
+
+See :doc:`Driver`.
+
+
 
 Documentation
 -------------
@@ -24,3 +30,4 @@
    :hidden:
 
    Readers
+   Driver