Adding BPatch_dependenceGraphNode and -Edge to represent graphs used in slicing
[dyninst.git] / dyninstAPI / README
1
2 This is the version 5.0 release of the Dyninst API.  Currently, the API
3 library is available for the Sparc/Solaris, POWER/AIX, x86/Linux,
4 x86/Windows XP/2000/2003, Alpha/Tru64 Unix, ia64/Linux, and x86_64/Linux 
5 platforms.
6
7 Documentation for the API can be found at:
8
9     http://www.dyninst.org/
10
11 The core/dyninstAPI/tests directory contains the source code for programs
12 that test the API functions.  These programs are useful as examples of how
13 to use the API.  See the README file in that directory for how to run or
14 rebuild them.
15
16 Setting up the environment
17 --------------------------
18
19 Before compiling or using the Dyninst API library, you should set the
20 environment variables PLATFORM and DYNINST_ROOT.  PLATFORM should be set to
21 one of the following values depending upon what operating system you are
22 running on:
23
24     alpha-dec-osf5.1            Tru64 Unix on the Alpha processor
25     i386-unknown-linux2.4       Linux 2.4/2.6 on an Intel x86 processor
26     i386-unknown-nt4.0          Windows XP/2000/2003 on an Intel x86 processor
27     ia64-unknown-linux2.4       Linux 2.4/2.6 on an IA-64 processor
28     rs6000-ibm-aix5.1           AIX Version 5.1
29     sparc-sun-solaris2.9        Solaris 2.9 on a SPARC processor
30     x86_64-unknown-linux2.4     Linux 2.4/2.6 on an AMD-64 processor
31
32 DYNINST_ROOT should be set to the pathname of the top of the library
33 directory tree (dyninstAPI-v5.0).
34
35 DYNINSTAPI_RT_LIB should be set to the full pathname of the file
36 libdyninstAPI_RT.so.1 (on Windows, libdyninstAPI_RT.dll).  If you have
37 correctly set the DYNINST_ROOT and PLATFORM environment variables, then the
38 proper pathname is:
39
40     $DYNINST_ROOT/$PLATFORM/lib/libdyninstAPI_RT.so.1 (UNIX)
41     %DYNINST_ROOT%/i386-unknown-nt4.0/lib/libdyninstAPI_RT.dll (Windows)
42
43 On Unix-based systems, you will also need to add $DYNINST_ROOT/$PLATFORM/lib
44 to your LD_LIBRARY_PATH environment variable (LIBPATH on AIX,
45 LD_LIBRARY64_PATH on Irix).  On Windows, you will instead need to add
46 %DYNINST_ROOT%/i386-unknown-nt4.0/lib to your PATH environment variable.  
47 This is so that mutator applications can be linked dynamically with the
48 Dyninst library.
49
50 Notes on Using Dyninst with Linux
51 ---------------------------------
52
53 On Linux, Dyninst requires some libraries that are not installed by default
54 in most distributions.  The first is libelf, which is included with most
55 distributions and can be installed using the distribution's package manager.
56 The second is libdwarf.  You can get the latest source code distribution
57 of libdwarf from http://reality.sgiweb.org/davea/.  RPM files for libdwarf
58 are also available from various sites.  Lastly, for IA-64, libunwind must
59 be installed, which can be found at 
60 http://www.hpl.hp.com/research/linux/libunwind/.
61
62 Building the Dyninst API from source
63 ------------------------------------
64
65 If you downloaded the source distribution of this package, you can build the
66 Dyninst API libraries by running "make" in the core directory (one level up
67 from where this README file is located), assuming your environment is set up
68 as described above.  On Unix platforms, you must use GNU make.  The top-level
69 makefile contains directives for compiling the Paradyn parallel performance
70 tool, from which the Dyninst API was derived.  If you have downloaded only the
71 Dyninst API, you will see a number of messages about missing directories.
72 These directories are needed only for making Paradyn, so you should ignore
73 these messages.  If you downloaded the entire Paradyn distribution, you can
74 make only the API libraries by running "make DyninstAPI" in the core
75 directory.
76
77 -----------------------------------------------------------------------------
78
79 This software is derived from the Paradyn system and therefore subject to
80 the same copyright.  A copy of the Paradyn copyright appears at the end of
81 this file.
82
83         The Dyninst API Team
84         6/23/2006
85
86 ----------------------- Start of Paradyn Copyright --------------------------
87 Copyright (c) 1996 Barton P. Miller
88
89 We provide the Paradyn Parallel Performance Tools (below
90 described as "Paradyn") on an AS IS basis, and do not warrant its
91 validity or performance.  We reserve the right to update, modify,
92 or discontinue this software at any time.  We shall have no
93 obligation to supply such updates or modifications or any other
94 form of support to you.
95
96 This license is for research uses.  For such uses, there is no
97 charge. We define "research use" to mean you may freely use it
98 inside your organization for whatever purposes you see fit. But you
99 may not re-distribute Paradyn or parts of Paradyn, in any form
100 source or binary (including derivatives), electronic or otherwise,
101 to any other organization or entity without our permission.
102
103 (for other uses, please contact us at paradyn@cs.wisc.edu)
104
105 All warranties, including without limitation, any warranty of
106 merchantability or fitness for a particular purpose, are hereby
107 excluded.
108
109 By your use of Paradyn, you understand and agree that we (or any
110 other person or entity with proprietary rights in Paradyn) are
111 under no obligation to provide either maintenance services,
112 update services, notices of latent defects, or correction of
113 defects for Paradyn.
114
115 Even if advised of the possibility of such damages, under no
116 circumstances shall we (or any other person or entity with
117 proprietary rights in the software licensed hereunder) be liable
118 to you or any third party for direct, indirect, or consequential
119 damages of any character regardless of type of action, including,
120 without limitation, loss of profits, loss of use, loss of good
121 will, or computer failure or malfunction.  You agree to indemnify
122 us (and any other person or entity with proprietary rights in the
123 software licensed hereunder) for any and all liability it may
124 incur to third parties resulting from your use of Paradyn.
125