Crux Installation Instructions

This page will walk you through the steps of installing crux on your computer. Seperate sections describe the installation for Linux, OS X, and Windows. You have the choice of installing precompiled binaries or building Crux from the source code. The compiled binaries offer the easiest installation option.

Linux

Note: when typing the commands shown in these instructions do not type the leading $ before each command; it indicates the prompt. These instructions will refer to your home directory as $HOME. You can type $HOME in the commands or you can use the fully qualified path to your home directory which may be something like /home/yourname/. Note that you can find out the location of your home directory by logging in and typing pwd or echo $HOME.

Installing Pre-compiled Crux Binaries on Linux

  • Download the files

    Crux is freely available for download under an Apache 2.0 license. On the download page click on the link "Linux [architecture] Build (zipped)" to download them to your computer. If your computer is running a 32-bit version of Linux select the i686 version. If your computer is running a 64-bit version of Linux select the x86_64 version. If a window pops up, select the "Save" button. To check that the file was transfered correctly, run this command

    $ md5sum [downloaded file]

    and compare the output to the "MD5 checksum" link next to the file you downloaded.

  • Unpack and install the files

    The file you downloaded should be named something like crux-x.xx-XXXX-GNU-Linux.zip where x.xx is replaced with the most current release version. and XXXX is either i686 or x86_64. Move this file to a convenient location and unpack the file with this command.

    $ unzip crux-x.xx-XXXX-GNU-Linux.zip

    You should now have a new directory, crux-x.xx-XXXX-GNU-Linux, with two subdirectories bin, and doc. The crux programs are in the bin directory. You may want to move these files somewhere more convenient for you, but otherwise, that completes the installation! Skip ahead to Setting the PATH on Linux and OS X for notes on how to run the executables.

Building Crux From Source on Linux

  • Prerequisites

    To build Crux from source on Linux you must have installed the following software:

    • gcc
    • g++
    • cmake
    • make
    • svn
    • wget (must support SSL)

    Building crux also requires the Proteowizard and Percolator libraries. These will automatically be copied from the Proteowizard and Percolator repositories and statically linked into crux.

  • Download the files

    The Crux source is freely available for download under an Apache 2.0 license>. On the download page click on the link "Source (tarred, gzipped)", and choose save to disk if prompted. To check that the file was transfered correctly, run this command

    $ md5sum [downloaded file]

    and compare the output to the "MD5 checksum" link next to the file you selected on the Crux download page.

    The file you downloaded should be named something like crux-x.xx.source.tar.gz, where x.xx is replaced with the most current release version.

  • Unpack the files

    Move the downloaded file to a convenient location and unpack it with this command.

    $ tar -zxvf crux-x.xx.Source.tar.gz
    A new directory named crux-x.xx.Source will be created and a long list of files will stream by as they are being put into the new directory.

  • Configure the build

    Move into the crux-x.xx.Source directory from step 1. Run the command

    cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX:PATH=<install directory> .

    where <install directory> is the location where you wish to install the crux programs. If you want crux to go in $HOME/bin, then <install directory> would be $HOME. The installation process will automatically put the programs in a directory called bin.

    Note, this configuration will build with optimizations turned on, and will not include debug symbols. To build with optimizations turned off, and debug symbols included, use the command:

    cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX:PATH=<install directory> .

  • Build and install

    To complete the process, run these two commands.

    • $ make
    $ make install

    The crux programs are in the bin subdirectory of the <install directory> That completes the installation! Skip ahead to Setting the PATH on Linux and OS X for notes on how to run the executables.

OS X

Crux requires OS X Yosemite or later.

Note: when typing the commands shown in these instructions do not type the leading $ before each command; it indicates the prompt. These instructions will refer to your home directory as $HOME. You can type $HOME in the commands or you can use the fully qualified path to your home directory which may be something like /home/yourname/. Note that you can find out the location of your home directory by logging in and typing pwd or echo $HOME.

To install and use crux on OS X you'll need to be familiar with the Terminal application.

Installing Pre-compiled Crux Binaries on OS X

  • Download the files

    Crux is freely available for download under an Apache 2.0 license. On the download page click on the link "OS X x86_64 Build (zipped)" to download them to your computer. If a window pops up, select the "Save" button. To check that the file was transfered correctly, run this command

    $ md5 [downloaded file]

    and compare the output to the "MD5 checksum" link next to the file you downloaded.

  • Unpack and install the files

    The file you downloaded should be named something like crux-x.xx.Darwin.x86_64.zip where x.xx is replaced with the most current release version. Move this file to a convenient location and unpack the file with this command.

    $ unzip crux-x.xx.Darwin.x86_64.zip

    You should now have a new directory, crux-x.xx.Darwin.x86_64, with two subdirectories bin, and doc. The crux programs are in the bin directory. You may want to move these files somewhere more convenient for you, but otherwise, that completes the installation! Skip ahead to Setting the PATH on Linux and OS X for notes on how to run the executables.

Building Crux From Source on OS X

  • Prerequisites

    To build Crux from source on OS X you must have installed the following software:

    • OS X Yosemite or later
    • XCode 6.3.1 or later
    • XCode Command Line Tools
    • cmake
    • make
    • svn
    • wget (must support SSL)
    • gnutar (Apple's version of tar is incompatible with GNU's version of tar)

    Building crux also requires the Proteowizard and Percolator libraries. These will automatically be copied from the Proteowizard and Percolator repositories and statically linked into crux.

    Building Crux on OS X requires a current version of XCode, and the XCode command line tools. Earlier versions of Crux had to be built using the GCC compilers. which are no supported by Apple.

    The programs cmake, svn, and wget, can be installed from MacPorts or Homebrew. Note that you must install the ssl variant of wget:

    $ sudo port install wget +ssl

  • Download the files

    The Crux source is freely available for download under an Apache 2.0 license>. On the download page click on the link "Source (tarred, gzipped)", and choose save to disk if prompted. To check that the file was transfered correctly, run this command

    $ md5sum [downloaded file]

    and compare the output to the "MD5 checksum" link next to the file you selected on the Crux download page.

    The file you downloaded should be named something like crux-x.xx.source.tar.gz, where x.xx is replaced with the most current release version.

  • Unpack the files

    Move the downloaded file to a convenient location and unpack it with this command.

    $ tar -zxvf crux-x.xx.Source.tar.gz
    A new directory named crux-x.xx.Source will be created and a long list of files will stream by as they are being put into the new directory.

  • Configure the build

    Move into the crux-x.xx.Source directory from step 1. Run the command

    cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX:PATH=<install directory> .

    where <install directory> is the location where you wish to install the crux programs. If you want crux to go in $HOME/bin, then <install directory> would be $HOME. The installation process will automatically put the programs in a directory called bin.

    Note, this configuration will build with optimizations turned on, and will not include debug symbols. To build with optimizations turned off, and debug symbols included, use the command:

    cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX:PATH=<install directory> .

  • Build and install

    To complete the process, run these two commands.

    • $ make
    $ make install

    The crux programs are in the bin subdirectory of the <install directory> That completes the installation! Skip ahead to Setting the PATH on Linux and OS X for notes on how to run the executables.

Setting the PATH on Linux and OS X

  • On Linux and OS X systems you can always run any of the programs by specifying its full path. For example,

    $ <install directory>/bin/crux comet

    In this final step of the installation, we'll set things up so that you can also run any of the programs by just typing its name. This is done with an environment variable called $PATH. $PATH is a list of places that the computer looks for executable programs. Find out what is in the current list with this command:

    $ echo $PATH

    The value returned might look something like this: /usr/local/bin:/usr/bin:/bin:/usr/bin/X11:/usr/games

    The first directory in this colon-separated list, /usr/local/bin, is the first place the computer looks for a program. If it doesn't find the program there it tries /usr/bin and so on down the list. You can either move the crux executable files into one of these directories already in your PATH, or you can add <install directory> to PATH with this command. (Remember to replace the word <install directory> with the actual location of your installation)

    $ export PATH=$PATH:<install directory>/bin

    Try 'echo $PATH' again to see that the change was made. <install directory>/bin should be at the end of the list. Now you can run the crux programs by just typing their names. Try this.

    $ crux comet

    The change to $PATH is only temporary. As soon as you close the window, the change will disappear. In order to make the change every time you log on, add the line export PATH=$PATH:<install directory>/bin to the file .bashrc located in your home directory. You will have to log on again for the change to take effect.

Windows

Installing Pre-compiled Crux Binaries on Windows

  • Prerequisites

    To run Crux with support for vendor specific file formats on Windows you must have installed the following software:

  • Download the files

    Crux is freely available for download under an Apache 2.0 license. On the download page click on the link "Windows x86 Build (zipped)" to download them to your computer. If a window pops up, select the "Save" button.

  • Unpack and install the files

    Browse to the downloaded file in Windows Explorer. Right click on the file and choose "Expand All ...". You should now have a new directory, crux-x.xx, with two subdirectories bin, and doc. The crux programs are in the bin directory. You may want to move these files somewhere more convenient for you, but otherwise, that completes the installation! Skip ahead to Setting the PATH on Windows for notes on how to run the executables.

Building Crux From Source on Windows

  • Prerequisites

    To build Crux from source on Windows you must have installed the following software:

    Other verions of Visual Studio will not be able to build Crux! You must have Visual Studio 2013. Visual Studio 2013 Express for Windows Desktop does work.

    wget is available as part of the GnuWin32 package. The easiest way to install this is via the GetGnuWin32 package manager. wget must support SSL, so install the optional packages provided by GetGnuWin32 .

    wget and svn must be included in the execution PATH for your system. See the section Setting the PATH on Windows for more information.

  • Download the file

    The Crux source is freely available for download under an Apache 2.0 license>. On the download page click on the link "Source (zipped)", and choose save to disk if prompted.

    The file you downloaded should be named something like crux-x.xx.Source.zip, where x.xx is replaced with the most current release version.

  • Unpack the files

    Unpack the downloaded file using Windows Explorer. Right click on the file icon and click on "Extract All ...". A new directory named crux-x.xx.Source will be created containing the source code and documentation for Crux.

    Note Windows has a fixed maximum path length of 270 characters. The Crux build creates several levels of directories so it is very easy to exceed this limit. This will cause the build to fail. To avoid this problem we recommend keeping the Crux source and build trees very near the disk root (typically C:\

  • Open the command line development environment.

    Under the "Start" button open the "Visual Studio 2013" folder, then open the "Visual Studio Tools" folder, and double-click on "Developer Command Prompt for VS2013". This will launch a cmd shell configured to use the Microsoft development tools.

  • Configure

    In the cmd shell you just opened, move into the crux-x.xx.Source directory from step 1. Run the command

    cmake -DCMAKE_INSTALL_PREFIX:PATH=<install directory> -G "Visual Studio 12 Win64" .

    where <install directory> is the location where you wish to install the crux programs. Note that, somewhat confusingly, Visual Studio 2013 is version 12.

    If you wish to disable support for vendor specific file formats, use this command instead

    cmake -DCMAKE_INSTALL_PREFIX:PATH=<install directory> -DINCLUDE_VENDOR_LIBRARIES=FALSE -G "Visual Studio 12 Win64" .

  • Build and install

    To complete the process run the commands

    • cmake --build . --config Release --target ALL_BUILD
    cmake --build . --config Release --target INSTALL

    Once you've run the configuration step you can also build and debug Crux from within the Visual Studio IDE. CMake will generate a file named crux.sln. Open this file in Visual Studio. You can select the build configuration: Release or Debug in the combo box under the menu bar.

    Note The Crux build will not automatically generate debugging symbols even if you've selected the Debug configuration. Right click on the Crux folder in the "Solution Explorer" and select "Properties" from the pop-up menu. In the "Properties" page select the "Debugging" item under the "Linker" properties. Set "Generate Debug Info" to "Yes".

    Changes made to the Visual Studio solution and project files will be lost the next time CMake regenerates the project.

Setting the PATH on Windows

  • On Windows systems you can always run any of the programs by specifying its full path. For example,

    C:\ <install directory>\bin\crux comet

    In this final step of the installation, we'll set things up so that you can also run any of the programs by just typing its name. This is done with an environment variable called PATH. PATH is a list of directoires that the computer looks for executable programs. Find out what is in the current list with this command:

    C:\ echo %PATH%

    The value returned might look something like this:

    C:\Windows;C:\Windows\system32;c:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE\;c:\Program Files\Microsoft Visual Studio 10.0\VC\BIN;C:\Program Files\Common Files\Microsoft Shared\ Windows Live;C:\Windows\System32\Wbem;C:\Windows\S ystem32\WindowsPowerShell\v1.0\;c:\Program files\Notepad++;C:\Program Files\Tort oiseSVN\bin;C:\Program Files\Windows Live\Shared;C:\Program Files\CMake 2.8\bin; C:\Program Files\PuTTY;C:\Program Files\Subversion\bin;C:\GnuWin32\bin;

    The first directory in this semicolon-separated list, C:\Windows, is the first place the computer looks for a program. If it doesn't find the program there it tries C:\WIndows\system32 and so on down the list. You can either move the crux executable files into one of these directories already in your PATH, or you can add <install directory> to PATH with this command. (Remember to replace the word <install directory> with the actual location of your installation)

    set PATH=%PATH%;<install directory>\bin;

    The change to PATH is only temporary. To make a permanent change to the path follow the following steps:

    1. Open the "Control Panel".
    2. Click on "System and Security".
    3. Click on "Advanced System Settings" in the list on the left (you may be asked to give an administrative password).
    4. You'll presented with a dialog box titled "System Properties". Click on the button labeled "Environment Variables".
    5. You'll be presented with a new dialog box containing two list boxes: one for user environment variables, and one for system environment variables. Select the PATH variable in the system variables list, and click on the "Edit ..." button.
    6. Add the full path to the directory containing the Crux executables to the list of directories. Remember that each PATH entry should end with a semi-colon.