**********************************************************
*   C o d e A n a l y s t  2.8 U1  I N S T A L L A T I O N  *
**********************************************************
Revision	: 2.8 U1
Last Update	: 6/3/2009


*********************
* Table Of Contents *
*********************

  * Source Build and Installation

	[ Required Packages ]

	[ Linux Distributions Special Notes ]

	[ CAInstaller.sh ]

	[ To Manual build/install CodeAnalyst ]
	
	[ For Java profiling ]

   	[ Building the CodeAnalyst Kernel Module ] 
	Required for Barcelona family (family10h) !!!

	[ Adding Non-root Users ]

	[ Build CodeAnalyst-Modified Oprofile Only ]

	[ Commonly Used CodeAnalyst Configurations ]

  * Trouble Shooting

  * Support and Bug Report


-----------------------------------------------------------------------------------------

*********************************
* Source Build and Installation *
*********************************

[ Required Packages ]

Building CodeAnalyst from sources requires the following packages be 
installed in addition to the above. Make sure that these required 
packages are installed before proceeding.

    autoconf
    automake 
    libtool
    gcc-4.1+
    g++-4.1+
    m4
    make
    popt-devel-1.7+
    binutils-devel   (Might be part of binutils package on some Linux distributions.)
    kernel-source    (Might be required on certain Linux distribution to build CAKM)
    elfutils-devel or elf-utils-devel 
                     (should contains gelf.h, libelf-xxxx.so, and libelf.a)
    qt-devel or qt3-devel-3.3.5+ 
                     (Might need to re-login to refresh the environment variables 
                      set by this package.)


----------------------------------------

[ Linux Distributions Special Notes ]

SLES11:
	* All development packages (devel) are located in the SDK DVD.

	* Failed to compile 32-bit application even when 32-bit envronment
	  already installed.

RHEL4 UX:
	* If 64-bit JVMTI fails to build on 64-bit RHEL4 system, please try create a 
	  softlink as shown below.  This helps resolve the issue of the libbfd.a was 
	  not build with -fPIC on these Linux distributions.
	  
		ln -s /usr/lib64/libbfd-xxxx.so.x.x /usr/lib64/libbfd.so
	
	* 32-bit binutils package does not exist.

Ubuntu:
	As root user:

	1. Run "apt-get update"

	2. To build CodeAnalyst GUI, run: 

		apt-get install qt3-dev-tools binutils-dev g++ libpopt-dev \
				libtool autoconf automake make libelfg0-dev \
				konqueror

	3. To build CAKM, run (as on Ubuntu-8.10 server): 

		apt-get install linux-headers-2.6.27-7-server
		ln -s /usr/src/linux-headers-2.6.27-7-server /usr/src/linux-2.6.27-7-server

	4. Follow steps as described for SuSE and Red Hat above.

	NOTE: Please use specify configure options "--with-qt-includes=/usr/include/qt3"



----------------------------------------

[ CAInstaller.sh ]

CodeAnalyst provides an installer script which automatically configures, builds,
and installs CodeAnalyst, CAKM, and CA-JVMTI based-on the user inputs to a set 
of questions.


----------------------------------------

[ To Manual build/install CodeAnalyst ]


NOTE: Please make sure to uninstall the prior version of CodeAnalyst
      before performing the following steps.

As root user:

1. Go to CodeAnalyst directory. Run "./autogen.sh"

2. Run "./configure", please see "./configure --help" for configuration
   options fine tuning the installation.

3. Run "make" to build CodeAnalyst.

4. Run "make install" to install CodeAnalyst. The default installation
   of CodeAnalyst is "/opt/CodeAnalyst/bin". The installation path 
   can be changed by specifying flag "--prefix=<path>" to the
   configure script in step 2.

5. By default, CodeAnalyst and utilities are installed in 

	/opt/CodeAnalyst/bin/ 

   and the libraries are installed in 

	/opt/CodeAnalyst/lib 
   or 
	/opt/CodeAnalyst/lib64 

6. Please make sure the "/opt/CodeAnalyst/bin/" and "opt/CodeAnalyst/sbin/" directories 
   are in the PATH environment variable.

7. Please make sure that the library path is either included in the 
   "/etc/ld.so.conf" (which will require to run ldconfig) 
   or LD_LIBRARY_PATH environment variable.


-----------------------------------------

[ For Java profiling ]

1. In the source tree, go to "jpa/jvmpi" or "jpa/jvmti" directory depending 
   on the interface you wish to use.

2. Run "./autogen.sh"

3. Run "./configure --with-java=<Java JDK Path>"

3. Run "make" to build CodaAnalyst Java profiling agent.

4. Run "make install" to install the profiling agent.

5. CodeAnalyst will install "libCAJVMPIA.so" or "libCAJVMTIA.so" in the
   "/opt/CodeAnalyst/bin/" and create a softlink in "/opt/CodeAnalyst/lib/" directory. 

NOTE:
In case CodeAnalyst was configured with "--prefix" option,
please run JVMTI or JVMPI configure script as following.

  ./configure --prefix=<prefix dir> --with-java=<java dir> LDFLAGS=-L<prefix dir>/lib/


-----------------------------------------

[ Building the CodeAnalyst Kernel Module ]
!!! Required for Barcelona (family10h) !!!

In this release, CodeAnalyst includes supports for Barcelona family 
(family10h) by providing standalone kernel driver.  This is a modified 
OProfile driver which will replace the stock one that comes with the 
Linux distribution.

1. Goto directory "src/cakm/"

2. To install CodeAnalyst Kernel Module, please run "mod_install.sh".
   This script will determine the version of pre-built kernel module 
   to be installed based on the running kernel version. If the pre-built 
   kernel module is not available, it will prompt users, and try to build 
   the kernel module from source. 

3. To uninstall CodeAnalyst Kernel Module, please run "mod_uninstall.sh".

NOTE: Manual installation can be done by:

1. Goto directory "src/cakm/". CodeAnalyst Kernel Module
source for each kernel is stored in the folowing directories:

	- sles10sp1	: SLES10SP1/2
	- rhel5u1	: RHEL5U1/2
	- rhel4u4	: RHEL4U4/5/6/7
	- kernel2.6.25	: FC9, OpenSUSE11
	- kernel2.6.23	: FC8
	- kernel2.6.22	: OpenSUSE10.3

2. Choose the kernel module source and go into that directory.

3. Run "make clean all install" to install CodeAnalyst kernel module.

NOTE: On certain Linux distribution (i.e. SLES11), we need to enable
      loading unsupported kernel module by editing the file 
      "/etc/modprobe.d/unsupported-modules" and set
      "allow_unsupported_modules" to 1.

4. Run "make uninstall" to uninstall Codeanalyst kernel module.


-----------------------------------------

[ Adding Non-root Users ]

In order for a regular user to use CodeAnalyst, the one of the following 
steps must be taken:

- Run "ca_user_manager":
	Use this utility to manage (add / delete) users of amdca group.

	NOTE :
	- Please run as root
	- This utility will create group "amdca", and add users to it.
	- This utility will modify /etc/group and /etc/sudoers.
	- This utility will create a backup copy of /etc/group file as /etc/group.amdca.bak

- Manually Adding Users :

	1. Add non-root users to the amdca group.

	2. Add the following line to the "/etc/sudoers" file to allow 
	   users of amdca group to control profiling session:

	   "%amdca ALL= NOPASSWD: /opt/CodeAnalyst/sbin/ca_oprofile_controller"

	3. Controling profiling via opcontrol as regular user is not supported.

	Note: If "--prefix" was used and CodeAnalyst is installed in a different directory 
	substitute the path specified  for "/opt/CodeAnalyst" in the above line.


-----------------------------------------

[ Build CodeAnalyst-Modified Oprofile Only ]

CodeAnalyst distributes a modified version of Oprofile to add supports for latest
AMD processors, and features which are not yet included in the upstream Oprofile 
source tree.  To build and install the CA-modified Oprofile, as root user:

1. Go to directory src/oprofile

2. Run "./autogen.sh"

3. Run "./configure"

4. Run "make clean all install"

5. Install CA-KM using the instruction above.


-----------------------------------------

[ Commonly Used CodeAnalyst Configurations ]

1. Default Configuration :
	* Run "./configure"

2. Builde CodeAnalyst GUI with external OProfile source : 
	* Build and install the Oprofile source you want to use.
	* Run "./configure \
		--with-oprofile-source=<path to Oprofile source> \
		--disable-shared"
	NOTE: CodeAnalyst can be built with Oprofile-0.9.3 or Oprofile-0.9.4. 
	      However, data collected by these versions are not compatible.

3. Builde CodeAnalyst GUI with external OProfile binaries : 
	* Run "./configure \
		--with-oprofile=<path to Oprofile installation> --disable-oprofile-lib"
	NOTE: This configuration will force to use XML output from opreport 
	      instead of directly access the OProfile sample files. 

4. Builde CodeAnalyst GUI with external libdwarf: 
	* Build the libdwarf and install dwarf.h, libdwarf.h, and libdwarf.so 
	* Run "./configure \
		--with-libdwarf-includes=<path to directory containing dwarf.h and libdwarf.h> \
		--with-libdwarf-libraries=<path to directory containing libdwarf.so> 

5. Builde CodeAnalyst GUI without libdwarf: 
	* Run "./configure \
		--disable-dwarf

NOTE: You do not need to install CAKM when using external OProfile

-----------------------------------------------------------------------------------------

********************
* Trouble Shooting *
********************

If CodeAnalyst fails to build, please check the following most commonly
seen errors:

1. Since CodeAnalyst uses Oprofile driver from the Linux kernel to collect 
   sample.  Enabling profiling using CodeAnalyst and Oprofile driver 
   simultaneously, may produce incorrect results.


2. On 32-bit distributions running on a 64-bit CPU, including Athlon64 
   and Opteron, SMP kernel is required. 


3. libpopt-dev is required, please ensure 64-bit version is installed on a
   64-bit system.


4. CodeAnalyst dialogs maybe bigger than the available screen size if
   resolution of the display is less than 1024x768. It is recommended that
   the resolution is at least 1024x768.


5. For other required packages, please see section [Required packages]


6. I cannot find the required package libqt3 or libqt3-dev, how do I get them?
   This package has different names in different platforms/repositories. 
   It is called qt-1:3.3.6 and qt-devel-1:3.3.6 in Fedora Core repositories, 
   qt3-mt-lib in Ubuntu etc.


7. When building from source ./configure and ./autogen can't find libiberty and libbfd. 
   They usually are part of binutils-devel. Be sure this is package is 
   installed correctly.


8. When building from source the make utility compains about can't find libelf.so
   Be sure libelf package is installed correctly. It has various name on different
   Linux distribution. (i.e. elfutils or libelf) Also, make sure that 
   /usr/lib/libelf.so or /usr/lib64/libelf.so links to an appropriate shared object.


9. In case the "configure" script failed due to QTDIR environment variable 
   is not set up correctly.  Please make sure the QTDIR points to the location where
   qt is installed (i.e. /usr/lib/qt3).  User might also want to try rebooting 
   the system   


10.If CodeAnalyst is installed in directories other than the default 
   location (/opt/CodeAnalyst), there might be multiple version of Oprofile utilities
   co-exisit on the system.  Please verify the version by specifying "--version" 
   flag on the command-line to make sure you are using the Oprofile utilities provided by 
   CodeAnalyst. 


11.Fedora 9 distribution does not come with kernel source package which is required
   in order to build the kernel module.  Please try the following:
	Run:
	1. rpm -Uvh kernel-2.6.25-14.fc9.src.rpm

	2. cd /usr/src/redhat/SPECS/

	3. rpmbuild -bp kernel.spec

	4. mkdir -p /usr/src/kernels/

	5. ln -s /usr/src/redhat/BUILD/kernel-2.6.25/linux-2.6.25.x86_64/ /usr/src/kernels/2.6.25-14.fc9.x86_64
	
	6. In the /usr/src/kernels/2.6.25-14.fc9.x86_64/Makefile, edit the "EXTRAVERSION" variable 
           to match the output from "uname -r". For example :

		[root@localhost 2.6.25-14.fc9.x86_64]# uname -r
		2.6.25-14.fc9.x86_64

		In Makefile, add the following :
	
		EXTRAVERSION = -14.fc9.x86_64

	7. In the /usr/src/kernel/2.6.25-14.fc9.x86_64/, run 

		make oldconfig; make bzImage 

	   This will generate the "/usr/src/kernel/2.6.25-14.fc9.x86_64/Module.symvers" 
	   needed for building kernel modules.
   
   Then try running mod_install.sh once more.


12.OpenSuSE 11 requires the following RPM package to be installed in order to build
   from source.

	- x86_64 : libelf-devel-0.131-37.1.x86_64.rpm
	- i586   : libelf-devel-0.131-37.1.i586.rpm

   User can download the package from 

	http://download.opensuse.org/distribution/11.0/repo/oss/suse/


13.Some newer Linux distributions come with QT4 as default QT package which
   is not compatible with CodeAnalyst. Please install QT3 package instead.


14.Some Linux distributions do not setup the build environment appropriate for 32-bit JVMTI
   cross-compilation on 64-bit platform.  In this case, the CAInstaller.sh will fail. 
   Please configure the CAInstaller.sh without JVMTI, and then manually build the JVMTI 
   module separately using the following steps:

	1. Set up the environment (i.e. install 32-bit version of glib-c, binutils-devel, and etc.)
	   This varies on different Linux distributions.
	
	2. In directory "src/oprofile/libopagent", run
		./autogen.sh
		./configure --enable-shared=bfd --prefix=/opt/CodeAnalyst/ CFLAGS=-m32 CXXFLAGS=-m32
		./make clean install

	3. In directory "src/ca/jpa/jvmti", run
		./autogen.sh
		./configure --prefix=/opt/CodeAnalyst/ --with-java=/usr/java/latest CFLAGS=-m32 CXXFLAGS=-m32
		./make clean install


   NOTE: There seems to be a problem building 32-bit JVMTI on the 64-bit 
	 version of the following Linux distributions:
	- SLES11 (Failed to compile 32-bit application.)
	- RHEL4  (32-bit binutils package does not exist.)


You can find additional documentation in the help directory.

-----------------------------------------------------------------------------------------

****************************
* Support and Bugs Reports *
****************************

- Please send feedback and questions to codeanalyst.support@amd.com.

- Upon sending email, please run "careport.sh" script found in the CodeAnalyst 
source directory or installation directory (/opt/CodeAnalyst/bin), and attach the 
output file "careport.txt".

