golang-fft/QUICKSTART.md

Quick Start Guide

This guide will help you quickly get started with building and testing the Golang AVX512 FFT implementation.

Prerequisites

• Docker: Must be installed and running
• Linux x86_64: The assembly code is x86_64 specific
• AVX512 Support: Your processor should support AVX512 instructions

Quick Start Options

Option 1: Simple Build Script (Recommended for beginners)

# Make the script executable (first time only)
chmod +x simple_build.sh

# Run the build script
./simple_build.sh

This will:

• Check Docker availability
• Create a Dockerfile
• Build the container
• Run tests and benchmarks
• Show results

Option 2: Advanced Build Script

# Make the script executable (first time only)
chmod +x build_and_test.sh

# Run interactive container
./build_and_test.sh

# Or run quick test without interaction
./build_and_test.sh --quick

# Clean up Docker resources
./build_and_test.sh --cleanup

Option 3: Makefile (For experienced users)

# Show all available commands
make help

# Build and test locally (requires Go installed)
make all

# Build and test in Docker
make docker-all

# Run interactive Docker container
make docker-run

# Clean up
make docker-clean

What Each Option Does

Simple Build Script

• Pros: Easy to use, clear output, handles everything automatically
• Cons: Less flexible, no interactive mode
• Best for: Quick testing, CI/CD, beginners

Advanced Build Script

• Pros: Full control, interactive mode, cleanup options, colored output
• Cons: More complex, more options to understand
• Best for: Development, debugging, advanced users

Makefile

• Pros: Standard tool, many targets, good for automation
• Cons: Requires Make, less visual feedback
• Best for: Development workflows, CI/CD, experienced users

Expected Output

When successful, you should see:

🚀 Starting Golang AVX512 FFT build process...
✅ Docker is available and running
📝 Creating Dockerfile...
✅ Dockerfile created
🔨 Building container...
✅ Container built successfully!

🎯 Running tests and benchmarks...
==================================
=== Building application ===
=== Running tests ===
PASS
ok      golang-fft    0.123s
=== Running benchmarks ===
goos: linux
goarch: amd64
pkg: golang-fft
BenchmarkFFT-8           1000           1234567 ns/op
BenchmarkFFTLarge-8        100          12345678 ns/op
BenchmarkIFFT-8           1000           1234567 ns/op
PASS
ok      golang-fft    0.234s
=== Application info ===
-rwxr-xr-x 1 root root 1234567 Jan 1 12:00 fft
fft: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, Go BuildID=...
=== Go environment ===
go version go1.21.0 linux/amd64
linux
amd64
v1

🎉 Build and test completed successfully!

Troubleshooting

Common Issues

1. Docker not running

   sudo systemctl start docker
   # or
   sudo service docker start
   

2. Permission denied

   chmod +x *.sh
   

3. Port already in use

   # Clean up existing containers
   ./build_and_test.sh --cleanup
   # or
   make docker-clean
   

4. Build fails

   • Check that all required files are present
   • Ensure Docker has enough memory/disk space
   • Check Docker logs: docker logs <container_name>

File Requirements

The build process requires these files:

• go.mod - Go module definition
• fft.go - Main Go implementation
• fft_avx512_working.s - AVX512 assembly code
• fft_test.go - Test suite
• README.md - Documentation

Next Steps

After successful build and test:

1. Run interactively: docker run -it --rm golang-fft
2. Test manually: Inside container, run ./fft
3. Modify code: Edit files and rebuild
4. Profile performance: Use Go's built-in profiling tools

Performance Notes

• The AVX512 implementation will only be used if your processor supports it
• The Go implementation will be used as a fallback
• Performance varies significantly between implementations
• Use benchmarks to measure actual performance on your system

Support

If you encounter issues:

1. Check the troubleshooting section above
2. Verify Docker is working: docker run hello-world
3. Check Go installation: go version
4. Review the full README.md for detailed information