initial commit

docs/FAQ.md

@@ -0,0 +1,327 @@
+# 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