Move 'first mutator' into overview

docs/basics/overview.rst

@@ -1,7 +1,7 @@
+.. _`sec-basic-using-dyninst`:
 
-========
-Overview
-========
+Using Dyninst
+#############
 
 The normal cycle of developing a program is to edit the source code,
 compile it, and then execute the resulting binary. However, sometimes
@@ -17,17 +17,80 @@ Another application is performance steering; for large simulations,
 computational scientists often find it advantageous to be able to make
 modifications to the code and data while the simulation is executing.
 
-This document describes an Application Program Interface (API) to permit
-the insertion of code into a computer application that is either running
-or on disk. The API for inserting code into a running application,
+Inserting code into a running application,
 called dynamic instrumentation, shares much of the same structure as the
 API for inserting code into an executable file or library, known as
-static instrumentation. The API also permits changing or removing
+static instrumentation. The Dyninst toolkits also permit changing or removing
 subroutine calls from the application program. Binary code changes are
 useful to support a variety of applications including debugging,
 performance monitoring, and to support composing applications out of
-existing packages. The goal of this API is to provide a machine
-independent interface to permit the creation of tools and applications
-that use runtime and static code patching. The API and a simple test
-application are described in [1]. This API is based on the idea of
-dynamic instrumentation described in [3].
+existing packages. The goal of Dyninst is to provide a machine-independent
+interface to permit the creation of tools and applications
+that use runtime and static code patching.
+
+
+Abstractions
+************
+
+Mutator
+  An application written by the user that utilizes Dyninst's API to read,
+  analyze, and/or manipulate a binary.
+
+Mutatee
+  The binary file analyzed by the mutator.
+
+
+Creating a Mutator Program
+**************************
+
+An example of basic usage is printing symbols names from a mutatee. The code below shows one
+possible way of doing this using :ref:`sec:parseapi-intro`.
+
+.. rli:: https://raw.githubusercontent.com/dyninst/examples/master/symtabAPI/printSymbols.cpp
+  :language: cpp
+  :linenos:
+
+This mutator can be compiled using the CMakeLists.txt
+
+.. code:: CMake
+
+  find_package(Dyninst 13.0.0 REQUIRED COMPONENTS parseAPI)
+
+  add_executable(printSymbols printSymbols.cpp)
+
+  target_link_libraries(printSymbols PRIVATE Dyninst::parseAPI)
+
+.. code:: shell
+
+  $ cmake /path/to/printSymbols -DDyninst_DIR=/path/to/Dyninst/lib/cmake/Dyninst
+  $ cmake --build .
+
+See :ref:`sec-importing` for details on building your application using Dyninst.
+
+Running a Mutator Program
+*************************
+
+Before executing a mutator, the Dyninst libraries need to be in the ``LD_LIBRARY_PATH`` and
+``DYNINSTAPI_RT_LIB`` needs to contain the path to ``libdyninstAPI_RT.so``.
+
+Assuming a simple mutatee program in `test.cpp`
+
+.. code:: cpp
+
+  int bar=3;
+
+built as a shared library (assuming a Linux environment)
+
+.. code:: shell
+
+  $ g++ -o libtest.so -fPIC -shared test.cpp
+
+can be consumed by the mutator program from above using
+
+.. code:: shell
+
+  $ export LD_LIBRARY_PATH=/path/to/Dyninst/lib:$LD_LIBRARY_PATH
+  $ export DYNINSTAPI_RT_LIB=/path/to/Dyninst/lib/libdyninstAPI_RT.so
+  $ ./printSymbols libtest.so
+
+More code examples can be found in :ref:`sec-examples`.

docs/examples/index.rst

@@ -1,3 +1,5 @@
+.. _`sec-examples`:
+
 Examples
 ########
 

docs/index.rst

@@ -99,7 +99,6 @@ Developed by
    basics/overview
    basics/building
    basics/using
-   basics/first_mutator
    examples/index
 
 .. toctree::