Initial support for FreeBSD.
[dyninst.git] / dyninstAPI / README
1
2 This is the version 6.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 dyninst/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 dyninst 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 dyninst  
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-2009 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 By your use of Paradyn, you understand and agree that we (or any
97 other person or entity with proprietary rights in Paradyn) are
98 under no obligation to provide either maintenance services,
99 update services, notices of latent defects, or correction of
100 defects for Paradyn.
101
102 This library is free software; you can redistribute it and/or
103 modify it under the terms of the GNU Lesser General Public
104 License as published by the Free Software Foundation; either
105 version 2.1 of the License, or (at your option) any later version.
106
107 This library is distributed in the hope that it will be useful,
108 but WITHOUT ANY WARRANTY; without even the implied warranty of
109 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
110 Lesser General Public License for more details.
111
112 You should have received a copy of the GNU Lesser General Public
113 License along with this library; if not, write to the Free Software
114 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
115