Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Shell M4 Makefile SourcePawn
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
===================== 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 =============