Read Me

/*
 * Copyright 2008 Xilinx, Inc. 
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); 
 * you may not use this file except in compliance with the License. 
 * You may obtain a copy of the License at 
 *     
 *     http://www.apache.org/licenses/LICENSE-2.0 
 *     
 * Unless required by applicable law or agreed to in writing, software 
 * distributed under the License is distributed on an "AS IS" BASIS, 
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 * See the License for the specific language governing permissions and 
 * limitations under the License. 
 */


/**********************************************/
/* Building the Code			      		  */
/**********************************************/
The code for this project contains native libraries that need to be built
for each platform on which this code will be run.  These instructions will 
describe how to build for Linux, Solaris, and Windows, and feel free to only
build the libraries about which you care. 

1). Download the libraries on which this project depends:
 	- Latest version of ANT   [tested using 1.7.1] 
 	- Latest version of Log4J [tested using 1.2.15]
	Place the Log4J library into the <project_root>/lib directory.

2). Compile the Java code:
		cd <project_root>
		<ant_home>/bin/ant build
	This should create a metrics.jar in the <project_root>/dist directory.

3). Download the Intel code necessary for detecting hyperthreading (see section 'Why do I need to manually build the libraries?' 
	for understanding why this is necessary):
	a). Download the Intel Code for Hyperthreading detecting from here:
		http://software.intel.com/en-us/articles/code-samples-license-2/?target=http://www.intel.com/cd/ids/developer/asmo-na/eng/276611.htm

		Agree to the license so that the code gets brought up in your browser window.  
		In your browser, do File -> Save As, and save it in the <root_dir>/native directory as "CPUHTDetector.cpp"

	b). Run the following on a Unix machine to remove any extraneous line endings (just in case):
		cd <root_dir>/native
		dos2unix CPUHTDetector.cpp

	c). Copy the constants and method signatures from the Intel code into the <project_root>/native/CPUHTDetector.h file:
		i).  Copy the Intel code from the very top of the file down to the following line:
			// Define constant ~LINUX~ to compile under Linux
		ii). Open the <project_root>/native/CPUHTDetector.h file, and paste the copied code between the following lines:
			// Define constants and method signatures necessary to use the Intel code below this point.
			// Put Intel constants and method signatures above this this point.
		
	d). Patch the CPUHTDetector.cpp file so it can be used with the ResourceDetector:
		cd <root_dir>/native
		patch CPUHTDetector.cpp < CPUCount-patch.txt

 
4). Compile the C code for Linux on a Linux machine with a kernel release of 2.6 or greater
	[you can check your kernel version by running 'uname -r']:	
		cd <project_root>
		<ant_home>/bin/ant compile_c
	The build file uses the C compiler located in the "linux.compiler" property in the build.xml.  If you run into a problem
	compiling the C code and wish to try an alternate compiler, then simply modify the value of the "linux.compiler" property 
	to point to the alternate compiler.
	
	This should create create the following files:
		<project_root>/dist/lib/resource_detector_lin32.so
		<project_root>/dist/lib/resource_detector_linht32.so		

5). Compile the C code for Solaris:	
		cd <project_root>
		<ant_home>/bin/ant compile_c
	The build file uses the C compiler located in the "solaris.compiler" property in the build.xml.  If you run into a problem
	compiling the C code and wish to try an alternate compiler, then simply modify the value of the "solaris.compiler" property 
	to point to the alternate compiler.
		
	This should create create a the following file:
		<project_root>/dist/lib/resource_detector_sol32.so

6). Compile the C code for Windows.  The instructions here are for building the native code on a machine
	running Visual Studio 2005, but you should be able to build with any suitable C compiler on Windows.
	If you do use a separate compiler, then please post your success story back to us so we can update this
	documentation on how to build using different tools.
	
	a). On a windows box with Visual Studio (version 2005 or higher) installed, map to the <project_root>.  This assumes
		that the <project_root> is located on a Linux box, and you are simply accessing it from windows via a map or a UNC path.
		Double click the following file:
			<root_dir>/native/win/MachineStats.vcproj

	b).	Update the project to include the Java Native Interface:
		i).   Right click on the "resource_detector_win" [the project node] on the right side of the screen, select properties.
		ii).  Change the "Configuration" drop down box to be "All Configurations".
		iii). Navigate to "Configuration Properties" > "C/C++".  Change the "Additional Include Directories" to point to your local java paths.  
			Ex.  If java is installed in the C:\Sun\jdk1.6.0_02\ directory, then you would add the following paths:
				C:\Sun\jdk1.6.0_02\include;
				C:\Sun\jdk1.6.0_02\include\win32 
		These include the JNI libraries needed by the project.
		
	c). On the toolbar, click the down arrow next to "Debug", and select "Release".

	d). On the top menu, click "Build", then "Build resource_detector_win".

	e). Once it is done, there will be a "resource_detector_win.dll" file in the Release directory.  This is the native DLL that
		is needed by the resource detector code to get the native windows information.  Copy this DLL to the directory where you will
		keep your native files.  For testing, I recommend putting the file in the <root_dir>/dist/lib directory.

7). Test the code.  If all the steps above went well, then you should have everything you need to test the code.
	On Linux, execute the following to test the code:		
		<ant_home>/bin/ant build run_resource_tester

	On Windows:
		net use <drive letter> <linux mapping of project_root>.
		cd <drive_letter>
		<ant_home>\bin\ant run_resource_tester
	Ex:
		net use t: \\filer\ResourceDetector\
		cd t:
		c:\ant\bin\ant run_resource_tester


/***************************************************/
/* Why do I need to manually build the libraries?  */
/***************************************************/
Why can't we simply package all the code necessary to run the resource detector, as well as the
compiled libraries so that users can just download this code and use it without having to build
it themselves?  Good question, and this was the original intent when we decided to open source this
code.  Unfortunately, the license of the Intel code stopped us from doing this. 

You see, we need the Intel code to detect some of the CPU core information since most operating
systems cannot detect things such as hyperthreading and the number of virtual cores per physical core.
The Intel code that we use has stipulations in the license that make us unable to assume the risk of 
distributing it, so users must manually download and patch it. 

We realize that this is a pain and might hinder adoption of the code, but this is an unfortunate side
effect of Intel's chosen licensing.  We're not complaining though; Intel wrote the code and they have
the right to license it as they wish - we're just lucky that it is available at all for public use.