### Step 1: Understand What You’re Getting Into

Vina-Carb isn’t a pre-packaged executable you can just download and run. It’s a source-code-based tool, meaning you’ll need to compile it yourself. You’ll also need specific dependencies, like the Boost C++ libraries, and a compiler like GCC (for Linux) or Visual Studio (for Windows). The process involves downloading the source code, setting up the environment, and building the executable. Don’t worry if this sounds daunting—I’ll break it down into manageable steps.

---

### Step 2: Check Your System Requirements

Before you start, make sure your system is ready:

- **Operating System**: Vina-Carb works on Linux, Windows, or macOS, but Linux is the most straightforward for compilation. I’ll assume you’re on a Linux system (like Ubuntu) unless you specify otherwise.

- **Compiler**: You’ll need a C++ compiler. On Linux, GCC is recommended. On Windows, Visual Studio (Community Edition is fine) works. On macOS, Xcode is the go-to.

- **Boost Libraries**: Vina-Carb requires Boost version 1.41.0 (the version used for the original AutoDock Vina 1.1.2). Other versions might work, but they’re untested, so stick with 1.41.0 to avoid headaches.

- **Disk Space**: Ensure you have a few gigabytes free for the source code, dependencies, and compiled files.

- **Command-Line Comfort**: You’ll need to use a terminal (Linux/macOS) or Command Prompt/PowerShell (Windows).

If you’re on Windows and prefer a simpler setup, you might consider using a Linux virtual machine or WSL2 (Windows Subsystem for Linux) to follow the Linux instructions.

---

### Step 3: Install Dependencies

First, you need to set up the tools and libraries Vina-Carb needs.

#### On Linux (Ubuntu/Debian)

1. **Update Your System**:

Open a terminal and run:

```bash

sudo apt update && sudo apt upgrade

```

This ensures your system is up to date.

2. **Install GCC**:

Install the GCC compiler suite if it’s not already on your system:

```bash

sudo apt install build-essential g++

```

3. **Install Boost 1.41.0**:

Vina-Carb specifically needs Boost 1.41.0. Newer versions might cause issues, so let’s stick with the recommended one.

- Download Boost 1.41.0 from the Boost website or a trusted archive:

```bash

wget https://sourceforge.net/projects/boost/files/boost/1.41.0/boost_1_41_0.tar.gz

```

- Extract the tarball:

```bash

tar -xzvf boost_1_41_0.tar.gz

cd boost_1_41_0

```

- Build and install Boost:

```bash

./bootstrap.sh

./b2 install --prefix=/usr/local/boost_1_41_0

```

This installs Boost to `/usr/local/boost_1_41_0`. Note the path—you’ll need it later.

4. **Verify Boost Installation**:

To confirm Boost is installed correctly, try compiling a simple Boost example (like the Regex example from the Boost documentation). If you run into issues, check the Boost community forums for help.

#### On Windows

- **Install Visual Studio**: Download and install Visual Studio Community Edition (free) from Microsoft’s website. Make sure to include the C++ development workload.

- **Install Boost 1.41.0**:

- Download the Boost 1.41.0 source from SourceForge.

- Extract it to a folder, e.g., `C:\boost_1_41_0`.

- Open the Visual Studio Developer Command Prompt and navigate to the Boost folder:

```cmd

cd C:\boost_1_41_0

```

- Build Boost:

```cmd

bootstrap.bat

b2 --prefix=C:\boost_1_41_0 install

```

- Add the Boost path to your environment variables (more on this later if needed).

#### On macOS

- **Install Xcode**: Get Xcode from the Mac App Store and install the command-line tools:

```bash

xcode-select --install

```

- **Install Boost 1.41.0**: Follow the same steps as for Linux, adjusting paths as needed (e.g., install to `/usr/local/boost_1_41_0`).

---

### Step 4: Download Vina-Carb Source Code

Now, grab the Vina-Carb source code from the official GLYCAM website:

1. Visit [glycam.org](http://glycam.org) and navigate to the “Other Tools & Services” section.

2. Find the Vina-Carb download link (it’s usually labeled as the source code for Vina-Carb 1.0).

3. Download the source code (likely a `.zip` or `.tar.gz` file). For example:

```bash

wget http://glycam.org/docs/othertoolsservices/files/VC_1_0.zip

```

4. Extract the file:

```bash

unzip VC_1_0.zip

cd VC_1_0

```

---

### Step 5: Set the VINA_CARB Environment Variable

Vina-Carb needs an environment variable to know where its parent directory (`VC_1_0`) is located.

1. Find the full path to the `VC_1_0` directory. If you extracted it in your home directory, it might be something like `/home/username/VC_1_0`.

2. Set the environment variable:

```bash

export VINA_CARB=/home/username/VC_1_0

```

3. To make this permanent, add it to your `~/.bashrc` or `~/.bash_profile`:

```bash

echo 'export VINA_CARB=/home/username/VC_1_0' >> ~/.bashrc

source ~/.bashrc

```

For Windows, set the environment variable via the System Properties:

- Right-click “This PC” > Properties > Advanced system settings > Environment Variables.

- Add a new variable named `VINA_CARB` with the path to the `VC_1_0` folder (e.g., `C:\VC_1_0`).

---

### Step 6: Compile Vina-Carb

Now it’s time to build the Vina-Carb executable. This step assumes you’re following the instructions for compiling AutoDock Vina from source, as Vina-Carb builds on it.

#### On Linux

1. Navigate to the Vina-Carb source directory (e.g., `VC_1_0/build/linux/release`).

2. Edit the `Makefile` to point to your Boost installation:

- Open the `Makefile` in a text editor (e.g., `nano Makefile`).

- Set the `BASE` variable to your Boost path (e.g., `/usr/local/boost_1_41_0`).

- Set `BOOST_VERSION` to `1_41_0`.

- Example:

```makefile

BASE=/usr/local/boost_1_41_0

BOOST_VERSION=1_41_0

```

3. Compile the source code:

```bash

make

```

This creates an executable named `vina-carb`.

#### On Windows

1. Open Visual Studio and create three projects: `lib`, `main`, and `split`.

- `lib`: A library project using source files from the `VC_1_0/src/lib` directory.

- `main` and `split`: Console applications using source files from `VC_1_0/src/main` and `VC_1_0/src/split`, respectively.

- Ensure `main` and `split` depend on `lib`.

2. Configure the projects to include the Boost 1.41.0 headers and libraries (set the include and library paths in Project Properties).

3. Build the solution in **Release mode** for optimal performance. This generates the `vina-carb.exe` executable.

#### On macOS

Follow the Linux instructions, but use the `build/macos/release` directory instead. Adjust the `Makefile` paths as needed.

---

### Step 7: Test the Installation

Once compiled, test the Vina-Carb executable to ensure it works:

1. Navigate to the directory containing `vina-carb` (e.g., `VC_1_0/build/linux/release`).

2. Run:

```bash

./vina-carb --help

```

On Windows, use:

```cmd

vina-carb.exe --help

```

3. You should see a help message with Vina-Carb’s command-line options, including the standard AutoDock Vina options plus two new ones:

- `chi_coeff [1.0]`: Adjusts the CHI-energy penalty magnitude (0 switches to regular AutoDock Vina).

- `chi_cutoff [2.0]`: Negates CHI-energy penalties below this value (12 switches to AutoDock Vina).

If you see the help message, congratulations—you’ve installed Vina-Carb!

---

### Step 8: Prepare for Docking

To use Vina-Carb, you’ll need properly formatted input files:

- **Ligand File**: The carbohydrate ligand must be in `.pdbqt` format and follow standard carbohydrate nomenclature for atom names. You can prepare this using AutoDockTools (ADT):

1. Download and install MGLTools from [http://mgltools.scripps.edu](http://mgltools.scripps.edu).

2. Open your carbohydrate `.pdb` file in ADT, add hydrogens and torsions, and save as `.pdbqt`.

- **Receptor File**: The protein receptor should also be in `.pdbqt` format, prepared with tools like ADT or Chimera.

- **Config File**: Create a plain text `.cfg` file specifying docking parameters (e.g., search space, exhaustiveness). Example:

```text

receptor = protein.pdbqt

ligand = carbohydrate.pdbqt

out = output_models.pdbqt

log = log.txt

center_x = 10.0

center_y = 20.0

center_z = 30.0

size_x = 20

size_y = 20

size_z = 20

exhaustiveness = 8

chi_coeff = 1.0

chi_cutoff = 2.0

```

---

### Step 9: Run a Test Docking

Try a test docking to confirm everything works:

1. Place your `protein.pdbqt`, `carbohydrate.pdbqt`, and `config.cfg` files in the same directory as `vina-carb`.

2. Run:

```bash

./vina-carb --config config.cfg

```

On Windows:

```cmd

vina-carb.exe --config config.cfg

```

3. Check the `log.txt` and `output_models.pdbqt` files for results.

---

### Troubleshooting Tips

- **Boost Issues**: If compilation fails, double-check your Boost version and paths. Stick to 1.41.0 to avoid compatibility problems.

- **Ligand Nomenclature**: If Vina-Carb crashes, ensure your carbohydrate ligand follows standard nomenclature (see GLYCAM documentation for details).

- **Permissions**: On Linux/macOS, ensure you have execute permissions for `vina-carb` (`chmod +x vina-carb`).

- **Windows Path Issues**: If `vina-carb.exe` isn’t found, add its directory to your system PATH or run it with the full path.

- **Still Stuck?**: Check the GLYCAM website, ResearchGate discussions, or the AutoDock Vina community for help. The Vina-Carb paper (J. Chem. Theory Comput. 2016, 12, 892–901) also has useful details.

---

### Optional: Install MGLTools for Easier Prep

MGLTools and AutoDockTools are super helpful for preparing ligands and receptors. On Windows:

1. Download the `.msi` installer from [http://mgltools.scripps.edu](http://mgltools.scripps.edu).

2. Double-click to install, following the prompts.

3. Use AutoDockTools to prepare your `.pdbqt` files.

On Linux/macOS, download the appropriate package and follow the installation instructions on the MGLTools website.