Installation Guide

This guide will help you set up the VHDL Digital Design Samples project on your local machine.

Prerequisites

Before you begin, ensure you have the following installed:

System Requirements

  • Operating System: macOS, Linux (Ubuntu/Debian), or Windows with WSL

  • Memory: At least 2GB RAM

  • Storage: 100MB free space

  • Internet: Required for downloading dependencies

Required Software

  1. Git (for cloning the repository)

  2. GHDL (VHDL simulator and compiler)

  3. Make (build system)

  4. Python 3.7+ (for documentation, optional)

Installation Steps

Step 1: Clone the Repository

git clone https://github.com/shishir-dey/vhdl-samples.git
cd vhdl-samples

Step 2: Install GHDL

On macOS (using Homebrew):

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install GHDL
brew install ghdl

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install ghdl

On Windows (using WSL):

First, install Windows Subsystem for Linux (WSL), then follow the Ubuntu instructions.

Verify Installation:

ghdl --version

You should see output similar to:

GHDL 5.0.1 (4.1.0.r602.g37ad91899) [Dunoon edition]

Step 3: Verify Make

Check if Make is installed:

make --version

If not installed:

On macOS:

xcode-select --install

On Ubuntu/Debian:

sudo apt-get install build-essential

Step 4: Test the Installation

Run the project’s test suite to verify everything is working:

make test

Expected output:

βœ“ GHDL found: GHDL 5.0.1 (4.1.0.r602.g37ad91899) [Dunoon edition]
Running complete test suite...
==================================================
           VHDL Test Suite Runner
==================================================

=== Testing gates ===
Testing: or_gate_tb
βœ“ Test passed
Testing: xor_testbench
βœ“ Test passed

=== Testing combinational ===
Testing: decoder_2x4_testbench
βœ“ Test passed
Testing: mux_2x1_tb
βœ“ Test passed
Testing: fa_testbench
βœ“ Test passed
Testing: ha_behave_tb
βœ“ Test passed
Testing: rc_adder_testbench
βœ“ Test passed

=== Testing sequential ===
Testing: d_flip_flop_tb
βœ“ Test passed

Total Tests: 8
Passed: 8
Failed: 0

πŸŽ‰ All tests passed!

Optional: Documentation Setup

If you want to build the documentation locally:

# Install Python dependencies
pip install -r docs/requirements.txt

# Build documentation
cd docs
make html

# View documentation
open _build/html/index.html  # macOS
xdg-open _build/html/index.html  # Linux

Quick Start Commands

Once installed, here are the most useful commands:

# Show all available targets
make help

# Run all tests
make test

# Test specific categories
make test-gates
make test-combinational
make test-sequential

# Test individual components
make test-or-gate
make test-decoder
make test-dff

# Build all sources (syntax check)
make build

# Show project statistics
make stats

# Clean build artifacts
make clean

Troubleshooting

Common Issues

GHDL not found:

Error: GHDL is not installed or not in PATH

Solution: Ensure GHDL is properly installed and in your system’s PATH.

Permission denied:

./scripts/run_tests.sh: Permission denied

Solution: Make the script executable:

chmod +x scripts/run_tests.sh

Test failures:

❌ Some tests failed.

Solution: Check the detailed error messages and ensure your GHDL version is compatible.

Make command not found:

Solution: Install build tools for your platform (see Step 3 above).

Getting Help

If you encounter issues:

  1. Check the Changelog for known issues

  2. Search existing GitHub Issues

  3. Create a new issue with: - Your operating system - GHDL version (ghdl --version) - Complete error message - Steps to reproduce

Development Environment

For development work, consider installing:

Code Editor Extensions:

  • VS Code: VHDL Language Support extension

  • Vim: vim-vhdl plugin

  • Emacs: VHDL mode

Additional Tools:

# Wave viewer for signal analysis
brew install gtkwave  # macOS
sudo apt-get install gtkwave  # Ubuntu

Environment Variables:

Add to your .bashrc or .zshrc:

export VHDL_SAMPLES_HOME=/path/to/vhdl-samples
export PATH=$PATH:$VHDL_SAMPLES_HOME/scripts

Next Steps

After successful installation:

  1. Explore the Quick Start Guide guide

  2. Learn about the Project Structure

  3. Run through the Basic Logic Gates examples

  4. Try Contributing Guide your own components

Performance Optimization

For faster compilation and testing:

Parallel Testing:

# Use multiple cores for faster builds
export MAKEFLAGS=-j$(nproc)  # Linux
export MAKEFLAGS=-j$(sysctl -n hw.ncpu)  # macOS

GHDL Optimization:

# Add to ~/.bashrc for faster GHDL compilation
export GHDL_PREFIX=/opt/homebrew  # macOS with Homebrew
export GHDL_PREFIX=/usr  # Linux

System Integration

IDE Integration:

Most modern IDEs can be configured to use the project’s Makefile:

  • Build Command: make build

  • Test Command: make test

  • Clean Command: make clean

Shell Completion:

For Bash/Zsh completion of make targets:

# Add to your shell config
complete -W "$(make -pRrq : 2>/dev/null | awk -F: '/^[a-zA-Z0-9][^$#\/\t=]*:([^=]|$)/ {split($1,A,/ /);for(i in A)print A[i]}' | sort -u)" make