Index: src/product/README.building.source
===================================================================
RCS file: /projects/compbio/cvsroot/kent/src/product/README.building.source,v
retrieving revision 1.18
retrieving revision 1.19
diff -b -B -U 1000000 -r1.18 -r1.19
--- src/product/README.building.source	6 Nov 2009 18:44:51 -0000	1.18
+++ src/product/README.building.source	29 Apr 2010 18:11:59 -0000	1.19
@@ -1,181 +1,191 @@
 
 To build the source tree.
 
 1. Check your shell environment.  It should
 	contain a MACHTYPE variable.  Typical values, for example:
 	i386 i686 sparc alpha x86_64 ppc
 	If there is none, set it to indicate your
 	CPU architecture, for example,
 	MACHTYPE=i686
 	export MACHTYPE
 	You need to do this if your existing MACHTYPE is a long string
 	such as: i686-pc-linux-gnu
 	since this is used as an argument on the command line to gcc
 	which will not work with the - signs in the strings.
 
 	To determine the machine cpu type of your computer, try
 	one of these uname command options:
 	$ uname -m
 	$ uname -p
 	$ uname -a
 
 	Remember to set this MACHTYPE in your .bashrc or .tcshrc home directory
 	environment files so it will be set properly at your next login.
 
 	The browser code has not been tested by UCSC outside a
 	CentOS Linux on Intel or AMD Opteron environment.
 	Other users do report successful operation on other systems.
 
 2.  Create a directory where binaries will be moved to during
 	the build of the source tree:
 	$ mkdir -p ~/bin/${MACHTYPE}
 
 3a. ALTERNATE PATH: 
         If you are going to do a full build anyway, skip this and proceed straight to step 3 below.
         Otherwise, to make a minimal utility build without mysql:
 	There are some utilities that depend only on jkweb.a and not jkhgap.a
 	which means they can be compiled without needing mysql client installed.
 	To make a utility like pslCDnaFilter without installing mysql client:
         # create jkweb.a
           cd kent/src/lib
           make
         # create stringify utility required by some makefiles
           cd kent/src/utils/stringify
           make
         # create pslCDnaFilter utility program
           cd kent/src/hg/pslCDnaFilter
           make
         Proceed similarly for any other such utilities.
         You are done and can stop here.
 
 3.  Create the following shell environment variables:
 	MYSQLINC=/usr/include/mysql
 	MYSQLLIBS="/usr/lib/mysql/libmysqlclient.a -lz"
 	export MYSQLINC MYSQLLIBS
 	Your setting may vary depending upon where your
 	mysql is installed.  The above example is typical.
 	If your system does not have this set of include files
 	or this static client.a file, you may need to install
 	the mysql-devel package to obtain the mysql development
 	environment.  (http://dev.mysql.com/downloads/)
 	With that package installed, this command:
 		mysql_config --libs
 	will display the appropriate libraries to link with
 	for your system configuration.  And:
 		mysql_config --include
 	will display the appropriate MYSQLINC directory.
 	The -lz requires a link to the libraries installed in the
 	zlib-devel rpm.
 
 4a. optional SSL support:
 	If you want the libraries to be able to use SSL,
 	for instance to support fetching HTTPS URLs,
 	install openssl.  We are currently using these packages: 
 	openssl-0.9.8b-10.el5
 	openssl-devel-0.9.8b-10.el5
         Add the following as an environment variable to 
         .bashrc or .tcshrc, OR alternatively add it as the first
 	line of your kent/src/inc/common.mk:
 	  USE_SSL=1
         If you try to fetch an https url without this support
 	you will see an error message:
 	  No openssl available in netMustConnectHttps for <hostName> : <port>
         SSL is also useful for accessing bigWig and bigBed over HTTPS.
 
 4.  In the source tree, perform the following:
 	$ cd kent/src
 	$ make libs
 	At this point, you can build utilities in other parts of
 	the source tree if that is your goal.  Go to the directory
 	of the utility command you want to build and run a 'make'
 	in that directory.  The resulting binary will be placed
 	in $HOME/bin/$MACHTYPE
 
 5.  To continue building the CGI binaries
 	$ cd kent/src/hg
 	$ make compile
 	$ make install DESTDIR=/destination/prefix
 
 	Where "/destination/prefix" is your choice, and
 	this will install the cgi binaries in:
 	/destination/prefix/usr/local/apache/cgi-bin
 
         If your cgi-bin directory is something different than
 	/usr/local/apache/cgi-bin then use the CGI_BIN variable
 
         If your apache DocumentRoot is something different than
         /usr/local/apache/htdocs then use the DOCUMENTROOT variable.
         This value should be a full path and should agree with the 
         browser.documentRoot setting in hg.conf; see README.mysql.setup 
         for more details.
 
 	$ make install DESTDIR=/destination/prefix CGI_BIN=/cgi-bin/path DOCUMENTROOT=/usr/local/apache/htdocs
 
 	to install binaries in "/destination/prefix/cgi-bin/path"
 
 	[NOTE:  These 'make' commands assume gnu make is being used]
 
 6.  After source tree updates, the make sequence is:
 	$ cd kent/src
 	$ make clean
 	$ make libs
 	$ cd hg
 	$ make compile
 	$ make install DESTDIR=/destination/prefix
 
 ====================================================================
 Known problems:
 
 1.  A compile/link of a utility has complaints about undefined symbols
 	such as: bind, accept, listen, gethostbyname, socket, setsockopt,
 	connect, inet_pton, inet_ntop or h_errno
     To fix this, you need to add '-lsocket -lnsl' to your MYSQLLIBS
     environment variable.  This is typically the case on Solaris systems:
 	MYSQLLIBS="/usr/lib/mysql/libmysqlclient.a -lsocket -lnsl -lz"
 
 2.  The build fails immediately in the first src/lib/ directory with
 	the compiler issuing a warning about unused variables.
 	Some newer versions of gcc issue these warnings and the
 	src/inc/common.mk file specifies -Werror which causes it to
 	exit on these warnings.  Either remove the -Werror specifications
 	in src/inc/common.mk or add the -Wno-unused-variable to instruct
 	the compiler to allow these warnings without an exit.
 
 3.  The build fails during a link of any program under the src/hg/
 	hierarchy with an error something like:
 	undefined reference to `SSL_CTX_free'
 	undefined reference to `ERR_get_error_line_data'
 	undefined reference to `SSL_read'
 	undefined reference to `SSL_get_error'
 	undefined reference to `SSL_write'
     This error is due to your mysql libraries have been compiled with SSL
 	functionality enabled.  To fix this build problem, add '-lssl'
 	to your MYSQLLIBS environment variable to satisify these SSL
 	library functions.
 
 4.  Build fails on Macintosh with an error:
 aliType.c:5: warning: `rcsid' defined but not used
 make: *** [aliType.o] Error 1
 
     The OSTYPE environment variable needs to be set to "darwin".  If your
     shell is bash, it is a shell local variable instead of an environment
     variable as with tcsh.
 
     To avoid this error, place an export statement in your $HOME/.bashrc
     environment:
     export OSTYPE
     This causes the OSTYPE variable to be recognized during the
     make and the conditional statements in src/inc/common.mk will
     include the -Wno-unused-variable option in the build.
 
 5.  The build fails with an error:
     gifdecomp.c:274: error: call to function 'gif_out_line' without
 	a real prototype
 
     This happens with newer versions of the gcc compiler.  To avoid the
     build stopping at this point, eliminate the -Werror argument from the
     src/inc/common.mk file.  We will fix this error as soon as we
     get our hands on a newer version of the gcc compiler.
 
+6.  The build fails with an error of this type:
+    pipeline.c: In function waitOnExec:
+    pipeline.c:351: error: ignoring return value of read, declared with
+	attribute warn_unused_result 
+
+    This happens with newer versions of the gcc compiler.  To avoid the
+    build stopping at this point, eliminate the -Werror argument from the
+    src/inc/common.mk file.  We will fix this error as soon as we
+    get our hands on a newer version of the gcc compiler.
+
 ====================================================================
 This file last updated: $Date$

