1e3cf842c6fb308daf4cecd94783804ca1667e4c kent Wed Apr 4 16:32:19 2012 -0700 Splitting up README to populate higher level README. diff --git README README new file mode 100644 index 0000000..0cb3a55 --- /dev/null +++ README @@ -0,0 +1,119 @@ +CONTENTS AND COPYRIGHT + +This directory contains the entire source tree for the +UCSC Genome Bioinformatics Group's suite of biological analysis +and web display programs as well as some of Jim Kent's own tools. +All files are copyrighted, but license is hereby granted for personal, +academic, and non-profit use. A license is also granted for the contents +of the src/lib, src/inc and src/utils and python directories for commercial +users. Commercial users should contact kent@soe.ucsc.edu for access to other +modules. Commercial users interested in the UCSC Genome Browser in particular +please see + http://genome.ucsc.edu/license/. + +Most source code users will only be interested in the src/inc and +src/lib directories, which contain the interfaces and implementations +to the library routines, and in a few specific applications. +The applications are scattered in other directories. +Many of them are web based. A few of them expect +the MySQL database to be around. + +GENERAL INSTALL INSTRUCTIONS + +1. Get the code. The best way to do this now for + Unix users is via Git following the instructions at: + http://genome.ucsc.edu/admin/git.html + Or, fetch the entire source in a single file: + http://hgdownload.cse.ucsc.edu/admin/jksrc.zip + Note further documentation for the build process in your + unpacked source tree in src/product/README.* + Especially note README.building.source and the "Known problems" + for typical situations you may encounter. +2. Check that the environment variable MACHTYPE + exists on your system. It should exist on Unix/Linux. + (And making this on non-Unix systems is beyond + the scope of this README). The default MACHTYPE is often a + long string: "i386-redhat-linux-gnu" + which will not function correctly in this build environment. + It needs to be something simple such as one of: + i386 i686 sparc alpha x86_64 ppc etc ... + with no other alpha characters such as: - + To determine what your system reports itself as, try the + uname options: 'uname -m' or 'uname -p' or 'uname -a' + on your command line. If necessary set this environment variable. + Do this under the bash shell as so: + MACHTYPE=something + export MACHTYPE + or under tcsh as so: + setenv MACHTYPE something + and place this setting in your home directory .bashrc or .tcshrc + environment files so it will be set properly the next time you + login. Remember to "export" it as show here for the bash shell. +3. Make the directory ~/bin/$MACHTYPE which is + where the (non-web) executables will go. + Add this directory to your path. +4. Go to the src/lib directory. If it doesn't + already exist do a mkdir $MACHTYPE. +5. Type make. On Alphas there will be + some warning messages about "crudeAli.c" + otherwise it should compile cleanly. + It's using gcc. +6. Go to src/jkOwnLib and type make. +7. Go to the application you want to make and type + make. (If you're not sure, as a simple test + go to src/utils/fixcr and type make, + then 'rehash' if necessary so your shell + can find the fixcr program in ~/bin/$(MACHTYPE). + The fixcr program changes Microsoft style + <CR><LF> line terminations to Unix style + <LF> terminations. Look at the "gotCr.c" + file in the fixCr directory, and then + do a "fixcr gotCr.c" on it. + + +INSTALL INSTRUCTIONS FOR BLAT + +1. Follow the general install instructions above. +2. If you're on an alpha system do a: + setenv SOCKETLIB -lxnet + on Solaris do + setenv SOCKETLIB "-lsocket -lnsl" + on SunOS do + setenv SOCKETLIB "-lsocket -lnsl -lresolv" + on Linux you can skip this step. +3. Execute make in each of the following directories: + src/gfServer + src/gfClient + src/blat + src/utils/faToNib + +INSTALL INSTRUCTIONS FOR CODE USING THE BROWSER DATABASE +(and other code in the src/hg subdirectory) + +1. Follow the general install instructions above. +2. Make the environment variable MYSQLINC point to + where MySQL's include files are. (On my + system they are at /usr/include/mysql.) + While you're at it set the MYSQLLIBS + variable to point to something like + /usr/lib/mysql/libmysqlclient.a -lz + When available, the commands: mysql_config --include + and mysql_config --libs + will display the required arguments for these environment settings. +3. Execute make in src/hg/lib +4. Execute make in the directory containing the + application you wish to build. +5. See also: http://genome.ucsc.edu/admin/jk-install.html + and more documentation in this source tree about setting up + a working browser in README files: + src/product/README.building.source + src/product/README.local.git.source + src/product/README.mysql.setup + src/product/README.install + src/product/README.trackDb + src/hg/makeDb/trackDb/README + There are numerous README files in the source tree describing + functions or modules in that area of the source tree. + The src/README in particular should be read by anyone modifying + the C source code, and python/README by anyone modifying the Python. +