Crux Installation Instructions
This page will walk you through the steps of installing Crux on your computer. Separate sections describe the installation for Linux, MacOS, and Windows. You have the choice of installing pre-compiled binaries or building Crux from the source code. The compiled binaries offer the easiest installation option. Only the Windows version of Crux supports the vendor specific file formats.Downloading
Crux is freely available for download under an Apache 2.0 license. The current stable and development releases are available from the download page. Older releases can be found in the GitHub releases page. Here we will describe how to download the latest stable or development release from the download page.- click on the list box under "Choose Download Type", and select the distribution
you want. Available choices are:
- Linux X86-64
- MacOS X86-64
- MacOS ARM64
- Windows X86-64
- Source
- Read the license agreements.
-
At the bottom of the page there are two buttons:
- Stable Release
- Click on the button labeled "I agree to the licensing terms, download release x.x of Crux" to download the latest stable release of crux.
- Latest Development Release
- Click on the button labeled "I agree to the licensing terms, download the most recent build of Crux" to download the latest development version of crux.
Linux
Installing Pre-compiled Crux Binaries on Linux
- The current Linux binary of Crux is compiled on Ubuntu 22.04 for X86-64,
but should work on most Linux distributions.
It requires that version 2.39 or later of the C runtime library be installed.
You can determine which version of the C runtime library is installed
by running
ldd --version
- Unpack and install the files
The file you downloaded
should be named something like
crux-x.xx.Linux.x86_64
where x.xx
is replaced with the current release version
Move this file
to a convenient location and unpack the file with this command:
You should now have a new directory, crux-x.xx.Linux.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 MacOS for notes on how to run the executables.
unzip crux-x.xx.Linux.x86_64.zip
Building Crux From Source on Linux
- Prerequisites
To build Crux from source on Linux you must have installed the
following software:
gcc
g++
cmake
(version 3.24 or later recommended)make
git
The file you downloaded should be named something like
crux-x.xx.source.tar.gz,
where x.xx
is replaced with the 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.gzA 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
Note: These instructions 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 typingpwd
orecho $HOME
. Move into the crux-x.xx.Source directory from step 1. Run the commandwhere <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=Release -DCMAKE_INSTALL_PREFIX:PATH=<install directory> .
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
MacOS
Pre-compiled binaries of Crux are available for both MacOS 13 on X86-64 and MacOS 15 on Apple silicon (ARM64). To install and usecrux
on MacOS
you'll need to be familiar with the Terminal
application.
Installing Pre-compiled Crux Binaries on MacOS
- Unpack and install the files
The file you downloaded
should be named
crux-x.xx.Darwin.x86_64.zip,
or
crux-x.xx.Darwin.arm64.zip,
where x.xx
is replaced with the most current release version.
Move this file
to a convenient location and unpack the file using the
unzip
command. For example,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 MacOS for notes on how to run the executables.unzip crux-x.xx.Darwin.x86_64.zip
Building Crux From Source on MacOS
- Prerequisites
To build Crux from source on MacOS you must have installed the
following software:
MacOS 13 (Ventura) or later
XCode Command Line Tools
cmake
(version 3.24 or later recommended)make
git
gnutar
(Apple's version of tar is incompatible with GNU's version of tar)
export CC=/usr/bin/gcc
export CXX=/usr/bin/g++ - Unpack the files
Move the downloaded file to a
convenient location and unpack it with this command.
tar -zxvf crux-x.xx.Source.tar.gzA 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
Note:
These instructions 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 typingpwd
orecho $HOME
. Move into the crux-x.xx.Source directory from step 1. Run the commandwhere <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=Release -DCMAKE_INSTALL_PREFIX:PATH=<install directory> .
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
Setting the PATH on Linux and MacOS
-
On Linux and MacOS 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:
- 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:
Microsoft Visual Studio C++ 2022 or later.
When installing Visual Studio check the "Individual Components" tab
and make sure the following are installed:
- .NET Framework 4.8 SDK
- .NET Framework 4.7 target pack
- Windows Universal C Runtime
- C++ MFC for latest v143 build tools
- Windows 11 SDK (10.0.22000..0)
- v142 - VS 2019 C++ x64/x86 build tools
- C++ v14.29 (16.11) ATL for v142 build tools
- C++/CLI support for v142 build tools
- MSVC v143 VS 2022 C++ x64/x86 build tools
CMake (version 3.24 or later recommended)
git
unzip
Windows wget (version 1.20 or later)
-
Thermo MSFileReader V3.0 SP3
(This may be omitted if support for vendor specific file formats is disabled.)
- Download the file 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.
In the file explorer, open the open the folder
\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools
. Double-click on theLaunchDevCmd.bat
file (you may want to create a shortcut to this file on your desktop). 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
where <install directory> is the location where you wish to install the crux programs. Note that, somewhat confusingly, Visual Studio 2019 is version 16. If you wish to disable support for vendor specific file formats, use this command instead
cmake -DCMAKE_INSTALL_PREFIX:PATH=<install directory> -G "Visual Studio 16" -A X64 .
cmake -DCMAKE_INSTALL_PREFIX:PATH=<install directory> -DINCLUDE_VENDOR_LIBRARIES=FALSE -G "Visual Studio 15 Win64" .
- Build and install To complete the process run the commands
cmake --build . --config Release --target ALL_BUILD
cmake --build . --config Release --target INSTALL
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 directories 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:
- Open the "Control Panel".
- Click on "System and Security".
- Click on "Advanced System Settings" in the list on the left (you may be asked to give an administrative password).
- You'll presented with a dialog box titled "System Properties". Click on the button labeled "Environment Variables".
- 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.
- 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.