b70c24dfd5fa26cf2eded5becef8abd7ae5f2990
hiram
  Tue Aug 6 11:24:49 2013 -0700
add note about MySQL access refs #9149
diff --git src/userApps/README src/userApps/README
index b49bb60..2e7a46a 100644
--- src/userApps/README
+++ src/userApps/README
@@ -1,170 +1,187 @@
 ========================================================================
 
 UCSC genome browser 'kent' bioinformatic utilities
 
   These are only the command line bioinformatic utilities
   from the kent source tree.  This is not the genome browser install.
   For the genome browser install, use the instructions from the source tree:
     http://genome-source.cse.ucsc.edu/gitweb/?p=kent.git;a=tree;f=src/product
 
 ========================================================================
 Pre-compiled binaries available:
 
 These binaries built at UCSC may already work in your linux/Mac
 environment.  Please access via:
   http://hgdownload.cse.ucsc.edu/admin/exe/linux.x86_64/
   http://hgdownload.cse.ucsc.edu/admin/exe/macOSX.x86_64/
   http://hgdownload.cse.ucsc.edu/admin/exe/macOSX.i386/
 
 Or via FTP:
   ftp://hgdownload.cse.ucsc.edu/admin/exe/linux.x86_64/
   ftp://hgdownload.cse.ucsc.edu/admin/exe/macOSX.x86_64/
   ftp://hgdownload.cse.ucsc.edu/admin/exe/macOSX.i386/
 
 ========================================================================
 
 System Requirements:
 
 Linux/Ubuntu/CentOS/Unix/MacOSX operating system
 gnu gcc - C code development system - http://www.gnu.org/software/gcc/
 gnu make - http://www.gnu.org/software/make/
 MySQL development system and libraries - http://dev.mysql.com/
 libpng runtime and development packages - http://www.libpng.org/
 libssl runtime and development packages - http://www.openssl.org/
 
 Optional:
 'git' source code management: http://git-scm.com/downloads
 
 It is best to install these packages with your standard operating
 system package management tools.
     (see notes below about installing packages)
 
 ========================================================================
 
 1. Fetch the userApps directory:
 
    Alternative to 'git' command, a gzipped tar file is available
    with all the source, via FTP or HTTP:
      ftp://hgdownload.cse.ucsc.edu/apache/htdocs/admin/exe/userApps.src.tgz
      http://hgdownload.cse.ucsc.edu/admin/exe/userApps.src.tgz
 
    Unpacking that file (tar xvzf userApps.src.tgz)
    creates a directory: ./userApps/
    with all the source.  Proceed to step 2 to build this directory.
 
    Using 'git' to fetch the source, creates a directory ./userApps/
 
    git archive --format=zip -9 \
       --remote=git://genome-source.cse.ucsc.edu/kent.git \
       beta src/userApps > userApps.zip
    unzip -d userApps -j userApps.zip
    cd userApps
    make fetchSource
 
 2. Build the utilities:
 
    cd userApps
    make
 
    This build fetches (with git) approximately 200 Mb/7,800 files of
       kent source code, and constructs about 223 command binaries
       of approximate size near 600 Mb.
    The resulting binaries are in ./userApps/bin/
 
    Note: there are no required shell environment settings as discussed
          in the genome browser build instructions.  In fact, this build
          system will ignore and override any shell environment settings
          you may have for the genome browser build environment.
 
 3. Install utilities
 
    The binaries are built into ./userApps/bin/
    To install them in a global bin/ directory, copy them
    to a desired location, e.g.:
 
       sudo rsync -a -P ./userApps/bin/ /usr/local/bin/kentUtils/
 
    The destination bin/kentUtils/ should be its own unique directory
    to avoid overwriting same-named binaries in a standard bin/ directory.
 
    Users add '/usr/local/bin/kentUtils' to their shell PATH
    to access the commands.
 
 4. Update utilities
 
    This procedure expects the 'git' command to be available.
    Without the 'git' command, run a 'make clean' to clean up the
    existing source tree, then repeat the fetch and unpack of the
    userApps.src.tgz file as mentioned in step 1.
 
    With the 'git' command available, the 'make update' will refresh
    the source tree and rebuild:
 
    cd userApps
    make update
 
    This runs a 'make clean' in the source tree, fetches all
    the source again, unpacks it to overlay the existing source tree,
    then runs a 'make utils' to rebuild everything.
 
 5. There are 'parasol' binaries built into ./userApps/kent/src/parasol/bin/
    Use these binaries to set up a job control system on a compute cluster
    or large machine with many CPU cores.  See also:
      http://genecats.cse.ucsc.edu/eng/parasol.htm
    for more information.  The usage messages from each command will help
    with the setup.
 
 ========================================================================
 
 Documentation:
 
 Each 'kent' command contains its own documentation.  Simply run the
 commands without any arguments to see the usage message for operating
 instructions.
 
 When the utilities are built here, their usage messages have
 been collected together in one file:
 	kentUtils.Documentation.txt
 
 ========================================================================
 
+MySQL database access:
+
+Many of the commands can use the UCSC public MySQL server, or
+your own local MySQL server with UCSC data formats.  Add these three
+lines to a file in your HOME directory called '.hg.conf' and set
+its permissions to: 'chmod 600 .hg.conf'
+
+    db.host=genome-mysql.cse.ucsc.edu
+    db.user=genomep
+    db.password=password
+
+This '.hg.conf' file is used by the kent commands to determine the
+MySQL host and user/password to the database.  For your local MySQL
+installation, use your host name and your read-only user/password names.
+
+========================================================================
+
 Installing required packages:
 
 On a MacOS system, you will need the XCode system installed:
    https://developer.apple.com/xcode/
 And the Mac Ports install system: http://www.macports.org/
 
 With the Mac ports and XCode systems installed, you can install
 the additional packages required (and helpful):
 
   sudo port install git-core gnutls rsync libpng mysql55 openssl curl wget
 
 On a typical Linux system, for example Ubuntu, use the apt-get command
 to install additional packages:
 
    sudo apt-get install git libssl-dev openssl mysql-client-5.1 \
       mysql-client-core-5.1
 
 Depending upon the version of your Linux/Ubuntu/CentOS operating system,
 the specific version of packages you need may be different than this example.
 
 Please use your standard operating system package management
 install system (e.g. 'yum' on CentOS) to obtain correct versions of
 these packages for your specific operating system version.
 
 See also:
         https://help.ubuntu.com/8.04/serverguide/apt-get.html
         http://www.centos.org/docs/5/html/yum/
 
 ========================================================================
 
 Known Problems:
 
    Please advise UCSC if you have the recommended installed libraries
    and development system and this build will not function.
    email to:  genome-www@soe.ucsc.edu
 
 1. These procedures will not work as-is on sparc or alpha machines or
    with the Sun Solaris operating system.
 
 ========================================================================