a2dc0fc3d881018bd83091a86b532468bfe2dc8f
hiram
  Fri May 24 10:33:37 2013 -0700
fixup the Makefile so it will correctly bootstrap itself, and expand the README, refs #9149
diff --git src/userApps/README src/userApps/README
index 7f36e9c..0f29380 100644
--- src/userApps/README
+++ src/userApps/README
@@ -1,90 +1,130 @@
-=========
+========================================================================
 
 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
 
-System Requirements:    (see notes below about installing packages)
+========================================================================
 
-Linux/Unix/MacOSX system
+System Requirements:
+
+Linux/Ubuntu/CentOS/Unix/MacOSX operating system
 'git' source code management: http://git-scm.com/downloads
 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
-libpng
-libssl
+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/
+
+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 from the kent source:
+
    git archive --format=zip -9 \
       --remote=git://genome-source.cse.ucsc.edu/kent.git \
       HEAD src/userApps > userApps.zip
    unzip -d userApps -j userApps.zip
 
-   Creates the directory: ./userApps/
-   with several files.
+   Creates the directory: ./userApps/ with several small files.
+
+2. Build the utilities:
 
-2. Build utilities:
    cd userApps
    make
 
    This build fetches (with git) approximately 200 Mb/7,800 files of
       kent source code, and constructs command binaries of approximately 200 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 any shell environment settings you may have
+         for the genome browser build environment.
 
 3. Install utilities
-   The binaries are built into userApps/bin/
+
+   The binaries are built into ./userApps/bin/
    To install them in a global bin/ directory, copy them
-   to desired location:
-      sudo rsync -a -P bin/ /usr/local/bin/userApps/
+   to a desired location, e.g.:
+
+      sudo rsync -a -P ./userApps/bin/ /usr/local/bin/kentUtils/
 
-   The destination bin/userApps/ should be its own unique directory
+   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/userApps' to their shell PATH
+   Users add '/usr/local/bin/kentUtils' to their shell PATH
    to access the commands.
 
+4. Update utilities
+
+   cd userApps
+   make update
 
-4. There are 'parasol' binaries built in kent/src/parasol/bin/
+   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
 
-=========
+========================================================================
 
 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
+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
 
-Or appropriate system management install software (e.g. 'yum' on CentOS)
+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:
+
+1. These procedures will not work as-is on sparc or alpha machines or
+   with the Sun Solaris operating system.
+
+========================================================================