181 lines
4.3 KiB
Markdown
181 lines
4.3 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
sudo systemctl start docker
|
|
# or
|
|
sudo service docker start
|
|
```
|
|
|
|
2. **Permission denied**
|
|
```bash
|
|
chmod +x *.sh
|
|
```
|
|
|
|
3. **Port already in use**
|
|
```bash
|
|
# 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 |