Move overview, building, and first-mutator into 'basics'

docs/basics/first_mutator.rst

@@ -0,0 +1,121 @@
+
+==================
+Your First Mutator
+==================
+
+In this section, we describe the steps needed to compile your mutator
+and mutatee programs and to run them. First we give you an overview of
+the major steps and then we explain each one in detail.
+
+Overview of Major Steps
+-----------------------
+
+To use Dyninst, you have to:
+
+(1) *Build and install DyninstAP:* DyninstAPI can be installed a package
+    system such as Spack or can be compiled from source. Our github
+    webpage contains detailed instructions for installing Dyninst:
+    https://github.com/dyninst/dyninst.
+
+(2) *Create a mutator program (Section 6.2):* You need to create a
+    program that will modify some other program. For an example, see the
+    mutator shown in Appendix A.
+
+(3) *Set up the mutatee (Section 6.3):* On some platforms, you need to
+    link your application with Dyninst’s run time instrumentation
+    library. [**NOTE**: This step is only needed in the current release
+    of the API. Future releases will eliminate this restriction.]
+
+(4) *Run the mutator (Section 6.4):* The mutator will either create a
+    new process or attach to an existing one (depending on the whether
+    createProcess or attachProcess is used).
+
+Sections 6.2 through 6.4 explain these steps in more detail.
+
+Creating a Mutator Program
+--------------------------
+
+The first step in using Dyninst is to create a mutator program. The
+mutator program specifies the mutatee (either by naming an executable to
+start or by supplying a process ID for an existing process). In
+addition, your mutator will include the calls to the API library to
+modify the mutatee. For the rest of this section, we assume that the
+mutator is the sample program given in Appendix A - Complete Examples.
+
+The following fragment of a Makefile shows how to link your mutator
+program with the Dyninst library on most platforms:
+
+.. code-block:: make
+
+   
+   # DYNINST_INCLUDE and DYNINST_LIB should be set to locations
+   # where Dyninst header and library files were installed, respectively
+
+   retee.o: retee.c
+      $(CC) -c $(CFLAGS) -I$(DYNINST_INCLUDE) retee.c –std=c++11x
+   
+   retee: retee.o
+      $(CC) retee.o -L$(DYNINST_LIB) -ldyninstAPI -o retee –std=c++11x
+
+On Linux, the options -lelf and -ldw may be required at the link step.
+You will also need to make sure that the LD_LIBRARY_PATH environment
+variable includes the directory that contains the Dyninst shared
+library.
+
+Since Dyninst uses the C++11x standard, you will also need to enable
+this option for your compiler. For GCC versions 4.3 and later, this is
+done by specifying -std=c++0x. For GCC versions 4.7 and later, this is
+done by specifying -std=c++11. Some of these libraries, such as libdwarf
+and libelf, may not be standard on various platforms. Check the README
+file in dyninst/dyninstAPI for more information on where to find these
+libraries.
+
+Under Windows NT, the mutator also needs to be linked with the dbghelp
+library, which is included in the Microsoft Platform SDK. Below is a
+fragment from a Makefile for Windows NT:
+
+.. code-block:: make
+
+   
+   # DYNINST_INCLUDE and DYNINST_LIB should be set to locations
+   # where Dyninst header and library files were installed, respectively
+
+   CC = cl
+   retee.obj: retee.c
+      $(CC) -c $(CFLAGS) -I$(DYNINST_INCLUDE)/h
+
+   retee.exe: retee.obj
+      link -out:retee.exe retee.obj $(DYNINST_LIB)\libdyninstAPI.lib dbghelp.lib
+
+Setting Up the Application Program (mutatee)
+--------------------------------------------
+
+On most platforms, any additional code that your mutator might need to
+call in the mutatee (for example files containing instrumentation
+functions that were too complex to write directly using the API) can be
+put into a dynamically loaded shared library, which your mutator program
+can load into the mutatee at runtime using the loadLibrary member
+function of BPatch_process.
+
+To locate the runtime library that Dyninst needs to load into your
+program, an additional environment variable must be set. The variable
+DYNINSTAPI_RT_LIB should be set to the full pathname of the run time
+instrumentation library, which should be:
+
+.. note::
+
+   DYNINST_LIB should be set to the location where Dyninst library files were installed
+
+   | ``$(DYNINST_LIB)/libdyninstAPI_RT.so`` (UNIX)
+   | ``%DYNINST_LIB/libdyninstAPI_RT.dll`` (Windows)
+
+Running the Mutator
+-------------------
+
+At this point, you should be ready to run your application program with
+your mutator. For example, to start the sample program shown in Appendix
+A - Complete Examples:
+
+.. code-block:: bash
+
+   $ retee foo <pid>

docs/basics/overview.rst

@@ -0,0 +1,33 @@
+
+========
+Overview
+========
+
+The normal cycle of developing a program is to edit the source code,
+compile it, and then execute the resulting binary. However, sometimes
+this cycle can be too restrictive. We may wish to change the program
+while it is executing or after it has been linked, thus avoiding the
+process of re-compiling, re-linking, or even re-executing the program to
+change the binary. At first, this may seem like a bizarre goal, however,
+there are several practical reasons why we may wish to have such a
+system. For example, if we are measuring the performance of a program
+and discover a performance problem, it might be necessary to insert
+additional instrumentation into the program to understand the problem.
+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,
+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
+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].

docs/basics/using.rst

@@ -0,0 +1,8 @@
+
+=================
+Importing Dyninst
+=================
+
+How to import Dyninst as a CMake project.
+
+Lorem ipsum.

docs/index.rst

@@ -45,3 +45,14 @@ Developed by
 |     Computer Science Department
 |     University of Maryland
 |     College Park, MD 20742
+
+.. toctree::
+   :caption: getting started
+   :name: basics
+   :hidden:
+   :maxdepth: 1
+
+   basics/overview
+   basics/building
+   basics/using
+   basics/first_mutator