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