\section{Installation} \label{section:installation} \setcounter{footnote}{0} \subsection{Quick installation instructions} Download \prog{infernal-1.1.1.tar.gz} from \url{http://infernal.janelia.org/}, or directly from \url{ftp://selab.janelia.org/pub/software/infernal/infernal-1.1.1.tar.gz}; unpack it, configure, and make: \user{wget ftp://selab.janelia.org/pub/software/infernal/infernal-1.1.1.tar.gz}\\ \user{tar xf infernal-1.1.1.tar.gz}\\ \user{cd infernal-1.1.1}\\ \user{./configure}\\ \user{make} To compile and run a test suite to make sure all is well, you can optionally do: \user{make check} All these tests should pass. You don't have to install Infernal programs to run them. The newly compiled binaries are now in the \prog{src} directory. You can run them from there. To install the programs and man pages somewhere on your system, do: \user{make install} By default, programs are installed in \prog{/usr/local/bin} and man pages in \prog{/usr/local/share/man/man1/}. You can change the \prog{/usr/local} prefix to any directory you want using the \prog{./configure --prefix} option, as in \prog{./configure --prefix /the/directory/you/want}. Optionally, you can install the Easel library package as well, including its various ``miniapplications'', in addition to its library and header files. We don't do this by default, in case you already have a copy of Easel separately installed: \user{cd easel; make install} That's it. You can keep reading if you want to know more about customizing a Infernal installation, or you can skip ahead to the next chapter, the tutorial. \subsection{System requirements} \paragraph{Operating system:} Infernal is designed to run on POSIX-compatible platforms, including UNIX, Linux and MacOS/X. The POSIX standard essentially includes all operating systems except Microsoft Windows. We have tested most extensively on Linux and on MacOS/X, because these are the machines we develop on. \paragraph{Processor:} Infernal depends on vector parallelization methods that are supported on most modern processors. Infernal requires either an x86-compatible (IA32, IA64, or Intel64) processor that supports the SSE2 vector instruction set, or a PowerPC processor that supports the Altivec/VMX instruction set. SSE2 is supported on Intel processors from Pentium 4 on, and AMD processors from K8 (Athlon 64) on; we believe this includes almost all Intel processors since 2000 and AMD processors since 2003. Altivec/VMX is supported on Motorola G4, IBM G5, and IBM PowerPC processors starting with the Power6, which we believe includes almost all PowerPC-based desktop systems since 1999 and servers since 2007. If your platform does not support one of these vector instruction sets, you won't be able to install and run Infernal 1.1 on it. We do aim to be portable to all modern processors. The acceleration algorithms are designed to be portable despite their use of specialized SIMD vector instructions. We hope to add support for the Sun SPARC VIS instruction set, for example. We believe that the code will be able to take advantage of GP-GPUs and FPGAs in the future. \paragraph{Compiler:} The source code is C conforming to POSIX and ANSI C99 standards. It should compile with any ANSI C99 compliant compiler, including the GNU C compiler \prog{gcc}. We test the code using both the \prog{gcc} and \prog{icc} compilers. We find that \prog{icc} produces somewhat faster code at present. \paragraph{Libraries and other installation requirements:} Infernal includes two software libraries, HMMER and Easel, which it will automatically compile during its installation process. By default, Infernal does not require any additional libraries to be installed by you, other than standard ANSI C99 libraries that should already be present on a system that can compile C code. Bundling HMMER and Easel instead of making them separate installation requirements is a deliberate design decision to simplify the installation process.\footnote{If you install standalone HMMER (which also bundles Easel), this may become an annoyance; you'll have multiple instantiations of HMMER and Easel lying around. Unfortunately this is necessary as Infernal requires the specific versions of HMMER and Easel bundled within it. Also, the Easel API is not yet stable enough to decouple it from the applications that use it.} Configuration and compilation use several UNIX utilities. Although these utilities are available on all UNIX/Linux/MacOS systems, old versions may not support all the features the \ccode{./configure} script and Makefiles are hoping to find. We aim to build on anything, even old Ebay'ed junk, but if you have an old system, you may want to hedge your bets and install up-to-date versions of GNU tools such as GNU make and GNU grep. \subsection{Multithreaded parallelization for multicores is the default} The main workhorse Infernal programs \prog{cmalign}, \prog{cmcalibrate}, \prog{cmsearch} and \prog{cmscan} support multicore parallelization using POSIX threads. By default, the configure script will identify whether your platform supports POSIX threads (almost all platforms do), and will automatically compile in multithreading support. If you want to disable multithreading at compile time, recompile from source after giving the \ccode{--disable-threads} flag to \ccode{./configure}. By default, our multithreaded programs will use all available cores on your machine. You can control the number of cores each Infernal process will use for computation with the \ccode{--cpu } command line option or the \ccode{INFERNAL\_NCPU} environment variable. Even with a single processing thread (\ccode{--cpu 1}), INFERNAL will devote a second execution thread to database input, resulting in speedup over serial execution. If you specify \ccode{--cpu 0}, the program will run in serial-only mode, with no threads. This might be useful if you suspect something is awry with the threaded parallel implementation. \subsection{MPI parallelization for clusters is optional} The \prog{cmalign}, \prog{cmcalibrate}, \prog{cmsearch} and \prog{cmscan} programs also support MPI (Message Passing Interface) parallelization on clusters. To use MPI, you first need to have an MPI library installed, such as OpenMPI (\url{www.open-mpi.org}). We use Intel MPI at Janelia. MPI support is not enabled by default, and it is not compiled into the precompiled binaries that we supply with Infernal. To enable MPI support at compile time, give the \ccode{--enable-mpi} option to the \ccode{./configure} command. To use MPI parallelization, each program that has an MPI-parallel mode has an \ccode{--mpi} command line option. This option activates a master/worker parallelization mode. (Without the \ccode{--mpi} option, if you run a program under \ccode{mpirun} on N nodes, you'll be running N independent duplicate commands, not a single MPI-enabled command. Don't do that.) The MPI implementation for \prog{cmcalibrate} scales well up to 161 processors.\footnote{By default, \prog{cmcalibrate} searches 160 random sequences of length 10 Kb (1.6 total Mb), so there's no reason to use more than 160 workers plus 1 master - unless you use the \ccode{-L } option to increase the total Mb searched (see the \prog{cmcalibrate} man page for more information).} \prog{cmalign} scales pretty well up to a couple hundred processors. \prog{cmsearch} scales all right, but the scaling performance will vary on different inputs\footnote{A database in which many high-scoring hits are clustered in sequences or exist in many sequences with similar names (that sort close together alphabetically) may show especially poor scaling performance.} \prog{cmscan} scales poorly, and probably shouldn't be used on more than tens of processors at most. Improving MPI scaling is one of our goals. \subsection{Using build directories} The configuration and compilation process from source supports using separate build directories, using the GNU-standard VPATH mechanism. This allows you to maintain separate builds for different processors or with different configuration/compilation options. All you have to do is run the configure script from the directory you want to be the root of your build directory. For example: \user{mkdir my-infernal-build}\\ \user{cd my-infernal-build}\\ \user{/path/to/infernal/configure}\\ \user{make} This assumes you have a \ccode{make} that supports VPATH. If your system's \ccode{make} does not, you can always install GNU make. \subsection{Makefile targets} \begin{sreitems}{\emprog{distclean}} \item[\emprog{all}] Builds everything. Same as just saying \ccode{make}. \item[\emprog{check}] Runs automated test suites in Infernal, and the HMMER and Easel libraries. \item[\emprog{clean}] Removes all files generated by compilation (by \ccode{make}). Configuration (files generated by \ccode{./configure}) is preserved. \item[\emprog{distclean}] Removes all files generated by configuration (by \ccode{./configure}) and by compilation (by \ccode{make}). Note that if you want to make a new configuration (for example, to try an MPI version by \ccode{./configure --enable-mpi; make}) you should do a \ccode{make distclean} (rather than a \ccode{make clean}), to be sure old configuration files aren't used accidentally. \end{sreitems} \subsection{Why is the output of 'make' so clean?} Because we're hiding what's really going on with the compilation with a pretty wrapper. If you want to see what the command lines really look like, in all their ugly glory, pass a \ccode{V=1} option (V for ``verbose'') to \ccode{make}, as in: \user{make V=1} \subsection{What gets installed by 'make install', and where?} Infernal's 'make install' generally follows the GNU Coding Standards and the Filesystem Hierarchy Standard. The top-level Makefile has variables that specify three directories where \ccode{make install} will install things: \begin{tabular}{ll} Variable & What \\ \hline \ccode{bindir} & All Infernal programs \\ \ccode{man1dir} & All Infernal man pages \\ \ccode{pdfdir} & \ccode{Userguide.pdf} \\ \hline \end{tabular} These variables are constructed from some other variables, in accordance with the GNU Coding Standards. All of these variables are at the top of the top-level Makefile. Their defaults are as follows: \begin{tabular}{ll} Variable & Default \\ \hline \ccode{prefix} & \ccode{/usr/local} \\ \ccode{exec\_prefix} & \ccode{\${prefix}} \\ \ccode{bindir} & \ccode{\${exec\_prefix}/bin}\\ \ccode{libdir} & \ccode{\${exec\_prefix}/lib}\\ \ccode{includedir} & \ccode{\${prefix}/include} \\ \ccode{datarootdir} & \ccode{\${prefix}/share} \\ \ccode{mandir} & \ccode{\${datarootdir}/man} \\ \ccode{man1dir} & \ccode{\${mandir}/man1} \\ \hline \end{tabular} The best way to change these defaults is when you use \ccode{./configure}, and the most important variable to consider changing is \ccode{--prefix}. For example, if you want to install Infernal in a directory hierarchy all of its own, you might want to do something like: \user{./configure --prefix /usr/local/infernal} That would keep Infernal out of your system-wide directories like \ccode{/usr/local/bin}, which might be desirable. Of course, if you do it that way, you'd also want to add \ccode{/usr/local/infernal/bin} to your \ccode{\$PATH}, \ccode{/usr/local/infernal/share/man} to your \ccode{\$MANPATH}, etc. These variables only affect \ccode{make install}. Infernal executables have no pathnames compiled into them. \subsection{Staged installations in a buildroot, for a packaging system} Infernal's \ccode{make install} supports staged installations, accepting the traditional \ccode{DESTDIR} variable that packagers use to specify a buildroot. For example, you can do: \user{make DESTDIR=/rpm/tmp/buildroot install} \subsection{Workarounds for some unusual configure/compilation problems} \paragraph{Configuration or compilation fails when trying to use a separate build directory.} If you try to build in a build tree (other than the source tree) and you have any trouble in configuration or compilation, try just building in the source tree instead. Some \ccode{make} versions don't support the VPATH mechanism needed to use separate build trees. Another workaround is to install GNU make. \paragraph{Configuration fails, complaining that the CFLAGS don't work.} Our configure script uses an Autoconf macro, \ccode{AX\_CC\_MAXOPT}, that tries to guess good optimization flags for your compiler. In very rare cases, we've seen it guess wrong. You can always set \ccode{CFLAGS} yourself with something like: \user{./configure CFLAGS=-O} \paragraph{Configuration fails, complaining ``no acceptable grep could be found''.} We've seen this happen on our Sun Sparc/Solaris machine. It's a known issue in GNU autoconf. You can either install GNU grep, or you can insist to \ccode{./configure} that the Solaris grep (or whatever grep you have) is ok by explicitly setting \ccode{GREP}: \user{./configure GREP=/usr/xpg4/bin/grep} \paragraph{Configuration fails with an error message saying that no SSE or VMX capability exists.} This is what you get if your system has a processor that we don't yet support the fast vector-parallel implementation of HMM filters that Infernal uses. We currently only support Intel/AMD compatible processors and PowerPC compatible processors. You'll have to install an older version of (version 1.0.2) if you want to use Infernal on other processors. \paragraph{Many 'make check' tests fail.} We have one report of a system that failed to link multithread-capable system C libraries correctly, and instead linked to one or more serial-only libraries.\footnote{The telltale phenotype of this failure is to configure with debugging flags on and recompile, run one of the failed unit test drivers (such as \ccode{easel/easel\_utest}) yourself and let it dump core; and use a debugger to examine the stack trace in the core. If it's failed in \ccode{\_\_errno\_location()}, it's linked a non-thread-capable system C library.} We've been unable to reproduce the problem here, and are not sure what could cause it -- we optimistically believe it's a messed-up system instead of our fault. If it does happen, it screws all kinds of things up with the multithreaded implementation. A workaround is to shut threading off: \user{./configure --disable-threads} This will compile code that won't parallelize across multiple cores, of course, but it will still work fine on a single processor at a time (and MPI, if you build with MPI enabled).