Personal tools
You are here: Home → Software → HPCToolkit → Downloads → docs → building.html
Navigation
 
Document Actions

building.html

by admin — last modified 2007-12-11 00:32

Click here to get the file

Size 18.0 kB - File type text/html

File contents

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<!--
  HPCToolkit Documentation: Editing within Netscape/Mozilla Composer
  is possible, but it generates strange stuff in-line.  
  Please use an ordinary text editor.
-->

<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

  <title>HPCToolkit: Downloading, Building and Testing</title>

  <link rel='stylesheet' type='text/css' href='styleForAll.css'>
</head>

<body>

<!-- ********************************************************************** -->

<script language="JavaScript" src="header_hpctools.js"></script>

<!-- ********************************************************************** -->

<div id="main">

<!-- automatically updated by Emacs hook below; nicer than CVS Date -->
<p class="lastupdated">Last Updated: 2004-03-10</p>

<a name="toc"></a>
<h2>Downloading, Building and Installing HPCToolkit</h2>

<h2>Contents</h2>
<ul>
  <li><a href="#sources">Downloading the Sources</a>

  <li><a href="#prerequisites">System Prerequisites</a>

  <li>Building and Installing
  <ul>
    <li><a href="#build_overview">Build Overview</a>
    <li><a href="#build_xlib_binutils">External Library: GNU binutils</a>
    <li><a href="#build_xlib_xercesc">External Library: Xerces-C++</a>
    <li><a href="#build_xlib_oa">External Library: OpenAnalysis</a>
    <li><a href="#build_hpctoolkit">HPCToolkit</a>
    <li><a href="#build_hpcviewer">hpcviewer</a>
    <li><a href="#build_evaluation">Evaluation</a>
  </ul>

  <li>Using
  <ul>
    <li><a href="#use_hpctoolkit">HPCToolkit</a>
    <li><a href="#use_hpcviewer">hpcviewer</a>
  </ul>

  <li><a href="#build_troubleshooting">Build Troubleshooting</a>
  
</ul>

<!-- ********************************************************************** -->
<!-- ********************************************************************** -->

<a name="sources"></a>

<h2>Downloading the Sources</h2>
<p><i>[<a href="#toc">Contents</a>]</i>

<p>To reduce the effort needed to distribute HPCToolkit, we have opted
to distribute it in source form only. Source files for the toolkit and
external libraries it requires are distributed via anonymous CVS
checkout.

<ol class="noindent">
<li>
<p>To retrieve the source files from CVS, you will need to download 
<code><a href="http://hipersoft.cs.rice.edu/cvs/hipersoft-anonssh">hipersoft-anonssh</a></code>, 
a ssh script that contains a key that will grant you read-only access
to the Hipersoft CVS repositories at Rice University.  Save this script in
<code>${HOME}/bin/hipersoft-anonssh</code>.

<li>
<p>Set up the required CVS environment variables to enable you to 
access the HPCToolkit repository.

<div class="indent">
  <i>(csh variants)</i><br>
  <code>setenv CVS_RSH ${HOME}/bin/hipersoft-anonssh</code><br>
  <code>setenv CVSROOT :ext:anoncvs@koolkat2.cs.rice.edu:/Volumes/cvsrep/developer</code><br>
<br>
  <i>(sh variants)</i><br>
  <code>export CVS_RSH=${HOME}/bin/hipersoft-anonssh</code><br>
  <code>export CVSROOT=:ext:anoncvs@koolkat2.cs.rice.edu:/Volumes/cvsrep/developer</code>
</div>

<li>
<p>Use CVS to check out the HPCToolkit sources using the command

<div class="indent">
  <code>cvs co HPCToolkit_all_source</code><br>
</div>

<br>
Please note - there are several HPCToolkit CVS modules. Please visit our
<a href="http://hipersoft.cs.rice.edu/cvs/#rice_repositories">CVS information pages</a> for a complete list of available modules. 

</ol>


<!-- ********************************************************************** -->
<!-- ********************************************************************** -->

<a name="prerequisites"></a>

<h2>System Prerequisites</h2>
<p><i>[<a href="#toc">Contents</a>]</i>

<ol class="noindent">

<li>
<p>HPCToolkit requires an ANSI/ISO C/C++ compliant compiler.
Generally speaking any relatively recent vendor compiler or GCC 3.x
should be fine.  The toolkit uses GNU binutils which requires a C
compiler that also supports a few GNU extensions; obviously, GCC may
be used.
    
<p>The list of compilers that we have successfully tested are listed
below.  (Special options or exceptions are noted in the build
instructions.):

  <ul class="noindent">
    <li>alpha-OSF1:
      <ul class="noindent">
        <li>Compaq C++/C 6.2, 6.3, 6.5
        <li>GCC C++/C 3.2.1
      </ul>

    <li>i686-Linux:
      <ul class="noindent">
        <li>GCC C++/C 3.0.4, 3.2.x, 3.3.x
      </ul>

    <li>ia64-Linux:
      <ul class="noindent">
        <li>Intel C++/C 8.0
        <li>Intel C++/C 7.0, 7.1
        <li>Intel C++/C 6.0
        <li>GCC C++/C 3.0.4, 3.2.x, 3.3.x
      </ul>

    <li>mips-IRIX64:
      <ul class="noindent">
        <li>SGI MIPSpro C++/C 7.3.x, 7.4
        <li>GCC C++/C 3.2.1
      </ul>

    <li>sparc-SunOS:
      <ul class="noindent">
        <li>Sun Forte C++/C 5.3 (WorkShop 6 update 2 with patch 111685-01
            or greater (bug id 4466915))
        <li>Sun Forte C++/C 5.1 (WorkShop 6)
        <li>GCC C++/C 3.0.4
      </ul>
  </ul>

<li>
<p>HPCToolkit requires a basic version of GNU make, not a vendor
supplied make.  We have successfully used:

  <ul class="noindent">
    <li>3.70 (alpha-OSF1, mips-IRIX64, sparc-SunOS)
    <li>3.76 (sparc-SunOS)
    <li>3.77 (alpha-OSF1)
    <li>3.78 (i686-Linux)
    <li>3.79 (alpha-OSF1, ia64-Linux, mips-IRIX64)
    <li>3.80 (alpha-OSF1)
  </ul>

<li>
<p>HPCToolkit contains some Perl-based tools which require that some
variant of Perl 5 installed and that it is in your path.  For the
record, we have succssfully used:

  <ul class="noindent">
    <li>5.004 (mips-IRIX64)
    <li>5.005 (alpha-OSF1, i686-Linux)
    <li>5.6.0 (alpha-OSF1, ia64-Linux)
    <li>5.6.1 (alpha-OSF1, ia64-Linux, sparc-SunOS)
  </ul>

<li>
<p>hpcviewer is a Java application that can be used on a variety of
platforms.  We have successfully used the following specific
configurations:

  <ul class="noindent">
    <li>Mac OS X: javac from JDK 1.4.2
    <li>ia64-Linux: using javac from jd2sdk1.4.2 
    <li>i686-Linux: using javac from jd2sdk1.4.2 
    <li>sparc-Solaris: using javac from JDK 1.4.0
    <li>alpha-Tru64: using javac from JDK 1.4.2
  </ul>

</ol>


<!-- ********************************************************************** -->
<!-- ********************************************************************** -->

<h2>Building and Installing</h2>
<p><i>[<a href="#toc">Contents</a>]</i>

<div class="indent">

<!-- ********************************************************************** -->

<a name="build_overview"></a>

<h2>Build Overview</h2>
<p><i>[<a href="#toc">Contents</a>]</i>


<p>There are three external libraries -- OpenAnalysis, Xerces-C++ and
GNU binutils -- that must be built before HPCToolkit can be built,
installed and used.  Please use the same C++ compiler for each
component.</p>

<p>HPCToolkit's hpcviewer tool is in a separate directory and built
separately. We often download, compile, and run hpcviewer on laptops
or desktops rather than the system on which we collect performance
measurements.  We briefly describe how to build hpcviewer here,
regardless of where you want to build it.</p>

<p>In some cases it may be possible to use versions of the external
libraries that may already be installed on your system.  However, we
do not support such configurations.</p>


<!-- ********************************************************************** -->

<a name="build_xlib_binutils"></a>

<h2>External Library: GNU binutils</h2>
<p><i>[<a href="#toc">Contents</a>]</i>


<h3>Notes</h3>

<p>Most of the C compilers listed in <a href="#prerequisites">System 
Prerequisites</a> can compile binutils.  Below is a list of exceptions or
special options.</p>

<ul>
  <li>GCC C 2.9x can also be used.
  <li>ia64-Linux:
    <ul class="noindent">
      <li>Intel C 6.x or 7.x <i>cannot</i> be used; use GCC C.
    </ul>
  <li>mips-IRIX64:
    <ul class="noindent">
      <li>SGI C <i>cannot</i> be used; use GCC C.
      <li>GCC C should be compiled with <code>-mabi=64</code>:
         <code>CFLAGS='-O -mabi=64'</code>.
    </ul>
</ul>


<h3>Building</h3>

<ol class="noindent">

<li>
<p>Change to the top-level binutils directory <code>binutils</code>.

<li>
<p>Configure, build and install.  Run make with the C compiler (CC)
and compilation options (CFLAGS).  Since this will produce a lot of
output, you may want to redirect it to a file.  For example:

<div class="indent">
  <code>gmake CC='gcc' CFLAGS='-O'</code><br>
</div>

<li>
<p>(Optional) Clean the build files.  

<div class="indent">
  <code>gmake clean</code><br>
</div>

<!--
The second command will remove unnecessary <i>installed</i> binutils
tools.
  <code>gmake minimize_install</code>
-->

</ol>


<!-- ********************************************************************** -->

<a name="build_xlib_xercesc"></a>

<h2>External Library: Xerces-C++</h2>
<p><i>[<a href="#toc">Contents</a>]</i>

<h3>Notes</h3>

<p>Below is a list of special options for compiling Xerces-C++.

<ul>
  <li>mips-IRIX64:
    <ul class="noindent">
      <li>SGI C++ should be compiled with <code>-64</code>:
         <code>CXXFLAGS='-64'</code>.
      <li>GCC C++ should be compiled with <code>-mabi=64</code>:
         <code>CXXFLAGS='-mabi=64'</code>.
    </ul>
</ul>


<h3>Building</h3>

<ol class="noindent">

<li>
<p>Change to the top-level Xerces-C++ directory <code>xercesc</code>.

<li>
<p>Configure, build and install.  Run make with the C++ and C compiler
(CXX and CC, respectively) and compilation options (CXXFLAGS).  Since
this will produce a lot of output, you may want to redirect it to a
file.  For example:

<div class="indent">
  <code>gmake CXX='g++' CC='gcc' CXXFLAGS=''</code><br>
</div>

<li>
<p>(Optional) Clean the build files.

<div class="indent">
  <code>gmake clean</code>
</div>

</ol>


<!-- ********************************************************************** -->

<a name="build_xlib_oa"></a>

<h2>External Library: OpenAnalysis</h2>
<p><i>[<a href="#toc">Contents</a>]</i>


<h3>Notes</h3>

<p>Below is a list of special options for compiling OpenAnalysis.

<ul>
  <li>mips-IRIX64:
    <ul class="noindent">
      <li>SGI C++ should be compiled with <code>-64</code>:
         <code>CXXFLAGS='-O -64'</code>.
      <li>GCC C++ should be compiled with <code>-mabi=64</code>:
         <code>CXXFLAGS='-O -mabi=64'</code>.
    </ul>
</ul>


<h3>Building</h3>

<ol class="noindent">

<li>
<p>Change to the top-level OpenAnalysis directory <code>OpenAnalysis</code>.

<li>
<p>Configure, build and install.  Run make with the C++ compiler (CXX)
and compilation options (CXXFLAGS).  Since this will produce a lot of
output, you may want to redirect it to a file.  For example:

<div class="indent">
  <code>gmake CXX='g++' CXXFLAGS='-O'</code><br>
</div>

<li>
<p>(Optional) Clean the build files.

<div class="indent">
  <code>gmake clean</code>
</div>

</ol>


<!-- ********************************************************************** -->

<a name="build_hpctoolkit"></a>

<h2>HPCToolkit</h2>
<p><i>[<a href="#toc">Contents</a>]</i>

<h3>Notes</h3>

<p>HPCToolkit can be built and installed using the typical Autoconf
sequence of commands (e.g. configure, make, make install).  The
instructions below use a wrapper which will do the right thing for the
typical user.

<h3>Building</h3>

<ol class="noindent">

<li>
<p>Change to the top-level HPCToolkit directory <code>HPCToolkit</code>.

<li>
<p>Configure, build and install.  Run make with the C++ compiler (CXX)
and C compiler (CC).  Since this will produce a lot of output, you may
want to redirect it to a file.  For example:

<div class="indent">
  <code>gmake -f Makefile.quick CXX='g++' CC='gcc'</code><br>
</div>

<p>After installation is complete, a message will be generated giving
the installation location.  By default, it is `HPCToolkit-[platform]'.

<li>
<p>(Optional) Clean the build files.

<div class="indent">
  <code>gmake -f Makefile.quick clean</code>
</div>

</ol>

<p>The HPCToolkit installation is compact and self-contained and may
be renamed or moved to another location.  All source code (including
external libraries) may be removed.  See 
<a href="#use_hpctoolkit">Using HPCToolkit</a> for instructions on using
the toolkit.

<!-- ********************************************************************** -->

<a name="build_hpcviewer"></a>

<h2>External tool: hpcviewer</h2>
<p><i>[<a href="#toc">Contents</a>]</i>


<h3>Notes</h3>

<p>These instructions are for Unix systems or for Cygwin-Windows.

<h3>Building</h3>

<ol class="noindent">

<li>
<p>Change to the top-level hpcviewer directory <code>hpcviewer</code>.

<li>
<p>Change to the build directory <code>build-unix</code> and initiate
the build with make.

<div class="indent">
  <code>cd build-unix</code><br>
  <code>make</code><br>
</div>

</ol>

<p>See <a href="#use_hpcviewer">Using hpcviewer</a> for instructions
on using the toolkit.

<!-- ********************************************************************** -->

<a name="build_evaluation"></a>

<h2>Evaluation</h2>
<p><i>[<a href="#toc">Contents</a>]</i>


<p>Yeah! If everything is built and installed, take a sip of your
favorite beverage and consider trying the toolkit out.

<!-- consider running the <a href="testing.html">tests</a>. -->

<p>Grrr! If everything fails miserably, take a sip of your favorite
beverage and send us some mail.  Also consult the 
<a href="#build_troubleshooting">Troubleshooting</a>
notes below.</p>

<!-- ********************************************************************** -->

</div>

<!-- end: Building -->

<!-- ********************************************************************** -->
<!-- ********************************************************************** -->


<h2>Using</h2>
<p><i>[<a href="#toc">Contents</a>]</i>

<div class="indent">

<!-- ********************************************************************** -->

<a name="use_hpctoolkit"></a>

<h2>HPCToolkit</h2>
<p><i>[<a href="#toc">Contents</a>]</i>

<p>To use the resulting installation, certain environment variables need
to be set.  To set these variables and to include a reference to the tools
in your PATH, source either
<a href="../Sourceme-csh"><code>Sourceme-csh</code></a> or 
<a href="../Sourceme-sh"><code>Sourceme-sh</code></a>. 
The former will setup your environment for <code>csh</code> variants;
the latter will do so for <code>sh</code> variants.  
Before sourcing these files, the HPCTOOLKIT environment
variable should be set to the root directory of the HPCToolkit 
installation.  For example:

<div class="indent">
  <i>(csh variants)</i><br>
  <code>setenv HPCTOOLKIT "/my_path/HPCToolkit"</code><br>
  <code>source $HPCTOOLKIT/Sourceme-csh</code>
<br><br>
  <i>(sh variants)</i><br>
  <code>export HPCTOOLKIT="/my_path/HPCToolkit"</code><br>
  <code>source $HPCTOOLKIT/Sourceme-sh</code>
</div>

<p>You may wish to add these commands to your shell initialization files.</p>


<!-- ********************************************************************** -->

<a name="use_hpcviewer"></a>

<h2>Using hpcviewer</h2>
<p><i>[<a href="#toc">Contents</a>]</i>

<p>On Unix, add the bin subdirectory of the hpcviewer directory to
your path. Run the <code>hpcviewer</code> command. When run with no
arguments, it will bring up a file chooser dialog to select the
performance database XML file. The pathname of the performance
database XML file can be specified as an argument to
<code>hpcviewer</code> to skip the file chooser dialog.

<p>On some systems with a GUI (e.g. Mac OS X), double clicking on the
HPCViewer.jar file icon can also be used to launch
<code>hpcviewer</code>.

<!-- ********************************************************************** -->

</div>

<!-- end: Using -->

<!-- ********************************************************************** -->
<!-- ********************************************************************** -->

<a name="build_troubleshooting"></a>

<h2>Troubleshooting</h2>
<p><i>[<a href="#toc">Contents</a>]</i>


<ol class="noindent">

<li>
<p>GNU binutils will not build.  For addition information go to the
binutils <a href="http://sources.redhat.com/binutils">website</a>.</p>

<!-- http://www.gnu.org/software/binutils/ -->


<li>
<p>When compiling OpenAnalysis with GCC 3.0.4 and <code>-0</code>, there is a
compilation error similar to:</p>

<div class="indent">
  <pre>DomTree.C:73: Internal compiler error in expand_end_loop, at stmt.c:2527</pre>
</div>

<p>OpenAnalysis exposes a bug in the GCC 3.0.4 optimizer.  Turn off
optimization and recompile.</p>


<li>
<p>When linking HPCToolkit, there is an error message similar to:

<div class="indent">
  <pre>undefined reference to `__udivsi3'</pre>
</div>

<p>Most likely you compiled GNU binutils with GCC and are compiling
HPCToolkit with a non-GCC compiler.  Unfortunately, sometimes the GNU
binutils libraries are not fully self-contained, and lack some symbols
that are defined in <code>libgcc.a</code> or <code>libgcc_s.so</code>
(depending on which compiler version you have).  

<p>There are two solutions to this problem.  First, you can compile
HPCToolkit with GCC and the appropriate library will be automatically
provided during the linking stage.  Secondly, you can continue
compiling with a non-GCC compiler while adding the appropriate library
to the link line.  To do this, first determine which library your
version of GCC uses.  Then, open the file
<code>${HPCTOOLKIT}/src/Makeinclude.config.${HPCTOOLKIT_PLATFORM}</code>
in an editor and modify the <code>USER_C_LDFLAGS</code> variable.  For
example, the lines below would add <code>libgcc.a</code> or
<code>libgcc_s.so</code>, respectively, to the link:

<div class="indent">
  <code>USER_C_LDFLAGS = /gcc_lib_path/libgcc.a</code><br>
  <code>USER_C_LDFLAGS = /gcc_lib_path/libgcc_s.so</code>
</div>

</ol>


<!-- ********************************************************************** -->
<!-- ********************************************************************** -->

<script language="JavaScript" src="footer_hpctools.js"></script>

<!-- ********************************************************************** -->

</div> <!-- id=main -->

</body>
</html>


<!-- Local Variables: -->
<!-- eval: (add-hook 'write-file-hooks 'time-stamp) -->
<!-- time-stamp-start: ">Last Updated: " -->
<!-- time-stamp-format: "%:y-%02m-%02d" -->
<!-- time-stamp-end: "<" -->
<!-- time-stamp-line-limit: 35 -->
<!-- End: -->
« September 2010 »
Su Mo Tu We Th Fr Sa
1234
567891011
12131415161718
19202122232425
2627282930
 
Powered by Plone

LACSI Collaborators include:

Rice University LANL UH UNM UIUC UNC UTK