This repository was archived by the owner on Apr 4, 2025. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathREADME
159 lines (123 loc) · 5.89 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
=====================
HPCToolkit Externals
=====================
$Id$
HPCToolkit has many prerequisites. Some, like libelf and libxml2 are
commonly found on Linux systems, but not always. Others, like Open
Analysis and SymtabAPI are almost never available. And then there's
binutils. HPCToolkit uses a heavily-patched and incompatible version
of binutils, so the only place you'll find it is in a Rice subversion
repository.
The externals tree is an attempt to deal with these prerequisites. It
scans your system to identify which packages are available and
attempts to build the ones that are missing. It is still a work in
progress.
=================================
Getting HPCToolkit and Externals
=================================
The HPCToolkit home page is at:
http://hpctoolkit.org/
HPCToolkit is currently hosted as project 'HPCToolkit' on GitHub.
https://github.com/hpctoolkit
The HPCToolkit source files come in two trees: one for HPCToolkit
proper and one for all of its prerequisites. Both are available from
GitHub via git clone. The normal usage is to clone both trees in
side-by-side directories.
git clone https://github.com/hpctoolkit/hpctoolkit-externals
git clone https://github.com/hpctoolkit/hpctoolkit
The email address for HPCToolkit and Externals questions and bug
reports is: hpctoolkit-forum at rice.edu.
===================
Building Externals
===================
Building HPCToolkit is done in two phases: first build all necessary
prerequisite packages (externals), and then build HPCToolkit. The
idea is to build the externals tree once, and then work solely in the
HPCToolkit tree. Technically, the externals tree is not necessary to
build HPCToolkit, but then you would need to build all of HPCToolkit's
prerequisites manually.
Normally, externals does not require any special options, just let
configure decide what packages need to be built (usually most or all),
build them and then clean up the tree.
cd externals
./configure
make all
make distclean
This build creates a staging area in a subdirectory named after the
host cpu and os. The staging area is a development directory, that
is, it contains the full installation of each package, including the
header files needed to compile other programs. This is the directory
HPCToolkit uses to build itself, so it is important to finish the
externals build before configuring HPCToolkit.
Note: it is possible, but unnecessary, to use the --prefix=PATH option
for configure. The externals's install directory (prefix) is only a
staging area, used as a build dependency for HPCToolkit and is not the
same as HPCToolkit's prefix.
Note: the externals tree is designed to be a one-time build step.
After building the external packages, then its tree can be cleaned up
(with make distclean) and HPCToolkit can be configured and built
several times with the same externals tree. That is, reconfiguring or
rebuilding HPCToolkit does not require rebuilding the externals tree.
====================
Building HPCToolkit
====================
After building the externals tree, return to the HPCToolkit directory
and configure and build HPCToolkit.
cd hpctoolkit
./configure --prefix=PATH \
--with-externals=PATH \
--with-papi=PATH
make
make install
Prefix is the install prefix, externals is the path to the root of the
externals tree, and papi is the path to a PAPI installation. The
prefix and PAPI paths, if used, should be absolute, the externals path
may be absolute or relative (relative to the directory in which
configure is run).
PAPI is optional and highly recommended, if available. Technically,
externals is optional, but if externals is not used, then you will
need to add all of HPCToolkit's prerequisites as configure options.
Note: HPCToolkit uses Autoconf and Automake, so it supports the
standard Autoconf options, the standard Automake targets and vpath
builds (separate build and source trees).
==================
Configure Options
==================
Although the normal usage is to have externals build all of the
prerequisite packages itself, it is also possible to build any of them
separately or use an existing installation. The following configure
options may be used to specify an alternate installation for these
packages.
--with-binutils=PATH path to binutils install directory
--with-libdwarf=PATH path to libdwarf install directory
--with-libelf=PATH path to libelf install directory
--with-libmonitor=PATH path to libmonitor install directory
--with-libunwind=PATH path to libunwind install directory
--with-libxml2=PATH path to libxml2 install directory
--with-old-monitor=PATH path to old monitor install directory
--with-open-analysis=PATH path to open analysis install directory
--with-symtabAPI=PATH path to symtabAPI install directory
--with-xed2=PATH path to xed2 install directory
--with-xerces=PATH path to xerces/c install directory
The default for all of these options is to have externals build the
package itself, depending on platform. In practice, none of these
options is necessary.
These same options, with the same names, may be used with either
externals's or HPCToolkit's configure, except that old-monitor in
externals is just called monitor in HPCToolkit.
Note: libunwind is only used on ia64 and xed2 is only used on x86 and
x86-64.
=================
What About PAPI?
=================
PAPI, the Performance API, provides access to the hardware performance
counters. HPCToolkit can run without PAPI, but then it is limited to
sampling via itimer. PAPI is available at:
http://icl.cs.utk.edu/papi/
Although PAPI is a recommended package for HPCToolkit, it is not
included in the externals tree. PAPI requires a kernel patch
(perfmon2 or perfctr) and if that patch is not already installed, then
it is not possible to fix that in user land.
=============
Known Issues
=============