* ------------------------------------------------------------------------- * * Introduction * * ------------------------------------------------------------------------- * The EMBOSS suite is available as a FreeBSD port. This makes the EMBOSS installation almost trivially easy for the experienced user of the FreeBSD operating system. If you are a FreeBSD user and you're not yet familiar with the ports system, this document should tell you all you need to know in order to install EMBOSS. The next section ("Installing EMBOSS from the port") tells you how to install the FreeBSD EMBOSS port in the simplest case, and is required reading. The rest of the document give you enough information for you to ensure that your ports tree is up to date, and that you are therefore installing the most recent version of EMBOSS. While not required, it is recommended that you read the entire document before proceeding. Parts of this document are somewhat specific to FreeBSD 4.1.1-RELEASE and later, while parts also assume that you're installing the latest version of the EMBOSS port available at the time of writing. * ------------------------------------------------------------------------- * * Installing EMBOSS from the port * * ------------------------------------------------------------------------- * Installing the EMBOSS port on a FreeBSD system can be as simple as issuing a single command! First, log in to your machine as the root user, or use the "su" command to become root. Now, change to the EMBOSS port's directory: # cd /usr/ports/biology/emboss Then, still as root, do a "make install": # make install That's it! You will be presented by a graphical screen where you can select which optional components you want to install (default: all), and then you can sit back and relax while EMBOSS is fetched, patched, compiled and installed. If you want to clean up the temporary files created by the installation of the EMBOSS port, follow the "make install" by a "make clean" (still in the "emboss" port directory): # make clean Alternatively, you can apply a little Unix shell magic and accomplish all three steps with but a single command! # cd /usr/ports/biology/emboss && make install clean * ------------------------------------------------------------------------- * * Configuring the EMBOSS installation * * ------------------------------------------------------------------------- * The configuration of EMBOSS is described in some detail in the EMBOSS Administrators Guide[1] and will not be covered here in great detail, except for a few details which pertain to the FreeBSD EMBOSS port. Once EMBOSS has been installed successfully you will need to copy (or move) /usr/local/etc/emboss.default.sample to /usr/local/etc/emboss.default. This is the system-wide configuration file for EMBOSS. At the top of the emboss.default.sample installed by the port, there are three variables which may need to be edited to suit a particular site's requirements: - "emboss_data" is set to "/usr/local/share/EMBOSS/data", but is commented out since this is the compiled-in default location. EMBOSS stores various ancillary databases and data files here. - "emboss_tempdata" is a convenient variable which is used later in the configuration file and shoult point to a location where a minimal set of sequence databases are stored. It should be customised for a specific site. - "emboss_logfile" is set to "/var/log/emboss.log", but is commented out. If it is required that EMBOSS usage be logged, this variable should be uncommented and the log file must be created and be writable by all EMBOSS users. A user who wishes to use those programs in the EMBOSS suite which produce graphical output may have to set the following environment variable: - set PLPLOT_LIB to: "/usr/local/share/EMBOSS" A file called ".embossrc" in a user's home directory will override settings in the system-wide configuration file (/usr/local/etc/emboss.default). An environment variable called "EMBOSSRC" can be set to the location of an alternative EMBOSS configuration file, should the user wish to use neither the system-wide default configuration file nor his own ".embossrc". [1] The Guide may be found at: ftp://ftp.no.embnet.org/pub/EMBOSS-extras/ * ------------------------------------------------------------------------- * * What does the port installation do? * * ------------------------------------------------------------------------- * Doing a "make install" in the EMBOSS port directory as described above will initiate a chain of events: 1. EMBOSS depends on a number of libraries and applications being installed on your system. The FreeBSD ports system keeps track of such depen- dencies, and will automatically fetch and install these libraries and applications first if required. 2. "EMBASSY" applications are third party programs which have been modified to work with EMBOSS, to the extent of sharing the same "look and feel". During the install process the EMBOSS port will present you with a graphical menu screen where you can choose which EMBASSY applications you want to install. 3. The packages containing the EMBOSS source code and the source code of selected EMBASSY applications will automatically be fetched from a distribution site if they do not already reside on your system. 4. Any patches necessary to allow EMBOSS to work properly on FreeBSD will be applied. 5. The EMBOSS suite (including EMBASSY applications) will be compiled from the source code. 6. The binary executables, EMBOSS documentation, configuration file, and all other components will be installed to various locations in the filesystem: - the EMBOSS programs are installed in /usr/local/bin - shared and library data is installed in /usr/local/share/EMBOSS - documentation is installed in /usr/local/share/doc/EMBOSS - a sample configuration file is installed as /usr/local/etc/emboss.default.sample * ------------------------------------------------------------------------- * * Installing EMBOSS from the package * * ------------------------------------------------------------------------- * Installing EMBOSS from the FreeBSD port is the simplest and arguably the most "correct" way of installing the suite on FreeBSD. However, precompiled binary "packages" can also be built from FreeBSD ports and it is possible to install EMBOSS from such a package. You will find a link to the FreeBSD binary package for EMBOSS on this page: http://www.freebsd.org/ports/biology.html Search for the word "emboss" on that page. The binary package may be downloaded by clicking on the "Package" link in the "emboss" section. It will be named something like "emboss-1.0.0.tgz" (the version number will vary, of course). Once you have this package on your local filesystem, you can install it (as root): # pkg_add emboss-1.0.0.tgz Note that you may also have to download packages for certain libraries and applications upon which EMBOSS depends. You'll find links to these in the "emboss" section on the web page given above. Simply place these additional packages in the same directory as the EMBOSS package before executing the "pkg_add" command. * ------------------------------------------------------------------------- * * A brief primer on the FreeBSD ports tree (and how to update it) * * ------------------------------------------------------------------------- * The FreeBSD ports tree provides a simple and effective way to install applications on your FreeBSD system. The ports tree is normally rooted at the directory /usr/ports in the filesystem. If /usr/ports does not exist (or is empty) on your system, it means you chose not to install the ports tree during the installation of the operating system. (If that is the case, then following these instructions on updating the ports tree will also suffice to create a new ports tree on your system!) The ports tree is divided into many categories, each of which appears as a subdirectory under /usr/ports. The EMBOSS port is in the "biology" category (and subdirectory). Before you go to the trouble of installing the EMBOSS port, you may want to ensure that the ports tree on your system contains the most recent version of it. To check the version of your EMBOSS port, execute the following commands (you do not have to be root): $ cd /usr/ports $ make search key=emboss The output should be similar to the following: Port: emboss-1.0.0 Path: /usr/ports/biology/emboss Info: A collection of open source tools for genetic sequence analysis Maint: johann@egenetics.com Index: biology B-deps: gd-1.8.3 gettext-0.10.35 gmake-3.79.1 jpeg-6b libtool-1.3.4 png-1.0.8 R-deps: gd-1.8.3 jpeg-6b png-1.0.8 The "Port:" line indicates the version of EMBOSS in your ports tree. If it lags significantly behind the version of EMBOSS available on the EMBOSS web site, you should probably update your ports tree before installing the EMBOSS port. You can find the most recent available version of the EMBOSS port for FreeBSD by scanning through this page: http://www.freebsd.org/ports/biology.html If the version given on this page *also* lags well behind the latest release, then please email the maintainer of the FreeBSD EMBOSS port, given in the "Maint:" line of the output given above. * Updating the FreeBSD ports tree Updating the FreeBSD ports tree is quite simple, and is a good thing to learn to do... and then do regularly. The FreeBSD ports tree (and indeed the FreeBSD source and documentation trees as well) is available via a protocol called CVSup. Before you can update your ports tree you need to install the CVSup client program. As root: # cd /usr/ports/net/cvsup-bin && make install clean Next, you should find a FreeBSD CVSup mirror, preferably one near you. FreeBSD CVSup mirrors are usually named: cvsup[number][.countrycode].freebsd.org In the United Kingdom, you may get "cvsup.uk.freebsd.org" and "cvsup2.uk.freebsd.org", whereas in the United States you may find "cvsup.freebsd.org", "cvsup2.freebsd.org", etc. If you can't find a mirror near you, you can always fall back on the central "cvsup.freebsd.org". You now need to ensure that the following lines appear in /etc/make.conf on your system: SUP_UPDATE= yes SUP= /usr/local/bin/cvsup SUPFLAGS= -g -L 2 SUPHOST= cvsup.uk.freebsd.org PORTSSUPFILE= /usr/share/examples/cvsup/ports-supfile "SUPHOST" should refer to the CVSup server you have chosen to use. (Note that you can copy these lines into /etc/make.conf from /etc/defaults/make.conf, and uncomment them.) You can now update your ports tree by simply changing to /usr/ports and executing, as root: # make update After your ports tree has been updated, you can optionally rebuild the ports index. This allows you (amongst other things) to search the ports tree with a "make search". To do so, simply go to /usr/ports and (as root) do a # make index *** Note for advanced users no. 1 *** The update of the ports tree is an ideal candidate process for inclusion in the daily housekeeping tasks. To do so, create the following little shell script in "/usr/local/etc/periodic/daily/", naming it "500.portsupdate". #!/bin/sh if [ -x /usr/bin/make -a -f /usr/ports/Makefile ] ; then echo "" echo "Starting CVSup update of /usr/ports:" echo " (output saved to /var/tmp/portsupdate.out)" cd /usr/ports && make update index > /var/tmp/portsupdate.out 2>&1 & fi *** Note for advanced users no. 2 *** If your bandwidth is restricted or you have some other reason for not wanting to update the entire ports tree, you may use a utility called "porteasy" to update only the required parts of the ports tree. Porteasy itself is available as a port in the "misc" category. Once it is installed, you can study its man page for further details. * ------------------------------------------------------------------------- * * Updating the EMBOSS port * * ------------------------------------------------------------------------- * To find out whether your ports tree contains a newer version of EMBOSS than you currently have installed, issue the following command: $ pkg_version -v | grep emboss If a newer EMBOSS is available, the output will resemble this: "emboss-1.0.0 < needs updateing (index has 1.7.0)" If you simply want to find the version of EMBOSS installed on your system, issue this command: $ pkg_info | grep emboss The output may look something like this: "emboss-1.0.0 A collection of open source tools for genetic sequence analysis" Either command tells you that the installed version of the port is "emboss-1.0.0". You need to deinstall the old version of the port first before you can install a later version. You can update the installed port with the minimum of disruption by following the following procedure (as root). The "pkg_delete" command must be given the currently installed version of the EMBOSS port as parameter: # cd /usr/ports/biology/emboss # make build # pkg_delete emboss-1.0.0 # make install clean Note that this update will NOT overwrite the system-wide EMBOSS configuration file, /usr/local/etc/emboss.default. It will, however, create a new sample configuration file, /usr/local/etc/emboss.default.sample. You may want to merge in any changes from the new sample configuration file manually after the upgrade. * ------------------------------------------------------------------------- * * When in doubt... * * ------------------------------------------------------------------------- * If you are uncertain about anything, you may always email the current maintainer of the FreeBSD port of EMBOSS. As shown before, you can find out who the maintainer is by changing directory to /usr/ports and issuing this command: $ make search key=emboss At the time of writing, the author of this document maintains the FreeBSD EMBOSS port. There exists a mailing list for FreeBSD users in bioinformatics and other biocomputing fields. The members of this mailing list are aware of the EMBOSS port and may also be able to provide some support. You may subscribe to this mailing list by filling in the web form at the following URL: http://www.plig.net/mailman/listinfo/freebsd-bio * ------------------------------------------------------------------------- * -- Johann Visagie $Id: EMBOSS-FreeBSD-HOWTO.txt,v 1.1 2001/03/15 13:52:37 gwilliam Exp $