src/product/README.building.source 1.16
1.16 2009/08/05 19:40:15 galt
adding alternate path for minimal utilities
Index: src/product/README.building.source
===================================================================
RCS file: /projects/compbio/cvsroot/kent/src/product/README.building.source,v
retrieving revision 1.15
retrieving revision 1.16
diff -b -B -U 1000000 -r1.15 -r1.16
--- src/product/README.building.source 26 Aug 2008 16:20:01 -0000 1.15
+++ src/product/README.building.source 5 Aug 2009 19:40:15 -0000 1.16
@@ -1,139 +1,157 @@
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.
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.
====================================================================
This file last updated: $Date$