deb-mock/docs/FAQ.md

# Deb-Mock FAQ

## Frequently Asked Questions

This FAQ addresses common issues and questions about **Deb-Mock**, a Debian-focused alternative to Fedora's Mock.

### Environment Variables in Chroot

**Q: I set environment variables in my configuration, but they're not preserved in the chroot environment.**

**A:** This is a common issue with chroot environments. **Deb-Mock** provides several solutions:

#### Solution 1: Use the `--preserve-env` flag
```bash
deb-mock shell --preserve-env
```

#### Solution 2: Configure specific environment variables
```yaml
# deb-mock.yaml
preserve_environment:
  - CC
  - CXX
  - CFLAGS
  - CXXFLAGS
  - DEB_BUILD_OPTIONS
  - CCACHE_DIR
```

#### Solution 3: Disable environment sanitization
```yaml
# deb-mock.yaml
environment_sanitization: false
```

#### Solution 4: Use the `--env-var` option
```bash
deb-mock shell --env-var CC=gcc --env-var CFLAGS="-O2"
```

**Why this happens:** Chroot environments sanitize environment variables for security reasons. **Deb-Mock** provides controlled ways to preserve necessary variables while maintaining security.

### Cross-Distribution Package Building

**Q: I'm on Debian Stable but need to build packages for Debian Sid. How can I do this?**

**A:** Use **Deb-Mock**'s bootstrap chroot feature, similar to Mock's `--bootstrap-chroot`:

#### Solution: Use bootstrap chroot
```bash
# Create a Sid chroot using bootstrap
deb-mock init-chroot debian-sid-amd64 --suite sid --bootstrap

# Build packages in the Sid chroot
deb-mock -r debian-sid-amd64 build package.dsc
```

#### Configuration-based approach
```yaml
# deb-mock.yaml
use_bootstrap_chroot: true
bootstrap_chroot_name: "debian-stable-bootstrap"
suite: "sid"
architecture: "amd64"
```

**Why this is needed:** Building packages for newer distributions on older systems can fail due to package manager version incompatibilities. Bootstrap chroots create a minimal environment with the target distribution's tools to build the final chroot.

### Build Dependencies Not Found

**Q: My build fails with "Package not found" errors for build dependencies.**

**A:** This usually indicates repository or dependency resolution issues:

#### Solution 1: Update the chroot
```bash
deb-mock update-chroot debian-bookworm-amd64
```

#### Solution 2: Check repository configuration
```yaml
# deb-mock.yaml
mirror: "http://deb.debian.org/debian/"
security_mirror: "http://security.debian.org/debian-security/"
backports_mirror: "http://deb.debian.org/debian/"
```

#### Solution 3: Install missing dependencies manually
```bash
deb-mock shell debian-bookworm-amd64
# Inside chroot:
apt-get update
apt-get install build-essential devscripts
```

#### Solution 4: Use verbose output for debugging
```bash
deb-mock --verbose build package.dsc
```

### Chroot Creation Fails

**Q: I get permission errors when creating chroots.**

**A:** Chroot creation requires root privileges:

#### Solution 1: Use sudo
```bash
sudo deb-mock init-chroot debian-bookworm-amd64
```

#### Solution 2: Add user to appropriate groups
```bash
sudo usermod -a -G sbuild $USER
# Log out and back in
```

#### Solution 3: Check disk space
```bash
df -h /var/lib/deb-mock
```

#### Solution 4: Verify debootstrap installation
```bash
sudo apt-get install debootstrap schroot
```

### Build Performance Issues

**Q: My builds are slow. How can I speed them up?**

**A:** **Deb-Mock** provides several performance optimization features:

#### Solution 1: Enable caching
```yaml
# deb-mock.yaml
use_root_cache: true
use_package_cache: true
use_ccache: true
```

#### Solution 2: Use parallel builds
```yaml
# deb-mock.yaml
parallel_jobs: 8
parallel_compression: true
```

#### Solution 3: Use tmpfs for temporary files
```yaml
# deb-mock.yaml
use_tmpfs: true
tmpfs_size: "4G"
```

#### Solution 4: Clean up old caches
```bash
deb-mock cleanup-caches
```

### Network and Proxy Issues

**Q: I'm behind a proxy and can't download packages.**

**A:** Configure proxy settings in your configuration:

#### Solution: Configure proxy
```yaml
# deb-mock.yaml
http_proxy: "http://proxy.example.com:3128"
https_proxy: "http://proxy.example.com:3128"
no_proxy: "localhost,127.0.0.1"
```

### Package Signing Issues

**Q: How do I sign packages with GPG keys?**

**A:** **Deb-Mock** supports package signing through configuration:

#### Solution: Configure signing
```yaml
# deb-mock.yaml
sign_packages: true
gpg_key: "your-gpg-key-id"
gpg_passphrase: "your-passphrase"  # Use environment variable in production
```

### Debugging Build Failures

**Q: My build failed. How can I debug it?**

**A:** **Deb-Mock** provides several debugging tools:

#### Solution 1: Use verbose output
```bash
deb-mock --verbose build package.dsc
```

#### Solution 2: Keep chroot for inspection
```bash
deb-mock build package.dsc --keep-chroot
deb-mock shell  # Inspect the failed build environment
```

#### Solution 3: Check build logs
```bash
# Build logs are automatically captured
ls -la ./output/
cat ./output/build.log
```

#### Solution 4: Use debug mode
```bash
deb-mock --debug build package.dsc
```

### Chain Building Issues

**Q: My chain build fails because later packages can't find earlier packages.**

**A:** This is a common issue with chain builds:

#### Solution 1: Use the chain command
```bash
deb-mock chain package1.dsc package2.dsc package3.dsc
```

#### Solution 2: Continue on failure
```bash
deb-mock chain package1.dsc package2.dsc --continue-on-failure
```

#### Solution 3: Check package installation
```bash
deb-mock shell
# Inside chroot, check if packages are installed:
dpkg -l | grep package-name
```

### Configuration Issues

**Q: How do I create a custom configuration?**

**A:** **Deb-Mock** supports custom configurations:

#### Solution 1: Create a custom config file
```yaml
# my-config.yaml
chroot_name: "custom-debian"
architecture: "amd64"
suite: "bookworm"
mirror: "http://deb.debian.org/debian/"
use_root_cache: true
use_ccache: true
parallel_jobs: 4
```

#### Solution 2: Use the config file
```bash
deb-mock -c my-config.yaml build package.dsc
```

#### Solution 3: Use core configurations
```bash
# List available configurations
deb-mock list-configs

# Use a core configuration
deb-mock -r debian-bookworm-amd64 build package.dsc
```

### Common Error Messages

#### "Chroot does not exist"
```bash
# Create the chroot first
deb-mock init-chroot debian-bookworm-amd64
```

#### "Permission denied"
```bash
# Use sudo for chroot operations
sudo deb-mock init-chroot debian-bookworm-amd64
```

#### "Package not found"
```bash
# Update the chroot
deb-mock update-chroot debian-bookworm-amd64
```

#### "Build dependencies not satisfied"
```bash
# Install build dependencies
deb-mock shell
# Inside chroot:
apt-get install build-essential devscripts
```

### Getting Help

**Q: Where can I get more help?**

**A:** Several resources are available:

1. **Documentation**: Check the main README and configuration documentation
2. **Verbose Output**: Use `--verbose` and `--debug` flags for detailed information
3. **Error Messages**: **Deb-Mock** provides detailed error messages with suggestions
4. **Logs**: Check build logs in the output directory
5. **Community**: Report issues on the project's issue tracker

### Performance Tips

1. **Use caching**: Enable root cache, package cache, and ccache
2. **Parallel builds**: Set appropriate `parallel_jobs` for your system
3. **Clean up**: Regularly run `deb-mock cleanup-caches`
4. **Monitor resources**: Use `deb-mock cache-stats` to monitor cache usage
5. **Optimize chroots**: Use tmpfs for temporary files if you have sufficient RAM

### Security Considerations

1. **Environment sanitization**: Keep environment sanitization enabled unless necessary
2. **Root privileges**: Only use sudo when required for chroot operations
3. **Package verification**: Verify source packages before building
4. **Network security**: Use HTTPS mirrors and configure proxies securely
5. **Cache security**: Regularly clean caches to remove sensitive build artifacts