Build Environment Variables
The kent/src build makes use of environment variables to configure include and lib paths used when compiling. The most important are MYSQLLIBS and MYSQLINC -- see step 3 of kent/src/product/README.building.source. This page focus on several optional environment variables, with defaults provided by kent/src/inc/common.mk.
External library configuration (USE_*)
Several browser features require the installation of additional external software packages. They are disabled unless their corresponding environment variables are set to 1. If you are compiling on hgwdev, then you can use any or none of these as you wish (but you may get an annoying track handler warning if you don't set USE_BAM to 1, and then visit hg18 in hgTracks). To set a variable USE_XXX to 1, if you have a ~/.cshrc or ~/.tcshrc variable, add this:
# Enable UCSC XXX features setenv USE_XXX 1
and if you have a ~/.bashrc, add this:
# Enable UCSC XXX features export USE_XXX=1
After editing, source the file that you edited (e.g. "source ~/.cshrc"). Then, do a clean build of your tree, to make sure that both libraries and CGIs/utils are compiled with consistent settings.
cd kent/src make clean make
USE_BAM (+KNETFILE_HOOKS)
BAM is the compressed binary form of the SAM/BAM file format for short read alignments. The Genome Browser can display BAM data tracks when this is enabled. The samtools C library must be installed first. Then, in addition to setting USE_BAM to 1, you must define another variable or two depending on how you have installed samtools locally. If you have done the default build, which places libbam.a in the top-level samtools directory along with the .c and .h files, then set the environment variable SAMDIR to that directory. If you have manually installed libbam.a and .h files in separate directories, then set SAMLIB and SAMINC to those directories.
UCSC has an extension to samtools that allows its network module (knetfile) to be configured as a wrapper on a different module, so we can configure it to use UCSC's network code. This speeds up BAM display by caching parts of the data file that have already been accessed, and supports https and http with authentication. If you obtain the extension from UCSC here (or if it is someday incorporated into the main distribution of samtools as we hope) and recompile samtools with it, then you can set KNETFILE_HOOKS to 1 to make the UCSC code utilize the extension.
USE_PNG
PNG (Portable Networks Graphics) is a widely used image file format, supported by all major browsers, that generally produces smaller image file sizes than the Genome Browser's default format, GIF. The libpng library must be installed before setting USE_PNG to 1; if on a linux system, use your favorite package manager (rpm, yum, apt-get etc.). A caveat: since kent/src/inc/common.h includes setjmp.h, libpng's pngconf.h must be edited to remove the syntax error that is intentionally generated when setjmp.h has already been included.
USE_SSL
SSL (Secure Socket Layer) provides encrypted transfer of data. In the Genome Browser, URLs that begin with "https://" or "ftps://" are supported only when this is enabled. The libssl library (development version w/headers) must be installed first; if on a linux system, use your favorite package manager (rpm, yum, apt-get etc.).
Compilation environment variables
COPT
Default: -O -g (optimize but keep debugger symbols). When debugging gets gnarly due to optimizations, recompile with COPT=-ggdb (or if not using gcc/gdb, just -g).
HG_WARN
By default, we use -Wall and add in a few others on specific platforms. When OSTYPE does not include "darwin" or "solaris", -Werror is added. This is appended to common.mk's CFLAGS.
OS
If OS is Windows_NT (as it is in the Cygwin environment), then necessary file suffixes are tweaked for a.out and executable names.
STRIP
Default: STRIP=strip is applied to executables after compilation, stripping their symbol tables and making them nice and small but not debugger-friendly. To bypass strip, set STRIP=true and make will run 'true exec' instead of 'strip exec'.
Installation environment variables
BINDIR
Installation directory for utility programs compiled from C.
CGI_BIN
Installation directory for CGI programs (hgTracks, hgc etc)
DOCUMENTROOT
/usr/local/apache/htdocs by default; if you use a different web server or htdocs root for Genome Browser files, change this. CGI programs expect to read some files from this directory.
SCRIPTS
Installation directory for utility programs written in an interpreted scripting language (bash, tcsh, perl etc.).
